> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BUGBOT

# Docs writing and positioning guide

**Severity: blocking.** Every rule in this file is mandatory. Flag violations as bugs, not suggestions. Do not approve a PR that violates any of these rules.

## Positioning

Browserbase docs are a demand-capture surface. They may use a customer's problem language when needed for discovery or clarity, but they must always resolve that problem using Browserbase's approved product language.

* **Ladder to the roof.** Every page must support the core narrative: "The web wasn't built for agents. Browserbase is." Position Browserbase in browser agents, not the entire agents category.
* **Lead with one pillar.** For developers, lead with browsers that work where APIs cannot. For leadership, lead with one platform instead of five vendors. At most one other pillar may support the lead.
* **Keep browsers at the center.** Do not position Browserbase as generic computer-use software or commodity infrastructure. Do not use roads, pipes, raw compute, or similar metaphors that reduce Browserbase to price per session.
* **Use only approved proof.** Do not invent statistics, customer names, performance claims, or superlatives. The approved proof points are 35m+ browser sessions per month; 10,000 customers; Ramp, Microsoft, and Lovable; SOC-2 Type II; Stagehand up to 2x faster with approximately 30% lower cost on repeated actions; and Functions with under 5ms latency to the browser.
* **Use the 15/85 or 25/75 API statistic only as an illustrative hook.** Never use it as a headline or as a claim Browserbase must defend. For leadership audiences, prefer the trend framing that 80% of an agent's context lives on the web.
* **Never name competitors in public copy.** This includes comparison copy unless PMM has explicitly reviewed it. Do not name Firecrawl, Browser Use, Kernel, HyperBrowser, Steel, Browserless, Anchor, Parallel, Exa, or Tavily.
* **Do not oversell agent intelligence.** Browserbase promises browsers, identity, observability, and infrastructure, not smarter agents.

## Writing style

These rules are non-negotiable. Flag every violation, even minor ones.

* **Brevity is mandatory.** Every sentence must earn its place. Cut filler words ("just," "simply," "basically," "actually," "in order to," "it should be noted that"). If a sentence can be shorter without losing meaning, it must be.
* **Sentence case for all titles and headings.** Only capitalize the first word and proper nouns (e.g., "How Browserbase took over the world" not "How Browserbase Took Over the World"). Flag any title-cased heading as a bug.
* **Conversational tone, not casual.** Text should sound natural if spoken aloud. Contractions are encouraged ("you'll," "it's," "don't"). No slang, no filler phrases like "let's dive in" or "as you can see."
* **Sound like an engineer stating a fact.** Lead with the outcome, prefer explicit language over clever phrasing, and avoid keynote language such as "revolutionizing how AI interacts with the digital world."
* **Active voice only.** Flag any use of passive voice (e.g., "the session is created" should be "Browserbase creates the session" or "you create the session").
* **Second person ("you") for the reader.** Always address the reader as "you," never as "we." Flag any use of "we" to mean the reader.
* **Oxford comma required.** Always use a comma before "and" or "or" in a list of three or more items. Flag missing oxford commas.
* **Capitalize product names** (Browserbase, Stagehand, Playwright, Functions, Search, Identity, etc.) but default to lowercase for everything else. Flag inconsistent capitalization.
* **No em dashes.** Flag every U+2014 em dash character in docs copy, frontmatter, tables, and code comments as blocking. Use judgment to recommend the clearest rewrite with a period, colon, comma, parentheses, or a rephrased sentence. Plain hyphens are allowed when they are semantically correct, such as compounds, ranges, product names, and command flags. Do not recommend replacing an em dash with a hyphen that still acts like an em dash.
  * **Exception:** em dashes are allowed inside fenced example content that readers copy verbatim: system prompts, model prompts, sample task strings, and pasted config/log snippets. The Agent copies these into its own runtime, so preserve authorial voice.
* **`Agent` casing.** Capitalize `Agent` and `Agents` when the word refers to the Browserbase product/feature or a concrete instance of it. Lowercase only when discussing agents as a generic industry concept. Flag mismatches.
  * Write "Create an Agent," "your first Agent run," "the Agent's goal," "Job Finder Agent," "an Agent renders each page."
  * Write "browser agents adapt to sites that change" or "the SDK for browser agents" (generic category).
  * API endpoint names track the OpenAPI spec: "Run an Agent," "Create an Agent," "List Agents."
* **No secrets in example prompts.** Never embed credentials, API keys, tokens, or personal data directly in example prompts, task strings, or code samples. Use `%variableName%` placeholders (Agent variables) or environment variables (`$BROWSERBASE_API_KEY`). Flag inline credentials as blocking.
* **No placeholder or dead links.** Flag any `](#)` or obviously broken href as blocking. Use canonical paths for repeated destinations:
  * Stagehand: `/welcome/quickstarts/stagehand`
  * Dashboard: `https://www.browserbase.com/overview`
  * Agents overview: `/platform/agents/overview`
  * Agents API endpoints under `/reference/api/...`.
* **Never use "we," "us," or "our" for Browserbase.** Always refer to the company by name. This applies to first-person plural in any form: subject ("we"), object ("us"), possessive ("our"), and contractions ("we're," "we've," "we'll"). Flag every instance.
  * Write "Browserbase recommends" not "we recommend."
  * Write "Browserbase provides" not "we provide."
  * Write "Browserbase's infrastructure" not "our infrastructure."
  * Write "Browserbase supports both transports" not "we support both transports."
  * Exception: direct quotes from customers or team members in case studies.

