docs(integrations): add fx guide

[miguelg719]

why

Add the public documentation for the fx integration introduced in #2776 and hardened in #2791.

This PR is intentionally stacked on #2791 because the guide documents its deterministic discovery instructions and transport-safe screenshot mode.

what changed

• add a complete fx integration guide following the existing v4 integration page structure
• add the official fx mark as a local docs asset
• add fx immediately after Mastra and before Pi in the integrations sidebar
• add the fx overview card in the same Mastra → fx → Pi position
• update overview lifecycle and source descriptions to include fx

test plan

• pnpm --filter @browserbasehq/stagehand-docs test:unit (27 tests)
• pnpm --filter @browserbasehq/stagehand-docs check
  • Mint build validation
  • broken links, anchors, redirects, and snippets
  • accessibility checks
• pnpm exec oxfmt --check packages/docs/docs.json
• git diff --check

---

Summary by cubic

Adds a complete fx integration guide to the v4 docs and updates the overview/sidebar to include fx, using a dark, centered PNG icon. Documents deterministic MCP tool discovery and a transport-safe screenshot mode to keep fx sessions stable.

• Verify the fx page renders and all anchors, code blocks, and links resolve, including fx v0.0.3 references.
• Confirm the dark, centered fx PNG displays with correct alt/aria and aligns with other integration icons across themes.
• Check sidebar ordering (Mastra → fx → Pi) and the updated overview card copy.
• Merge only after the stdio facade exposes the --max-screenshot-base64-bytes flag and stable tool names; otherwise the guide will be inaccurate.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: e3d0714

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

[cubic-dev-ai]

1 issue found across 4 files

Confidence score: 4/5

• packages/docs/v4/integrations/fx.mdx does not explain that an exported BROWSERBASE_API_KEY causes the facade to select Browserbase unless STAGEHAND_BROWSER="local", which could unexpectedly launch a remote browser; document this conditional default and the local override.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/docs/v4/integrations/fx.mdx">

<violation number="1" location="packages/docs/v4/integrations/fx.mdx:64">
P2: When `BROWSERBASE_API_KEY` is already exported, the facade selects Browserbase unless `STAGEHAND_BROWSER="local"`. Document the conditional default so users do not unknowingly launch a remote browser.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Docs as Documentation Site
    participant Eng as fx Integration Engineer
    participant FX as fx Agent (v0.0.3)
    participant MCP as Stagehand MCP Server
    participant Browser as Chrome / Browserbase
    participant User

    Note over User,Docs: fx Integration Documentation (v4)

    User->>Docs: Read fx.mdx quickstart
    Docs-->>User: Prereqs: Node 24, pnpm, fx v0.0.3, Vercel AI Gateway key

    User->>FX: Install & login (fx login)
    alt API key instead of login
        User->>FX: export AI_GATEWAY_API_KEY
    end

    User->>FX: Configure ~/.fx/mcp.json (stdio server)
    FX-->>User: Reads MCP config on reload

    User->>FX: Start fx session
    FX->>MCP: Launch stdio server (mcp_stagehand_run, snapshot, screenshot)
    MCP->>Browser: Create persistent browser session

    Note over FX,MCP: Tool discovery (fx v0.0.3)
    FX->>MCP: mcp_search_tools (Stagehand tools)
    MCP-->>FX: mcp_stagehand_run, snapshot, screenshot
    FX-->>FX: Fallback to exact names from skill if search missing

    FX->>MCP: mcp_stagehand_run (page.goto etc.)
    MCP->>Browser: Navigate/persist state
    MCP-->>FX: Screenshot (base64, max 60000 JPEG)
    alt Screenshot exceeds frame limit
        MCP->>MCP: Encode viewport JPEG, reduce bytes
        alt Still too large
            MCP-->>FX: Request oversized screenshot via run snapshot
        end
    end

    Note over MCP,Browser: Browser launched lazily, state persists across tool calls
    FX->>MCP: mcp_stagehand_snapshot
    MCP->>Browser: Read page state
    MCP-->>FX: Snapshot
    FX->>MCP: mcp_stagehand_run (auth script)
    MCP->>Browser: Authenticate, state shared

    Note over FX,MCP: If non-interactive: permission allow from ~/.fx/settings.json
    FX->>MCP: Pre-approved tools only

    Note over MCP: Environment: STAGEHAND_BROWSER, BROWSERBASE_API_KEY
    Note over MCP: Node 24 for stdio server, Chrome for local mode

    Note over Browser,FX: Security warning for untrusted code (run tools)

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When BROWSERBASE_API_KEY is already exported, the facade selects Browserbase unless STAGEHAND_BROWSER="local". Document the conditional default so users do not unknowingly launch a remote browser.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/fx.mdx, line 64:

<comment>When `BROWSERBASE_API_KEY` is already exported, the facade selects Browserbase unless `STAGEHAND_BROWSER="local"`. Document the conditional default so users do not unknowingly launch a remote browser.</comment>

<file context>
@@ -0,0 +1,162 @@
+Start a new fx session after saving the file, or run `/mcp reload` in an open session.
+  </Step>
+  <Step title="Choose the browser">
+The facade uses local Chrome by default. To use a disposable Browserbase browser instead:
+
+```bash
</file context>

Suggested change

	The facade uses local Chrome by default. To use a disposable Browserbase browser instead:
	The facade uses Browserbase when `BROWSERBASE_API_KEY` is set; otherwise it uses local Chrome. To force local mode, set `STAGEHAND_BROWSER="local"`.