browser-automation-skill 0.71.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "browser-automation-skill",
+  "version": "0.71.0",
+  "description": "MCP server + bash CLI that drives a real browser from Claude Code by routing across chrome-devtools-mcp, playwright-cli, playwright-lib, and obscura adapters. 42 verbs covering site/session/credential management, snapshot+ref interaction, capture pipelines, declarative flows, and a per-archetype memory cache.",
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "model-context-protocol",
+    "browser-automation",
+    "playwright",
+    "chrome-devtools-mcp",
+    "anthropic",
+    "skill",
+    "agent"
+  ],
+  "homepage": "https://github.com/xicv/browser-automation-skill#readme",
+  "bugs": {
+    "url": "https://github.com/xicv/browser-automation-skill/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xicv/browser-automation-skill.git"
+  },
+  "license": "MIT",
+  "author": "Nick Cao <nick.cao@avcrm.com>",
+  "type": "module",
+  "bin": {
+    "browser-automation-skill": "bin/cli.mjs",
+    "browser-mcp": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "references/",
+    "SKILL.md",
+    "SECURITY.md",
+    "install.sh",
+    "uninstall.sh",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "scripts": {
+    "mcp": "bash scripts/browser-mcp.sh serve",
+    "test:smoke": "printf '%s\\n' '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' | bash scripts/browser-mcp.sh serve",
+    "prepublishOnly": "npm run test:smoke >/dev/null && echo 'smoke OK'"
+  }
+}

package/references/adapter-candidates.md

