Reagan/eng 5397 make docs better for agents pt 1

.gitignore

@@ -35,6 +35,12 @@ docs/.mintlify/
 # Claude Code
 .claude/skills/
 
+# OMC / harness state (any directory level)
+.omc/
+.harness/
+omc/
+harness/
+
 # Personal notes
 reagan_*
 .pnpm-store

docs/cloud/agent/overview.mdx

@@ -0,0 +1,35 @@
+---
+title: Overview
+description: "The hosted agent takes a task in plain language and drives a stealth browser until it's done."
+icon: robot
+---
+
+The agent is a hosted loop: it reads the page, decides an action, executes it, and repeats until the task is complete. You send a task, you get a result.
+
+```python
+from browser_use_sdk import BrowserUse
+
+client = BrowserUse()
+result = client.run("List the top 5 posts on Hacker News with their points")
+print(result.output)
+```
+
+Each run gets its own [stealth cloud browser](/cloud/browser/stealth) with proxies and CAPTCHA handling already on. No browser management, no selectors, no waiting logic.
+
+## When to use the agent
+
+The agent fits tasks where you care about the outcome, not the exact clicks: data extraction from sites that change layout, workflows across several pages, form submission, or anything you'd rather describe than script. If you need pixel-exact control or deterministic repetition, drive a [browser session](/cloud/browser/overview) directly instead, or record an agent run once and replay it with [cache scripts](/cloud/agent/cache-script).
+
+## What the agent can do
+
+- [Structured output](/cloud/agent/structured-output) — get results as typed JSON matching your schema
+- [Follow-up tasks](/cloud/agent/follow-up-tasks) — continue in the same browser with context intact
+- [Streaming](/cloud/agent/streaming) — watch steps as they happen
+- [Workspaces](/cloud/agent/workspaces) — files the agent reads and writes during a run
+- [Human-in-the-loop](/cloud/agent/human-in-the-loop) — take over the browser mid-task, then hand back
+- [Models](/cloud/agent/models) — pick the LLM that drives the loop
+- [Cache scripts](/cloud/agent/cache-script) — record a run, replay it without LLM calls
+
+## Next
+
+Start with the [agent quickstart](/cloud/agent/quickstart). For latency and cost tuning, see [Performance & speed](/cloud/agent/performance).

docs/cloud/agent/performance.mdx

