browser-automation-skill 0.71.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Cao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# browser-automation-skill
+
+A [Claude Code](https://claude.com/claude-code) skill for driving real browsers from an LLM. **44 verbs + a per-action audit surface** routed across four tools (chrome-devtools-mcp / playwright-cli / playwright-lib / obscura), with a 5-tier cache defense chain (cached selector → fingerprint rescue → local-VLM rescue → cloud LLM → user fixup) that lets agents skip LLM ref-resolution on repeat actions and per-schema state migration tooling. Credentials and sessions stay strictly local under `$HOME/.browser-skill/`.
+
+> **Status:** Phases 1–14 ✅ ALL COMPLETE. **Phase 14 (local-VLM cache rescue + auto-managed VLM stack + MCP server) ✅ shipped** — `scripts/browser-vlm.sh` wraps `llama-server` with idle-stop watchdog + lazy-start; `scripts/lib/visual-rescue-default.sh` is the canonical Path 3 probe (gated by `BROWSER_SKILL_VISION_FALLBACK=1`); `scripts/lib/node/mcp-server.mjs` publishes 5 verbs (open/snapshot/click/fill/extract) over JSON-RPC NDJSON for external agents (auto-discovers TOOLS from adapter capabilities + `mcp-tools.json` allowlist); `browser-stats prune` closes the telemetry feedback loop by auto-detecting cache-pollution from `oblivious_success` clusters. **Production-ready v1.3.** Full bats: 1086/1086 green. Architecture map: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). New contributors: [`CONTRIBUTING.md`](CONTRIBUTING.md).
+>
+> **One-command enable Path 3 cache rescue:** `bash scripts/browser-vlm.sh install-env` (idempotent — appends env exports to `~/.zshrc`; lazy auto-start handles the rest).
+
+## What it does
+
+- **Sites + sessions + credentials.** Register sites; capture/restore Playwright `storageState`; store credentials in keychain (macOS) / libsecret (Linux) / plaintext-with-typed-confirmation; rotate TOTP shared secrets.
+- **Navigation + interaction.** `open` · `snapshot` (eN-indexed accessibility tree) · `click`/`fill`/`hover`/`press`/`select`/`drag`/`upload` by `--ref eN` or `--selector CSS` · `wait` · `route` (network mock) · multi-tab (`tab-list`/`tab-switch`/`tab-close`).
+- **Capture pipelines.** `inspect` aggregates console + network (sanitized HAR) + screenshot. `audit` runs Lighthouse. All captures persist under `~/.browser-skill/captures/<NNN>/` with `meta.json` + per-aspect files; auto-prune at retention thresholds (default: 500 captures / 14 days; baselines exempt).
+- **Declarative flow runner.** `flow run task.flow.yaml` executes a YAML flow with `${var}` + `${refs.NAME}` templating. `flow record` wraps `playwright codegen` (password-canary write-side: `/password/i` becomes `${secrets.password}` placeholder; literal dropped). `replay <id>` re-executes a capture's steps + emits structured per-step diff. `history list/show/diff/clear` + `baseline save/list/remove` for managing the capture corpus.
+- **Per-archetype memory cache (Phase 11).** `browser-do --intent "click delete" --pattern '/devices/:id'` looks up cached selector for the `(site, archetype, intent)` triple; on hit, dispatches the existing verb at zero LLM tokens; on miss, emits `cache_miss` event. `browser-do record` for explicit write-back. `browser-do propose` auto-clusters URLs into patterns. Self-heal: 4 consecutive failures disable the cached selector; agent re-resolves + re-records to heal.
+- **Per-action telemetry + balance-triangle audit (Phase 12).** Every adapter call (`open`/`click`/`fill`/`snapshot`/`extract`) emits one OTel-shaped JSONL event to `~/.browser-skill/memory/stats.jsonl` (mode 0600). `browser-stats report --pareto` rolls events into a route × verb table: success rate, post-condition hit rate, token-proxy byte counts, p50 duration, $$ cost (when `CLAUDE_USAGE_*` env injected), 14-value failure-mode histogram (Phase-14 added `unknown_failure` catch-all), and **`oblivious_success` detection** (adapter said ok but post-condition assertion failed — the dominant invisible-error class for browser agents). `browser-stats tune` surfaces worst-performing `(verb, route)` candidates for `/autoresearch` handoff. **`browser-stats prune` (Phase 14)** closes the feedback loop: finds (site, selector) tuples with ≥3 `oblivious_success` events; `--apply` disables the matching cache interactions so cloud LLM re-derives. `browser-stats mark <span> success|fail[:reason]` records user overrides. Schema follows OpenInference + OTel GenAI v1.40 naming for forward-compat with Langfuse/Phoenix/Jaeger via OTLP exporter. See [`references/browser-stats-cheatsheet.md`](references/browser-stats-cheatsheet.md).
+- **Local-VLM cache rescue (Phase 14, Path 3).** 5th tier in the cache defense chain — between Phase-13 fingerprint rescue and cloud-LLM fallback. When `BROWSER_SKILL_VISION_FALLBACK=1` + `BROWSER_SKILL_VISUAL_RESCUE_CMD=<path>` set, browser-do invokes an external hook that probes whether the cached element is still semantically present. Bundled canonical probe `scripts/lib/visual-rescue-default.sh` (text-mode v1) reads the accessibility-tree snapshot + asks a local OpenAI-compatible LLM (default `http://127.0.0.1:8080` — matches `bash scripts/browser-vlm.sh start`) yes/no. Smart-skip when `fail_count ≥ 3` (cache likely fundamentally broken; skip the probe). One env var pair via `bash scripts/browser-vlm.sh install-env` enables everything; lazy-start + 10-min idle-stop watchdog manage the llama-server lifecycle. See [`references/recipes/visual-rescue-hook.md`](references/recipes/visual-rescue-hook.md).
+- **MCP server (Phase 14).** `bash scripts/browser-mcp.sh serve` publishes 5 verbs (open / snapshot / click / fill / extract) over JSON-RPC NDJSON for external agents (Claude Code, midscene, agent-browser, Stagehand, Continue, Cline). TOOLS auto-discovered from each adapter's `tool_capabilities()` + `scripts/lib/node/mcp-tools.json` allowlist — adding a verb to MCP is a 1-JSON-entry change. Env-var passthrough is whitelisted (AP-7: client's `OPENAI_API_KEY` and other foreign secrets are filtered; only `BROWSER_SKILL_*` / `MIDSCENE_MODEL_*` / `CLAUDE_*` / `PLAYWRIGHT_*` / etc inherit). `browser_fill` has no `secret` field and `additionalProperties: false` — secrets stay on the bash entry point via `--secret-stdin`. See [`references/browser-mcp-cheatsheet.md`](references/browser-mcp-cheatsheet.md).
+
+## Security at a glance
+
+- Credentials are on disk only at `$HOME/.browser-skill/` (mode 0700 dir, 0600 files).
+- Credentials never appear on argv, in `ps`, in git, or in the Claude transcript (AP-7 stdin-only pattern enforced via `tests/argv_leak.bats`).
+- Cache writes refuse `PASSWORD-CANARY` sentinel (privacy guard in `browser-do record`).
+- `.gitignore` blocks every credential / session / capture / memory pattern from the repo.
+- `.githooks/pre-commit` rejects any staged file or diff that looks like a credential.
+- See `SECURITY.md` for the full threat model + `references/recipes/{privacy-canary,cache-write-security,path-security}.md` for codified discipline.
+
+## Requirements
+
+**Skill itself (always required):**
+- bash **≥ 5.0** (`brew install bash` on macOS — system bash 3.2 is too old; bash 5.0 needed for `$EPOCHREALTIME` fast path used by the Phase-12 telemetry emitter)
+- `jq`
+- `sqlite3` (Phase 12 — lazy-built SQLite mirror at `memory/stats.db`; standard on macOS and most Linux distros)
+
+**For real browser flows (install at least one):**
+- **chrome-devtools-mcp** (recommended; most-complete adapter): `npx -y chrome-devtools-mcp@latest`
+- **playwright-cli**: `npm i -g playwright @playwright/test @playwright/cli && playwright install chromium`
+- **playwright-lib**: requires `node` + `npm i -g playwright` (driver lazy-imports)
+- **obscura** (single-binary; scrape + stealth-only): download from https://github.com/h4ckf0r0day/obscura/releases
+
+**For tests:** `bats-core` (`brew install bats-core`)
+
+`browser doctor` reports which adapters are present + install hints for missing ones.
+
+## Install
+
+### Personal (one machine, all your projects)
+
+```bash
+git clone https://github.com/xicv/browser-automation-skill ~/Projects/browser-automation-skill
+cd ~/Projects/browser-automation-skill
+./install.sh --with-hooks   # --with-hooks enables the credential-leak pre-commit blocker
+```
+
+Symlinks `~/.claude/skills/browser-automation-skill` → repo. Creates `~/.browser-skill/` mode 0700. Runs `doctor` at the end.
+
+## Verify (in Claude Code)
+
+```
+/browser doctor
+```
+
+Expected: exit 0; final line is a JSON summary with `"status":"ok"`. Doctor also enumerates installed adapters.
+
+## Quickstart
+
+```bash
+# Register your first site
+bash scripts/browser-add-site.sh --name myapp --url 'https://app.example.com'
+bash scripts/browser-use.sh --set myapp
+
+# Open + snapshot (uses chrome-devtools-mcp by default)
+bash scripts/browser-open.sh --url 'https://app.example.com'
+bash scripts/browser-snapshot.sh
+# → emits aria_yaml + eN refs you can pass to click/fill/hover/etc.
+
+# Click a ref
+bash scripts/browser-click.sh --ref e3
+
+# Or click by CSS (cacheable; required for browser-do cache dispatch)
+bash scripts/browser-click.sh --selector 'button.delete'
+
+# Phase 11 cache: record a learned selector once, dispatch zero-LLM-token thereafter
+bash scripts/browser-do.sh record \
+  --site myapp --intent "click delete" \
+  --selector "button.delete" \
+  --url 'https://app.example.com/devices/123'
+
+bash scripts/browser-do.sh \
+  --site myapp --verb click \
+  --intent "click delete" \
+  --pattern '/devices/:id'
+# → cache hit; dispatches click; bumps success_count
+
+# Phase 12 telemetry: every adapter call above emits one stats event automatically.
+# Review the audit:
+bash scripts/browser-stats.sh rebuild
+bash scripts/browser-stats.sh report --days 7 --pareto
+
+# Assert a post-condition so the audit can flag oblivious_success:
+BROWSER_STATS_EXPECT_TYPE=url \
+BROWSER_STATS_EXPECT_MATCH=include \
+BROWSER_STATS_EXPECT_VALUE='/devices/123' \
+  bash scripts/browser-open.sh --url 'https://app.example.com/devices/123'
+```
+
+## Output contract
+
+Every verb prints zero or more streaming JSON lines, then ends with a single-line JSON summary. Parse with `jq`; route on `.status` (`ok`, `partial`, `error`, `empty`, `aborted`).
+
+```bash
+$ bash scripts/browser-doctor.sh | tail -1 | jq .
+{"verb":"doctor","tool":"none","why":"health-check","status":"ok","problems":0,"adapters_ok":4,"duration_ms":42}
+```
+
+## Layout
+
+```
+install.sh              # preflight + state dir + symlink + (opt) hooks
+uninstall.sh            # remove symlink (state preserved)
+SKILL.md                # Claude Code skill manifest (verb table; updated at every phase ship)
+SECURITY.md             # threat model + disclosure
+.gitignore              # blocks credential / session / capture / memory patterns
+.githooks/pre-commit    # credential-leak blocker
+scripts/                # 42 verbs + browser-stats + 7 lib/ + 4 lib/tool/ adapters + lib/node/ driver helpers + lib/fingerprint-rescue.js + lib/migrators/{memory,recent_urls,stats}
+tests/                  # 1002 bats (25 new across Phases 12 + 13); runs in <60s
+references/             # routing-heuristics + recipes (incl. fingerprint-rescue.md) + browser-stats-cheatsheet + stats-schema.json + stats-prices.json
+docs/superpowers/       # design specs + per-phase plan-docs + HANDOFF.md
+```
+
+## Uninstall
+
+```bash
+./uninstall.sh
+```
+
+Removes the `~/.claude/skills/browser-automation-skill` symlink. State at `~/.browser-skill/` is preserved by default.
+
+## Roadmap
+
+See `docs/superpowers/specs/2026-04-27-browser-automation-skill-design.md` for the design and `docs/superpowers/plans/` for executable plans. Current "what's next" lives in `docs/superpowers/HANDOFF.md` (refreshed after every shipped PR).
+
+**v1.2 work ✅ COMPLETE.** Remaining hardening (all opt-in, none blocking): Phase 11 v2 backlog A2-A6 (slug heuristic / `--auto-record` / pattern-equivalence canonicalization / `self_heal_history[]` audit trail / active observation `recent_urls.jsonl`); daemon e2e for playwright-lib selector path; press cache-scope decision codification; Phase 12 backlog (TOON output mode for tabular verbs, plugin-wrapper distribution shape, wire remaining 25 verbs to `stats_run_adapter_emit`); Phase 13 backlog (strong-fingerprint mode that captures dimensions at `browser-do record` time instead of parsing them out of the cached selector string; LLM-judge upgrade for the `semantic` post-condition matcher).

