diff --git a/docs/cli/browser.md b/docs/cli/browser.md
new file mode 100644
index 000000000..9c25d563f
--- /dev/null
+++ b/docs/cli/browser.md
@@ -0,0 +1,106 @@
+---
+summary: "CLI reference for `clawdbot browser` (profiles, tabs, actions, extension relay, remote serve)"
+read_when:
+  - You use `clawdbot browser` and want examples for common tasks
+  - You want to control a remote browser via `browser.controlUrl`
+  - You want to use the Chrome extension relay (attach/detach via toolbar button)
+---
+
+# `clawdbot browser`
+
+Manage Clawdbot’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks, typing).
+
+Related:
+- Browser tool + API: [Browser tool](/tools/browser)
+- Chrome extension relay: [Chrome extension](/tools/chrome-extension)
+
+## Common flags
+
+- `--url <controlUrl>`: override `browser.controlUrl` for this command invocation.
+- `--browser-profile <name>`: choose a browser profile (default comes from config).
+- `--json`: machine-readable output (where supported).
+
+## Quick start (local)
+
+```bash
+clawdbot browser status
+clawdbot browser start
+clawdbot browser tabs
+clawdbot browser open https://example.com
+clawdbot browser snapshot
+```
+
+## Profiles
+
+Profiles are named browser instances with their own data directory and CDP settings.
+
+```bash
+clawdbot browser profiles
+clawdbot browser create-profile --name work --color "#FF5A36"
+clawdbot browser delete-profile --name work
+```
+
+Use a specific profile:
+
+```bash
+clawdbot browser --browser-profile work tabs
+```
+
+## Tabs
+
+```bash
+clawdbot browser tabs
+clawdbot browser open https://docs.clawd.bot
+clawdbot browser focus <targetId>
+clawdbot browser close <targetId>
+```
+
+## Snapshot / screenshot / actions
+
+Snapshot:
+
+```bash
+clawdbot browser snapshot
+```
+
+Screenshot:
+
+```bash
+clawdbot browser screenshot
+```
+
+Navigate/click/type (ref-based UI automation):
+
+```bash
+clawdbot browser navigate https://example.com
+clawdbot browser click <ref>
+clawdbot browser type <ref> "hello"
+```
+
+## Chrome extension relay (attach via toolbar button)
+
+This mode lets the agent control an existing Chrome tab that you attach manually (it does not auto-attach).
+
+Install the unpacked extension to a stable path:
+
+```bash
+clawdbot browser extension install
+clawdbot browser extension path
+```
+
+Then Chrome → `chrome://extensions` → enable “Developer mode” → “Load unpacked” → select the printed folder.
+
+Full guide: [Chrome extension](/tools/chrome-extension)
+
+## Remote browser control (`clawdbot browser serve`)
+
+If the Gateway runs on a different machine than the browser, run a standalone browser control server on the machine that runs Chrome:
+
+```bash
+clawdbot browser serve --bind 127.0.0.1 --port 18791 --token <token>
+```
+
+Then point the Gateway at it using `browser.controlUrl` + `browser.controlToken` (or `CLAWDBOT_BROWSER_CONTROL_TOKEN`).
+
+Security + TLS best-practices: [Browser tool](/tools/browser), [Tailscale](/gateway/tailscale), [Security](/gateway/security)
+
diff --git a/docs/cli/index.md b/docs/cli/index.md
index a39f1a4bf..99866c619 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -748,7 +748,7 @@ Location:
 
 ## Browser
 
-Browser control CLI (dedicated Chrome/Chromium). See [/tools/browser](/tools/browser).
+Browser control CLI (dedicated Chrome/Chromium). See [`clawdbot browser`](/cli/browser) and the [Browser tool](/tools/browser).
 
 Common options:
 - `--url <controlUrl>`
diff --git a/docs/docs.json b/docs/docs.json
index 6a7a6ac53..f0168aa49 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -760,6 +760,7 @@
         "group": "CLI",
         "pages": [
           "cli/index",
+          "cli/browser",
           "cli/message",
           "cli/gateway",
           "cli/update",
diff --git a/src/cli/browser-cli.ts b/src/cli/browser-cli.ts
index 626163211..cfa97e602 100644
--- a/src/cli/browser-cli.ts
+++ b/src/cli/browser-cli.ts
@@ -26,8 +26,8 @@ export function registerBrowserCli(program: Command) {
       "after",
       () =>
         `\nExamples:\n  ${[...browserCoreExamples, ...browserActionExamples].join("\n  ")}\n\n${theme.muted("Docs:")} ${formatDocsLink(
-          "/tools/browser",
-          "docs.clawd.bot/tools/browser",
+          "/cli/browser",
+          "docs.clawd.bot/cli/browser",
         )}\n`,
     )
     .action(() => {