## Tagline

* Current: "Give your agents access to the whole web."
* Deprecated (flag if seen): "Agents can now browse and interact with the web like humans."
* Deprecated (flag if seen): "Autonomously read, write, and perform tasks on the web with a headless browser."

## Structure and formatting

* Make content easy to skim: use bullet points, break up text, include images/videos/tables where helpful.
* Headlines should outline a clear structure and make sense on their own.
* Lead with the main information. Get to the point fast, add details later. Front-load keywords for scanning.
* Make customer choices and next steps obvious.

## Code examples

* Default to SDK code examples over raw API calls whenever possible.
* Label every Node.js code block as `Node.js`, including snippets written in TypeScript or JavaScript. Keep the syntax language for highlighting, then add the visible label, such as `typescript Node.js` or `javascript Node.js`. Never present these snippets as `TypeScript`, `TS`, `JavaScript`, or `JS`.
* Define OpenAPI `x-codeSamples` in the owning API route schema under `apps/api/src/routes/`. Never edit generated code samples only in `apps/docs/reference/api/openapi.v1.yaml`; `pnpm run gen-swagger` overwrites that file. After changing route schemas, run `pnpm run gen-swagger` from `apps/api/`, and commit the generated spec.
* Highlight the pieces that are changing and link out to related docs.

## SEO

* Write with new users, search terms, and AI consumption in mind.

## Terminology

Use these terms consistently:

| Use this                                                                  | Not this                          |
| ------------------------------------------------------------------------- | --------------------------------- |
| browser agent                                                             | web agent                         |
| agents                                                                    | AI (in most external copy)        |
| headless browsers                                                         | serverless browsers               |
| Verified, for the customer-facing access feature                          | Stealth Mode or Agent Identity    |
| Agent Identity, for Web Bot Auth, Signed Agents, and agent-owned accounts | Verified or stealth               |
| SDK for browser agents (Stagehand)                                        | browser automation framework      |
| agents                                                                    | agentic workflows                 |
| browser agent platform (Browserbase)                                      | browser automation infrastructure |

* When listing platform primitives, always put browsers first.
* Capitalize `Browser Agent` and `Browser Agent Platform` when naming the category. Never use `Web Agent`.
* Use `agents` in headings and body copy. `AI Agent` and `AI Agents` are allowed only in SEO or tab titles and on first-touch surfaces for non-AI-native readers.
* Don't lead with Search or Fetch as standalone products; browsers are the core.
* Do not blur Agents and Stagehand. Agents is the managed API product. Stagehand is the SDK and AI browser driver.
* Never include Director in product lists or copy. Director is sunset.
* `Automation` is allowed when it describes the user's outcome, speaks to legacy automation or RPA users, or matches demand-capture search terms.
* `Scraping`, `scraper`, `crawler`, and related terms require case-by-case PMM review. They may match a customer's use-case language, but must not appear in an H1, page title, or sidebar title.
* Don't position around benchmarks that can't be defended ("best search API," "fastest fetch").

### Access and identity language

* Docs may use `stealth`, `blocked`, `bot detection`, `anti-bot`, and similar customer language only to name or explain the problem. Never use these terms to name Browserbase, the platform, or a Browserbase product.
* Ladder from the customer's words to Browserbase's answer: their problem (`stealth`, `blocked`, or `CAPTCHA`) to **Verified**, then to the differentiation of **Agent Identity** and Web Bot Auth.
* The only valid positioning frame for `stealth` is educational: identity is stronger than stealth. Never claim that Browserbase has better stealth.
* `CAPTCHA` and `CAPTCHA solving` are allowed when describing a solution, such as "solving CAPTCHAs."
* Never use bot-protection vendor or product trademarks in public copy, including `reCAPTCHA`, `hCaptcha`, `Turnstile`, and `Cloudflare`.
* Preserve exact API parameters, error messages, code identifiers, and quoted third-party text when technical accuracy requires them. Do not promote those identifiers into headings or product names.

### Restricted use cases

Never create or approve use-case pages, demos, examples, growth hooks, SEO or SEM copy, or sales promises around:

* Apple domains, including iTunes and the App Store
* Entertainment, including Netflix and PlayStation
* Banking and other financial institutions
* Google domains without explicit approval
* Streaming
* Event ticketing, including Ticketmaster (travel such as flights is allowed)
* LinkedIn
* Mailing

Flag any copy that touches a restricted use case for PMM review before it ships.

## Product descriptions

Use these canonical descriptions when referring to Browserbase products:

* **Browserbase**: the complete platform to run agents that use the web like humans.
* **Browsers**: the core; browsers that work where APIs can't.
* **Agents**: API for reusable browser agents, with no code or deployment.
* **Search and Fetch**: primitives that give agents fast, token-efficient web context.
* **Functions**: run code next to the browser and deploy instantly, with under 5ms latency to the browser.
* **Model Gateway**: access to major models via a single Browserbase API key with unified billing.
* **Agent Identity**: the attestation layer for Web Bot Auth, Signed Agents, and agent-owned accounts.
* **Verified**: the customer-facing feature that gives agents reliable access when websites block automation.
* **Stagehand**: the SDK and AI browser driver for browser agents.
* **Browse.sh**: the open web skills catalog, accessed through the Browse CLI.