browser-automation-skill 0.71.0

package/references/recipes/add-a-tool-adapter.md

@@ -0,0 +1,134 @@
+# Recipe: Add a tool adapter
+
+A 30-minute walkthrough for adding a new browser-automation adapter to the skill. Follow the **Path A** checklist for the initial commit; promote to default in a separate PR via **Path B**.
+
+## When to use this recipe
+
+Use this when adding a new browser-automation tool to the toolbox:
+- `puppeteer`, `playwright-mcp`, `browserless`, etc.
+
+Do NOT use this recipe for:
+- Adding a verb (see `add-a-verb.md`).
+- Changing routing precedence among existing tools (see `change-a-routing-rule.md`).
+
+## Path A — Ship-without-promotion (zero edits to existing .sh files)
+
+The adapter is reachable via `--tool=<name>` but is never the default for any verb. **This is the recommended way to introduce ANY new tool.** Soak-test in real workflows; promote later.
+
+### Checklist
+
+```
+1. Create scripts/lib/tool/<tool>.sh — implement the contract:
+   - Identity (3 fns):   tool_metadata, tool_capabilities, tool_doctor_check
+   - Verb dispatch (8):  tool_open, tool_click, tool_fill, tool_snapshot,
+                         tool_inspect, tool_audit, tool_extract, tool_eval
+                         (return 41 / TOOL_UNSUPPORTED_OP for unsupported.)
+   - tool_metadata.name MUST equal the filename (lint enforces).
+   - tool_metadata.abi_version MUST equal BROWSER_SKILL_TOOL_ABI in common.sh.
+   - The adapter MUST `source "$(dirname "${BASH_SOURCE[0]}")/../output.sh"`
+     so verb output goes through emit_summary / emit_event (lint tier 3 enforces).
+2. Create tests/stubs/<tool> — mock binary; logs argv to ${STUB_LOG_FILE}; returns canned JSON.
+3. Create tests/fixtures/<tool>/ — JSON keyed by sha256(argv joined by NUL).
+4. Create tests/<tool>_adapter.bats — contract conformance + happy-path tests.
+5. Create references/<tool>-cheatsheet.md — usage notes.
+6. Run scripts/regenerate-docs.sh — autogen edits references/tool-versions.md
+   and the marker block in SKILL.md.
+7. Add CHANGELOG entry: [adapter] added <tool> (Path A — opt-in via --tool=<tool>)
+8. Run tests/run.sh and tests/lint.sh — must be green.
+```
+
+### What's NOT touched in Path A
+
+| File | Action |
+|---|---|
+| `scripts/lib/router.sh` | UNTOUCHED — adapter is reachable via `--tool=<name>` only |
+| `scripts/lib/common.sh` | UNTOUCHED |
+| `scripts/lib/output.sh` | UNTOUCHED |
+| `scripts/browser-doctor.sh` | UNTOUCHED — doctor walks `lib/tool/*.sh` automatically |
+| `scripts/browser-<verb>.sh` (any) | UNTOUCHED |
+| `references/routing-heuristics.md` | UNTOUCHED |
+
+## Path B — Promote to default (run AFTER Path A ships)
+
+Once the adapter has been validated via `--tool=<name>` in real workflows, you can promote it to default for one or more verbs.
+
+### Checklist
+
+```
+1. Edit scripts/lib/router.sh — add a rule_<trigger> function and append it to ROUTING_RULES.
+2. Update references/routing-heuristics.md — add a row matching the rule.
+3. Update tests/router.bats — one positive + one negative case for the new rule.
+4. Add CHANGELOG entry: [adapter] promoted <tool> to default for <trigger>.
+```
+
+## File-by-file: what every contributor sees
+
+| File | Path A | Path B |
+|---|---|---|
+| `scripts/lib/tool/<tool>.sh` | **CREATE** | (untouched) |
+| `tests/stubs/<tool>` | **CREATE** | (untouched) |
+| `tests/fixtures/<tool>/` | **CREATE** | (untouched) |
+| `tests/<tool>_adapter.bats` | **CREATE** | (untouched) |
+| `references/<tool>-cheatsheet.md` | **CREATE** | (untouched) |
+| `scripts/lib/router.sh` | (untouched) | **EDIT** (one fn + one array append) |
+| `scripts/lib/common.sh` | (untouched) | (untouched) |
+| `scripts/lib/output.sh` | (untouched) | (untouched) |
+| `scripts/browser-doctor.sh` | (untouched) | (untouched) |
+| `scripts/browser-<verb>.sh` | (untouched) | (untouched) |
+| `references/tool-versions.md` | **AUTOGEN** | (autogen) |
+| `SKILL.md` | **AUTOGEN** (between markers) | (untouched) |
+| `references/routing-heuristics.md` | (untouched) | **EDIT** (one row) |
+| `tests/router.bats` | (untouched) | **EDIT** (positive + negative) |
+| `CHANGELOG.md` | **EDIT** (one line) | **EDIT** (one line) |
+
+**Path A is 5 creates + 2 autogen + 1 changelog line, with zero edits to .sh files in core.**
+
+## Worked example: adding `puppeteer-via-bridge` in 30 minutes
+
+```bash
+# 1. Scaffold from playwright-cli (similar shape)
+cp scripts/lib/tool/playwright-cli.sh scripts/lib/tool/puppeteer.sh
+
+# 2. Edit puppeteer.sh:
+#    - sentinel guard: _BROWSER_TOOL_PUPPETEER_LOADED
+#    - readonly _BROWSER_TOOL_PUPPETEER_BIN="${PUPPETEER_BIN:-puppeteer}"
+#    - tool_metadata.name = "puppeteer", cheatsheet_path = "references/puppeteer-cheatsheet.md"
+#    - tool_capabilities: declare what puppeteer actually supports
+#    - tool_doctor_check: command -v puppeteer; install hint = "npm i -g puppeteer"
+#    - tool_open / tool_click / tool_fill / tool_snapshot / tool_inspect: shell to puppeteer
+#    - tool_audit / tool_extract / tool_eval: return 41
+
+# 3. Stub + fixtures (copy & adapt)
+cp tests/stubs/playwright-cli tests/stubs/puppeteer
+mkdir tests/fixtures/puppeteer
+
+# 4. Test (copy & adapt)
+cp tests/playwright-cli_adapter.bats tests/puppeteer_adapter.bats
+sed -i.bak 's/playwright-cli/puppeteer/g' tests/puppeteer_adapter.bats
+rm tests/puppeteer_adapter.bats.bak
+
+# 5. Cheatsheet
+cp references/playwright-cli-cheatsheet.md references/puppeteer-cheatsheet.md
+# (edit the cheatsheet content for puppeteer specifics)
+
+# 6. Regen autogen docs
+scripts/regenerate-docs.sh all
+
+# 7. Test the lot
+tests/run.sh
+tests/lint.sh
+
+# 8. CHANGELOG
+echo "- [adapter] added puppeteer adapter (Path A — opt-in via --tool=puppeteer)" >> CHANGELOG.md
+
+# 9. Commit
+git add -A
+git commit -m "feat(tool): puppeteer adapter (Path A — opt-in)"
+```
+
+## See also
+
+- [Anti-patterns: tool extension](anti-patterns-tool-extension.md) — what NOT to do.
+- [Tool adapter extension model spec](../../docs/superpowers/specs/2026-04-30-tool-adapter-extension-model-design.md) — the *why*.
+- [Token-efficient adapter output spec](../../docs/superpowers/specs/2026-05-01-token-efficient-adapter-output-design.md) — `eN` refs, capture paths, single-line summaries.
+- [Routing heuristics](../routing-heuristics.md) — current precedence table.

