@flrande/browserctl 0.1.0 → 0.2.0-dev.9.1

package/README.md

@@ -2,1154 +2,65 @@
 
 English | [简体中文](README-CN.md)
 
-Universal browser control CLI + daemon with MCP-style tool routing.
+Fastest path: control your current Edge/Chrome through the relay extension.
 
-## What This CLI Does
-
-`browserctl` is a TCP client for `browserd`.
-
-1. It parses command arguments.
-2. It sends tool calls to `browserd`.
-3. If the daemon is not reachable, it auto-starts `browserd` and retries once.
-
-The root package also publishes:
-
-- `browserctl` -> `bin/browserctl.cjs`
-- `browserd` -> `bin/browserd.cjs`
-
-## Quick Start
+## Extension Quick Start (Recommended)
 
 Prerequisites:
 
 - Node.js 22+
-- pnpm
+- npm or pnpm
 - PowerShell 7 (`pwsh`)
+- Edge or Chrome
 
-Minimum setup (first run, ~2 minutes):
-
-```powershell
-pnpm install
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json
-```
-
-Full repository checks (recommended before you contribute code):
-
-```powershell
-pnpm lint
-pnpm typecheck
-pnpm run test:all
-pnpm build
-pwsh -NoLogo -NoProfile -File .\scripts\smoke.ps1
-```
-
-Start daemon in persistent TCP mode:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-status --json
-```
-
-Change daemon port for current shell:
-
-```powershell
-$env:BROWSERCTL_DAEMON_PORT = "42491"
-```
-
-## Release Workflow
-
-Use this checklist before pushing a release tag:
-
-```powershell
-pnpm lint
-pnpm typecheck
-pnpm run test:all
-pnpm build
-pwsh -NoLogo -NoProfile -File .\scripts\smoke.ps1
-```
-
-Tag publish flow:
+1. Install the released package:
 
 ```powershell