@@ -0,0 +1,55 @@
+---
+title: Performance & speed
+description: "Every setting that affects agent latency, from model choice to typing speed."
+icon: gauge-high
+---
+
+Agent latency has four sources, in descending order of impact: LLM inference per step, number of steps, page-load waits, and input mechanics. Tune them in that order.
+
+## Model choice
+
+The model runs on every step, so it dominates end-to-end time. Smaller models cut per-step latency at some cost in reliability on hard pages. See [Models](/cloud/agent/models) for the current lineup and speed characteristics.
+
+## Fewer, cheaper steps
+
+- **`use_thinking`** — disables the model's extended reasoning per step.
+- **`use_judge`** — the post-task quality evaluator; disabling it saves a final LLM call when you don't need verification.
+- **`use_vision`** — controls whether screenshots are sent to the model; text-only steps are faster and cheaper, at the cost of visual grounding.
+- **`max_history_items`** — caps how much history is resent each step; smaller history means smaller prompts.
+
+{/* TEAM REVIEW: confirm which of these parameters are exposed on cloud v3/v4 runs vs library-only, and document defaults per surface. Evals found them documented only in legacy v2 docs — flash_mode was removed as inaccurate, verify the rest are current before publish. */}
+
+## Waits and page loads
+
+The agent waits between actions and for pages to settle. In the library these are browser-level settings (`wait_between_actions`, `minimum_wait_page_load_time`, `wait_for_network_idle_page_load_time`); lowering them speeds up action-dense tasks on fast sites and risks acting before slow pages are ready.
+
+{/* TEAM REVIEW: reconcile the documented default for wait_between_actions (docs said 0.5s, source says 0.1s) and state the correct values here. */}
+
+## Typing speed
+
+Text is typed character by character through CDP with a small fixed delay per keystroke. This is deliberate: instant-fill is a bot tell, and human-paced input is part of staying unblocked. If a form fill feels slow, that's the trade-off working.
+
+{/* TEAM REVIEW: the per-character delay is hardcoded at 5ms in the library source and documented nowhere. Confirm the value, whether cloud uses the same, and whether we want to expose it as a config field (product ticket exists). */}
+
+## The fast path, all together
+
+```python
+result = await client.run(
+    "Get the price of iPhone 16 on amazon.de",
+    use_thinking=False,
+    use_judge=False,
+    use_vision=False,
+)
+```
+
+{/* TEAM REVIEW: verify this exact snippet against the current v3/v4 run signature before publish. */}
+
+## Deterministic replay: skip the LLM entirely
+
+For workflows you run repeatedly, do the slow run once and replay it: [cache scripts](/cloud/agent/cache-script) re-execute a recorded run without LLM calls, which is faster and cheaper than any tuning above.
+
+## Further reading
+
+- [Speed matters: how Browser Use achieves the fastest agent execution](https://browser-use.com/posts/speed-matters)
+- [The fastest web agent in the world](https://browser-use.com/posts/llm-gateway)
+- [What LLM model should I use for Browser Use?](https://browser-use.com/posts/what-model-to-use) — the speed/accuracy tradeoff per model

docs/cloud/api-reference.mdx

@@ -21,6 +21,16 @@ Get a key at [cloud.browser-use.com/settings](https://cloud.browser-use.com/sett
 https://api.browser-use.com/api/v3
 ```
 
+## OpenAPI spec
+
+The full API surface is published as a machine-readable OpenAPI 3.1 spec — use it to generate typed clients or validate payloads:
+
+```
+https://docs.browser-use.com/openapi.json
+```
+
+Also at [/cloud/openapi/v3.json](https://docs.browser-use.com/cloud/openapi/v3.json). Legacy v2 spec: [/cloud/openapi/v2.json](https://docs.browser-use.com/cloud/openapi/v2.json).
+
 ## Quick example
 
 ```bash Create a session

docs/cloud/api-v2-overview.mdx

@@ -13,6 +13,8 @@ export BROWSER_USE_API_KEY=your_key
 
 Base URL: `https://api.browser-use.com/api/v2`
 
+OpenAPI spec: [/cloud/openapi/v2.json](https://docs.browser-use.com/cloud/openapi/v2.json) — legacy; new projects should use [v3](https://docs.browser-use.com/openapi.json).
+
 ---
 
 Prefer the SDK? See the [Agent (v2) docs](/cloud/legacy/agent).

docs/cloud/browser/captcha.mdx

@@ -0,0 +1,47 @@
+---
+title: CAPTCHA Solving
+description: "Browser Use remote browsers solve CAPTCHAs automatically, on by default, on every plan."
+icon: shield-check
+---
+
+Browser Use remote browsers are state-of-the-art for stealth. By using a custom Chromium fork with dozens of patches, web agents get blocked by CAPTCHAs and anti-bot systems noticeably less on the websites users care about most. Read how we do it in [We stealth benchmarked every major cloud browser provider](https://browser-use.com/posts/stealth-benchmark), and see the [benchmark results](https://browser-use.com/benchmarks): 84.8% on BrowserBench and 81% bypass on high-security sites, ahead of every other provider.
+
+When a CAPTCHA does appear, remote browsers have **automatic CAPTCHA solving** built in. You do not need to configure anything, on the browser or on the attached agent or automation library (Playwright, Puppeteer, Selenium). It is on by default on every plan, including the [free tier](/cloud/pricing).
+
+## Setting up a stealth browser
+
+There is nothing to turn on. Stealth and CAPTCHA solving come with every session. Start one:
+
+<CardGroup cols={2}>
+  <Card title="Create a browser session" icon="plus" href="/cloud/browser/create">
+    SDK, REST, or a single WebSocket URL.
+  </Card>
+  <Card title="Connect your framework" icon="code" href="/cloud/browser/playwright">
+    Playwright, Puppeteer, or Selenium over CDP.
+  </Card>
+  <Card title="Stealth" icon="user-secret" href="/cloud/browser/stealth">
+    What the hardened Chromium fork does.
+  </Card>
+  <Card title="Proxies" icon="globe" href="/cloud/browser/proxies">
+    Residential IPs in 195+ countries, on by default.
+  </Card>
+</CardGroup>
+
+## FAQ
+
+**Does the open-source library solve CAPTCHAs?**
+
+Without remote browsers, [open-source](https://github.com/browser-use/browser-use) agents have no stealth or CAPTCHA solving. Giving your agent stealth is easy: run it on a remote browser with a single parameter. See [Cloud browser + open source agent](/cloud/browser/open-source-agent).
+
+**Can I use a third-party CAPTCHA solver?**
+
+No, we do not support third-party CAPTCHA solver plugins on the browser. If your CAPTCHAs are not being solved properly, reach out and we will look into it.
+
+**Do I need to enable anything for CAPTCHA solving?**
+
+No. Remote browsers solve CAPTCHAs for you automatically.
+
+## Further reading
+
+- [Prove you are a robot: CAPTCHAs for agents](https://browser-use.com/posts/prove-you-are-a-robot)
+- [Browser agent bot detection is about to change](https://browser-use.com/posts/bot-detection)

docs/cloud/browser/create.mdx

@@ -0,0 +1,99 @@
+---
+title: Create a browser session
+description: "Every way to start a cloud browser: SDK, REST, or a single WebSocket URL, with all parameters and the response schema."
+icon: plus
+---
+
+Three ways to create a session. All of them return a browser with stealth, CAPTCHA solving, and a residential proxy already on.
+
+## SDK
+
+<CodeGroup>
+```python Python
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+client = AsyncBrowserUse()
+browser = await client.browsers.create(proxy_country_code="us")
+print(browser.cdp_url)   # connect any CDP client here
+print(browser.live_url)  # watch the session in a browser tab
+```
+```typescript TypeScript
+import { BrowserUse } from "browser-use-sdk/v3";
+
+const client = new BrowserUse();
+const browser = await client.browsers.create({ proxyCountryCode: "us" });
+console.log(browser.cdpUrl);
+console.log(browser.liveUrl);
+```
+</CodeGroup>
+
+## REST
+
+```bash
+curl -X POST "https://api.browser-use.com/api/v3/browsers" \
+  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"proxyCountryCode": "us", "timeout": 60}'
+```
+
+## WebSocket URL (no SDK, no create call)
+
+Connect directly and the session is created for you. Configuration goes in query parameters, and the session stops when the socket disconnects.
+
+```text
+wss://connect.browser-use.com?apiKey=YOUR_API_KEY&proxyCountryCode=us
+```
+
+## Parameters
+
+All parameters are optional.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `profileId` | `string` (UUID) | — | Load a saved [profile](/cloud/guides/profile-sync) (cookies, localStorage) into the session. |
+| `proxyCountryCode` | `string` | `us` | Residential proxy country. Set to `null` to disable the proxy. |
+| `timeout` | `int` | `60` | Session lifetime in minutes, 1–240. The session stops automatically when it expires. |
+| `browserScreenWidth` | `int` | — | Screen width in pixels, 320–6144. |
+| `browserScreenHeight` | `int` | — | Screen height in pixels, 320–3456. |
+| `allowResizing` | `bool` | `false` | Allow window resizing during the session. Not recommended: resizing reduces stealth. |
+| `customProxy` | `object` | — | Bring your own proxy instead of ours. |
+| `enableRecording` | `bool` | `false` | Record the session. The video is available as `recordingUrl` after the session stops. |
+
+{/* TEAM REVIEW: the WSS connection path previously documented timeout default as 15 minutes; the v3 API spec says 60. Confirm which is correct per method and align the framework pages. */}
+
+## Response
+
+`201` with a browser session object:
+
+```json
+{
+  "id": "0d5f16f3-96cc-4d5f-a5a4-4a4d3b5f9d2e",
+  "status": "active",
+  "liveUrl": "https://live.browser-use.com?wss=...",
+  "cdpUrl": "https://0d5f16f3.cdp1.browser-use.com",
+  "timeoutAt": "2026-07-15T21:00:00Z",
+  "startedAt": "2026-07-15T20:00:00Z",
+  "finishedAt": null,
+  "proxyUsedMb": "0.0",
+  "proxyCost": "0.0",
+  "browserCost": "0.0",
+  "agentSessionId": null,
+  "recordingUrl": null
+}
+```
+
+Field names are camelCase in REST and TypeScript (`cdpUrl`, `liveUrl`), snake_case in Python (`cdp_url`, `live_url`). `cdpUrl` and `liveUrl` are nullable, check them before connecting.
+
+## Errors
+
+| Status | Meaning |
+|--------|---------|
+| `403` | Session timeout limit exceeded for your plan. |
+| `404` | The `profileId` doesn't exist. |
+| `422` | Invalid parameter value. |
+| `429` | Too many concurrent active sessions. Stop unused sessions or raise your limit. |
+
+## Next
+
+- Connect with [Playwright](/cloud/browser/playwright), [Puppeteer](/cloud/browser/puppeteer), or [Selenium](/cloud/browser/selenium)
+- [Manage the session](/cloud/browser/sessions): lifecycle, stopping, billing

docs/cloud/browser/open-source-agent.mdx

@@ -0,0 +1,56 @@
+---
+title: Cloud browser + open source agent
+description: "Run the open-source Browser Use agent on a cloud stealth browser. Your code, our infrastructure."
+icon: plug
+---
+
+The [open-source library](/open-source/introduction) runs the agent on your machine. By default it also runs the *browser* on your machine, which means no stealth, no residential proxy, and no CAPTCHA solving. This page connects the two: keep your local agent code, point it at a cloud browser.
+
+## Connect by CDP URL
+
+Create a cloud browser, then pass its CDP URL to the library's `Browser`:
+
+```python
+import asyncio
+from browser_use import Agent, Browser, ChatOpenAI
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+async def main():
+    client = AsyncBrowserUse()
+    cloud_browser = await client.browsers.create(proxy_country_code="us")
+
+    try:
+        agent = Agent(
+            task="Find the current price of iPhone 16 on amazon.de",
+            llm=ChatOpenAI(model="gpt-4o"),
+            browser=Browser(cdp_url=cloud_browser.cdp_url),
+        )
+        await agent.run()
+    finally:
+        await client.browsers.stop(cloud_browser.id)
+
+asyncio.run(main())
+```
+
+The agent behaves exactly as it does locally. The browser it drives is a [stealth Chromium](/cloud/browser/stealth) with [CAPTCHA solving](/cloud/browser/captcha) and a [residential proxy](/cloud/browser/proxies), and you can watch it work through the session's `live_url`.
+
+{/* TEAM REVIEW: confirm the `use_cloud=True` shorthand on Browser() — parameter name, minimum library version, and whether it should be the primary example instead of the cdp_url form. */}
+
+## What you get, what you keep
+
+| | Stays yours | Comes from Cloud |
+|---|---|---|
+| Agent loop, prompts, custom tools | ✓ | |
+| LLM choice and API keys | ✓ | |
+| Browser runtime | | ✓ stealth Chromium |
+| Proxy / IP | | ✓ residential, 195+ countries |
+| CAPTCHA handling | | ✓ automatic |
+| Live view and recording | | ✓ per session |
+
+Billing: only the browser session ($0.02/hour plus proxy data). Your LLM tokens go to your own provider.
+
+## Related
+
+- [Create a browser session](/cloud/browser/create) — all session parameters
+- [Open source vs Cloud](/cloud/open-source-vs-cloud) — the full decision guide
+- [Manage browser sessions](/cloud/browser/sessions) — always stop sessions when done

docs/cloud/browser/overview.mdx

@@ -0,0 +1,35 @@
+---
+title: Overview
+description: "Remote stealth browsers you control over CDP. What they are and when to use one."
+icon: globe
+---
+
+A Browser Use cloud browser is a real Chromium instance running on our infrastructure that your code controls remotely over the Chrome DevTools Protocol (CDP). Create one with an API call, get back a `cdpUrl`, and drive it with Playwright, Puppeteer, or any CDP client, the same way you'd drive a local browser.
+
+The difference from local Chromium is what's built in. Every session runs our [hardened Chromium fork](/cloud/browser/stealth) with anti-fingerprinting patches, [automatic CAPTCHA solving](/cloud/browser/captcha), and a [residential proxy](/cloud/browser/proxies) in your choice of 195+ countries. None of it needs configuration.
+
+## When to use a cloud browser
+
+- **Your Playwright/Puppeteer scripts get blocked.** Same code, but running on infrastructure that sites treat as a normal user.
+- **You don't want to run browsers.** No Chrome processes, no headless servers, no scaling browser pools.
+- **You're building your own agent.** Full CDP access means any framework or custom tooling works. You can also run the [open-source Browser Use agent on a cloud browser](/cloud/browser/open-source-agent).
+- **You need a watchable, recordable session.** Every session has a [live view](/cloud/browser/live-preview) you can open or embed, and optional recording.
+
+If you'd rather describe the task and let AI do the driving, use the [Agent](/cloud/agent/overview) instead. The two combine: agents run inside browser sessions, and you can connect your own code to the browser behind an agent run.
+
+## How it fits together
+
+1. [Create a browser session](/cloud/browser/create) — SDK, REST, or a single WebSocket URL
+2. Connect your framework — [Playwright](/cloud/browser/playwright), [Puppeteer](/cloud/browser/puppeteer), or [Selenium](/cloud/browser/selenium)
+3. Automate as usual — the session behaves like local Chromium with better manners from websites
+4. [Manage the session](/cloud/browser/sessions) — timeouts, stopping, what you're billed for
+
+## Logging into websites
+
+Sessions start clean by default. To carry login state across sessions, use [profiles / cookie sync](/cloud/guides/profile-sync), [authentication](/cloud/guides/authentication), and [2FA support](/cloud/guides/2fa).
+
+## Further reading
+
+- [Stealth Browser Infrastructure](https://browser-use.com/posts/browser-infra) — how the cloud browser is built
+- [Closer to the Metal: Leaving Playwright for CDP](https://browser-use.com/posts/playwright-to-cdp) — why the browser is driven over CDP
+- [We stealth benchmarked every major cloud browser provider](https://browser-use.com/posts/stealth-benchmark), and the [benchmark results](https://browser-use.com/benchmarks) (84.8% BrowserBench, 81% bypass on high-security sites)