package/references/recipes/agent-workflows/README.md

@@ -0,0 +1,37 @@
+# Agent-workflow recipes
+
+End-to-end command sequences for common browser-automation tasks. Each
+recipe assumes a **fresh `~/.browser-skill/`** (run `./install.sh` first if
+needed) and walks through the full toolchain: site → session → action →
+observation → cache build-up.
+
+These are distinct from the **pattern recipes** in the parent directory
+(`../privacy-canary.md`, `../path-security.md`, etc.), which codify
+discipline ("when adding X, do Y, never Z"). Workflow recipes show
+sequenced commands + expected output for actual user-facing tasks.
+
+## Index
+
+| Recipe | When to read it |
+|---|---|
+| [`login-then-scrape.md`](login-then-scrape.md) | First end-to-end task: register site, capture session, scrape pages. The "hello world" of the skill. |
+| [`incremental-pattern-discovery.md`](incremental-pattern-discovery.md) | Build up the memory cache from a real session. Demonstrates PR #115/#125/#127 loop end-to-end. |
+| [`flow-record-and-replay.md`](flow-record-and-replay.md) | Capture a manual interaction via `flow record`, replay it, diff against a baseline. |
+| [`cache-driven-bulk-operation.md`](cache-driven-bulk-operation.md) | Process 50+ items with zero LLM tokens via the memory cache. The "ROI proof" workflow. |
+
+## Convention
+
+Each recipe:
+- States the **goal** + **outcome** up front (one sentence each).
+- Lists **prerequisites** (assumes clean `~/.browser-skill/`).
+- Walks **numbered steps** with `bash` commands + abbreviated expected output.
+- Ends with **verification** + **next-step** pointers.
+
+Commands are runnable verbatim from any directory with `${CLAUDE_SKILL_DIR}`
+set (or substituting the repo path if running standalone).
+
+## When you're ready to ship
+
+After working through 1-2 recipes end-to-end, the toolchain's full surface
+is in muscle memory. Subsequent agent sessions can read SKILL.md + the
+verb tables instead of stepping through workflows.

