[CE-865] feat: bundle Stagehand docs for agents

[shrey150]

Linear: https://linear.app/browserbase/issue/CE-865/bundle-stagehand-docs-and-ship-agentsmd

Summary

• generate markdown Stagehand docs into dist/docs during package builds
• publish package-root AGENTS.md that points agents to the local docs
• include docs sources in Turbo build inputs and add a patch changeset

Verification

• pnpm exec turbo run build --filter=@browserbasehq/stagehand
• pnpm --filter @browserbasehq/stagehand run lint
• npm pack dry run includes AGENTS.md and 58 dist/docs markdown files

---

Summary by cubic

Bundles version-matched Stagehand docs into the @browserbasehq/stagehand package so agents and devs can read local docs that match the installed version. Addresses Linear CE-865 and adds an AGENTS.md entry point for quick navigation.

• New Features
  • Generate and ship markdown docs from packages/docs/v3/**/*.mdx to dist/docs during build (via scripts/build-docs.ts).
  • Add package-root AGENTS.md that points to local docs and suggests search commands.
  • Publish dist/docs and AGENTS.md, and include docs sources in Turbo build inputs; add a patch changeset.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: a2531db

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	Patch

Not sure what this means? Click here to learn what changesets are.

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

[cubic-dev-ai]

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant Turbo as Turbo Build
    participant CorePkg as @browserbasehq/stagehand
    participant BuildScript as scripts/build-docs.ts
    participant DocsSource as packages/docs/v3
    participant DistDocs as dist/docs/
    participant PkgJson as package.json files

    Note over Dev,DistDocs: PR: Bundle version-matched Stagehand docs for agents

    Dev->>Turbo: pnpm exec turbo run build --filter=@browserbasehq/stagehand
    Turbo->>CorePkg: Execute build task
    CorePkg->>CorePkg: Run build:esm and build:cjs in parallel
    CorePkg->>CorePkg: Run build-docs script

    CorePkg->>BuildScript: Call tsx scripts/build-docs.ts
    activate BuildScript

    BuildScript->>BuildScript: Clear & recreate dist/docs/

    BuildScript->>DocsSource: Read v3 directory recursively
    DocsSource-->>BuildScript: List of .mdx files

    loop For each .mdx file
        BuildScript->>DocsSource: Read .mdx content
        DocsSource-->>BuildScript: Content with frontmatter
        BuildScript->>BuildScript: Parse frontmatter (title, description)
        BuildScript->>BuildScript: Strip import/V3Banner lines
        BuildScript->>BuildScript: Convert .mdx to .md extension
        BuildScript->>DistDocs: Write converted .md file in dist/docs/v3/
    end

    BuildScript->>DistDocs: Generate index.md with metadata & navigation
    BuildScript-->>CorePkg: Done - 58 markdown files created

    deactivate BuildScript

    CorePkg->>PkgJson: Include dist/docs and AGENTS.md in publish files

    Dev->>CorePkg: Read AGENTS.md at package root
    CorePkg-->>Dev: Pointers to dist/docs/index.md and search commands

    Dev->>DistDocs: Search using rg for Stagehand API references
    DistDocs-->>Dev: Version-matched local documentation

Loading