-$version = node -p "require('./package.json').version"
-git tag "v$version"
-git push origin "v$version"
+npm install --global @flrande/browserctl
+# or: pnpm add --global @flrande/browserctl
 ```
 
-Notes:
-
-- `publish.yml` runs a cross-platform verify matrix before publish.
-- Publish job uploads dry-run and npm dist-tag artifacts for traceability.
-- Manual publish (`workflow_dispatch`) supports `dry_run` and `dist_tag`.
-
-## Start Here (Beginner Guide)
-
-If you are new, use this order:
-
-1. Run the minimum setup once.
-2. Start with Path A (`managed-local`, recommended).
-3. Use Path B (`chrome-relay`) only when you need to control your already-open browser.
-
-### Path A: Control a New Local Browser (Recommended)
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session demo --profile managed-local
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session demo --profile managed-local https://example.com
-pnpm exec tsx .\apps\browserctl\src\main.ts tabs --json --session demo --profile managed-local
-```
-
-Optional snapshot in PowerShell:
-
-```powershell
-$tabs = pnpm exec tsx .\apps\browserctl\src\main.ts tabs --json --session demo --profile managed-local | ConvertFrom-Json
-$targetId = $tabs.data.tabs[0]
-pnpm exec tsx .\apps\browserctl\src\main.ts snapshot --json --session demo --profile managed-local $targetId
-pnpm exec tsx .\apps\browserctl\src\main.ts screenshot --json --session demo --profile managed-local $targetId
-```
-
-### Path B: Control Your Current Edge/Chrome (Extension Relay)
-
-1. Configure daemon for extension relay:
+2. Start daemon in extension relay mode:
 
 ```powershell
 $env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
 $env:BROWSERD_CHROME_RELAY_MODE = "extension"
 $env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
 $env:BROWSERD_CHROME_RELAY_EXTENSION_TOKEN = "relay-secret"
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json
-```
-
-2. In `edge://extensions` or `chrome://extensions`, enable Developer mode and load unpacked extension from `extensions/chrome-relay`.
-3. Open extension popup, set `Bridge URL` to `ws://127.0.0.1:9223/bridge`, set the same token (`relay-secret`), click Save, then Reconnect.
-4. Verify connection:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session relay --profile chrome-relay
-```
-
-Expected signal: `status.data.status.connected = true`.
-
-### Quick Failure Checks
-
-If commands fail, run these first:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-status --json
-Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:9223/browserctl/relay/status" -TimeoutSec 3
-```
-
-If relay status says `connected: false`, re-open extension popup and click Reconnect.
-
-## Extended Read/Control APIs
-
-The CLI now includes additional browser reading/control commands:
-
-```text
-dom-query <targetId> <selector>
-dom-query-all <targetId> <selector>
-element-screenshot <targetId> <selector>
-a11y-snapshot <targetId> [selector]
-network-wait-for <targetId> <urlPattern> [--method <METHOD>] [--status <CODE>] [--timeout-ms <ms>] [--poll-ms <ms>]
-cookie-get <targetId> [name]
-cookie-set <targetId> <name> <value> [url]
-cookie-clear <targetId> [name]
-storage-get <targetId> <local|session> <key>
-storage-set <targetId> <local|session> <key> <value>
-frame-list <targetId>
-frame-snapshot <targetId> <frameId>
-```
-
-Example:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts dom-query --json --session demo $targetId "article h1"
-pnpm exec tsx .\apps\browserctl\src\main.ts element-screenshot --json --session demo $targetId "#main"
-pnpm exec tsx .\apps\browserctl\src\main.ts network-wait-for --json --session demo $targetId "/api/items" --method GET --status 200 --timeout-ms 15000
-pnpm exec tsx .\apps\browserctl\src\main.ts cookie-get --json --session demo $targetId
-pnpm exec tsx .\apps\browserctl\src\main.ts storage-set --json --session demo $targetId local theme dark
-pnpm exec tsx .\apps\browserctl\src\main.ts frame-list --json --session demo $targetId
-```
-
-## Global Command Model
-
-Syntax:
-
-```text
-browserctl [--json] <command> [command-options] [positionals]
-```
-
-Global options handled by command context:
-
-- `--session <id>`: session namespace, default `cli:local`
-- `--profile <driverKey>`: driver key override (`managed`, `managed-local`, `chrome-relay`, `remote-cdp`)
-- `--token <authToken>`: auth token override
-- `--browser <preset>`: startup browser preset (`chromium`, `chrome`, `edge`)
-
-Notes:
-
-- `--json` is consumed globally and controls envelope output.
-- Unknown flags are not validated as option schema; they may be treated as positional tokens.
-- `--browser` affects daemon startup only. If daemon is already running, it does not hot-reconfigure the existing process.
-
-## Core Concepts
-
-## Session Namespace (`--session`)
-
-A session namespace is the `sessionId` used by daemon-side session store.
-
-1. Daemon tracks per-session state such as current `profile` (driver key) and current `targetId`.
-2. Default is `cli:local`; override with `--session <id>`.
-3. Different session IDs isolate control context from each other.
-4. This is context isolation, not security isolation.
-5. Session state is in-memory and resets when daemon restarts.
-
-## Auth Token (`--token`, `BROWSERD_AUTH_TOKEN`)
-
-Auth token is a shared secret string used for request authentication.
-
-1. If daemon sets `BROWSERD_AUTH_TOKEN`, each tool call must include matching `authToken`.
-2. CLI forwards token from `--token` or `BROWSERCTL_AUTH_TOKEN`.
-3. Missing or mismatched token returns `E_PERMISSION: Invalid auth token.`.
-4. Token controls authentication; operation scope is separately limited by `BROWSERD_AUTH_SCOPES`.
-
-## Browser Presets (`--browser`)
-
-Browser preset controls managed-local startup channel selection.
-
-1. `chromium`: `browserName=chromium` with no channel override.
-2. `chrome`: `browserName=chromium`, `channel=chrome`.
-3. `edge`: `browserName=chromium`, `channel=msedge`.
-4. Presets do not affect `chrome-relay` or `remote-cdp`.
-5. Presets apply when daemon starts. If daemon is already running, restart daemon to switch preset.
-
-## Exit Codes and Output
-
-Exit codes:
-
-- `0`: success
-- `1`: command execution error
-- `2`: invalid args or unknown command
-
-Success envelope (`--json`):
-
-```json
-{
-  "ok": true,
-  "command": "status",
-  "data": {
-    "kind": "browserd",
-    "ready": true
-  }
-}
-```
-
-Error envelope (`--json`, written to stderr):
-
-```json
-{
-  "ok": false,
-  "error": {
-    "message": "E_PERMISSION: Invalid auth token.",
-    "exitCode": 1
-  }
-}
+browserctl daemon-stop --json
+browserctl daemon-start --json
 ```
 
-## Environment Variables
-
-### CLI (`browserctl`)
-
-| Variable | Default | Notes |
-| --- | --- | --- |
-| `BROWSERCTL_DAEMON_PORT` | `41337` | TCP port for daemon requests. |
-| `BROWSERCTL_DAEMON_STARTUP_TIMEOUT_MS` | `10000` | Max wait for daemon readiness. |
-| `BROWSERCTL_DAEMON_REQUEST_TIMEOUT_MS` | `5000` | Per-request socket timeout. |
-| `BROWSERCTL_BROWSER` | unset | Default browser preset for daemon startup (`chromium`, `chrome`, `edge`). |
-| `BROWSERCTL_AUTH_TOKEN` | unset | Default auth token for requests. |
-
-Precedence:
-
-- token: `--token` > `BROWSERCTL_AUTH_TOKEN`
-- browser preset: `--browser` > `BROWSERCTL_BROWSER`
-
-### Daemon (`browserd`)
-
-| Variable | Default | Notes |
-| --- | --- | --- |
-| `BROWSERD_TRANSPORT` | `stdio` | CLI-managed daemon startup uses `tcp`. |
-| `BROWSERD_STDIO_PROTOCOL` | `mcp` | `legacy` is JSON-line legacy mode. |
-| `BROWSERD_HOST` | `127.0.0.1` | TCP host when transport is tcp. |
-| `BROWSERD_PORT` | `41337` | TCP port when transport is tcp. |
-| `BROWSERD_DEFAULT_DRIVER` | `managed-local` if enabled, else `managed` | Falls back to `managed` if unavailable. |
-| `BROWSERD_MANAGED_LOCAL_ENABLED` | `true` | Disable to unregister `managed-local`. |
-| `BROWSERD_MANAGED_LOCAL_BROWSER` | `chromium` | `chromium`, `firefox`, `webkit`. |
-| `BROWSERD_MANAGED_LOCAL_HEADLESS` | `true` | Supports `1/0`, `true/false`, `yes/no`, `on/off`. |
-| `BROWSERD_MANAGED_LOCAL_CHANNEL` | unset | Optional channel override. |
-| `BROWSERD_MANAGED_LOCAL_EXECUTABLE_PATH` | unset | Optional executable path. |
-| `BROWSERD_MANAGED_LOCAL_LAUNCH_TIMEOUT_MS` | unset | Non-negative integer. |
-| `BROWSERD_MANAGED_LOCAL_ARGS` | unset (`[]`) | Comma-separated launch args. |
-| `BROWSERD_CHROME_RELAY_URL` | `http://127.0.0.1:9223` | `chrome-relay` endpoint. |
-| `BROWSERD_CHROME_RELAY_MODE` | `cdp` | `chrome-relay` mode: `cdp` or `extension`. |
-| `BROWSERD_CHROME_RELAY_EXTENSION_TOKEN` | unset | Required when `BROWSERD_CHROME_RELAY_MODE=extension`. |
-| `BROWSERD_CHROME_RELAY_EXTENSION_REQUEST_TIMEOUT_MS` | `5000` | Extension bridge RPC timeout (ms). |
-| `BROWSERD_REMOTE_CDP_URL` | `http://127.0.0.1:9222/devtools/browser/default` | `remote-cdp` endpoint. |
-| `BROWSERD_AUTH_TOKEN` | unset | Required when `BROWSERD_TRANSPORT=tcp`; each tool call must include matching `authToken`. |
-| `BROWSERD_AUTH_SCOPES` | `read,act,upload,download` | Allowed scopes. |
-| `BROWSERD_UPLOAD_ROOT` | unset | Upload path allowlist root. |
-| `BROWSERD_DOWNLOAD_ROOT` | unset | Download path allowlist root. |
-
-## Runtime Defaults and Driver Notes
-
-Default runtime behavior:
-
-- `managed-local` is enabled by default and selected as default driver.
-- `managed`, `chrome-relay`, and `remote-cdp` are always registered.
-- `BROWSERD_DEFAULT_DRIVER` can force a default driver key.
-- If the configured default is unavailable, runtime falls back to `managed`.
-- Default remote endpoints:
-  - `BROWSERD_CHROME_RELAY_URL=http://127.0.0.1:9223`
-  - `BROWSERD_REMOTE_CDP_URL=http://127.0.0.1:9222/devtools/browser/default`
-
-`managed-local` notes:
-
-- Browser launch is lazy (first operation requiring a browser context).
-- Optional launch controls:
-  - `BROWSERD_MANAGED_LOCAL_BROWSER` (`chromium|firefox|webkit`, default `chromium`)
-  - `BROWSERD_MANAGED_LOCAL_HEADLESS` (default `true`)
-  - `BROWSERD_MANAGED_LOCAL_CHANNEL`
-  - `BROWSERD_MANAGED_LOCAL_EXECUTABLE_PATH`
-  - `BROWSERD_MANAGED_LOCAL_LAUNCH_TIMEOUT_MS`
-  - `BROWSERD_MANAGED_LOCAL_ARGS` (comma-separated)
-
-`chrome-relay` notes:
-
-- Uses `BROWSERD_CHROME_RELAY_URL` (default `http://127.0.0.1:9223`).
-- Default mode is `BROWSERD_CHROME_RELAY_MODE=cdp` and accepts `ws(s)` or `http(s)` URLs.
-- For `http(s)`, runtime attempts `/json/version` and uses `webSocketDebuggerUrl` if available.
-- `BROWSERD_CHROME_RELAY_MODE=extension` starts a local extension bridge on `BROWSERD_CHROME_RELAY_URL`.
-- In extension mode, install `extensions/chrome-relay` as unpacked extension and set popup Bridge URL to `ws://127.0.0.1:9223/bridge` (or your custom relay host/port).
-- Extension mode requires `BROWSERD_CHROME_RELAY_EXTENSION_TOKEN` and the same popup token.
-- Extension mode now streams console and network telemetry (including response bodies when available) through the bridge.
-- On connection failures while using `--profile chrome-relay`, CLI appends guided checklist text.
+3. Load extension:
 