package/references/recipes/agent-workflows/cache-driven-bulk-operation.md

@@ -0,0 +1,110 @@
+# Workflow: cache-driven bulk operation
+
+**Goal:** process 50+ items via the memory cache. Demonstrate the ROI of the Phase 11 cache + Phase 11 v2 observation log loop.
+
+**Outcome:** after a one-time learning phase (~3 actions), 50 subsequent actions dispatch with zero LLM ref-resolution. Token cost drops from ~5K × 50 = 250K to ~200 × 50 = 10K (25× reduction; representative ballpark).
+
+## Prerequisites
+
+- Site registered + session captured ([`login-then-scrape.md`](login-then-scrape.md) steps 0-3).
+- Patterns + archetypes set up for the target action ([`incremental-pattern-discovery.md`](incremental-pattern-discovery.md) steps 1-4).
+- A list of 50+ URLs that share the same archetype (e.g. `https://app.acme.com/orders/1001` through `/orders/1050`).
+
+## Steps
+
+### 1. Confirm the cache is primed
+
+```bash
+# Pattern should exist for /orders/:id, archetype orders-id, with at least one
+# intent recorded (e.g. "cancel order").
+jq '.patterns[] | select(.url_pattern == "/orders/:id")' \
+  ~/.browser-skill/memory/acme/patterns.json
+# → 1 row
+
+jq '.interactions[] | select(.intent == "cancel order")' \
+  ~/.browser-skill/memory/acme/archetypes/orders-id.json
+# → 1 row with success_count >= 1
+```
+
+If either is empty, run [`incremental-pattern-discovery.md`](incremental-pattern-discovery.md) first.
+
+### 2. Generate the URL list
+
+```bash
+seq 1001 1050 | sed 's|^|https://app.acme.com/orders/|' > /tmp/order-urls.txt
+wc -l /tmp/order-urls.txt
+# → 50 /tmp/order-urls.txt
+```
+
+### 3. Dispatch in a loop — zero LLM tokens after warm-up
+
+```bash
+bash scripts/browser-use.sh --set acme
+exec 3</tmp/order-urls.txt
+while IFS= read -r url <&3; do
+  bash scripts/browser-do.sh \
+    --site acme --verb click \
+    --intent "cancel order" \
+    --url "${url}" \
+    --as acme--admin 2>&1 | tail -1 | jq -c '{verb, mode, cache_hit, dispatch_rc, url}'
+done
+exec 3<&-
+```
+
+Each iteration emits a one-line JSON summary. Watch `cache_hit:true` repeat 50 times.
+
+### 4. Confirm ROI signal in doctor
+
+```bash
+bash scripts/browser-doctor.sh | grep "memory cache hit"
+# → memory cache hit rate: 96% (50/52 events)
+# (the 2 misses are the warm-up actions from step 1; hits scale linearly)
+```
+
+Or query `events.jsonl` directly:
+
+```bash
+jq -s '
+  {
+    total: length,
+    hits: ([.[] | select(.cache_hit == true)] | length),
+    rate_pct: (([.[] | select(.cache_hit == true)] | length) * 100 / length)
+  }
+' ~/.browser-skill/memory/events.jsonl
+# → {total: 52, hits: 50, rate_pct: 96}
+```
+
+## Self-heal in motion
+
+If the cached selector breaks mid-run (e.g. URL #25 is a different layout):
+
+1. The dispatched `browser-click --selector ...` exits 11 (`EXIT_EMPTY_RESULT`).
+2. `browser-do --intent` catches this on the D1 exit-code whitelist + calls `memory_record_failure`.
+3. After 4 such failures, `disabled:true` flips + `self_heal_history[]` gains a `"disabled"` entry.
+4. Subsequent iterations return `cache_miss reason:intent_not_cached` (disabled is indistinguishable from never-cached per D3).
+5. Agent re-resolves the new selector + calls `browser-do record` → `disabled:false` + `"healed"` entry.
+6. Loop resumes with cache hits.
+
+Inspect the audit trail:
+
+```bash
+jq '.interactions[] | select(.self_heal_history | length > 0)
+    | {intent, self_heal_history}' \
+  ~/.browser-skill/memory/acme/archetypes/orders-id.json
+```
+
+## Numbers worth measuring
+
+Before the dogfood loop, the comparison is theoretical. Run the script for 7 days against a real site you actually use. Then:
+
+- **Cache hit rate per day:** trends upward as patterns are observed + recorded.
+- **Wall-clock per action:** cache hit ≈ adapter dispatch only (50-200ms); cache miss ≈ full snapshot + agent reasoning (5-20s on cdt-mcp).
+- **Token cost per action:** measure with `claude -p` harness (cache hit ≈ <500 input tokens; miss ≈ 3-10K).
+
+The ROI claim ("zero LLM tokens on cache hit") is exact for the skill turn — the parent session may still consume tokens for context that's not skill-related.
+
+## Don't
+
+- **Don't run with `--auto-record` on an unverified corpus.** A bad heuristic match could pollute `patterns.json` with garbage. Validate the propose output first; auto-record after.
+- **Don't assume cache hit means "did the right thing."** Cache hit means "skipped LLM ref-resolution + dispatched verb." Verb-level success (did the click actually cancel the order?) is the verb's exit code, not the cache lookup's status.
+- **Don't run the loop in parallel against the same site.** `browser-do --intent` is single-shot; concurrent runs race on `memory_record_pattern`'s upsert. Serial is the design (PID-locking only on `browser-migrate`).

package/references/recipes/agent-workflows/flow-record-and-replay.md

@@ -0,0 +1,102 @@
+# Workflow: flow record and replay
+
+**Goal:** capture a manual multi-step interaction via `playwright codegen`, replay it, diff against a baseline.
+
+**Outcome:** a `.flow.yaml` file describes a deterministic action sequence; `replay` re-executes it + emits a per-step diff against a captured baseline.
+
+## Prerequisites
+
+- Site registered + session captured (run [`login-then-scrape.md`](login-then-scrape.md) steps 0-3 first).
+- `playwright` installed (`npm i -g playwright @playwright/test && playwright install chromium`).
+- A multi-step task in mind — e.g. "create a new task, assign to me, set priority high."
+
+## Steps
+
+### 1. Record the flow
+
+```bash
+bash scripts/browser-flow.sh record \
+  --site acme --as acme--admin \
+  --out create-task.flow.yaml
+# → opens a browser via `playwright codegen`
+# → perform the multi-step task in the real UI
+# → close the browser; the regex-based JS→YAML mapper emits the .flow.yaml
+```
+
+Password-canary write-side fires automatically (PR for Phase 9 part 1-iii): any field matching `/password/i` becomes `${secrets.password}` placeholder; the literal is dropped from the YAML.
+
+Inspect the result:
+
+```bash
+cat create-task.flow.yaml
+# steps:
+#   - open: { url: "https://app.acme.com/tasks/new" }
+#   - fill: { ref: e3, text: "Ship Pick D recipes" }
+#   - click: { ref: e7 }
+#   - select: { ref: e12, value: "high" }
+#   - click: { ref: e15 }
+#   - assert: { selector: ".toast-success", text-contains: "Created" }
+```
+
+`${refs.NAME}` and `${var}` templating are available; see `docs/superpowers/specs/2026-05-10-phase-09-flow-runner-design.md` for the full schema.
+
+### 2. Run the flow with whole-flow capture
+
+```bash
+bash scripts/browser-flow.sh run create-task.flow.yaml --capture
+# → executes each step; emits one _kind:step JSON event per step
+# → on success: summary line + capture_id NNN
+# → captures all per-step events + final state to ~/.browser-skill/captures/NNN/
+
+# Capture id is in the summary; e.g. capture_id: 042
+```
+
+### 3. Mark this run as a baseline
+
+```bash
+bash scripts/browser-flow.sh baseline save 042 --as after-redesign
+# → ~/.browser-skill/baselines.json gains entry
+# → captures/042/meta.json gets is_baseline:true (skip-rule honored by prune)
+```
+
+### 4. Replay later + diff against baseline
+
+Time passes. Site changes. Re-run + diff:
+
+```bash
+bash scripts/browser-flow.sh run create-task.flow.yaml --capture
+# → new capture_id 043
+
+bash scripts/browser-replay.sh 043 --strict
+# → per-step replay_diff events
+# → exit 13 (ASSERTION_FAILED) on first divergent step under --strict;
+#   exit 0 with non-zero diff count under default mode
+
+bash scripts/browser-flow.sh history diff 042 043
+# → structured per-step diff, with duration_ms stripped before compare
+# (Phase 9 part 1-iv strip-timing-from-semantic-comparison pattern)
+```
+
+The diff stripping ensures timing-sensitive fields don't pollute the comparison — only semantic differences surface.
+
+## Verification
+
+```bash
+bash scripts/browser-flow.sh history list --limit 5
+# → newest-first table; 043 above 042; both with their summary fields
+
+bash scripts/browser-flow.sh baseline list
+# → after-redesign → capture 042
+```
+
+## Variations
+
+- **Re-record after schema change:** the YAML's `${refs.NAME}` references break when the page restructures. Re-record, re-baseline.
+- **Cross-environment replay:** capture against staging, replay against prod — drift the URL via `--var base=https://prod.example.com` if the flow uses `${base}` templating.
+- **Multi-baseline:** keep one baseline per release (`baseline save NNN --as v1.2.3`); compare any new capture against any historical baseline.
+
+## Don't
+
+- **Don't commit `.flow.yaml` files with real secrets in them.** The recorder strips `/password/i` fields, but other sensitive content (API tokens in URL query strings, PII in text values) survives. Inspect every recorded YAML before committing.
+- **Don't `baseline remove` a capture you still need to diff against.** The removal is a typed-phrase-confirmed delete; gone for good.
+- **Don't expect deterministic replay across browser versions.** Playwright codegen-generated refs (`e3`, `e7`, etc.) are snapshot-relative; a major Chromium update may rearrange the accessibility tree. Re-record on upgrade.

package/references/recipes/agent-workflows/incremental-pattern-discovery.md

@@ -0,0 +1,125 @@
+# Workflow: incremental pattern discovery
+
+**Goal:** demonstrate the full passive-observation → propose → cache-hit loop.
+
+**Outcome:** after a few sessions of normal navigation, the skill auto-clusters visited URLs into patterns, stores them in `patterns.json`, and starts serving cache hits on subsequent agent actions.
+
+## Prerequisites
+
+- Site already registered (run [`login-then-scrape.md`](login-then-scrape.md) steps 0-3 if not).
+- At least one cached archetype (or willingness to record one in step 3 below).
+
+## The full loop in 5 steps
+
+### 1. Navigate (passive observation writes `recent_urls.jsonl`)
+
+```bash
+bash scripts/browser-use.sh --set acme
+bash scripts/browser-open.sh --url 'https://app.acme.com/orders/1001'
+bash scripts/browser-open.sh --url 'https://app.acme.com/orders/1002'
+bash scripts/browser-open.sh --url 'https://app.acme.com/orders/1003'
+bash scripts/browser-open.sh --url 'https://app.acme.com/customers/jane-doe'
+bash scripts/browser-open.sh --url 'https://app.acme.com/customers/john-roe'
+bash scripts/browser-open.sh --url 'https://app.acme.com/customers/jim-roe'
+
+cat ~/.browser-skill/memory/recent_urls.jsonl
+# → 6 rows; each {ts, url, verb:"open", site:"acme", schema_version:1}
+```
+
+The tee is automatic on successful `browser-open` (PR #125 Pick A6).
+
+### 2. Propose patterns from the observation log
+
+```bash
+bash scripts/browser-do.sh propose --site acme --from-recent
+# → 2 _kind:proposal events:
+#   {url_pattern:"/orders/:id",      archetype_id:"orders-id",      count:3}
+#   {url_pattern:"/customers/:slug", archetype_id:"customers-slug", count:3}
+# → summary: proposals:2 auto_recorded:0 skipped_known:0
+```
+
+`:id` from PR #97 (11-2-ii numeric heuristic); `:slug` from PR #127 (Pick A2). Neither row written to `patterns.json` yet — `propose` is read-only by default (C5 invariant from 11-2-ii).
+
+### 3. Auto-record the proposals
+
+```bash
+bash scripts/browser-do.sh propose --site acme --from-recent --auto-record
+# → same 2 proposals, but now auto_recorded:2 in summary
+# → patterns.json gains 2 rows
+
+cat ~/.browser-skill/memory/acme/patterns.json | jq '.patterns'
+# → [
+#     {url_pattern:"/orders/:id",      archetype_id:"orders-id",      hit_count:1, ...},
+#     {url_pattern:"/customers/:slug", archetype_id:"customers-slug", hit_count:1, ...}
+#   ]
+```
+
+Re-running with `--auto-record` is idempotent (filter-before-write pattern from PR #121).
+
+### 4. Record an intent against the archetype
+
+Need a cached selector for an action. Snapshot a real page + pick a ref:
+
+```bash
+bash scripts/browser-open.sh --url 'https://app.acme.com/orders/1001'
+bash scripts/browser-snapshot.sh
+# → eN list; find the "cancel order" button's ref, e.g. e12
+
+# Record the intent → selector binding. browser-do record auto-derives
+# the archetype-id from the URL pattern.
+bash scripts/browser-do.sh record \
+  --site acme \
+  --intent "cancel order" \
+  --selector 'button[data-action="cancel"]' \
+  --url 'https://app.acme.com/orders/1001'
+# → patterns.json + archetypes/orders-id.json updated
+```
+
+### 5. Cache hit dispatch (zero LLM tokens)
+
+```bash
+bash scripts/browser-do.sh \
+  --site acme --verb click \
+  --intent "cancel order" \
+  --url 'https://app.acme.com/orders/1002'
+# → cache_hit:true; dispatches click with --selector button[data-action="cancel"]
+# → no snapshot needed; no LLM ref-resolution
+```
+
+Same intent across different URLs of the same archetype → all served by one cached selector.
+
+## Observation
+
+The cache hit + write events both tee into `events.jsonl` (PR #115 Pick A1):
+
+```bash
+jq -c 'select(.cache_hit==true)' ~/.browser-skill/memory/events.jsonl | wc -l
+# → count of cache hits across all browser-do --intent runs
+
+bash scripts/browser-doctor.sh | grep "memory cache hit"
+# → memory cache hit rate: X% (H/T events)
+```
+
+Run the loop on enough URLs and the hit-rate climbs. Design target: ≥70% after 20+ same-archetype actions.
+
+## Self-heal
+
+If a selector breaks (4 consecutive failures), `disabled:true` flips in the archetype JSON + an entry appends to `self_heal_history[]` (PR #119 Pick A5):
+
+```bash
+jq '.interactions[] | select(.self_heal_history | length > 0)' \
+  ~/.browser-skill/memory/acme/archetypes/orders-id.json
+# → array of {ts, event:"disabled"|"healed", fail_count, selector_at_time}
+```
+
+Next `browser-do --intent "cancel order"` returns `cache_miss reason:intent_not_cached` (disabled is indistinguishable from never-cached per D3); agent re-resolves + re-records via step 4, which appends a `"healed"` entry.
+
+## Next steps
+
+- Run [`cache-driven-bulk-operation.md`](cache-driven-bulk-operation.md) to see ROI at scale.
+- Tweak the slug heuristic (`scripts/lib/node/url-pattern-cluster.mjs`) if your site uses non-standard patterns.
+
+## Don't
+
+- **Don't manually edit `patterns.json` or archetype JSONs.** Use `browser-do record` / `memory_record_pattern` (the lib API). Hand edits bypass the canonical-pattern compare (PR #123 Pick A4) and may create redundant rows.
+- **Don't auto-record without reviewing.** First-time run on a new site: omit `--auto-record`, read the proposals, decide. `--auto-record` shines after the heuristics have been validated on the site.

package/references/recipes/agent-workflows/login-then-scrape.md

@@ -0,0 +1,100 @@
+# Workflow: login then scrape
+
+**Goal:** register a site, capture an authenticated session, scrape multiple URLs from it.
+
+**Outcome:** a single `obscura` adapter call returns JSON for N URLs, all using the same logged-in cookie state from a Playwright `storageState`. Zero LLM tokens after step 4.
+
+## Prerequisites
+
+- Clean `~/.browser-skill/` (or skip step 0 if already installed).
+- At least one adapter installed (`chrome-devtools-mcp` recommended for login capture; `obscura` for bulk scrape).
+- The target site has username+password login (TOTP optional).
+
+## Steps
+
+### 0. Install (one-time)
+
+```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 installs the credential-leak pre-commit blocker
+bash scripts/browser-doctor.sh
+# → expect: "ok: all checks passed (4 adapter(s) ok)" if all 4 adapters installed
+```
+
+### 1. Register the site
+
+```bash
+bash scripts/browser-add-site.sh --name acme --url 'https://app.acme.com'
+bash scripts/browser-use.sh --set acme
+# → sticky "current site" set; subsequent verbs can omit --site
+```
+
+### 2. Store credentials (stdin-only; never on argv)
+
+```bash
+printf '%s' 'your-password' | bash scripts/browser-creds-add.sh \
+  --site acme --as acme--admin \
+  --password-stdin \
+  --auth-flow single-step-username-password
+# → keychain (macOS) or libsecret (Linux) by default; plaintext requires typed-phrase
+```
+
+If TOTP is required:
+
+```bash
+printf '%s' 'BASE32SECRET' | bash scripts/browser-creds-add.sh \
+  --site acme --as acme--admin \
+  --totp-secret-stdin \
+  --auth-flow single-step-username-password-with-totp
+```
+
+### 3. Interactive login (one-time; captures `storageState`)
+
+```bash
+bash scripts/browser-login.sh \
+  --site acme --as acme--admin \
+  --interactive
+# → opens a real browser; fill the login form; press Enter in the terminal
+# → captures cookies + localStorage into ~/.browser-skill/sessions/acme--admin.json
+```
+
+After this, all subsequent verbs can pass `--as acme--admin` to reuse the session.
+
+### 4. Bulk scrape
+
+```bash
+bash scripts/browser-extract.sh --site acme --as acme--admin \
+  --scrape \
+    'https://app.acme.com/orders/1001' \
+    'https://app.acme.com/orders/1002' \
+    'https://app.acme.com/orders/1003' \
+  --eval 'document.querySelector(".order-total")?.textContent' \
+  --format json
+# → streams 3 JSON events (one per URL) + a summary line
+# → routed to obscura adapter via the rule_scrape_flag router rule
+```
+
+## Verification
+
+```bash
+# Confirm session was captured + is mode 0600.
+bash scripts/browser-list-sessions.sh --site acme
+# → table includes acme--admin
+
+# Confirm session file mode.
+ls -la ~/.browser-skill/sessions/
+# → expect: -rw------- (mode 0600) on acme--admin.json
+```
+
+## Next steps
+
+- Want to scrape 50+ URLs? See [`cache-driven-bulk-operation.md`](cache-driven-bulk-operation.md).
+- Want to record + replay a multi-step interaction? See [`flow-record-and-replay.md`](flow-record-and-replay.md).
+- The login flow auto-detects 2FA prompts; for non-interactive re-login, see `browser-login.sh --help`.
+
+## Don't
+
+- **Don't pass `--password` or `--totp` on argv.** Always use `--password-stdin` / `--totp-secret-stdin`. The pre-commit hook + tests/argv_leak.bats enforce this; bypassing leaks secrets into `ps`, shell history, and the Claude transcript.
+- **Don't commit `~/.browser-skill/`** to git. `.gitignore` blocks the pattern; verify with `git check-ignore ~/.browser-skill/credentials/foo.json`.
+- **Don't store credentials with `--backend plaintext`** unless the typed-phrase confirms understanding. Keychain (macOS) / libsecret (Linux) is the default — let it stay default.