@@ -0,0 +1,40 @@
+# Adapter candidates
+
+Browser-automation tools we have considered for the adapter roster but have **not** committed to. This file is a holding pen so candidates survive handoffs and don't get re-discovered from scratch every six months.
+
+The shipped roster lives in `references/tool-versions.md` (autogenerated from each adapter's `tool_metadata`). The planned roster lives in the parent spec Appendix B routing matrix. Candidates here are **neither shipped nor planned** — they're "we looked, we declined, here's why, here's what would change our mind."
+
+## Format
+
+Each candidate gets one short section: what it is, why we declined now, and the concrete trigger that would flip the decision.
+
+---
+
+## pinchtab — `https://github.com/pinchtab/pinchtab`
+
+**What:** Standalone Go HTTP server (~16MB binary) controlling Chrome via CDP. User-installed daemon model (`pinchtab daemon install`). HTTP API at `127.0.0.1:9867` plus a `pinchtab` CLI with subcommands (`nav`, `snap`, `click`, `fill`, `text`, `press`). First-class profile model, multi-instance, token-efficient text extraction (~800 tokens/page). Local-first security posture (loopback bind, IDPI allowlist).
+
+**Considered:** 2026-05-02.
+
+**Declined now because:**
+- **No empty roster slot.** Inspect/audit/extract → chrome-devtools-mcp (Phase 5 part 1c). Stealth-scrape → obscura (Phase 8). Navigation primitives → playwright-cli/lib. PinchTab competes in occupied lanes without a knockout differentiator.
+- **Daemon-ownership conflict.** Skill invariant: skill manages all process lifecycle. PinchTab inverts this — daemon is user-installed, persists across sessions, has its own update cadence. Adapting requires a new "attach-to-external-daemon" abstraction we don't have.
+- **Architectural duplication.** PinchTab's HTTP-daemon overlaps with our already-shipped IPC daemon (Phase 4 part 4b). Two daemon models would split the contributor mental model.
+- **Maturity risk.** Brand-new project (~2026 H1), single-org. Roster incumbents (Microsoft Playwright, Chrome team's chrome-devtools-mcp) are bets the ecosystem already made.
+- **Token-efficiency overlap.** Our token-efficient-output spec (`docs/superpowers/specs/2026-05-01-token-efficient-adapter-output-design.md`) already captures the `eN` refs + capture files + summary-only-on-stdout discipline. Marginal pinchtab gain ≈ small.
+
+**Triggers that would flip the decision:**
+| Trigger | Action |
+|---|---|
+| Phase 8 obscura design surfaces and pinchtab's multi-instance model is a viable non-stealth scrape alternative | reconsider as alt-path for `extract --scrape` |
+| User has a pinchtab daemon running for *other* agents and wants browser-skill to share it | add as 5th adapter targeting the running daemon (requires "attach-to-external-daemon" abstraction first) |
+| PinchTab matures (~12mo), gets community adapters, or Anthropic ships an MCP wrapper for it | re-evaluate against then-current roster |
+| Need a no-node, no-300MB-browser footprint adapter (e.g. CI minimal images) | pinchtab's ~16MB Go binary becomes attractive |
+
+---
+
+## How to add a new candidate
+
+Copy the section template above. Keep it short — what / why-declined / triggers. The point is to make the next consideration a 30-second decision, not a 30-minute re-research.
+
+If a trigger fires and a candidate becomes shippable, follow [`recipes/add-a-tool-adapter.md`](recipes/add-a-tool-adapter.md) Path A and remove the section from this file.

package/references/browser-mcp-cheatsheet.md

@@ -0,0 +1,132 @@
+# browser-mcp — cheatsheet
+
+`scripts/browser-mcp.sh serve` starts an MCP (Model Context Protocol) server
+that exposes our verbs as MCP tools. Spawn it from any MCP-capable client
+(Claude Code, Continue, Cline, agent-browser, midscene, Stagehand,
+browser-use, etc.) to drive our cache + telemetry + secrets vault without
+re-implementing them.
+
+Phase 14 origin: midscene research showed midscene publishes its own MCP
+server so upper-layer agents can call it via natural language. We mirror that
+pattern so anything that speaks MCP can reuse our entire skill — turning us
+into the shared middleware browser agents delegate to.
+
+## Wire format
+
+- Transport: stdio (NDJSON — one JSON object per line)
+- Protocol: MCP 2024-11-05 (matches our existing chrome-devtools-bridge client)
+- Envelope: JSON-RPC 2.0
+
+## Tools exposed (Stage 1 + Stage 2)
+
+| Tool | Wraps | Required inputs | Optional |
+|---|---|---|---|
+| `browser_open`     | `scripts/browser-open.sh`     | `url`              | `site`, `tool` |
+| `browser_snapshot` | `scripts/browser-snapshot.sh` | _none_             | `site`, `tool`, `capture` |
+| `browser_click`    | `scripts/browser-click.sh`    | one of `ref` / `selector` | `site`, `tool` |
+| `browser_fill`     | `scripts/browser-fill.sh`     | `text` + one of `ref` / `selector` | `site`, `tool` |
+| `browser_extract`  | `scripts/browser-extract.sh`  | one of `selector` / `eval` | `site`, `tool` |
+
+Each `tools/call` response carries `content: [{type: "text", text: "<summary JSON>"}]`
+where `<summary JSON>` is the verb's last stdout line (per the token-efficient
+output spec §3.1). `_meta.exitCode` and `_meta.stderr` are surfaced for
+diagnostics.
+
+### Secrets discipline (AP-7)
+
+`browser_fill` deliberately has NO `secret` field. MCP has no stdin channel
+and putting secrets in tool arguments lands them in the request transcript.
+For real secret values, call `scripts/browser-fill.sh --secret-stdin`
+directly (the secret is piped via stdin and never reaches argv). Phase 14
+unit-tests this contract: `tests/browser-mcp.bats` asserts the schema does
+not expose any "secret" property and rejects unknown props via
+`additionalProperties: false`.
+
+### Env-var passthrough (whitelist)
+
+The MCP server does NOT inherit the client's full env. Only these prefixes
++ POSIX essentials pass through to spawned bash verbs (see
+`scripts/lib/node/mcp-server.mjs::ENV_WHITELIST_PREFIXES`):
+
+| Prefix | Purpose |
+|---|---|
+| `BROWSER_SKILL_*`     | skill internals (`BROWSER_SKILL_HOME`, trace ID, etc.) |
+| `BROWSER_STATS_*`     | post-condition contract + model-name injection |
+| `CLAUDE_*`            | `CLAUDE_MODEL`, `CLAUDE_USAGE_*`, `CLAUDE_SESSION_ID` |
+| `MIDSCENE_MODEL_*`    | local-VLM endpoint config (one envvar block reaches BOTH our skill AND midscene) |
+| `PLAYWRIGHT_*`        | adapter knobs + test injection |
+| `CHROME_DEVTOOLS_*`   | cdt-mcp adapter knobs |
+| `OBSCURA_*`           | obscura adapter knobs |
+| `STUB_*` / `FIXTURES_*` | test-only seams |
+| `MCP_*`               | reserved for future MCP overrides |
+
+Everything else (e.g. arbitrary `OPENAI_API_KEY` or unknown secrets in the
+client process) is filtered out. This is the AP-7-aligned default — opt-in
+later via expanding the whitelist, not via removing it.
+
+## Smoke test
+
+```bash
+printf '%s\n%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+  | bash scripts/browser-mcp.sh serve
+```
+
+Expected output (two NDJSON lines): an `initialize` reply with
+`protocolVersion: "2024-11-05"` + a `tools/list` reply enumerating
+`browser_open` and `browser_snapshot`.
+
+## Wiring from Claude Code
+
+Add to `~/.claude/config.json` (or per-project):
+
+```json
+{
+  "mcpServers": {
+    "browser-skill": {
+      "command": "bash",
+      "args": ["/abs/path/to/scripts/browser-mcp.sh", "serve"]
+    }
+  }
+}
+```
+
+After Claude Code restart, the `browser_open` / `browser_snapshot` tools
+appear in the tool list. They run against the same `~/.browser-skill/` state
+(sites, sessions, captures, memory) as the bash entry points — one cache,
+two surfaces.
+
+## Why this exists
+
+- **Cache reuse**: `browser-do` archetype cache + Phase 13 fingerprint rescue
+  apply automatically when called via MCP — the bash verb is the same entry
+  point either way.
+- **Telemetry parity**: every MCP `tools/call` results in one `stats.jsonl`
+  event (same as a direct bash call), so `browser-stats report` shows MCP
+  and direct calls in one table.
+- **Secrets stay local**: the MCP server spawns the same `scripts/browser-*.sh`
+  verbs, which honour AP-7 (no secrets in argv). MCP clients NEVER see
+  credentials.
+
+## Limitations (Stage 1 + 2)
+
+- 5 verbs exposed (open + snapshot + click + fill + extract). The other ~37
+  verbs (site / session / credential management, flow runner, capture mgmt,
+  stats, baseline, schema migration) are reachable only via direct bash.
+  Stage 3 candidates: `browser_wait`, `browser_press`, `browser_select`,
+  `browser_assert`.
+- No streaming progress events — request/response only. MCP supports
+  `notifications/progress`; wiring it is a Stage 3 task.
+- No tool-side authorization. Anything that can spawn the server can call any
+  verb. The skill's existing per-verb typed-phrase confirmations (e.g.
+  `--yes-i-know` on destructive ops) still apply at the bash boundary.
+- `browser_extract` does NOT expose `--scrape` (multi-URL batch mode) — too
+  many args and the output shape changes. Use `scripts/browser-extract.sh`
+  directly for that.
+
+## Environment
+
+| Var | Meaning | Default |
+|---|---|---|
+| `BROWSER_SKILL_NODE_BIN` | Node binary used by `browser-mcp.sh serve` | `node` |