package/SECURITY.md

@@ -0,0 +1,39 @@
+# Security policy
+
+## Threat model
+
+This skill is for single-developer, local-machine use.
+
+### In scope (we defend against)
+- Credentials leaking via argv / `ps` / shell history / git / Claude transcript
+- Captures (HARs / console / screenshots) leaking auth tokens (Phase 7 sanitization)
+- Sessions injected into the wrong origin (Phase 5 origin binding)
+- Accidental commits of any credential-shaped file
+
+### Out of scope
+- Malware on your machine
+- Compromised macOS / Linux kernel
+- OS keychain compromise
+- Compromised upstream tool (Playwright, chrome-devtools-mcp, Obscura)
+- Compromised npm / cargo dependency
+- Targeted nation-state attacker
+
+## Reporting vulnerabilities
+
+Use GitHub Security Advisories (private disclosure path) for any vulnerability. Do **not** open a public issue for security bugs.
+
+PGP key: (TBD on first release).
+
+## Defense layers (full set lands across phases)
+
+| Layer | Phase |
+|---|---|
+| Filesystem perms (0700/0600, umask 077) | 1 |
+| Pre-commit credential-leak blocker | 1 |
+| Process argv invariants (creds via stdin only) | 5 |
+| Origin binding (sessions refuse cross-origin) | 5 |
+| OS keychain backend | 5 |
+| Typed-phrase confirmations for risky paths | 5 |
+| Capture sanitization (HAR + console + DOM) | 7 |
+
+See `docs/superpowers/specs/2026-04-27-browser-automation-skill-design.md` §8 for the full security design.

