chore(docs): update style guide and make positioning changes to intro…

[Kylejeong2]

… and ai rules

why

Stagehand is changing, and so is the way that we talk about it.

what changed

Some of these things are updating the docs, cubic MD, that reviews PRs to our docs to make sure that they're aligned, and then also making some raw positioning changes to our documentation.

test plan

---

Summary by cubic

Updates docs to Stagehand v4 positioning and expands the intro with Playwright-style API examples alongside AI primitives, plus Model Router docs (model: "auto"). Also exposes the Browserbase session ID on TS, Python, and Go SDK browser handles to simplify reconnect flows (GRO-1708).

• New Features

  • TS: StagehandBrowser.sessionId for Browserbase-backed browsers; undefined for local.
  • Python: StagehandBrowser.session_id; None for local.
  • Go: Browser.SessionID(); empty string for local.

• Refactors

  • Style guide and intros: position Stagehand as “the SDK for browser agents,” contrast with Playwright, update active-voice example (“Stagehand creates the session”).
  • Introduction: add Playwright-style page API section with TS/Python/Go samples; clarify two layers (AI primitives + deterministic page APIs); update “Why developers choose Stagehand.”
  • AI rules templates: align TS/Python/Go project descriptions, headings, and casing with the new positioning.
  • Deployments: remove Browser Functions beta tip.
  • Minor copy edits: punctuation and warning formatting tweaks in config/logging.
  • Dependencies: bump mint and @mintlify/* to current versions.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7888660

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 3 files

Confidence score: 5/5

• In .cubic/docs-style-guide.md, the rewritten bullet currently reads awkwardly (“Connect top-level positioning that Playwright was not built for agents”), which could confuse contributors and lead to inconsistent guidance edits—restore the missing object or revert to the original phrasing to keep the style rule clear.

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=".cubic/docs-style-guide.md">

<violation number="1" location=".cubic/docs-style-guide.md:23">
P3: This bullet in the style guide itself reads awkwardly after the rewrite. "Connect top-level positioning that Playwright was not built for agents" drops the object of "connect" — the original phrasing was "Connect top-level positioning to the Browserbase narrative that..." — so it now reads as though "top-level positioning" is taken by the that-clause. Suggest restoring the object: "Connect top-level positioning to the fact that Playwright was not built for agents, but Stagehand is."</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant SG as Style Guide (.cubic/docs-style-guide.md)
    participant Docs as Documentation (MDX files)
    participant Cubic as Cubic (PR review bot)
    participant AIRules as AI Rules (TS/Python/Go templates)
    participant Agent as Agent Tools (Cursor/Windsurf)

    Note over Dev,Agent: Documentation Architecture for Stagehand v4

    Dev->>SG: Reads positioning guidelines
    Dev->>Docs: Updates introduction and AI rules content
    Dev->>AIRules: Aligns project descriptions to SDK positioning
    Dev->>Cubic: Submits docs PR
    Cubic->>SG: Validates PR against style guide rules
    SG-->>Cubic: Compliance status
    alt Compliance OK
        Cubic-->>Dev: Approve
    else Violations
        Cubic-->>Dev: Request changes
    end
    Agent->>AIRules: Loads rules for Stagehand projects
    Agent->>Docs: References SDK docs for implementation

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: This bullet in the style guide itself reads awkwardly after the rewrite. "Connect top-level positioning that Playwright was not built for agents" drops the object of "connect" — the original phrasing was "Connect top-level positioning to the Browserbase narrative that..." — so it now reads as though "top-level positioning" is taken by the that-clause. Suggest restoring the object: "Connect top-level positioning to the fact that Playwright was not built for agents, but Stagehand is."

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .cubic/docs-style-guide.md, line 23:

<comment>This bullet in the style guide itself reads awkwardly after the rewrite. "Connect top-level positioning that Playwright was not built for agents" drops the object of "connect" — the original phrasing was "Connect top-level positioning to the Browserbase narrative that..." — so it now reads as though "top-level positioning" is taken by the that-clause. Suggest restoring the object: "Connect top-level positioning to the fact that Playwright was not built for agents, but Stagehand is."</comment>

<file context>
@@ -16,28 +16,24 @@ If a PR materially adds or changes a hero, tagline, product description, quantit
 - Keep Stagehand distinct from Browserbase Agents. Stagehand is the SDK and browser driver; Agents is Browserbase's managed API product. Do not use the names interchangeably.
 - Position computer use as one Stagehand capability, not Stagehand's identity.
-- Connect top-level positioning to the Browserbase narrative that the web was not built for agents, but Browserbase is. Keep Stagehand copy focused on the developer's browser-agent workflow rather than the entire Browserbase platform.
+- Connect top-level positioning that Playwright was not built for agents, but Stagehand is. Keep Stagehand copy focused on the developer's browser-agent workflow rather than the entire Browserbase platform.
 - Lead with one primary idea per page or section. Do not compress every Browserbase product pillar into Stagehand copy.
-- Do not lead Stagehand positioning with Search, Fetch, or other supporting Browserbase products.
</file context>

Suggested change

	- Connect top-level positioning that Playwright was not built for agents, but Stagehand is. Keep Stagehand copy focused on the developer's browser-agent workflow rather than the entire Browserbase platform.
	- Connect top-level positioning to the fact that Playwright was not built for agents, but Stagehand is. Keep Stagehand copy focused on the developer's browser-agent workflow rather than the entire Browserbase platform.

[cubic-dev-ai]

5 issues found across 9 files (changes from recent commits).

Confidence score: 3/5

• In packages/docs/v4/first-steps/introduction.mdx, both the Python active_page() and TypeScript activePage() samples can hit None/undefined when no tab is active, so copied examples can fail at runtime (and TS can fail strict compile) — add an active-page guard before dereferencing in both snippets.
• In packages/docs/v4/first-steps/introduction.mdx, the updated architecture bullet swaps a concrete description for an unverified speed claim, which can set incorrect performance expectations for readers — restore factual architecture wording or qualify the claim with evidence.
• Docs-prose compliance is currently inconsistent across packages/docs/v3/configuration/models.mdx and packages/docs/v4/first-steps/introduction.mdx (banned em dash usage and metaphor-heavy phrasing), which increases editorial churn and drift from the style guide — rewrite these lines in explicit, policy-aligned language.

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/first-steps/introduction.mdx">

<violation number="1" location="packages/docs/v4/first-steps/introduction.mdx:116">
P2: This TypeScript sample does not compile with strict null checks and throws when the context has no active tab, because `activePage()` can return `undefined`. Check for an active page before calling its methods.</violation>

<violation number="2" location="packages/docs/v4/first-steps/introduction.mdx:127">
P2: This Python sample fails when the context has no active tab, because `active_page()` may return `None` and the next line dereferences it. Add the same active-page guard used by the Go example.</violation>

<violation number="3" location="packages/docs/v4/first-steps/introduction.mdx:159">
P2: Custom agent: **Stagehand docs prose guide**

The new bullet replaces a factual architecture description with an unsubstantiated performance claim ("so remote browsers feel as fast as local ones"). The prose guide requires describing documented behavior precisely and not implying certainty beyond what the documented feature supports. A search of the docs shows no other page substantiates this speed parity claim. Rewrite this to documented behavior only: for example, state that Stagehand's runtime executes in the browser next to the page and leave performance claims out unless they are documented elsewhere.</violation>

<violation number="4" location="packages/docs/v4/first-steps/introduction.mdx:164">
P1: Custom agent: **Stagehand docs prose guide**

The 'Built for agent harnesses' bullet uses metaphorical phrasing ('Stagehand is the hands. Bring your own agent as the brain') rather than explicit engineer-style language. The prose guide's Voice rule requires explicit language over clever phrasing and states engineers should write like an engineer stating a fact, not a keynote speaker. Rewrite with a direct description of the division of labor, for example: 'Stagehand provides the browser controls; connect your own agent framework (LangChain, CrewAI, Mastra, or a custom loop).'</violation>
</file>

<file name="packages/docs/v3/configuration/models.mdx">

<violation number="1">
P1: Custom agent: **Stagehand docs prose guide**

The added callout prose uses an em dash (—), which the docs prose guide explicitly bans: "Do not use em dashes in prose, frontmatter, tables, or authored code comments." Replace the em dash with a colon or period. For example: "**(NEW) Model Gateway**: Use your Browserbase API key..."</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Custom agent: Stagehand docs prose guide

The 'Built for agent harnesses' bullet uses metaphorical phrasing ('Stagehand is the hands. Bring your own agent as the brain') rather than explicit engineer-style language. The prose guide's Voice rule requires explicit language over clever phrasing and states engineers should write like an engineer stating a fact, not a keynote speaker. Rewrite with a direct description of the division of labor, for example: 'Stagehand provides the browser controls; connect your own agent framework (LangChain, CrewAI, Mastra, or a custom loop).'

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/first-steps/introduction.mdx, line 164:

<comment>The 'Built for agent harnesses' bullet uses metaphorical phrasing ('Stagehand is the hands. Bring your own agent as the brain') rather than explicit engineer-style language. The prose guide's Voice rule requires explicit language over clever phrasing and states engineers should write like an engineer stating a fact, not a keynote speaker. Rewrite with a direct description of the division of labor, for example: 'Stagehand provides the browser controls; connect your own agent framework (LangChain, CrewAI, Mastra, or a custom loop).'</comment>

<file context>
@@ -99,15 +106,62 @@ fmt.Println(len(observed.Data), "candidate actions")
 - **Extraction is typed:** [`extract`](/v4/basics/extract) validates results against a schema you define and hands back fully typed data.
 - **Models are flexible:** Use a supported provider by name or supply your own client-side LLM callback.
 - **Metrics are built in:** Read per-method token usage and inference timing with [`metrics()`](/v4/reference/stagehand).
+- **Built for agent harnesses:** Stagehand is the hands. Bring your own agent as the brain (LangChain, CrewAI, Mastra, or a custom loop).
 
 ## Built for modern development
</file context>

Suggested change

	- **Built for agent harnesses:** Stagehand is the hands. Bring your own agent as the brain (LangChain, CrewAI, Mastra, or a custom loop).
	- **Built for agent harnesses:** Stagehand provides the browser controls; connect your own agent framework (LangChain, CrewAI, Mastra, or a custom loop).

[cubic-dev-ai]

P2: This Python sample fails when the context has no active tab, because active_page() may return None and the next line dereferences it. Add the same active-page guard used by the Go example.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/first-steps/introduction.mdx, line 127:

<comment>This Python sample fails when the context has no active tab, because `active_page()` may return `None` and the next line dereferences it. Add the same active-page guard used by the Go example.</comment>

<file context>
@@ -99,15 +106,62 @@ fmt.Println(len(observed.Data), "candidate actions")
+
+<Tab title="Python">
+```python
+page = await stagehand.browser.context.active_page()
+
+await page.goto("https://example.com")
</file context>

Suggested change

	page = await stagehand.browser.context.active_page()
	page = await stagehand.browser.context.active_page()
	if page is None:
	raise RuntimeError("Stagehand has no active page")

[cubic-dev-ai]

P2: This TypeScript sample does not compile with strict null checks and throws when the context has no active tab, because activePage() can return undefined. Check for an active page before calling its methods.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/first-steps/introduction.mdx, line 116:

<comment>This TypeScript sample does not compile with strict null checks and throws when the context has no active tab, because `activePage()` can return `undefined`. Check for an active page before calling its methods.</comment>

<file context>
@@ -99,15 +106,62 @@ fmt.Println(len(observed.Data), "candidate actions")
+<Tabs>
+<Tab title="TypeScript">
+```typescript
+const page = await stagehand.browser.context.activePage();
+
+await page.goto("https://example.com");
</file context>

Suggested change

	const page = await stagehand.browser.context.activePage();
	const page = await stagehand.browser.context.activePage();
	if (!page) {
	throw new Error("Stagehand has no active page");
	}

[cubic-dev-ai]

P2: Custom agent: Stagehand docs prose guide

The new bullet replaces a factual architecture description with an unsubstantiated performance claim ("so remote browsers feel as fast as local ones"). The prose guide requires describing documented behavior precisely and not implying certainty beyond what the documented feature supports. A search of the docs shows no other page substantiates this speed parity claim. Rewrite this to documented behavior only: for example, state that Stagehand's runtime executes in the browser next to the page and leave performance claims out unless they are documented elsewhere.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/first-steps/introduction.mdx, line 159:

<comment>The new bullet replaces a factual architecture description with an unsubstantiated performance claim ("so remote browsers feel as fast as local ones"). The prose guide requires describing documented behavior precisely and not implying certainty beyond what the documented feature supports. A search of the docs shows no other page substantiates this speed parity claim. Rewrite this to documented behavior only: for example, state that Stagehand's runtime executes in the browser next to the page and leave performance claims out unless they are documented elsewhere.</comment>

<file context>
@@ -99,15 +106,62 @@ fmt.Println(len(observed.Data), "candidate actions")
-- **First-class TypeScript, Python, and Go SDKs:** Each client is generated from the same protocol, so every method and option matches across supported languages.
-- **The AI primitives live on Stagehand:** `act`, `extract`, and `observe` are methods on [`stagehand`](/v4/reference/stagehand). They run on the browser's active page by default, or on a page you pass. Deterministic controls like `goto`, `click`, and `type` stay on [`page`](/v4/reference/page).
+- **Precise control:** Mix AI-powered actions with deterministic `page` APIs. You decide exactly how much AI to use.
+- **Runtime lives in the browser:** Stagehand runs next to the page, so remote browsers feel as fast as local ones.
+- **First-class TypeScript, Python, and Go SDKs:** Every method and option matches across supported languages.
 - **Extraction is typed:** [`extract`](/v4/basics/extract) validates results against a schema you define and hands back fully typed data.
</file context>

Suggested change

	- **Runtime lives in the browser:** Stagehand runs next to the page, so remote browsers feel as fast as local ones.
	- **Runtime lives in the browser:** Stagehand runs next to the page.

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Confidence score: 5/5

• In packages/docs/v4/configuration/browser.mdx, the comma splice in the plan-restriction sentence can make the guidance read as a run-on, which may briefly confuse readers about support instructions—replace the comma with a period or semicolon to clarify the meaning.

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/configuration/browser.mdx">

<violation number="1" location="packages/docs/v4/configuration/browser.mdx:329">
P3: This comment has a comma splice, which makes the plan restriction read as a run-on. Use a period or semicolon before the support instruction.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: This comment has a comma splice, which makes the plan restriction read as a run-on. Use a period or semicolon before the support instruction.

Prompt for AI agents

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

<comment>This comment has a comma splice, which makes the plan restriction read as a run-on. Use a period or semicolon before the support instruction.</comment>

<file context>
@@ -326,7 +326,7 @@ const browser = await browserbase.launch({
   keepAlive: true, // Available on Startup plan
   browserSettings: {
-    verified: false, // this is a Scale Plan feature - reach out to support@browserbase.com to enable
+    verified: false, // this is a Scale Plan feature, reach out to support@browserbase.com to enable
     blockAds: true,
     solveCaptchas: true,
</file context>

Suggested change

	verified: false, // this is a Scale Plan feature, reach out to support@browserbase.com to enable
	verified: false, // This is a Scale Plan feature. Reach out to support@browserbase.com to enable it.