package/references/browser-stats-cheatsheet.md

@@ -0,0 +1,155 @@
+# browser-stats — telemetry / audit / tuning surface
+
+Per-action JSONL audit log under `${BROWSER_SKILL_HOME}/memory/stats.jsonl`
+plus a lazy-built SQLite mirror at `memory/stats.db`. JSONL is the source of
+truth; SQLite is regenerated from cursor (`memory/stats.db::stats_cursor`).
+
+## Mental model — balance triangle
+
+```
+   tokens
+      \
+       \
+        \____ accuracy
+        /
+       /
+   latency
+```
+
+Every adapter invocation emits one event. `browser-stats report` rolls events
+up by (route × verb × outcome) and surfaces:
+
+- success rate (and post-condition hit-rate — the *real* accuracy signal)
+- p50/avg token proxies (`stdout_bytes`, `stderr_bytes`, `argv_bytes`)
+- avg duration_ms
+- $/event when `CLAUDE_USAGE_*` env vars present (priced via
+  [`stats-prices.json`](stats-prices.json))
+- failure-mode histogram (13-value enum — see schema)
+- **`oblivious_success`** count: adapter reported `outcome=success` but
+  the post-condition assertion failed. This is the audit's killer signal —
+  without it, naive self-reported success rates lie.
+
+## Verbs
+
+| Verb | What it does |
+|---|---|
+| `browser-stats rebuild` | Tail `stats.jsonl` from cursor → upsert into `stats.db`. Idempotent. Builds schema on first run. |
+| `browser-stats report [--days N] [--route R] [--verb V] [--pareto]` | Human-readable summary. `--pareto` adds a per-route composite efficiency score. |
+| `browser-stats mark <span_id> success\|fail[:reason]` | Record a user override on one event. Audit-report applies overrides over self-reported outcomes. |
+| `browser-stats tune [--days N] [--route R]` | Surface worst-performing (verb, route) candidates for `/autoresearch` handoff. Human-in-loop — never auto-mutates the skill. |
+
+## Examples
+
+```bash
+# Daily summary (last 7 days, all routes):
+bash scripts/browser-stats.sh report
+
+# Per-route Pareto frontier (success_rate × output-byte efficiency):
+bash scripts/browser-stats.sh report --pareto --days 30
+
+# Just one route:
+bash scripts/browser-stats.sh report --route chrome-devtools-mcp --days 14
+
+# Override an event (e.g. you know the audit miscategorized this):
+bash scripts/browser-stats.sh mark a1b2c3d4e5f6a7b8 fail:wrong_element_acted
+
+# Find tuning candidates:
+bash scripts/browser-stats.sh tune --days 30
+```
+
+## Wiring an adapter call site
+
+Every verb script that invokes an adapter should emit one stats event per
+invocation. Pattern (see `scripts/browser-open.sh` for a real example):
+
+```bash
+source "${SCRIPT_DIR}/lib/stats.sh"
+
+stats_t0="$(now_ms)"
+set +e
+adapter_out="$(invoke_with_retry open "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+# Phase 12 part 2: post-condition contract via env vars (keeps the helper
+# call-site readable — 6 positional args instead of 10). Verb script sets
+# OBSERVED to the verb-specific signal (URL for open, adapter_out for
+# click/extract). End-user sets EXPECT_* via env to assert specific values.
+BROWSER_STATS_OBSERVED="${url}" \
+  stats_run_adapter_emit \
+    "open" "${tool_name}" "${stats_t0}" "${adapter_rc}" \
+    "${adapter_out}" "" \
+    -- "${verb_argv[@]}"
+```
+
+### Post-condition env vars (caller sets before invoking the verb)
+
+| Env var | Values | Default |
+|---|---|---|
+| `BROWSER_STATS_EXPECT_TYPE`  | `url`, `element_path`, `element_value` | (none — disables check) |
+| `BROWSER_STATS_EXPECT_MATCH` | `exact`, `include`, `semantic` | `include` |
+| `BROWSER_STATS_EXPECT_VALUE` | any string | (none — disables check) |
+| `BROWSER_STATS_OBSERVED`     | any string | set by verb script |
+
+Example:
+```bash
+BROWSER_STATS_EXPECT_TYPE=url \
+BROWSER_STATS_EXPECT_MATCH=include \
+BROWSER_STATS_EXPECT_VALUE='/devices/42' \
+  bash scripts/browser-open.sh --url https://example.com/devices/42
+# → event will carry post_condition_hit:true; oblivious_success detected on mismatch
+```
+
+### Contract
+
+- Helper is best-effort — failure never taints caller's exit code (warns to stderr).
+- `parent_span_id` is null unless caller exported `BROWSER_SKILL_PARENT_SPAN_ID`
+  (used by `browser-flow` to nest step spans inside a run span).
+- `model` + `gen_ai_usage_*` fields populate only when `CLAUDE_USAGE_*` /
+  `CLAUDE_MODEL` env vars are set. Outside Claude Code → null.
+- `stats_random_id` is fork-free `$RANDOM` by default (~60 bits, fine for
+  correlation). Set `STATS_USE_CRYPTO_ID=1` if you need `openssl rand` strength.
+- Requires **bash 5.0+** (`$EPOCHREALTIME`). Falls back to second precision
+  on legacy bash; the skill's other bash-isms already require Homebrew bash
+  on macOS.
+
+## Schema
+
+See [`stats-schema.json`](stats-schema.json) for the full JSON Schema. Field
+names follow OpenInference + OTel GenAI v1.40 conventions (snake_case
+flattening) for direct compatibility with Langfuse / Phoenix / Jaeger via an
+OTLP exporter.
+
+Failure-mode enum (13 values, sourced from WAREX + Agent-E + WebVoyager
+taxonomies):
+
+```
+element_not_found     element_ambiguous     wrong_element_acted
+stale_ref             action_timeout        navigation_mismatch
+js_not_ready          network_error         captcha_blocked
+auth_required         popup_intercept       extraction_mismatch
+oblivious_success
+```
+
+## Privacy
+
+- All writes are local (`memory/` mode 0700, files mode 0600).
+- chrome-devtools-mcp opt-out of upstream Clearcut telemetry recommended:
+  pass `--no-usage-statistics` in the adapter wrapper (or set
+  `CDT_MCP_NO_USAGE_STATISTICS=1`).
+- `selector_value` and `post_condition_observed` may contain user data.
+  No remote sink ever. Future `--redact` mode can hash these.
+
+## Doctor integration
+
+`browser-doctor` surfaces:
+- `ok: stats events recorded: N` (or `warn: stats.jsonl absent`)
+- `ok: stats SQLite indexed: N (delta from JSONL: K)`
+- `warn: stats has N oblivious_success in last 7 days` (when > 0)
+
+## Schema migrations
+
+`stats.jsonl` starts at `schema_version: 1`. Future shape changes ship a
+migrator under `scripts/lib/migrators/stats/v1_to_v2.sh` (same pattern as
+`memory/`); `browser-migrate run` applies it. SQLite is rebuilt from JSONL
+on the first `rebuild` after a bump.

