fix(docs): preserve v3 API docs without the unavailable Stainless spec

[miguelg719]

Summary

• Fix mint validate failing with error 404 Not Found because the configured Stainless OpenAPI endpoint is unavailable. Reproduced with the CI-pinned mint@4.2.788 on current main before making changes.
• Check in the spec content currently published on docs.stagehand.dev: 8 endpoints, 67 schemas, 2 security schemes, and all 8 code-sample languages. Recovered from the OpenAPI YAML blocks in all 32 published v3 API-reference Markdown pages, not from a different server-generated schema.
• Replace only the five OpenAPI source references. Preserve all existing language sections, page URLs, navigation order, descriptions, request/response schemas, authentication, and code examples. No MDX pages or CI checks removed/disabled.
• Document provenance and add 11 regression tests for local sources, endpoint titles, sample languages, reference resolution, and authentication.

No-content-regression verification

• Deep equality checked every published fragment against the snapshot across Python, Java, Go, and Ruby (32/32): metadata, operations, shared schemas, servers, authentication, and code samples all match.
• Compared all 32 locally generated API pages to published content: URLs, titles, descriptions, and method/path mappings match.
• Confirmed docs.json is byte-identical to main after normalizing the five source substitutions.

Validation

• CI-pinned Mintlify: mint validate
• mint broken-links --check-anchors --check-redirects --check-snippets
• mint a11y --skip-contrast (145 MDX files)
• vitest run packages/docs/tests (38 tests)
• Focused oxfmt, oxlint, and git diff --check

This fixes the shared docs-validation failure blocking #2939 without modifying its content. Future v3 spec updates must be reviewed as explicit content changes rather than fetched during every build.

---

Summary by cubic

Fixes Mint validation failing with a 404 from the unavailable Stainless OpenAPI endpoint by switching the v3 API reference to a checked-in snapshot. The snapshot was recovered from the published v3 API pages, so the existing endpoints, schemas, auth, and code samples are unchanged. Future v3 spec updates must be reviewed as explicit content changes.

Changes

• Replaces all five docs.json OpenAPI source references with v3/openapi.json.
• Adds the recovered spec as packages/docs/v3/openapi.json, containing 8 endpoints, 67 schemas, 2 security schemes, and 8 code-sample languages.
• Adds 11 regression tests for local sources, endpoint titles, sample languages, reference resolution, and authentication.
• Documents snapshot provenance and update guidance in packages/docs/README.md.
• Keeps existing language sections, URLs, navigation, descriptions, schemas, auth, and examples; no pages or CI checks removed.

Validation

• mint validate, broken-links, a11y, and docs tests pass.

^{Written for commit 5f49e60. Summary will update on new commits.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
stagehand	🟢 Ready	View Preview	Sep 15, 2026, 10:16 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5f49e60

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[miguelg719]

Post-deployment verification: Mintlify preview deployment passed and persisted all 32 API pages. I fetched all 32 API-reference Markdown pages from https://stagehand-fix-docs-v3-openapi-source.mintlify.site and compared them with the production baseline captured before this change. Every page passed deep equality for its full OpenAPI document (including schemas, descriptions, auth, and code samples), plus equality of the surrounding Markdown after normalizing only the site origin and spec-source metadata. Result: 32/32 match; no docs content differences found.

[cubic-dev-ai]

All reported issues were addressed across 4 files

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant CI as CI Pipeline
    participant Mint as Mintlify CLI
    participant Spec as v3/openapi.json
    participant Docs as Mintlify Build
    participant Tests as Vitest Test Suite

    Note over Dev,Tests: Runtime Flow After This PR

    Dev->>CI: Push docs changes
    CI->>Mint: Run mint validate
    
    Note over Mint,Spec: NEW: Spec resolution now local
    Mint->>Spec: Read v3/openapi.json (local file)
    Spec-->>Mint: OpenAPI spec content
    
    alt Spec unavailable or invalid
        Mint-->>CI: Validation failed
        CI-->>Dev: Build blocked
    end

    Mint->>Docs: Generate v3 API reference pages
    Docs->>Docs: Create pages for Python, Java, Go, Ruby
    
    CI->>Mint: Run broken-links check
    Mint->>Spec: Resolve $ref pointers in spec
    Spec-->>Mint: Local schema references
    
    CI->>Tests: Run vitest suite
    Tests->>Spec: Read openapi.json
    Tests->>Spec: Validate endpoint titles & code samples
    Tests->>Spec: Check schema refs resolve locally
    Tests->>Spec: Verify auth schemes & server config
    
    alt All tests pass
        Tests-->>CI: 11/11 regression tests pass
        CI-->>Dev: Validation complete
    else Test failure
        Tests-->>CI: Test assertions failed
        CI-->>Dev: Investigation needed
    end
    
    Note over CI,Mint: Future spec updates ride on explicit content changes

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>