-Example:
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
-$env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session cli:relay --profile chrome-relay
-```
-
-`remote-cdp` notes:
-
-- Uses `BROWSERD_REMOTE_CDP_URL` (default `http://127.0.0.1:9222/devtools/browser/default`).
-- Connects directly over CDP to the configured URL.
-
-Example:
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "remote-cdp"
-$env:BROWSERD_REMOTE_CDP_URL = "http://127.0.0.1:9222/devtools/browser/default"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session cli:remote --profile remote-cdp
-```
-
-## Driver Modes and How To Use Them
-
-Driver comparison:
-
-| Driver | What it is | Best for | Requirements | Typical status field |
-| --- | --- | --- | --- | --- |
-| `managed` | In-memory managed stub driver | Contract tests, deterministic local checks | None | `status.kind = managed` |
-| `managed-local` | Real local browser launched by Playwright | Default local automation | Local browser runtime; optional channel/executable config | `status.kind = managed-local` |
-| `chrome-relay` | CDP connection via relay endpoint (`ws/http`) | Attach workflow, extension relay workflow | Reachable relay endpoint (`BROWSERD_CHROME_RELAY_URL`) | `status.kind = chrome-relay` |
-| `remote-cdp` | Direct CDP connection to remote/local browser endpoint | Existing browser/CDP infra | Reachable CDP endpoint (`BROWSERD_REMOTE_CDP_URL`) | `status.kind = remote-cdp` |
-
-How to select a driver:
-
-1. Per command: pass `--profile <driverKey>`.
-2. Per session: `profile-use <driverKey> --session <id>`.
-3. Daemon default: set `BROWSERD_DEFAULT_DRIVER`.
-
-### Use `managed` (stub)
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "managed"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session demo --profile managed
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session demo --profile managed https://example.com
-```
-
-### Use `managed-local` (real local browser)
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "managed-local"
-$env:BROWSERD_MANAGED_LOCAL_HEADLESS = "false"
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json --browser edge
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session demo --profile managed-local
-```
-
-### Use `chrome-relay`
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
-$env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session relay --profile chrome-relay
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session relay --profile chrome-relay https://example.com
-```
-
-If connection fails, CLI appends relay guidance (extension activation, endpoint check, URL check).
-
-Extension mode example:
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
-$env:BROWSERD_CHROME_RELAY_MODE = "extension"
-$env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
-$env:BROWSERD_CHROME_RELAY_EXTENSION_TOKEN = "relay-secret"
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session relay --profile chrome-relay
-```
-
-Install extension (Chrome/Edge):
-
-1. Open `chrome://extensions` or `edge://extensions`.
+1. Open `edge://extensions` or `chrome://extensions`.
 2. Enable Developer mode.