package/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: browser-automation-skill
+description: Drives a real browser from Claude Code by routing across four backends (chrome-devtools-mcp, playwright-cli, playwright-lib, obscura), so verbs like open/click/fill/scrape/inspect/audit pick the cheapest adapter that supports each operation. Persists credentials, sessions, captures, and per-action telemetry strictly local under $HOME/.browser-skill/ (mode 0700 dir, 0600 files); secrets never appear on argv, in git, or in the Claude transcript. Surfaces a balance-of-tokens-accuracy-latency audit via browser-stats.
+when_to_use: User mentions a browser task — registering a site, capturing a session, verifying a page, filling a form, capturing console errors, running a lighthouse audit, scraping multiple URLs, debugging a UI bug iteratively, replaying a recorded flow, or auditing skill efficiency (browser-stats report/tune).
+argument-hint: [verb] [--site NAME] [--session NAME] [--tool NAME] [--dry-run]
+allowed-tools: Bash(bash *) Bash(jq *) Bash(chmod *) Bash(mkdir *) Bash(stat *) Bash(rm *) Bash(mv *) Bash(cat *) Bash(sqlite3 *) Bash(awk *) Bash(sed *) Bash(grep *) Bash(openssl *) Bash(date *) Bash(wc *) Bash(tr *) Bash(tail *) Bash(head *) Bash(sleep *) Bash(printf *) Bash(python3 *)
+model: sonnet
+effort: low
+---
+
+# browser-automation-skill
+
+Drive a real browser from Claude Code via four routed tools (chrome-devtools-mcp / playwright-cli / playwright-lib / obscura). 42 verbs covering site/session/credential management, navigation, snapshot+ref-based interaction, capture pipelines (console/network/screenshot/Lighthouse), declarative flow runner with replay+diff, a per-archetype memory cache (`browser-do`) that lets agents skip LLM ref-resolution on repeat actions, and per-schema state migration tooling (`browser-migrate`).
+
+## Verbs
+
+### Site + session + credential management
+
+| Verb | What it does | Example |
+|---|---|---|
+| `doctor`        | Health check: deps, state dir mode, disk encryption, adapters | `bash "${CLAUDE_SKILL_DIR}/scripts/browser-doctor.sh"` |
+| `add-site`      | Register a site profile | `… add-site --name prod --url https://app.example.com` |
+| `list-sites`    | List registered sites | `… list-sites` |
+| `show-site`     | Show one site's profile JSON | `… show-site --name prod` |
+| `remove-site`   | Typed-name confirmed delete | `… remove-site --name prod --yes-i-know` |
+| `use`           | Get / set / clear current site | `… use --set prod` |
+| `login`         | Capture a Playwright storageState into a session | `… login --site prod --as prod--admin --interactive` |
+| `list-sessions` | List captured sessions (optionally filter by site) | `… list-sessions --site prod` |
+| `show-session`  | Show session metadata (NEVER cookie/token values) | `… show-session --as prod--admin` |
+| `remove-session`| Typed-name confirmed delete of a captured session | `… remove-session --as prod--admin --yes-i-know` |
+| `creds-add`     | Register credential (smart per-OS backend; AP-7 stdin-only; declares `--auth-flow`) | `printf 'pw' \| … creds-add --site prod --as prod--admin --password-stdin --auth-flow single-step-username-password` |
+| `creds-list`    | List credentials (optional `--site` filter; metadata only) | `… creds-list --site prod` |
+| `creds-show`    | Show credential metadata (NEVER secret unless `--reveal` typed-phrase confirmed) | `… creds-show --as prod--admin` |
+| `creds-remove`  | Typed-name confirmed delete | `… creds-remove --as prod--admin --yes-i-know` |
+| `creds-migrate` | Move credential between backends (fail-safe ordering) | `… creds-migrate --as prod--admin --to keychain --yes-i-know` |
+| `creds-totp`    | Generate current 6-digit TOTP code (RFC 6238) | `… creds-totp --as prod--admin` |
+| `creds-rotate-totp` | Re-enroll TOTP shared secret (typed-phrase confirmed) | `printf '%s' NEW_BASE32 \| … creds-rotate-totp --as prod--admin --totp-secret-stdin --yes-i-know` |
+
+### Navigation + interaction
+
+| Verb | What it does | Example |
+|---|---|---|
+| `open`          | Open a URL in the picked browser adapter | `… open --url https://app.example.com` |
+| `snapshot`      | Capture an `eN`-indexed accessibility snapshot | `… snapshot` |
+| `click`         | Click element by `--ref eN` or `--selector CSS` | `… click --ref e3` |
+| `fill`          | Fill input — `--text VALUE` or `--secret-stdin`; `--ref eN` or `--selector CSS` | `… fill --ref e3 --text "search query"` |
+| `hover`         | Pointer hover — `--ref eN` or `--selector CSS` | `… hover --ref e5` |
+| `press`         | Keyboard key (Enter, Tab, Cmd+S, etc.) — focused element | `… press --key Enter` |
+| `select`        | Pick option from `<select>` — `--ref eN`/`--selector CSS` + `--value`/`--label`/`--index` | `… select --ref e7 --value US` |
+| `drag`          | Drag from `--src-ref` to `--dst-ref` | `… drag --src-ref e3 --dst-ref e9` |
+| `wait`          | Wait for selector / state | `… wait --selector .toast --state visible --timeout 5000` |
+| `upload`        | Upload file to `<input type=file>` ref | `… upload --ref e2 --file path.png` |
+| `route`         | Network mock / fulfill pattern | `… route --pattern '*/api/users' --status 200 --body '{}'` |
+| `tab-list`      | List open tabs | `… tab-list` |
+| `tab-switch`    | Switch active tab | `… tab-switch --to tab2` |
+| `tab-close`     | Close a tab | `… tab-close --to tab2` |
+
+### Capture + extract + audit
+
+| Verb | What it does | Example |
+|---|---|---|
+| `inspect`       | Page inspection — `--capture-console`, `--capture-network`, `--screenshot`, `--selector` (multi-flag aggregation; sanitized HAR + console; cdt-mcp real-mode) | `… inspect --capture-console --capture-network --capture` |
+| `audit`         | Lighthouse / perf-trace audit (cdt-mcp real-mode) | `… audit --lighthouse` |
+| `extract`       | Selector or JS extraction — `--selector CSS` / `--eval JS` (cdt-mcp); `--scrape u1 u2 ...` / `--stealth URL --eval EXPR` (obscura) | `… extract --selector .title` · `… extract --scrape https://a https://b --format json` |
+| `assert`        | Assertion — `--selector` + `--text-contains` predicate | `… assert --selector .toast-success --text-contains "Saved"` |
+
+### Flow runner
+
+| Verb | What it does | Example |
+|---|---|---|
+| `flow run`      | Execute a `.flow.yaml` file (declarative steps; `${var}` + `${refs.NAME}` templating; whole-flow capture) | `… flow run task.flow.yaml --var url_path=/users` |
+| `flow record`   | Wrap `playwright codegen`; emit `.flow.yaml`; password-canary write-side | `… flow record --site prod --out task.flow.yaml` |
+| `replay`        | Re-execute a capture's steps; structured per-step diff | `… replay 042 --strict` |
+| `history list`  | Enumerate captures (newest first) | `… history list --limit 10` |
+| `history show`  | Show one capture's meta + steps | `… history show 042` |
+| `history diff`  | Diff two captures' step events | `… history diff 041 042` |
+| `history clear` | Manual prune (`--keep N` / `--days D` / `--not-baseline`); honors `is_baseline:true` skip-rule | `… history clear --keep 100` |
+| `baseline save` | Mark capture as baseline (`meta.is_baseline:true` + `baselines.json` entry) | `… baseline save 042 --as after-redesign` |
+| `baseline list` | List named baselines | `… baseline list` |
+| `baseline remove` | Remove baseline marker (capture dir untouched) | `… baseline remove after-redesign --yes-i-know` |
+
+### Telemetry / audit / tuning (`browser-stats`)
+
+| Verb | What it does | Example |
+|---|---|---|
+| `stats rebuild`  | Tail `memory/stats.jsonl` from cursor → upsert into `memory/stats.db`. Idempotent; builds schema on first run. | `bash scripts/browser-stats.sh rebuild` |
+| `stats report`   | Human-readable per-route × verb summary: success rate, post-condition hit-rate, p50 token-proxy bytes, avg duration, failure-mode histogram, oblivious_success count, cost ($) when `CLAUDE_USAGE_*` env injected. `--pareto` adds composite efficiency score. | `bash scripts/browser-stats.sh report --days 7 --pareto` |
+| `stats mark`     | User override: record `success` / `fail[:reason]` for one `span_id`. Audit-report applies overrides over self-reported outcomes. | `bash scripts/browser-stats.sh mark a1b2c3d4e5f6a7b8 fail:wrong_element_acted` |
+| `stats tune`     | Surface worst-performing `(verb, route)` candidates over last N days for `/autoresearch` handoff. Human-in-loop — never auto-mutates the skill. | `bash scripts/browser-stats.sh tune --days 30` |
+
+Per-action events are emitted automatically by `open`, `click`, `fill`,
+`snapshot`, and `extract` (covering all 4 routes). Adding emission to a new
+verb = 3 lines (see [`references/browser-stats-cheatsheet.md`](references/browser-stats-cheatsheet.md)).
+Schema: [`references/stats-schema.json`](references/stats-schema.json) — follows
+OpenInference + OTel GenAI v1.40 conventions for forward-compat with
+Langfuse/Phoenix/Jaeger exporters.
+
+### Memory cache (`browser-do`)
+
+| Verb | What it does | Example |
+|---|---|---|
+| `do --intent`   | Look up cached selector for `(site, archetype, intent)`; on hit dispatch existing verb (zero LLM tokens); on miss emit `cache_miss` event | `… do --site prod --verb click --intent "click delete" --pattern '/devices/:id'` |
+| `do record`     | Explicit cache write-back; auto-derives pattern + archetype-id; refuses `PASSWORD-CANARY` | `… do record --site prod --intent "click delete" --selector "button.delete" --url 'https://prod/devices/123'` |
+| `do propose`    | Auto-cluster URLs into URL patterns (`:id`, `:uuid`); emits proposals for clusters >= threshold; suppresses already-known | `… do propose --site prod --threshold 3 --url 'https://x/devices/1' --url '...'` |
+
+### Schema migration (`browser-migrate`)
+
+| Verb | What it does | Example |
+|---|---|---|
+| `migrate check`         | Read-only — enumerate pending migrations (one `_kind:migration_needed` event per registered migrator with current schema_version == from). No lock acquired; safe to call any time (and `doctor` does). | `bash scripts/browser-migrate.sh check` |
+| `migrate status`        | Echo current per-schema versions from `~/.browser-skill/versions.json`. Read-only. | `bash scripts/browser-migrate.sh status` |
+| `migrate run`           | Apply registered migrators. Atomic-swap + automatic backup; refuses bump on JSON validation failure. Destructive: requires `--yes` flag OR interactive typed-phrase `migrate now`. `--schema NAME` narrows scope. PID-tracked lock prevents concurrent runs. | `bash scripts/browser-migrate.sh run --yes --schema memory` |
+| `migrate rollback`      | Restore one schema from its most-recent backup. Requires `--schema NAME`. Destructive: requires `--yes` OR typed-phrase `migrate rollback <schema>`. | `bash scripts/browser-migrate.sh rollback --schema memory --yes` |
+| `migrate clean-backups` | Prune old backups; keep newest `--keep N` per schema (default 5). Destructive: requires `--yes` OR typed-phrase `clean backups`. | `bash scripts/browser-migrate.sh clean-backups --keep 3 --yes` |
+
+## Migration & schema evolution
+
+Skill state (`~/.browser-skill/`) is versioned per-schema (`versions.json`). Each schema (sites / sessions / credentials / captures / baselines / memory / config) carries its own `schema_version`; migrating one doesn't touch the others. When the skill ships a schema bump, it lands a migrator under `scripts/lib/migrators/<schema>/v<from>_to_<to>.sh`; the migrator becomes pending on every machine until the user runs `browser-migrate run`.
+
+Key invariants:
+- **Doctor never auto-migrates.** It only surfaces pending count as a `warn:` line; user runs `browser-migrate run` explicitly.
+- **Atomic-swap + automatic backup.** Each migrated file is backed up to `backups/<schema>/<basename>.bak.v<prior_version>` (mode 0600) before the migrator runs. JSON validation via `jq -e .` precedes the version bump; failure restores from backup.
+- **Manual rollback.** Single-step `rollback --schema NAME` restores from the newest backup. Multi-version chains require multiple invocations.
+- **Lock file** (`~/.browser-skill/.migrate.lock`) prevents concurrent runs; stale PID auto-cleared.
+
+Today's only real migration is the no-op `memory v1_to_v2` identity bump (bumps `schema_version` from 1 to 2; no data shape change). Future per-schema migrators land case-by-case (~30 LOC + ~3 bats per new migrator).
+
+`${CLAUDE_SKILL_DIR}` is the absolute path Claude Code injects when invoking the skill — symlink under `~/.claude/skills/`.
+
+`${CLAUDE_SKILL_DIR}` is the absolute path that Claude Code injects when it
+invokes the skill — it points at the symlink under `~/.claude/skills/`. Use it
+in command examples so they work whether the user installed at `--user` or
+`--project` scope.
+
+## Agent-workflow recipes (end-to-end command sequences)
+
+See [`references/recipes/agent-workflows/`](references/recipes/agent-workflows/README.md) for tutorial-shaped walkthroughs:
+
+- [`login-then-scrape.md`](references/recipes/agent-workflows/login-then-scrape.md) — first task: register site, capture session, bulk scrape
+- [`incremental-pattern-discovery.md`](references/recipes/agent-workflows/incremental-pattern-discovery.md) — passive observation → propose → cache-hit loop end-to-end
+- [`flow-record-and-replay.md`](references/recipes/agent-workflows/flow-record-and-replay.md) — capture a manual interaction, replay, diff against baseline
+- [`cache-driven-bulk-operation.md`](references/recipes/agent-workflows/cache-driven-bulk-operation.md) — 50+ actions at zero LLM tokens (ROI proof)
+
+For pattern recipes (codified discipline: privacy-canary, path-security, cache-write-security, etc.) see [`references/recipes/`](references/recipes/).
+
+## Tools
+
+The skill routes verbs to one of these underlying tools (precedence is decided
+by [router.sh](scripts/lib/router.sh); see [routing heuristics](references/routing-heuristics.md)
+for the rules):
+
+<!-- BEGIN AUTOGEN: tools-table — generated by scripts/regenerate-docs.sh -->
+| Tool | Strengths | Cheatsheet |
+|---|---|---|
+| chrome-devtools-mcp | declares 18 verbs | [references/chrome-devtools-mcp-cheatsheet.md](references/chrome-devtools-mcp-cheatsheet.md) |
+| obscura | declares 1 verbs | [references/obscura-cheatsheet.md](references/obscura-cheatsheet.md) |
+| playwright-cli | declares 4 verbs | [references/playwright-cli-cheatsheet.md](references/playwright-cli-cheatsheet.md) |
+| playwright-lib | declares 5 verbs | [references/playwright-lib-cheatsheet.md](references/playwright-lib-cheatsheet.md) |
+<!-- END AUTOGEN: tools-table -->
+
+## Before running anything
+
+If `doctor` reports `~/.browser-skill` missing, run `./install.sh` (or
+`./install.sh --with-hooks` for the credential-leak blocker).
+
+`doctor` also surfaces (advisory; never fails):
+
+- **Pending schema migrations** — `warn: N pending migration(s) — run 'browser-migrate check' for details`.
+  Doctor never auto-migrates (MIG4 invariant from Phase 10 design); apply via `browser-migrate run`.
+- **Memory cache hit-rate** — `ok: memory cache hit rate: X% (H/T events)` once
+  `browser-do --intent` has run at least once (writer landed in Phase 11 v2 part 1;
+  events.jsonl is lazy-created mode 0600 inside the mode-0700 memory dir).
+  Cheapest daily ROI signal: high hit-rate = the cache is paying for itself; low/empty = repetition isn't compounding yet.
+
+## Output contract
+
+Every verb prints zero or more streaming JSON lines, then ends with a
+single-line JSON summary. Parse with jq; route on `.status` (`ok`,
+`partial`, `error`, `empty`, `aborted`).
+
+```
+$ bash scripts/browser-doctor.sh | tail -1 | jq .
+{"verb":"doctor","tool":"none","why":"health-check","status":"ok","problems":0,"duration_ms":42}
+```
+
+## Storage layout
+
+```
+~/.browser-skill/                       # mode 0700
+├── version                              # schema marker
+├── config.json                          # mode 0600; retention thresholds
+├── current                              # current site name (mode 0600, [personal])
+├── baselines.json                       # mode 0600; named baseline registry (Phase 9)
+├── sites/    <name>.json + .meta.json   # mode 0600 ([shareable])
+├── sessions/ <name>.json + .meta.json   # mode 0600 ([PERSONAL — gitignored])
+├── credentials/                         # Phase 5 (keychain / libsecret / plaintext)
+├── captures/  <NNN>/                    # Phase 7 (snapshot.json, console.json, network.har, steps.jsonl, meta.json)
+└── memory/    <site>/                   # Phase 11 ([PERSONAL — gitignored])
+    ├── patterns.json                    # mode 0600; URL pattern → archetype-id
+    └── archetypes/<id>.json             # mode 0600; cached interactions per archetype
+```
+
+## Roadmap
+
+See `docs/superpowers/specs/2026-04-27-browser-automation-skill-design.md` for
+the full design and `docs/superpowers/plans/` for phase plans.