package/references/chrome-devtools-mcp-cheatsheet.md

@@ -0,0 +1,232 @@
+# chrome-devtools-mcp — cheatsheet
+
+The browser-skill's chrome-devtools-mcp adapter is the **inspection / audit /
+extract** path. Upstream is the `chrome-devtools-mcp` MCP server
+(`npx chrome-devtools-mcp@latest`) which exposes the rich set of CDP-backed
+tools — console messages, network requests, lighthouse audits, performance
+traces — that the playwright-* adapters do not.
+
+## Status — Path A introduction (phase-05 part 1) + bridge scaffold (part 1b)
+
+This adapter ships **opt-in** via `--tool=chrome-devtools-mcp`. Router
+promotion (Path B — making it the default for capture-flag verbs and for
+`audit` / `inspect` per parent spec Appendix B) is deferred to phase-05
+part 1d after a soak window.
+
+Phase-05 part 1b shipped the **node bridge scaffold** at
+`scripts/lib/node/chrome-devtools-bridge.mjs`. The adapter shells to that
+bridge (mirrors `playwright-lib`'s shape: adapter → node bridge → upstream).
+
+**Phase-05 part 1c shipped the real MCP stdio transport** for stateless
+verbs. With `${CHROME_DEVTOOLS_MCP_BIN}` pointing at a real
+`chrome-devtools-mcp` (e.g. `npx chrome-devtools-mcp@latest`), the bridge:
+1. spawns the upstream MCP server with stdio piped,
+2. sends the `initialize` handshake (protocol version `2024-11-05`),
+3. translates the verb → MCP `tools/call`,
+4. shapes the response into the skill's single-line summary JSON,
+5. exits cleanly.
+
+`uid → eN` translation happens at the adapter boundary (per token-efficient-
+output spec §5) for snapshot output. The original `uid` is kept on each ref
+for traceability.
+
+| Verb | Real-mode behavior |
+|---|---|
+| `open` | `navigate_page {url}` — works (one-shot, or via daemon when running) |
+| `snapshot` | `take_snapshot` — works; refs translated to `eN`. When daemon is running, refMap is cached server-side so subsequent `click` / `fill` resolve `eN → uid` |
+| `eval` | `evaluate_script {script}` — works |
+| `audit` | `lighthouse_audit` — works (60s timeout) |
+| `click`, `fill` | works **via daemon** (phase-05 part 1c-ii) — `daemon-start` first, then `snapshot`, then `click eN` / `fill eN ...`. Without daemon → exit 41 with hint |
+| `inspect` | works real-mode (phase-05 part 1e-ii). Multi-flag aggregation: `--capture-console` → `list_console_messages`; `--capture-network` → `list_network_requests`; `--screenshot` → `take_screenshot`; `--selector CSS` → `evaluate_script` with querySelectorAll. One-shot or daemon-routed |
+| `extract` | works real-mode (phase-05 part 1e-ii). `--selector CSS` → evaluate_script with querySelectorAll → text join; `--eval JS` → raw evaluate_script. One-shot or daemon-routed |
+
+### Daemon mode (phase-05 part 1c-ii)
+
+`daemon-start` spawns a detached node child that holds ONE long-lived MCP
+server child + the `eN ↔ uid` ref map + a TCP loopback IPC server. Verb
+clients connect over loopback (Unix sun_path 104-char cap on macOS bats temp
+paths — TCP loopback with ephemeral port sidesteps it). State written to
+`${BROWSER_SKILL_HOME}/cdt-mcp-daemon.json` (mode 0600, dir 0700).
+
+```bash
+node scripts/lib/node/chrome-devtools-bridge.mjs daemon-start
+node scripts/lib/node/chrome-devtools-bridge.mjs open https://example.com
+node scripts/lib/node/chrome-devtools-bridge.mjs snapshot
+node scripts/lib/node/chrome-devtools-bridge.mjs click e1
+node scripts/lib/node/chrome-devtools-bridge.mjs daemon-stop
+```
+
+`daemon-status` reports `daemon-running` / `daemon-not-running`. `daemon-stop`
+when none is a no-op success. Idempotent `daemon-start` returns
+`daemon-already-running`. Daemon stderr lands at
+`${BROWSER_SKILL_HOME}/cdt-mcp-daemon.log` (mode 0600).
+
+Stub mode (`BROWSER_SKILL_LIB_STUB=1`) still works exactly as part-1b — used by the bats suite + CI for adapter contract tests without spawning anything.
+
+## When the router picks this adapter
+
+After Phase 5 part 1d, four routing rules promote chrome-devtools-mcp to a default for verbs and flags where it's the only sensible adapter (per parent spec Appendix B):
+
+| Verb / flag | Default? | Why |
+|---|---|---|
+| `open` (no flags) | no | router default is playwright-cli |
+| `click` (no flags) | no | playwright-cli |
+| `fill` (no flags) | no | playwright-cli (or playwright-lib for `--secret-stdin`) |
+| `snapshot` (no flags) | no | playwright-cli |
+| `--capture-console` / `--capture-network` (any verb) | **YES** (part 1d) | `rule_capture_flags` — only adapter with console + network MCP tools |
+| `--lighthouse` / `--perf-trace` (any verb) | **YES** (part 1d) | `rule_audit_or_perf` — only adapter with `lighthouse_audit` + `performance_*` |
+| `audit` (any flags) | **YES** (part 1d) | `rule_audit_or_perf` |
+| `inspect` | **YES** (part 1d) | `rule_inspect_default` |
+| `extract` | **YES** (part 1d) | `rule_extract_default`. With `--scrape <urls...>` → obscura (when Phase 8 lands) |
+| `eval` | no — opt-in | playwright-cli/lib both support it |
+
+`session_required` (storage-state loaded) still wins above all capture-flag rules; that path keeps routing through playwright-lib, so flag combos like `--site app --capture-console` route to playwright-lib (capture flags silently ignored). Limitation tracked for part 1f (Chrome `--user-data-dir` lets cdt-mcp do session loading too).
+
+## Capabilities declared
+
+```json
+{
+  "verbs": {
+    "open":     { "flags": ["--headed", "--url"] },
+    "click":    { "flags": ["--ref"] },
+    "fill":     { "flags": ["--ref", "--text", "--secret-stdin"] },
+    "snapshot": { "flags": ["--depth"] },
+    "inspect":  { "flags": ["--capture-console", "--capture-network", "--screenshot"] },
+    "audit":    { "flags": ["--lighthouse", "--perf-trace"] },
+    "extract":  { "flags": ["--selector", "--eval"] },
+    "eval":     { "flags": ["--expression"] }
+  }
+}
+```
+
+All eight verbs are declared so `--tool=chrome-devtools-mcp` makes the full
+surface reachable today (the capability filter in `pick_tool` admits any
+declared verb regardless of router precedence).
+
+## Architecture
+
+```
+bash adapter            node bridge                upstream MCP server
+┌─────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
+│ chrome-devtools-│───▶│ chrome-devtools-     │───▶│ chrome-devtools-mcp │
+│ mcp.sh          │    │ bridge.mjs           │    │ (npx, JSON-RPC over │
+│ (8 tool_* fns)  │    │ - stub mode          │    │  stdio) — part 1c   │
+│                 │    │ - real mode (1c)     │    │                     │
+└─────────────────┘    └──────────────────────┘    └─────────────────────┘
+```
+
+This mirrors the `playwright-lib → playwright-driver.mjs → real Playwright`
+shape. The bridge is the translation boundary between skill verb argv and
+the MCP `tools/call` JSON-RPC envelope (real mode) OR fixture lookup (stub
+mode).
+
+## Doctor check
+
+Verifies `node` is on PATH and the bridge file is present (mirror
+`playwright-lib::tool_doctor_check`). Reports node version and the
+`mcp_server_bin` name. Includes a `note` field stating real-mode MCP
+transport is deferred to part 1c.
+
+To install (real-mode, once part 1c lands):
+
+```bash
+npm i -g chrome-devtools-mcp
+# or run via npx (no global install):
+#   CHROME_DEVTOOLS_MCP_BIN='npx chrome-devtools-mcp@latest' \
+#     bash scripts/browser-<verb>.sh --tool=chrome-devtools-mcp ...
+```
+
+## Version pin
+
+- `version_pin: "0.x"` — the upstream package is pre-1.0; capabilities are
+  expected to drift. The pin will move once a stable major lands.
+
+## Override
+
+Force this adapter even when the router would pick another:
+
+```bash
+bash scripts/browser-<verb>.sh --tool=chrome-devtools-mcp ...
+```
+
+This is the **Path A entry point** — it works without router edits and is
+how every new adapter is introduced (see
+[references/recipes/add-a-tool-adapter.md](recipes/add-a-tool-adapter.md)).
+
+## Stub mode
+
+Set `BROWSER_SKILL_LIB_STUB=1` to make the bridge perform a fixture lookup
+instead of spawning the upstream MCP server (which the bridge doesn't yet do
+anyway — that's part 1c). The bridge hashes argv (`sha256` of args
+joined+terminated by NUL — matches `printf '%s\0' "$@" | shasum -a 256`) and
+echoes the corresponding `tests/fixtures/chrome-devtools-mcp/<sha>.json`.
+Misses exit 41 with a JSON error line.
+
+To regenerate fixture filenames after changing the adapter's argv translation:
+
+```bash
+printf '%s\0' inspect --capture-console | shasum -a 256 | awk '{print $1}'
+```
+
+The same digest in node (the bridge's path):
+
+```bash
+node -e "const{createHash}=require('crypto'); \
+  console.log(createHash('sha256') \
+    .update(['inspect','--capture-console'].map(a=>a+'\0').join('')) \
+    .digest('hex'))"
+```
+
+## Environment variables
+
+| Var | Meaning | Default |
+|---|---|---|
+| `BROWSER_SKILL_LIB_STUB` | When `=1`, bridge skips MCP transport and reads fixtures | unset |
+| `BROWSER_SKILL_NODE_BIN` | Node binary the adapter invokes | `node` |
+| `CHROME_DEVTOOLS_MCP_BIN` | Upstream MCP server binary the bridge spawns in real mode (part 1c) | `chrome-devtools-mcp` |
+| `CHROME_DEVTOOLS_MCP_FIXTURES_DIR` | Override fixture directory in stub mode | `tests/fixtures/chrome-devtools-mcp` (relative to bridge file) |
+| `STUB_LOG_FILE` | When set, bridge in stub mode appends each invocation's argv (one line per arg) here | unset |
+| `CHROME_USER_DATA_DIR` | When set (phase-5 part 1f), bridge forwards `--user-data-dir DIR` to the spawned upstream MCP child. Chrome reuses the profile (cookies, localStorage, extensions persist). | unset |
+
+## Session loading (phase-5 part 1f)
+
+cdt-mcp's session mechanism is **Chrome's native `--user-data-dir`**, NOT
+playwright-lib's `storageState` JSON. To reuse a logged-in profile:
+
+```bash
+# 1. Log in once with real Chrome at a known directory:
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --user-data-dir=/tmp/my-profile https://app.example.com
+
+# 2. Now point cdt-mcp at it:
+export CHROME_USER_DATA_DIR=/tmp/my-profile
+bash scripts/browser-snapshot.sh --capture-console
+```
+
+The bridge forwards the directory as `--user-data-dir DIR` to the upstream
+MCP server child. If upstream chrome-devtools-mcp accepts the flag (most
+versions do — it's a standard Chrome arg), Chrome reuses the profile.
+
+**Limitations:**
+- User provides the directory. Capture / automation of user-data-dir creation is out of scope (no `bash scripts/browser-login.sh --user-data-dir-mode` yet).
+- Concurrent runs sharing the same profile dir → Chrome lock conflicts. Serialize.
+- Upstream chrome-devtools-mcp version dictates whether the flag is honored.
+
+## Limitations (current state)
+
+- **No router promotion.** Per anti-pattern AP-4, this PR ships dark only.
+  Promotion is part 1d.
+- **No `inspect` / `extract` verbs yet.** `scripts/browser-audit.sh` and
+  `scripts/browser-extract.sh` don't exist; `tests/browser-inspect.bats` is
+  still skipped. Verb-side wiring (and daemon dispatch for these two) is
+  phase-05 part 1e.
+- **No session loading.** Chrome's `--user-data-dir` mechanism (different
+  from playwright-lib's `storageState`) is phase-05 part 1f.
+
+## See also
+
+- Parent spec: [`docs/superpowers/specs/2026-04-27-browser-automation-skill-design.md`](../docs/superpowers/specs/2026-04-27-browser-automation-skill-design.md) — Appendix B routing matrix.
+- Add-a-tool-adapter recipe: [`references/recipes/add-a-tool-adapter.md`](recipes/add-a-tool-adapter.md).
+- Anti-patterns: [`references/recipes/anti-patterns-tool-extension.md`](recipes/anti-patterns-tool-extension.md).
+- Token-efficient output spec: [`docs/superpowers/specs/2026-05-01-token-efficient-adapter-output-design.md`](../docs/superpowers/specs/2026-05-01-token-efficient-adapter-output-design.md).
+- Phase 5 part 1b plan: [`docs/superpowers/plans/2026-05-02-phase-05-part-1b-cdt-mcp-bridge.md`](../docs/superpowers/plans/2026-05-02-phase-05-part-1b-cdt-mcp-bridge.md).