-3. Click Load unpacked and select `extensions/chrome-relay`.
-4. Open extension popup, set Bridge URL and the same token, then click Save/Reconnect.
+3. Load unpacked extension from `extensions/chrome-relay`.
+4. In extension popup, set:
+- `Bridge URL`: `ws://127.0.0.1:9223/bridge`
+- `Token`: `relay-secret`
+5. Click `Save` then `Reconnect`.
 
-### Use `remote-cdp`
+4. Verify and run first command:
 
 ```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "remote-cdp"
-$env:BROWSERD_REMOTE_CDP_URL = "http://127.0.0.1:9222/devtools/browser/default"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session remote --profile remote-cdp
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session remote --profile remote-cdp https://example.com
+browserctl status --json --session relay --profile chrome-relay
+browserctl tab-open --json --session relay --profile chrome-relay https://example.com
 ```
 
-Recommended switching pattern:
-
-1. Use one dedicated session per driver (`session:local`, `session:relay`, `session:remote`).
-2. Prefer explicit `--profile` in automation scripts to avoid implicit session carry-over.
-
-## Auth and Guardrails
-
-- `BROWSERD_TRANSPORT=tcp` requires `BROWSERD_AUTH_TOKEN`.
-- If `BROWSERD_AUTH_TOKEN` is set, every tool call must include matching `authToken`.
-- `BROWSERD_AUTH_SCOPES` is a comma-separated allowlist of `read`, `act`, `upload`, `download`.
-- `browser.upload.arm` is denied unless `BROWSERD_UPLOAD_ROOT` is set.
-- `browser.download.wait` is denied unless `BROWSERD_DOWNLOAD_ROOT` is set.
-- `BROWSERD_UPLOAD_ROOT` restricts `upload-arm` files to paths under that root.
-- `BROWSERD_DOWNLOAD_ROOT` restricts `download-wait` output paths to that root.
-- `download-wait` accepts optional positional `path`.
-- If `BROWSERD_DOWNLOAD_ROOT` is set and neither request path nor driver payload path exists, `download-wait` returns an internal error.
-
-## Driver and Session Behavior
-
-Registered drivers:
-
-- `managed`
-- `managed-local` (unless disabled)
-- `chrome-relay`
-- `remote-cdp`
-
-Session store behavior:
-
-1. `--profile` overrides driver for the current call and updates the session profile.
-2. If `--profile` is omitted, daemon resolves from session profile first, then default driver.
-3. `tab-open` updates session target to the newly opened target.
-
-## Edge and Browser Presets
-
-`--browser` or `BROWSERCTL_BROWSER` mapping:
-
-- `edge` -> `chromium + channel=msedge`
-- `chrome` -> `chromium + channel=chrome`
-- `chromium` -> `chromium` without channel override
-
-Examples:
+## 30-Second Troubleshooting
 
 ```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json --browser edge
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json
-```
-
-## Command Reference (With JSON Examples)
-
-All examples below use:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts
-```
-
-## `daemon-start`
-
-Purpose: Ensure daemon is running. Starts it if not running.
-
-Syntax:
-
-```text
-daemon-start [--json] [--token <authToken>] [--browser <chromium|chrome|edge>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json --browser edge
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "daemon-start",
-  "data": {
-    "running": true,
-    "port": 41337,
-    "pid": 24680
-  }
-}
-```
-
-## `daemon-status`
-
-Purpose: Check if daemon is reachable.
-
-Syntax:
-
-```text
-daemon-status [--json] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-status --json
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "daemon-status",
-  "data": {
-    "running": true,
-    "port": 41337,
-    "pid": 24680
-  }
-}
-```
-
-## `daemon-stop`
-
-Purpose: Stop daemon using PID file.
-
-Syntax:
-
-```text
-daemon-stop [--json]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "daemon-stop",
-  "data": {
-    "stopped": true,
-    "port": 41337,
-    "pid": 24680
-  }
-}
-```
-
-## `status`
-
-Purpose: Get browserd status plus selected driver status.
-
-Syntax:
-
-```text
-status [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session demo --profile managed-local
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "status",
-  "data": {
-    "kind": "browserd",
-    "ready": true,
-    "driver": "managed-local",
-    "drivers": [
-      "chrome-relay",
-      "managed",
-      "managed-local",
-      "remote-cdp"
-    ],
-    "status": {
-      "kind": "managed-local",
-      "connected": false,
-      "launched": false,
-      "browserName": "chromium",
-      "headless": true
-    }
-  }
-}
-```
-
-## `tabs`
-
-Purpose: List target IDs for current driver/profile context.
-
-Syntax:
-
-```text
-tabs [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts tabs --json --session demo
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "tabs",
-  "data": {
-    "driver": "managed-local",
-    "tabs": [
-      "target:managed-local:profile:managed-local:default:1"
-    ]
-  }
-}
-```
-
-## `profile-list`
-
-Purpose: List profiles for the selected driver.
-
-Syntax:
-
-```text
-profile-list [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts profile-list --json --profile managed-local
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "profile-list",
-  "data": {
-    "driver": "managed-local",
-    "profiles": [
-      "profile:managed-local:default"
-    ]
-  }
-}
-```
-
-## `profile-use`
-
-Purpose: Bind session to a driver key.
-
-Syntax:
-
-```text
-profile-use <driverKey> [--json] [--session <id>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts profile-use --json --session demo chrome-relay
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "profile-use",
-  "data": {
-    "profile": "chrome-relay"
-  }
-}
-```
-
-## `tab-open`
-
-Purpose: Open a new tab and navigate to URL.
-
-Syntax:
-
-```text
-tab-open <url> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session demo https://example.com
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "tab-open",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:2"
-  }
-}
-```
-
-## `tab-focus`
-
-Purpose: Focus an existing target.
-
-Syntax:
-
-```text
-tab-focus <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-focus --json --session demo target:managed-local:profile:managed-local:default:2
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "tab-focus",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:2",
-    "focused": true
-  }
-}
-```
-
-## `tab-close`
-
-Purpose: Close an existing target.
-
-Syntax:
-
-```text
-tab-close <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-close --json --session demo target:managed-local:profile:managed-local:default:2
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "tab-close",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:2",
-    "closed": true
-  }
-}
-```
-
-## `snapshot`
-
-Purpose: Capture target snapshot (URL/title/HTML/request summaries when available).
-
-Syntax:
-
-```text
-snapshot <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts snapshot --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "snapshot",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "snapshot": {
-      "kind": "managed-local",
-      "profile": "profile:managed-local:default",
-      "targetId": "target:managed-local:profile:managed-local:default:1",
-      "hasTarget": true,
-      "url": "https://example.com/",
-      "title": "Example Domain",
-      "html": "<!doctype html>...",
-      "requestSummaries": []
-    }
-  }
-}
-```
-
-## `screenshot`
-
-Purpose: Capture target screenshot (PNG base64 payload).
-
-Syntax:
-
-```text
-screenshot <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts screenshot --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "screenshot",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "screenshot": {
-      "kind": "managed-local",
-      "profile": "profile:managed-local:default",
-      "targetId": "target:managed-local:profile:managed-local:default:1",
-      "hasTarget": true,
-      "mimeType": "image/png",
-      "encoding": "base64",
-      "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
-    }
-  }
-}
-```
-
-## `act`
-
-Purpose: Execute an action by type on a target.
-
-Syntax:
-
-```text
-act <actionType> <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Important behavior in current CLI:
-
-- CLI sends only `action.type`.
-- It does not send `action.payload`.
-- Actions that require payload may return `ok: false` in `data.result`.
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts act --json --session demo click target:managed-local:profile:managed-local:default:1
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "act",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "result": {
-      "actionType": "click",
-      "profile": "profile:managed-local:default",
-      "targetId": "target:managed-local:profile:managed-local:default:1",
-      "targetKnown": true,
-      "ok": false,
-      "executed": false,
-      "error": "action.payload.selector is required for click action."
-    }
-  }
-}
-```
-
-## `upload-arm`
-
-Purpose: Arm upload files for target.
-
-Syntax:
-
-```text
-upload-arm <targetId> <file1> [file2 ...] [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts upload-arm --json --session demo target:managed-local:profile:managed-local:default:1 .\fixtures\a.txt .\fixtures\b.txt
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "upload-arm",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "armed": true,
-    "files": [
-      "C:\\repo\\fixtures\\a.txt",
-      "C:\\repo\\fixtures\\b.txt"
-    ]
-  }
-}
-```
-
-## `dialog-arm`
-
-Purpose: Arm dialog handling for target.
-
-Syntax:
-
-```text
-dialog-arm <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts dialog-arm --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "dialog-arm",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "armed": true
-  }
-}
-```
-
-## `download-trigger`
-
-Purpose: Trigger download flow for target.
-
-Syntax:
-
-```text
-download-trigger <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts download-trigger --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "download-trigger",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "triggered": true
-  }
-}
-```
-
-## `download-wait`
-
-Purpose: Wait for and return download metadata.
-
-Syntax:
-
-```text
-download-wait <targetId> [path] [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts download-wait --json --session demo target:managed-local:profile:managed-local:default:1 .\downloads\artifact.bin
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "download-wait",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "download": {
-      "path": "C:\\repo\\downloads\\artifact.bin",
-      "profile": "profile:managed-local:default",
-      "targetId": "target:managed-local:profile:managed-local:default:1",
-      "uploadFiles": [
-        "C:\\repo\\fixtures\\a.txt"
-      ],
-      "dialogArmedCount": 1,
-      "triggerCount": 1
-    }
-  }
-}
-```
-
-## `console-list`
-
-Purpose: Read console telemetry entries for target.
-
-Syntax:
-
-```text
-console-list <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts console-list --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "console-list",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "entries": [
-      {
-        "type": "warning",
-        "text": "Example warning",
-        "timestamp": "2026-02-23T10:00:00.000Z",
-        "location": {
-          "url": "https://example.com",
-          "lineNumber": 12,
-          "columnNumber": 4
-        }
-      }
-    ]
-  }
-}
-```
-
-## `response-body`
-
-Purpose: Read captured network response body for a request ID.
-
-Syntax:
-
-```text
-response-body <targetId> <requestId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-Example command:
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts response-body --json --session demo target:managed-local:profile:managed-local:default:1 request:managed-local:profile%3Amanaged-local%3Adefault:target%3Amanaged-local%3Aprofile%3Amanaged-local%3Adefault%3A1:1
-```
-
-Example JSON output:
-
-```json
-{
-  "ok": true,
-  "command": "response-body",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "requestId": "request:managed-local:profile%3Amanaged-local%3Adefault:target%3Amanaged-local%3Aprofile%3Amanaged-local%3Adefault%3A1:1",
-    "body": "{\"ok\":true}",
-    "encoding": "utf8"
-  }
-}
+browserctl daemon-status --json
+Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:9223/browserctl/relay/status" -TimeoutSec 3
 ```
 
-## Relay Troubleshooting
-
-When relay profile operations fail with connection errors (`ECONNREFUSED`, timeout, `ENOTFOUND`, etc.), CLI appends guidance:
-
-1. For extension relay, set `BROWSERD_CHROME_RELAY_MODE=extension`.
-2. Load unpacked extension from `extensions/chrome-relay` and keep it active.
-3. Ensure extension popup Bridge URL matches `BROWSERD_CHROME_RELAY_URL` (`ws://<host>:<port>/bridge`).
-4. For CDP relay, verify browser remote debugging endpoint is running.
-5. Verify `BROWSERD_CHROME_RELAY_URL`.
+If `connected` is `false`, reopen extension popup and click `Reconnect`.
 
-## Notes on Accuracy of Example Payloads
-
-- The JSON examples are representative and aligned with current command/result shapes.
-- Runtime values vary by active driver, browser state, and environment policy.
-- `snapshot.html`, `screenshot.imageBase64`, and telemetry fields can be large and are abbreviated in examples.
-
-## Smoke Flow
-
-Run smoke flow:
-
-```powershell
-pwsh -NoLogo -NoProfile -File .\scripts\smoke.ps1
-```
+## Full Docs
 
-Smoke flow behavior:
+- [Full User Guide (English)](docs/user-guide.md)
+- [完整使用文档（中文）](docs/user-guide-cn.md)
+- [Chrome Relay Extension README (English)](extensions/chrome-relay/README.md)
+- [Chrome Relay 扩展文档（中文）](extensions/chrome-relay/README-CN.md)
 
-1. Starts `browserd`.
-2. Runs `browserctl status --json`.
-3. Waits until daemon is reachable via TCP.
-4. Fails if response contains an error or `ok` is `false`.