package/bin/cli.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// bin/cli.mjs — symlink-safe entry-point for the browser-automation-skill MCP
+// server. npm installs this file as ~/.../.bin/browser-automation-skill via
+// a symlink; the bash script we delegate to (scripts/browser-mcp.sh) uses
+// `cd "$(dirname ...)" && pwd` which does NOT resolve the symlink and would
+// look for scripts/lib/common.sh inside .bin/ if invoked directly.
+//
+// import.meta.url is resolved by Node against the realpath of the loaded
+// module, so fileURLToPath(...) here returns this file's true location
+// inside the published package — letting us reliably locate scripts/.
+//
+// We forward argv + stdio so the spawned bash process speaks JSON-RPC
+// over the same stdio channel its MCP client opened to us.
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(here, '..');
+const script = resolve(pkgRoot, 'scripts/browser-mcp.sh');
+
+if (!existsSync(script)) {
+  console.error(
+    `browser-automation-skill: missing entry script at ${script}.\n` +
+      'Reinstall the package or report a packaging bug.'
+  );
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const child = spawn('bash', [script, ...(args.length ? args : ['serve'])], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('error', (err) => {
+  console.error(`browser-automation-skill: failed to spawn bash: ${err.message}`);
+  process.exit(127);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(sig, () => {
+    if (!child.killed) child.kill(sig);
+  });
+}

package/install.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# install.sh — preflight + state dir + symlink + (opt) git hooks. Idempotent.
+set -euo pipefail
+IFS=$'\n\t'
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/lib/common.sh
+# shellcheck disable=SC1091
+source "${REPO_ROOT}/scripts/lib/common.sh"
+
+WITH_HOOKS=0
+DRY_RUN=0
+MODE=user   # phase-1 only supports --user; --project arrives in a later phase
+
+usage() {
+  cat <<'USAGE'
+Usage: ./install.sh [options]
+
+  --user           (default) symlink to ~/.claude/skills/, state at ~/.browser-skill/
+  --with-hooks     enable .githooks/pre-commit credential-leak blocker
+  --dry-run        print what would happen, change nothing
+  -h, --help       this message
+USAGE
+}
+
+for arg in "$@"; do
+  case "${arg}" in
+    --user)        MODE=user ;;
+    --with-hooks)  WITH_HOOKS=1 ;;
+    --dry-run)     DRY_RUN=1 ;;
+    -h|--help)     usage; exit 0 ;;
+    *)             warn "ignoring unknown arg: ${arg}" ;;
+  esac
+done
+
+preflight() {
+  command -v jq >/dev/null 2>&1 || die "${EXIT_PREFLIGHT_FAILED}" "jq required but not found. Remediation: brew install jq (macOS) or apt install jq (Debian)"
+  ok "jq found: $(command -v jq)"
+  command -v python3 >/dev/null 2>&1 || die "${EXIT_PREFLIGHT_FAILED}" "python3 required but not found"
+  ok "python3 found: $(command -v python3)"
+  local major="${BASH_VERSINFO[0]:-0}"
+  [ "${major}" -ge 4 ] || die "${EXIT_PREFLIGHT_FAILED}" "bash >= 4 required (have ${BASH_VERSION}). Remediation: brew install bash"
+  ok "bash version: ${BASH_VERSION}"
+}
+
+ok "browser-automation-skill installer (mode=${MODE} dry-run=${DRY_RUN})"
+preflight
+
+if [ "${DRY_RUN}" = "1" ]; then
+  init_paths
+  ok "dry-run: would create ${BROWSER_SKILL_HOME} and symlink to ${HOME}/.claude/skills/browser-automation-skill"
+  exit 0
+fi
+
+init_paths
+
+create_state_dir() {
+  mkdir -p \
+    "${BROWSER_SKILL_HOME}" \
+    "${SITES_DIR}" \
+    "${SESSIONS_DIR}" \
+    "${CREDENTIALS_DIR}" \
+    "${CAPTURES_DIR}" \
+    "${FLOWS_DIR}"
+  chmod 700 \
+    "${BROWSER_SKILL_HOME}" \
+    "${SITES_DIR}" \
+    "${SESSIONS_DIR}" \
+    "${CREDENTIALS_DIR}" \
+    "${CAPTURES_DIR}" \
+    "${FLOWS_DIR}"
+  # Defense in depth: if this dir ever ends up inside a git repo, ignore it.
+  printf '*\n' > "${BROWSER_SKILL_HOME}/.gitignore"
+  # Schema version marker.
+  printf '1\n' > "${BROWSER_SKILL_HOME}/version"
+  # Phase 7 part 1-v: default capture-retention config. Idempotent — never
+  # overwrite an existing user-edited config. Defaults per parent spec §4.5.
+  if [ ! -f "${CONFIG_FILE}" ]; then
+    cat > "${CONFIG_FILE}" <<'EOF'
+{
+  "schema_version": 1,
+  "retention_days": 14,
+  "retention_count": 500,
+  "warn_at_pct": 90
+}
+EOF
+    chmod 600 "${CONFIG_FILE}"
+  fi
+  ok "state dir ready: ${BROWSER_SKILL_HOME}"
+}
+
+create_state_dir
+
+install_symlink() {
+  local skills_dir="${HOME}/.claude/skills"
+  local link="${skills_dir}/browser-automation-skill"
+  mkdir -p "${skills_dir}"
+
+  if [ -L "${link}" ]; then
+    ln -sfn "${REPO_ROOT}" "${link}"
+    ok "updated existing symlink: ${link} -> ${REPO_ROOT}"
+  elif [ -e "${link}" ]; then
+    die "${EXIT_PREFLIGHT_FAILED}" "${link} exists and is not a symlink; refusing to overwrite. Move it aside and re-run."
+  else
+    ln -s "${REPO_ROOT}" "${link}"
+    ok "created symlink: ${link} -> ${REPO_ROOT}"
+  fi
+}
+
+install_symlink
+
+if [ "${WITH_HOOKS}" = "1" ]; then
+  bash "${REPO_ROOT}/scripts/install-git-hooks.sh"
+fi
+
+ok "running doctor..."
+doctor_rc=0
+doctor_out="$(bash "${REPO_ROOT}/scripts/browser-doctor.sh" 2>&1)" || doctor_rc=$?
+printf '%s\n' "${doctor_out}"
+
+# Count adapters_ok from the doctor JSON summary line (last line).
+adapters_ok="$(printf '%s\n' "${doctor_out}" | tail -1 | jq -r '.adapters_ok // 0' 2>/dev/null || printf '0')"
+
+ok "install complete; next steps:"
+ok "  1. /browser doctor       (verify in Claude Code)"
+ok "  2. /browser add-site --name NAME --url URL    (register your first site)"
+ok "  3. /browser use --set NAME    (set as current)"
+
+if [ "${doctor_rc}" -ne 0 ]; then
+  warn "doctor reported issues (exit ${doctor_rc}); run 'bash scripts/browser-doctor.sh' to review"
+fi
+
+# v1-polish: when no adapters installed, surface the install-adapter guidance
+# explicitly so first-time users don't have to decode the doctor JSON.
+if [ "${adapters_ok}" = "0" ] || [ -z "${adapters_ok}" ]; then
+  warn ""
+  warn "no browser adapters installed. install at least one to drive a real browser:"
+  warn "  - chrome-devtools-mcp  (recommended; most-complete):  npx -y chrome-devtools-mcp@latest"
+  warn "  - playwright-cli       (npm; supports headless+headed): npm i -g playwright @playwright/test @playwright/cli && playwright install chromium"
+  warn "  - obscura              (single-binary; scrape+stealth-only): https://github.com/h4ckf0r0day/obscura/releases"
+  warn ""
+  warn "without an adapter: site/session/credential management + cache record + propose work; navigation/interaction/capture verbs return EXIT_TOOL_MISSING (21)."
+fi