@quantumclaw/quantumclaw 2026.3.22

package/docs/tools/browser.md

@@ -0,0 +1,731 @@
+---
+summary: "Integrated browser control service + action commands"
+read_when:
+  - Adding agent-controlled browser automation
+  - Debugging why quantumclaw is interfering with your own Chrome
+  - Implementing browser settings + lifecycle in the macOS app
+title: "Browser (QuantumClaw-managed)"
+---
+
+# Browser (quantumclaw-managed)
+
+QuantumClaw can run a **dedicated Chrome/Brave/Edge/Chromium profile** that the agent controls.
+It is isolated from your personal browser and is managed through a small local
+control service inside the Gateway (loopback only).
+
+Beginner view:
+
+- Think of it as a **separate, agent-only browser**.
+- The `quantumclaw` profile does **not** touch your personal browser profile.
+- The agent can **open tabs, read pages, click, and type** in a safe lane.
+- The built-in `user` profile attaches to your real signed-in Chrome session via Chrome MCP.
+
+## What you get
+
+- A separate browser profile named **quantumclaw** (orange accent by default).
+- Deterministic tab control (list/open/focus/close).
+- Agent actions (click/type/drag/select), snapshots, screenshots, PDFs.
+- Optional multi-profile support (`quantumclaw`, `work`, `remote`, ...).
+
+This browser is **not** your daily driver. It is a safe, isolated surface for
+agent automation and verification.
+
+## Quick start
+
+```bash
+quantumclaw browser --browser-profile quantumclaw status
+quantumclaw browser --browser-profile quantumclaw start
+quantumclaw browser --browser-profile quantumclaw open https://example.com
+quantumclaw browser --browser-profile quantumclaw snapshot
+```
+
+If you get “Browser disabled”, enable it in config (see below) and restart the
+Gateway.
+
+## Profiles: `quantumclaw` vs `user`
+
+- `quantumclaw`: managed, isolated browser (no extension required).
+- `user`: built-in Chrome MCP attach profile for your **real signed-in Chrome**
+  session.
+
+For agent browser tool calls:
+
+- Default: use the isolated `quantumclaw` browser.
+- Prefer `profile="user"` when existing logged-in sessions matter and the user
+  is at the computer to click/approve any attach prompt.
+- `profile` is the explicit override when you want a specific browser mode.
+
+Set `browser.defaultProfile: "quantumclaw"` if you want managed mode by default.
+
+## Configuration
+
+Browser settings live in `~/.quantumclaw/quantumclaw.json`.
+
+```json5
+{
+  browser: {
+    enabled: true, // default: true
+    ssrfPolicy: {
+      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
+      // allowPrivateNetwork: true, // legacy alias
+      // hostnameAllowlist: ["*.example.com", "example.com"],
+      // allowedHostnames: ["localhost"],
+    },
+    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
+    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
+    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
+    defaultProfile: "quantumclaw",
+    color: "#FF4500",
+    headless: false,
+    noSandbox: false,
+    attachOnly: false,
+    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    profiles: {
+      quantumclaw: { cdpPort: 18800, color: "#FF4500" },
+      work: { cdpPort: 18801, color: "#0066CC" },
+      user: {
+        driver: "existing-session",
+        attachOnly: true,
+        color: "#00AA00",
+      },
+      brave: {
+        driver: "existing-session",
+        attachOnly: true,
+        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
+        color: "#FB542B",
+      },
+      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
+    },
+  },
+}
+```
+
+Notes:
+
+- The browser control service binds to loopback on a port derived from `gateway.port`
+  (default: `18791`, which is gateway + 2).
+- If you override the Gateway port (`gateway.port` or `QUANTUMCLAW_GATEWAY_PORT`),
+  the derived browser ports shift to stay in the same “family”.
+- `cdpUrl` defaults to the managed local CDP port when unset.
+- `remoteCdpTimeoutMs` applies to remote (non-loopback) CDP reachability checks.
+- `remoteCdpHandshakeTimeoutMs` applies to remote CDP WebSocket reachability checks.
+- Browser navigation/open-tab is SSRF-guarded before navigation and best-effort re-checked on final `http(s)` URL after navigation.
+- In strict SSRF mode, remote CDP endpoint discovery/probes (`cdpUrl`, including `/json/version` lookups) are checked too.
+- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` defaults to `true` (trusted-network model). Set it to `false` for strict public-only browsing.
+- `browser.ssrfPolicy.allowPrivateNetwork` remains supported as a legacy alias for compatibility.
+- `attachOnly: true` means “never launch a local browser; only attach if it is already running.”
+- `color` + per-profile `color` tint the browser UI so you can see which profile is active.
+- Default profile is `quantumclaw` (QuantumClaw-managed standalone browser). Use `defaultProfile: "user"` to opt into the signed-in user browser.
+- Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
+- Local `quantumclaw` profiles auto-assign `cdpPort`/`cdpUrl` — set those only for remote CDP.
+- `driver: "existing-session"` uses Chrome DevTools MCP instead of raw CDP. Do
+  not set `cdpUrl` for that driver.
+- Set `browser.profiles.<name>.userDataDir` when an existing-session profile
+  should attach to a non-default Chromium user profile such as Brave or Edge.
+
+## Use Brave (or another Chromium-based browser)
+
+If your **system default** browser is Chromium-based (Chrome/Brave/Edge/etc),
+QuantumClaw uses it automatically. Set `browser.executablePath` to override
+auto-detection:
+
+CLI example:
+
+```bash
+quantumclaw config set browser.executablePath "/usr/bin/google-chrome"
+```
+
+```json5
+// macOS
+{
+  browser: {
+    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+  }
+}
+
+// Windows
+{
+  browser: {
+    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
+  }
+}
+
+// Linux
+{
+  browser: {
+    executablePath: "/usr/bin/brave-browser"
+  }
+}
+```
+
+## Local vs remote control
+
+- **Local control (default):** the Gateway starts the loopback control service and can launch a local browser.
+- **Remote control (node host):** run a node host on the machine that has the browser; the Gateway proxies browser actions to it.
+- **Remote CDP:** set `browser.profiles.<name>.cdpUrl` (or `browser.cdpUrl`) to
+  attach to a remote Chromium-based browser. In this case, QuantumClaw will not launch a local browser.
+
+Remote CDP URLs can include auth:
+
+- Query tokens (e.g., `https://provider.example?token=<token>`)
+- HTTP Basic auth (e.g., `https://user:pass@provider.example`)
+
+QuantumClaw preserves the auth when calling `/json/*` endpoints and when connecting
+to the CDP WebSocket. Prefer environment variables or secrets managers for
+tokens instead of committing them to config files.
+
+## Node browser proxy (zero-config default)
+
+If you run a **node host** on the machine that has your browser, QuantumClaw can
+auto-route browser tool calls to that node without any extra browser config.
+This is the default path for remote gateways.
+
+Notes:
+
+- The node host exposes its local browser control server via a **proxy command**.
+- Profiles come from the node’s own `browser.profiles` config (same as local).
+- Disable if you don’t want it:
+  - On the node: `nodeHost.browserProxy.enabled=false`
+  - On the gateway: `gateway.nodes.browser.mode="off"`
+
+## Browserless (hosted remote CDP)
+
+[Browserless](https://browserless.io) is a hosted Chromium service that exposes
+CDP endpoints over HTTPS. You can point an QuantumClaw browser profile at a
+Browserless region endpoint and authenticate with your API key.
+
+Example:
+
+```json5
+{
+  browser: {
+    enabled: true,
+    defaultProfile: "browserless",
+    remoteCdpTimeoutMs: 2000,
+    remoteCdpHandshakeTimeoutMs: 4000,
+    profiles: {
+      browserless: {
+        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
+        color: "#00AA00",
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- Replace `<BROWSERLESS_API_KEY>` with your real Browserless token.
+- Choose the region endpoint that matches your Browserless account (see their docs).
+
+## Direct WebSocket CDP providers
+
+Some hosted browser services expose a **direct WebSocket** endpoint rather than
+the standard HTTP-based CDP discovery (`/json/version`). QuantumClaw supports both:
+
+- **HTTP(S) endpoints** (e.g. Browserless) — QuantumClaw calls `/json/version` to
+  discover the WebSocket debugger URL, then connects.
+- **WebSocket endpoints** (`ws://` / `wss://`) — QuantumClaw connects directly,
+  skipping `/json/version`. Use this for services like
+  [Browserbase](https://www.browserbase.com) or any provider that hands you a
+  WebSocket URL.
+
+### Browserbase
+
+[Browserbase](https://www.browserbase.com) is a cloud platform for running
+headless browsers with built-in CAPTCHA solving, stealth mode, and residential
+proxies.
+
+```json5
+{
+  browser: {
+    enabled: true,
+    defaultProfile: "browserbase",
+    remoteCdpTimeoutMs: 3000,
+    remoteCdpHandshakeTimeoutMs: 5000,
+    profiles: {
+      browserbase: {
+        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
+        color: "#F97316",
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- [Sign up](https://www.browserbase.com/sign-up) and copy your **API Key**
+  from the [Overview dashboard](https://www.browserbase.com/overview).
+- Replace `<BROWSERBASE_API_KEY>` with your real Browserbase API key.
+- Browserbase auto-creates a browser session on WebSocket connect, so no
+  manual session creation step is needed.
+- The free tier allows one concurrent session and one browser hour per month.
+  See [pricing](https://www.browserbase.com/pricing) for paid plan limits.
+- See the [Browserbase docs](https://docs.browserbase.com) for full API
+  reference, SDK guides, and integration examples.
+
+## Security
+
+Key ideas:
+
+- Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.
+- If browser control is enabled and no auth is configured, QuantumClaw auto-generates `gateway.auth.token` on startup and persists it to config.
+- Keep the Gateway and any node hosts on a private network (Tailscale); avoid public exposure.
+- Treat remote CDP URLs/tokens as secrets; prefer env vars or a secrets manager.
+
+Remote CDP tips:
+
+- Prefer encrypted endpoints (HTTPS or WSS) and short-lived tokens where possible.
+- Avoid embedding long-lived tokens directly in config files.
+
+## Profiles (multi-browser)
+
+QuantumClaw supports multiple named profiles (routing configs). Profiles can be:
+
+- **quantumclaw-managed**: a dedicated Chromium-based browser instance with its own user data directory + CDP port
+- **remote**: an explicit CDP URL (Chromium-based browser running elsewhere)
+- **existing session**: your existing Chrome profile via Chrome DevTools MCP auto-connect
+
+Defaults:
+
+- The `quantumclaw` profile is auto-created if missing.
+- The `user` profile is built-in for Chrome MCP existing-session attach.
+- Existing-session profiles are opt-in beyond `user`; create them with `--driver existing-session`.
+- Local CDP ports allocate from **18800–18899** by default.
+- Deleting a profile moves its local data directory to Trash.
+
+All control endpoints accept `?profile=<name>`; the CLI uses `--browser-profile`.
+
+## Existing-session via Chrome DevTools MCP
+
+QuantumClaw can also attach to a running Chromium-based browser profile through the
+official Chrome DevTools MCP server. This reuses the tabs and login state
+already open in that browser profile.
+
+Official background and setup references:
+
+- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
+- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
+
+Built-in profile:
+
+- `user`
+
+Optional: create your own custom existing-session profile if you want a
+different name, color, or browser data directory.
+
+Default behavior:
+
+- The built-in `user` profile uses Chrome MCP auto-connect, which targets the
+  default local Google Chrome profile.
+
+Use `userDataDir` for Brave, Edge, Chromium, or a non-default Chrome profile:
+
+```json5
+{
+  browser: {
+    profiles: {
+      brave: {
+        driver: "existing-session",
+        attachOnly: true,
+        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
+        color: "#FB542B",
+      },
+    },
+  },
+}
+```
+
+Then in the matching browser:
+
+1. Open that browser's inspect page for remote debugging.
+2. Enable remote debugging.
+3. Keep the browser running and approve the connection prompt when QuantumClaw attaches.
+
+Common inspect pages:
+
+- Chrome: `chrome://inspect/#remote-debugging`
+- Brave: `brave://inspect/#remote-debugging`
+- Edge: `edge://inspect/#remote-debugging`
+
+Live attach smoke test:
+
+```bash
+quantumclaw browser --browser-profile user start
+quantumclaw browser --browser-profile user status
+quantumclaw browser --browser-profile user tabs
+quantumclaw browser --browser-profile user snapshot --format ai
+```
+
+What success looks like:
+
+- `status` shows `driver: existing-session`
+- `status` shows `transport: chrome-mcp`
+- `status` shows `running: true`
+- `tabs` lists your already-open browser tabs
+- `snapshot` returns refs from the selected live tab
+
+What to check if attach does not work:
+
+- the target Chromium-based browser is version `144+`
+- remote debugging is enabled in that browser's inspect page
+- the browser showed and you accepted the attach consent prompt
+- `quantumclaw doctor` migrates old extension-based browser config and checks that
+  Chrome is installed locally for default auto-connect profiles, but it cannot
+  enable browser-side remote debugging for you
+
+Agent use:
+
+- Use `profile="user"` when you need the user’s logged-in browser state.
+- If you use a custom existing-session profile, pass that explicit profile name.
+- Only choose this mode when the user is at the computer to approve the attach
+  prompt.
+- the Gateway or node host can spawn `npx chrome-devtools-mcp@latest --autoConnect`
+
+Notes:
+
+- This path is higher-risk than the isolated `quantumclaw` profile because it can
+  act inside your signed-in browser session.
+- QuantumClaw does not launch the browser for this driver; it attaches to an
+  existing session only.
+- QuantumClaw uses the official Chrome DevTools MCP `--autoConnect` flow here. If
+  `userDataDir` is set, QuantumClaw passes it through to target that explicit
+  Chromium user data directory.
+- Existing-session screenshots support page captures and `--ref` element
+  captures from snapshots, but not CSS `--element` selectors.
+- Existing-session `wait --url` supports exact, substring, and glob patterns
+  like other browser drivers. `wait --load networkidle` is not supported yet.
+- Some features still require the managed browser path, such as PDF export and
+  download interception.
+- Existing-session is host-local. If Chrome lives on a different machine or a
+  different network namespace, use remote CDP or a node host instead.
+
+## Isolation guarantees
+
+- **Dedicated user data dir**: never touches your personal browser profile.
+- **Dedicated ports**: avoids `9222` to prevent collisions with dev workflows.
+- **Deterministic tab control**: target tabs by `targetId`, not “last tab”.
+
+## Browser selection
+
+When launching locally, QuantumClaw picks the first available:
+
+1. Chrome
+2. Brave
+3. Edge
+4. Chromium
+5. Chrome Canary
+
+You can override with `browser.executablePath`.
+
+Platforms:
+
+- macOS: checks `/Applications` and `~/Applications`.
+- Linux: looks for `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.
+- Windows: checks common install locations.
+
+## Control API (optional)
+
+For local integrations only, the Gateway exposes a small loopback HTTP API:
+
+- Status/start/stop: `GET /`, `POST /start`, `POST /stop`
+- Tabs: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
+- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot`
+- Actions: `POST /navigate`, `POST /act`
+- Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog`
+- Downloads: `POST /download`, `POST /wait/download`
+- Debugging: `GET /console`, `POST /pdf`
+- Debugging: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight`
+- Network: `POST /response/body`
+- State: `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear`
+- State: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear`
+- Settings: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device`
+
+All endpoints accept `?profile=<name>`.
+
+If gateway auth is configured, browser HTTP routes require auth too:
+
+- `Authorization: Bearer <gateway token>`
+- `x-quantumclaw-password: <gateway password>` or HTTP Basic auth with that password
+
+### Playwright requirement
+
+Some features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require
+Playwright. If Playwright isn’t installed, those endpoints return a clear 501
+error. ARIA snapshots and basic screenshots still work for quantumclaw-managed Chrome.
+
+If you see `Playwright is not available in this gateway build`, install the full
+Playwright package (not `playwright-core`) and restart the gateway, or reinstall
+QuantumClaw with browser support.
+
+#### Docker Playwright install
+
+If your Gateway runs in Docker, avoid `npx playwright` (npm override conflicts).
+Use the bundled CLI instead:
+
+```bash
+docker compose run --rm quantumclaw-cli \
+  node /app/node_modules/playwright-core/cli.js install chromium
+```
+
+To persist browser downloads, set `PLAYWRIGHT_BROWSERS_PATH` (for example,
+`/home/node/.cache/ms-playwright`) and make sure `/home/node` is persisted via
+`QUANTUMCLAW_HOME_VOLUME` or a bind mount. See [Docker](/install/docker).
+
+## How it works (internal)
+
+High-level flow:
+
+- A small **control server** accepts HTTP requests.
+- It connects to Chromium-based browsers (Chrome/Brave/Edge/Chromium) via **CDP**.
+- For advanced actions (click/type/snapshot/PDF), it uses **Playwright** on top
+  of CDP.
+- When Playwright is missing, only non-Playwright operations are available.
+
+This design keeps the agent on a stable, deterministic interface while letting
+you swap local/remote browsers and profiles.
+
+## CLI quick reference
+
+All commands accept `--browser-profile <name>` to target a specific profile.
+All commands also accept `--json` for machine-readable output (stable payloads).
+
+Basics:
+
+- `quantumclaw browser status`
+- `quantumclaw browser start`
+- `quantumclaw browser stop`
+- `quantumclaw browser tabs`
+- `quantumclaw browser tab`
+- `quantumclaw browser tab new`
+- `quantumclaw browser tab select 2`
+- `quantumclaw browser tab close 2`
+- `quantumclaw browser open https://example.com`
+- `quantumclaw browser focus abcd1234`
+- `quantumclaw browser close abcd1234`
+
+Inspection:
+
+- `quantumclaw browser screenshot`
+- `quantumclaw browser screenshot --full-page`
+- `quantumclaw browser screenshot --ref 12`
+- `quantumclaw browser screenshot --ref e12`
+- `quantumclaw browser snapshot`
+- `quantumclaw browser snapshot --format aria --limit 200`
+- `quantumclaw browser snapshot --interactive --compact --depth 6`
+- `quantumclaw browser snapshot --efficient`
+- `quantumclaw browser snapshot --labels`
+- `quantumclaw browser snapshot --selector "#main" --interactive`
+- `quantumclaw browser snapshot --frame "iframe#main" --interactive`
+- `quantumclaw browser console --level error`
+- `quantumclaw browser errors --clear`
+- `quantumclaw browser requests --filter api --clear`
+- `quantumclaw browser pdf`
+- `quantumclaw browser responsebody "**/api" --max-chars 5000`
+
+Actions:
+
+- `quantumclaw browser navigate https://example.com`
+- `quantumclaw browser resize 1280 720`
+- `quantumclaw browser click 12 --double`
+- `quantumclaw browser click e12 --double`
+- `quantumclaw browser type 23 "hello" --submit`
+- `quantumclaw browser press Enter`
+- `quantumclaw browser hover 44`
+- `quantumclaw browser scrollintoview e12`
+- `quantumclaw browser drag 10 11`
+- `quantumclaw browser select 9 OptionA OptionB`
+- `quantumclaw browser download e12 report.pdf`
+- `quantumclaw browser waitfordownload report.pdf`
+- `quantumclaw browser upload /tmp/quantumclaw/uploads/file.pdf`
+- `quantumclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'`
+- `quantumclaw browser dialog --accept`
+- `quantumclaw browser wait --text "Done"`
+- `quantumclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"`
+- `quantumclaw browser evaluate --fn '(el) => el.textContent' --ref 7`
+- `quantumclaw browser highlight e12`
+- `quantumclaw browser trace start`
+- `quantumclaw browser trace stop`
+
+State:
+
+- `quantumclaw browser cookies`
+- `quantumclaw browser cookies set session abc123 --url "https://example.com"`
+- `quantumclaw browser cookies clear`
+- `quantumclaw browser storage local get`
+- `quantumclaw browser storage local set theme dark`
+- `quantumclaw browser storage session clear`
+- `quantumclaw browser set offline on`
+- `quantumclaw browser set headers --headers-json '{"X-Debug":"1"}'`
+- `quantumclaw browser set credentials user pass`
+- `quantumclaw browser set credentials --clear`
+- `quantumclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"`
+- `quantumclaw browser set geo --clear`
+- `quantumclaw browser set media dark`
+- `quantumclaw browser set timezone America/New_York`
+- `quantumclaw browser set locale en-US`
+- `quantumclaw browser set device "iPhone 14"`
+
+Notes:
+
+- `upload` and `dialog` are **arming** calls; run them before the click/press
+  that triggers the chooser/dialog.
+- Download and trace output paths are constrained to QuantumClaw temp roots:
+  - traces: `/tmp/quantumclaw` (fallback: `${os.tmpdir()}/quantumclaw`)
+  - downloads: `/tmp/quantumclaw/downloads` (fallback: `${os.tmpdir()}/quantumclaw/downloads`)
+- Upload paths are constrained to an QuantumClaw temp uploads root:
+  - uploads: `/tmp/quantumclaw/uploads` (fallback: `${os.tmpdir()}/quantumclaw/uploads`)
+- `upload` can also set file inputs directly via `--input-ref` or `--element`.
+- `snapshot`:
+  - `--format ai` (default when Playwright is installed): returns an AI snapshot with numeric refs (`aria-ref="<n>"`).
+  - `--format aria`: returns the accessibility tree (no refs; inspection only).
+  - `--efficient` (or `--mode efficient`): compact role snapshot preset (interactive + compact + depth + lower maxChars).
+  - Config default (tool/CLI only): set `browser.snapshotDefaults.mode: "efficient"` to use efficient snapshots when the caller does not pass a mode (see [Gateway configuration](/gateway/configuration-reference#browser)).
+  - Role snapshot options (`--interactive`, `--compact`, `--depth`, `--selector`) force a role-based snapshot with refs like `ref=e12`.
+  - `--frame "<iframe selector>"` scopes role snapshots to an iframe (pairs with role refs like `e12`).
+  - `--interactive` outputs a flat, easy-to-pick list of interactive elements (best for driving actions).
+  - `--labels` adds a viewport-only screenshot with overlayed ref labels (prints `MEDIA:<path>`).
+- `click`/`type`/etc require a `ref` from `snapshot` (either numeric `12` or role ref `e12`).
+  CSS selectors are intentionally not supported for actions.
+
+## Snapshots and refs
+
+QuantumClaw supports two “snapshot” styles:
+
+- **AI snapshot (numeric refs)**: `quantumclaw browser snapshot` (default; `--format ai`)
+  - Output: a text snapshot that includes numeric refs.
+  - Actions: `quantumclaw browser click 12`, `quantumclaw browser type 23 "hello"`.
+  - Internally, the ref is resolved via Playwright’s `aria-ref`.
+
+- **Role snapshot (role refs like `e12`)**: `quantumclaw browser snapshot --interactive` (or `--compact`, `--depth`, `--selector`, `--frame`)
+  - Output: a role-based list/tree with `[ref=e12]` (and optional `[nth=1]`).
+  - Actions: `quantumclaw browser click e12`, `quantumclaw browser highlight e12`.
+  - Internally, the ref is resolved via `getByRole(...)` (plus `nth()` for duplicates).
+  - Add `--labels` to include a viewport screenshot with overlayed `e12` labels.
+
+Ref behavior:
+
+- Refs are **not stable across navigations**; if something fails, re-run `snapshot` and use a fresh ref.
+- If the role snapshot was taken with `--frame`, role refs are scoped to that iframe until the next role snapshot.
+
+## Wait power-ups
+
+You can wait on more than just time/text:
+
+- Wait for URL (globs supported by Playwright):
+  - `quantumclaw browser wait --url "**/dash"`
+- Wait for load state:
+  - `quantumclaw browser wait --load networkidle`
+- Wait for a JS predicate:
+  - `quantumclaw browser wait --fn "window.ready===true"`
+- Wait for a selector to become visible:
+  - `quantumclaw browser wait "#main"`
+
+These can be combined:
+
+```bash
+quantumclaw browser wait "#main" \
+  --url "**/dash" \
+  --load networkidle \
+  --fn "window.ready===true" \
+  --timeout-ms 15000
+```
+
+## Debug workflows
+
+When an action fails (e.g. “not visible”, “strict mode violation”, “covered”):
+
+1. `quantumclaw browser snapshot --interactive`
+2. Use `click <ref>` / `type <ref>` (prefer role refs in interactive mode)
+3. If it still fails: `quantumclaw browser highlight <ref>` to see what Playwright is targeting
+4. If the page behaves oddly:
+   - `quantumclaw browser errors --clear`
+   - `quantumclaw browser requests --filter api --clear`
+5. For deep debugging: record a trace:
+   - `quantumclaw browser trace start`
+   - reproduce the issue
+   - `quantumclaw browser trace stop` (prints `TRACE:<path>`)
+
+## JSON output
+
+`--json` is for scripting and structured tooling.
+
+Examples:
+
+```bash
+quantumclaw browser status --json
+quantumclaw browser snapshot --interactive --json
+quantumclaw browser requests --filter api --json
+quantumclaw browser cookies --json
+```
+
+Role snapshots in JSON include `refs` plus a small `stats` block (lines/chars/refs/interactive) so tools can reason about payload size and density.
+
+## State and environment knobs
+
+These are useful for “make the site behave like X” workflows:
+
+- Cookies: `cookies`, `cookies set`, `cookies clear`
+- Storage: `storage local|session get|set|clear`
+- Offline: `set offline on|off`
+- Headers: `set headers --headers-json '{"X-Debug":"1"}'` (legacy `set headers --json '{"X-Debug":"1"}'` remains supported)
+- HTTP basic auth: `set credentials user pass` (or `--clear`)
+- Geolocation: `set geo <lat> <lon> --origin "https://example.com"` (or `--clear`)
+- Media: `set media dark|light|no-preference|none`
+- Timezone / locale: `set timezone ...`, `set locale ...`
+- Device / viewport:
+  - `set device "iPhone 14"` (Playwright device presets)
+  - `set viewport 1280 720`
+
+## Security & privacy
+
+- The quantumclaw browser profile may contain logged-in sessions; treat it as sensitive.
+- `browser act kind=evaluate` / `quantumclaw browser evaluate` and `wait --fn`
+  execute arbitrary JavaScript in the page context. Prompt injection can steer
+  this. Disable it with `browser.evaluateEnabled=false` if you do not need it.
+- For logins and anti-bot notes (X/Twitter, etc.), see [Browser login + X/Twitter posting](/tools/browser-login).
+- Keep the Gateway/node host private (loopback or tailnet-only).
+- Remote CDP endpoints are powerful; tunnel and protect them.
+
+Strict-mode example (block private/internal destinations by default):
+
+```json5
+{
+  browser: {
+    ssrfPolicy: {
+      dangerouslyAllowPrivateNetwork: false,
+      hostnameAllowlist: ["*.example.com", "example.com"],
+      allowedHostnames: ["localhost"], // optional exact allow
+    },
+  },
+}
+```
+
+## Troubleshooting
+
+For Linux-specific issues (especially snap Chromium), see
+[Browser troubleshooting](/tools/browser-linux-troubleshooting).
+
+For WSL2 Gateway + Windows Chrome split-host setups, see
+[WSL2 + Windows + remote Chrome CDP troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
+
+## Agent tools + how control works
+
+The agent gets **one tool** for browser automation:
+
+- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
+
+How it maps:
+
+- `browser snapshot` returns a stable UI tree (AI or ARIA).
+- `browser act` uses the snapshot `ref` IDs to click/type/drag/select.
+- `browser screenshot` captures pixels (full page or element).
+- `browser` accepts:
+  - `profile` to choose a named browser profile (quantumclaw, chrome, or remote CDP).
+  - `target` (`sandbox` | `host` | `node`) to select where the browser lives.
+  - In sandboxed sessions, `target: "host"` requires `agents.defaults.sandbox.browser.allowHostControl=true`.
+  - If `target` is omitted: sandboxed sessions default to `sandbox`, non-sandbox sessions default to `host`.
+  - If a browser-capable node is connected, the tool may auto-route to it unless you pin `target="host"` or `target="node"`.
+
+This keeps the agent deterministic and avoids brittle selectors.