@browserbridge/bbx 1.8.0 → 1.10.0

package/skills/browser-bridge/SKILL.md

@@ -14,6 +14,8 @@ Permission prompts are controlled by the host agent, not by Browser Bridge. In p
 Skill name: `browser-bridge` (also known as `bbx`). In GitHub Copilot, invoke as `/browser-bridge`. `bbx` is the CLI command used throughout this skill.
 When the runtime supports subagents, delegate bridge inspection to a smaller, lower-cost worker and return only concise findings to the parent.
 For open-ended investigation, start with structured reads (`page.get_state`, `dom.query`, `page.get_text`, `page.extract_content`, `styles.get_computed`, and `bbx batch` for CLI or `browser_batch` for MCP) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient. `browser_call` accepts one protocol method at a time; `batch` is not a valid `browser_call` method.
+When an unfamiliar method is needed, run `bbx protocol describe <method|group>` before guessing parameters. In MCP mode, call `browser_call` with method `protocol.describe` and params `{ "method": "dom.query" }` or `{ "group": "inspect" }`.
+MCP exposes common tools first. Load one specialized typed tool only when needed by calling `browser_toolset` with its exact name, for example `{ "tool": "browser_dom" }`; `browser_call` remains the universal fallback.
 
 ## CLI
 
@@ -32,6 +34,7 @@ bbx tab-create [url]        # open a new tab (avoid unless necessary)
 bbx tab-close <tabId>       # close a tab
 bbx tab-activate <tabId>    # bring a tab to the foreground
 bbx skill                   # live runtime presets + limits
+bbx protocol describe [method|group] # local method params or compact group index
 ```
 
 Use the globally installed `bbx` command or `node packages/agent-client/src/cli.js ...` for live readiness checks from this repository. Avoid `rtk npm exec -- bbx status` as a health signal: that path can restart/replace the daemon and report `Extension: disconnected` before Chrome reconnects. If it happens, wait a few seconds and verify with `bbx status`.
@@ -59,11 +62,13 @@ bbx a11y-tree [maxNodes] [maxDepth]  # accessibility tree
 bbx eval [--await] <expression>      # JS eval (--await for promises, - for stdin)
 bbx console [level]                  # console output
 bbx network [limit]                  # recent fetch/XHR requests
+bbx har [options] [outPath]          # export armed CDP capture as sanitized HAR 1.2
 bbx intercept add <pattern> [--respond <body>] [--status <code>] [--block]  # intercept matching requests
 bbx intercept list|remove <id>|clear # manage interception rules
 bbx page-text [budget]               # full page text
-bbx storage [local|session] [keys]   # browser storage
-bbx perf                             # performance metrics
+bbx storage [local|session] [keys]   # storage key/presence metadata
+bbx call sensitive.read '{"source":"local_storage","key":"name"}' # deliberate exact value
+bbx perf                             # raw Chrome/CDP counter point sample
 bbx navigate <url>                   # navigate to URL
 bbx reload                           # reload current page
 bbx back                             # navigate back
@@ -145,7 +150,7 @@ After access is enabled:
 | `DIALOG_ACTION_CONFLICT`  | No       | Inspect current dialog state; never auto-repeat accept/dismiss                            |
 | `TAB_MISMATCH`            | No       | Tab closed or not found - use `tabs.list` to find an available tab                        |
 | `TIMEOUT`                 | Once     | Retry once; if still failing, simplify (smaller `maxNodes`, narrower selector)            |
-| `RATE_LIMITED`            | After 2s | Back off 2 seconds, then retry                                                            |
+| `CONTENT_SCRIPT_UNAVAILABLE` | No     | Switch to a normal http(s) page in the enabled window                                    |
 | `EXTENSION_DISCONNECTED`  | After 3s | Check Chrome is running; `bbx status` to verify, then retry                               |
 | `NATIVE_HOST_UNAVAILABLE` | No       | Run `bbx doctor` to diagnose the installation                                             |
 | `INTERNAL_ERROR`          | Once     | Retry once; if persistent, check `page.get_console` for details                           |
@@ -155,6 +160,13 @@ After access is enabled:
 
 Error responses now include a machine-readable `error.recovery` field with `retry`, `retryAfterMs`, `alternativeMethod`, and `hint`.
 
+`health.ping`, `daemon.metrics`, and `bbx doctor` also expose process-local
+five-minute recovery summaries for six fixed, content-free categories. Three
+failures in the same hidden group within 60 seconds marks an active loop. Stop
+repeating the action and follow Doctor's fixed category guidance. Extension
+summaries reset on service-worker restart and daemon summaries on daemon restart;
+they contain no page data, URLs, selectors, payloads, errors, or group names.
+
 ## Core Rules
 
 1. **Work in existing tabs** - Never create new tabs unless the user explicitly asks for it, or the task absolutely requires a fresh page (e.g., testing a clean state, comparing across URLs). Prefer `tabs.list` to find an appropriate existing tab.
@@ -168,7 +180,8 @@ Error responses now include a machine-readable `error.recovery` field with `retr
 9. **Batch reads** - combine independent reads with `bbx batch` in CLI mode or `browser_batch` in MCP mode; do not pass `batch` as a `browser_call` method.
 10. **Avoid debugger first** - prefer DOM/content-script methods (`dom.*`, `styles.*`, `layout.get_box_model`, `page.get_console`, `page.get_text`, `page.get_storage`, `page.get_network`) before any debugger-backed method. Escalate to CDP only when those cannot answer the question.
 11. **Evaluate only when needed** - `page.evaluate` is powerful but debugger-backed; use it only when DOM, storage, console, network, or text reads cannot expose the needed state.
-12. **Debugger-backed methods are last resort** - treat `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, `page.get_network` with `source: 'cdp'`, input with `executionMode: 'cdp'`, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and all `cdp.*` methods as escalation steps because they attach `chrome.debugger`.
+12. **Treat exact storage as sensitive** - use `page.get_storage` for metadata first. Call `sensitive.read` for one exact key only when necessary; never batch or automatically retry it, and never repeat a failed attempt without new evidence.
+12. **Debugger-backed methods are last resort** - treat `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, `page.get_network` with `source: 'cdp'`, input with `executionMode: 'cdp'`, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and all `cdp.*` methods as escalation steps because they attach `chrome.debugger`. `performance.get_metrics` is a raw browser-maintained CDP counter point sample, not Web Vitals.
 13. **Wait after change** - after editing source, wait for expected new text, a selector matching the changed attribute, or a detach/attach remount; waiting for `attached` on a selector that already exists does not prove HMR ran. Use `page.wait_for_load_state` for navigation, not HMR.
 14. **Prime event buffers** - before reproducing a console or fetch/XHR issue, call `page.get_console` and default `page.get_network` once with `clear: true`; then reproduce and read without clearing. CDP all-resource capture instead requires explicit `start`, reproduce, `read`, and `stop` calls.
 15. **Semantic finding** - use `dom.find_by_text` / `dom.find_by_role` when you know the label but not the selector.
@@ -180,6 +193,8 @@ Error responses now include a machine-readable `error.recovery` field with `retr
 21. **Do not guess input targets** - for targeted click, focus, type, fill, press-key, checked-state, option-selection, hover, and drag calls, honor actionability errors and returned `resolution` metadata. `cdp_press_key` and `scroll_into_view` use separate contracts. `executionMode` is only `dom` or `cdp`; `input.fill.mode: auto` is a separate DOM setter/keystroke strategy.
 22. **Stale recovery stays opt-in** - prefer re-querying. Use `recoverStale: true` once only when the same document/URL and a strong unique semantic descriptor should still identify the target; inspect `recovered`, old/new refs, and matched fields. A scan with more than 100 same-tag candidates fails as `ELEMENT_AMBIGUOUS`/`scan_incomplete` because uniqueness is not provable.
 23. **Dialogs are explicit** - inspect first, then accept or dismiss only when intended. `expectedDialogId` is a pre-dispatch stale-decision check, not an atomic CDP binding; never auto-repeat `DIALOG_ACTION_CONFLICT`.
+24. **DOM diffs use explicit baselines** - call `dom.baseline.create` before the action, `dom.baseline.compare` afterward, then `dom.baseline.release`. Use a narrow selector and bounded evidence. Never substitute unrelated DOM reads for the retained baseline, and recreate it after `DOM_BASELINE_INVALIDATED`.
+25. **HAR export reads an armed capture** - use CDP capture `start`, reproduce, `network.export_har`/`bbx har`, then `stop`. Export never starts, stops, or clears capture. Inspect truncation plus `dropped`, `abandoned`, and `inflight` before claiming completeness.
 
 ## Token Budget Quick Rules
 
@@ -251,12 +266,12 @@ bbx page-text 2000                                  # extract page content
 | Find        | `dom.find_by_text`, `dom.find_by_role`, `dom.wait_for`, `dom.get_accessibility_tree`                                                                |
 | Page State  | `page.get_console`, `page.get_storage`, `page.get_text`, `page.wait_for_load_state`, `page.evaluate` (debugger-backed)                              |
 | Dialogs     | `page.handle_dialog` (debugger-backed; explicit inspect/accept/dismiss only)                                                                  |
-| Network     | `page.get_network` (fetch/XHR default; optional CDP lifecycle), `network.intercept.add/remove/list/clear` (debugger-backed)                         |
+| Network     | `page.get_network` (fetch/XHR default; optional CDP lifecycle), `network.export_har`, `network.intercept.add/remove/list/clear` (debugger-backed)   |
 | Interact    | `input.click`, `input.type`, `input.fill`, `input.focus`, `input.press_key`, `cdp.dispatch_key_event`, `input.hover`, `input.drag`, `input.scroll_into_view` |
 | Tabs        | `tabs.list` (preferred), `tabs.create` (avoid unless necessary), `tabs.close`, `tabs.activate`                                                      |
 | Patch       | `patch.apply_styles`, `patch.apply_dom`, `patch.rollback`                                                                                           |
 | Navigate    | `navigation.navigate`, `viewport.scroll`, `viewport.resize`                                                                                         |
-| Performance | `performance.get_metrics` (debugger-backed)                                                                                                         |
+| Performance | `performance.get_metrics` (raw Chrome/CDP counter point sample; debugger-backed)                                                                    |
 | Escalate    | `dom.get_accessibility_tree`, `screenshot.capture_element`, `screenshot.capture_region` (tight crops only), `screenshot.capture_full_page`, `cdp.*` |
 
 ## Dev-Server Workflow (HMR-aware)
@@ -336,8 +351,10 @@ Every CLI shortcut command produces consistent `{ok, summary, evidence}` JSON. U
 - `input.drag` uses `source`, `destination`, and optional destination offsets `offsetX` / `offsetY`.
 - `executionMode` accepts `dom` or `cdp` and defaults to `dom`; CDP supports only click, hover, drag, type, and fill. `input.fill.mode` (`auto`, `setter`, `keystrokes`) is a separate DOM strategy.
 - `page.get_network` defaults to low-cost fetch/XHR instrumentation. All-resource CDP capture must be armed before the activity with `source: "cdp", capture: "start"`, read later, and explicitly stopped.
+- `network.export_har` requires that explicit capture to still be armed. Params are `limit` (1-200), sanitized-URL substring `urlPattern`, and `delivery` (`auto`, `inline`, `artifact`). Inline bounds remove whole oldest entries; export never changes capture state. `bbx har` uses the same client to download, length/SHA-256 verify, delete, validate, and atomically write artifacts locally.
 - `page.handle_dialog` mutations are not atomically bound to `expectedDialogId`; treat `commandDispatched` as dispatch evidence and verify follow-up state.
-- Raw `screenshot.capture_region` and `screenshot.capture_full_page` return base64 JSON; prefer `bbx screenshot <ref> [outPath]` when one element is enough.
+- Raw screenshot calls default to inline base64. Use `delivery: "auto"` for size-aware artifact fallback, or explicit `inline` when MCP image content is required; prefer `bbx screenshot <ref> [outPath]` when one element is enough because the CLI downloads and verifies artifacts locally.
+- Artifact delivery returns a descriptor (artifactId, sha256, byteLength), not bytes. From MCP, read chunks with the `browser_artifact` tool (`action: "read"`, paging `offset` until `nextOffset` is null, then verify the reassembled bytes against `sha256`) and free storage with `action: "delete"`. Each standalone CLI invocation has a new artifact owner, so use `bbx screenshot` / `bbx har` to capture, download, verify, and delete within one CLI process; use `delivery: "inline"` for raw CLI screenshot calls that need the bytes in their immediate result.
 
 ## Response Shapes
 
@@ -360,13 +377,14 @@ Shortcut commands intentionally expose only the common case. Use `bbx call <meth
 | Computed styles  | `result.properties + elementRef` | `Computed N style(s) for ref.`                               |
 | Box model        | `result.content + border`        | `Box model: W×H at (x, y).`                                  |
 | Network          | `result.source + entries`        | `Network: N requests.`                                       |
+| HAR export       | `result.format === "har"`        | `HAR export delivered mode: N/M entries.`                    |
 | Console          | `entries` (no type field)        | `Console: N entries.`                                        |
 | Logs             | `entries[0].at + method`         | `Log: N entries.`                                            |
 | Patch apply      | `result.patchId`                 | `Patch id applied.`                                          |
 | Patch rollback   | `result.rolled_back`             | `Patch rolled back.`                                         |
 | Patch list       | `result.patches`                 | `N active patch(es).`                                        |
 | HTML             | `result.html`                    | `HTML fragment: N chars.`                                    |
-| Performance      | `result.metrics`                 | `Performance: N metrics collected.`                          |
+| Performance      | `result.metrics`                 | `Raw CDP performance counters: N collected; Web Vitals not measured.` |
 | Storage          | `result.type + count + entries`  | `Storage (type): N entries.`                                 |
 | Click/Focus/Type | `result.clicked/focused/typed`   | `Clicked/Focused/Typed ref.`                                 |
 | Key press        | `result.pressed`                 | `Key pressed (key).`                                         |

package/skills/browser-bridge/references/protocol.md

@@ -27,11 +27,16 @@ The table below includes the legacy capability bucket for each method so agents
 - `-` means the method is global/system-scoped and was never gated by a former capability bucket.
 - Capability names are descriptive coverage labels only. Browser Bridge access is window-scoped now; there are no capability-scoped sessions.
 
-## All Methods (67)
+Use `bbx protocol describe <method|group>` for a compact local signature lookup. In MCP mode,
+call `browser_call` with method `protocol.describe` and params containing `method` or `group`;
+omit both for the group index.
+
+## All Methods (76)
 
 | Method                             | Tab? | CDP?       | Group       | Capability           | Notes                                                                                      |
 | ---------------------------------- | ---- | ---------- | ----------- | -------------------- | ------------------------------------------------------------------------------------------ |
 | `access.request`                   | No   | -          | system      | `intent?`            | Request window access with bounded operation context in the extension UI                    |
+| `protocol.describe`                | No   | -          | system      | `-`                  | Local compact method/group parameters and metadata                                          |
 | `tabs.list`                        | No   | -          | tabs        | `-`                  | Discover tabs in the enabled window                                                        |
 | `tabs.create`                      | No   | -          | tabs        | `tabs.manage`        | Open a new tab; optional `url` and `active`                                                |
 | `tabs.close`                       | No   | -          | tabs        | `tabs.manage`        | Close a tab by `tabId`                                                                     |
@@ -39,18 +44,20 @@ The table below includes the legacy capability bucket for each method so agents
 | `skill.get_runtime_context`        | No   | -          | system      | `-`                  | Live budget presets and method groups                                                      |
 | `setup.get_status`                 | No   | -          | system      | `-`                  | Global MCP config and CLI skill install status                                             |
 | `setup.install`                    | No   | -          | system      | `-`                  | Install or uninstall MCP/skill integration targets                                         |
-| `health.ping`                      | No   | -          | system      | `-`                  | Connectivity, enabled-window routing, debugger, and capture state                          |
+| `health.ping`                      | No   | -          | system      | `-`                  | Connectivity, routing, capture, and daemon/routed-extension recovery summaries             |
 | `log.tail`                         | No   | -          | system      | `-`                  | Recent redacted bridge logs                                                                |
-| `daemon.metrics`                   | No   | -          | system      | `-`                  | Daemon health and performance metrics                                                      |
+| `daemon.metrics`                   | No   | -          | system      | `-`                  | Daemon health, performance, and process-local recovery metrics                              |
 | `page.get_state`                   | Yes  | -          | page        | `page.read`          | URL, readiness, focus, viewport, and observable dialog status                              |
 | `page.evaluate`                    | Yes  | CDP        | page        | `page.evaluate`      | JS expression in page context; last resort                                                 |
 | `page.get_console`                 | Yes  | -          | page        | `page.read`          | Buffered console messages; filter by `level`, `limit`                                      |
 | `page.handle_dialog`               | Yes  | CDP        | page        | `navigation.control` | Inspect or explicitly accept/dismiss the currently observable dialog                       |
 | `page.wait_for_load_state`         | Yes  | -          | wait        | `page.read`          | Wait for truthful tab `complete` state and/or a URL condition                              |
-| `page.get_storage`                 | Yes  | -          | page        | `page.read`          | `localStorage`/`sessionStorage`; optional `keys`                                           |
+| `page.get_storage`                 | Yes  | -          | page        | `page.read`          | Bounded storage key/presence metadata; optional `keys`; never values                        |
+| `sensitive.read`                   | Yes  | -          | sensitive   | `sensitive.read`     | One exact local/session storage key; sequential, non-retryable, whole-or-error              |
 | `page.get_text`                    | Yes  | -          | page        | `page.read`          | Full page text; `textBudget` limits size                                                   |
 | `page.extract_content`             | Yes  | -          | page        | `page.read`          | Node-processed semantic text/Markdown with bounded HTML snapshots and optional settlement   |
 | `page.get_network`                 | Yes  | Conditional | page        | `network.read`       | Fetch/XHR by default; explicit CDP all-resource capture lifecycle                          |
+| `network.export_har`               | Yes  | No*        | page        | `network.read`       | Read an already armed CDP capture as bounded metadata-only HAR 1.2                         |
 | `network.intercept.add`            | Yes  | CDP        | page        | `network.intercept`  | Add interception rule; action fulfill/continue/block                                       |
 | `network.intercept.remove`         | Yes  | CDP        | page        | `network.intercept`  | Remove rule by `ruleId`                                                                    |
 | `network.intercept.list`           | Yes  | CDP        | page        | `network.intercept`  | List active rules (rules drop on debugger detach)                                          |
@@ -60,6 +67,10 @@ The table below includes the legacy capability bucket for each method so agents
 | `navigation.go_back`               | Yes  | -          | navigate    | `navigation.control` | History back                                                                               |
 | `navigation.go_forward`            | Yes  | -          | navigate    | `navigation.control` | History forward                                                                            |
 | `dom.query`                        | Yes  | -          | inspect     | `dom.read`           | Query subtree with budget constraints                                                      |
+| `dom.baseline.create`              | Yes  | -          | inspect     | `dom.read`           | Retain a short-lived memory-only semantic snapshot; sequential only                        |
+| `dom.baseline.compare`             | Yes  | -          | inspect     | `dom.read`           | Compare current semantic DOM to an explicit retained baseline; batch-safe                  |
+| `dom.baseline.describe`            | Yes  | -          | inspect     | `dom.read`           | Return exact baseline scope, options, expiry, and snapshot statistics; batch-safe          |
+| `dom.baseline.release`             | Yes  | -          | inspect     | `dom.read`           | Idempotently release retained baseline state; sequential only                              |
 | `dom.describe`                     | Yes  | -          | inspect     | `dom.read`           | Single element details via `elementRef`                                                    |
 | `dom.get_text`                     | Yes  | -          | inspect     | `dom.read`           | Text content with `textBudget`                                                             |
 | `dom.get_attributes`               | Yes  | -          | inspect     | `dom.read`           | Targeted attribute read                                                                    |
@@ -87,28 +98,35 @@ The table below includes the legacy capability bucket for each method so agents
 | `screenshot.capture_element`       | Yes  | CDP        | capture     | `screenshot.partial` | Complete element screenshot with explicit completeness metadata                            |
 | `screenshot.capture_region`        | Yes  | CDP        | capture     | `screenshot.partial` | Cropped viewport region in PNG, JPEG, or WebP                                               |
 | `screenshot.capture_full_page`     | Yes  | CDP        | capture     | `screenshot.partial` | Full document screenshot; fails coherently above Chrome capture limits                     |
+| `artifact.read`                    | No   | daemon     | raw         | None                 | Read one bounded chunk from an owner-scoped artifact handle                                 |
+| `artifact.delete`                  | No   | daemon     | raw         | None                 | Delete an owner-scoped artifact handle                                                      |
 | `patch.apply_styles`               | Yes  | -          | patch       | `patch.styles`       | Reversible CSS patch; `verify` returns computed result                                     |
-| `patch.apply_dom`                  | Yes  | -          | patch       | `patch.dom`          | Reversible DOM mutation; `verify` returns result                                           |
+| `patch.apply_dom`                  | Yes  | -          | patch       | `patch.dom`          | Reversible text, attribute, add/remove/toggle-class mutation; `verify` returns result       |
 | `patch.list`                       | Yes  | -          | patch       | `patch.dom`          | Active rollback records in the current document                                            |
 | `patch.rollback`                   | Yes  | -          | patch       | `patch.dom`          | Revert one active patch                                                                    |
 | `patch.commit_session_baseline`    | Yes  | -          | patch       | `patch.dom`          | Keep current mutations and discard their rollback history                                  |
 | `performance.get_metrics`          | Yes  | CDP        | performance | `performance.read`   | Chrome performance counters                                                                |
 | `cdp.get_document`                 | Yes  | CDP        | cdp         | `cdp.dom_snapshot`   | DevTools document tree                                                                     |
-| `cdp.get_dom_snapshot`             | Yes  | CDP        | cdp         | `cdp.dom_snapshot`   | DevTools DOM snapshot                                                                      |
+| `cdp.get_dom_snapshot`             | Yes  | CDP        | cdp         | `cdp.dom_snapshot`   | DevTools DOM snapshot; optional bounded `computedStyles` property names                     |
 | `cdp.get_box_model`                | Yes  | CDP        | cdp         | `cdp.box_model`      | DevTools-backed element geometry                                                           |
 | `cdp.get_computed_styles_for_node` | Yes  | CDP        | cdp         | `cdp.styles`         | DevTools-backed computed styles                                                            |
 | `cdp.dispatch_key_event`           | Yes  | CDP        | cdp         | `cdp.input`          | DevTools keyDown/keyUp without foreground focus                                            |
 
+`No*` means HAR export issues no CDP command itself, but its source capture must
+already be armed and continues to hold debugger ownership until explicitly
+stopped.
+
 ## CLI
 
 ```bash
 bbx status | doctor | restart | logs | tabs | skill # no routed tab needed
+bbx protocol describe [method|group]             # local signature or compact group index
 bbx call <method> '{"key":"val"}'           # generic RPC (routes to active tab in enabled window)
 bbx call --tab 123 <method> '{...}'         # explicit tab target inside enabled window
 bbx batch '[{"method":"...","params":{}}]'  # parallel calls
 ```
 
-**Convenience shortcuts:** `access-request`, `dom-query`, `describe`, `text`, `styles`, `box`, `click`, `focus`, `type`, `press-key`, `cdp-press-key`, `patch-style`, `patch-text`, `patches`, `rollback`, `screenshot`, `eval`, `console`, `wait`, `find`, `find-role`, `html`, `hover`, `navigate`, `storage`, `tab-create`, `tab-close`, `page-text`, `network`, `a11y-tree`, `perf`, `scroll`, `resize`, `reload`, `back`, `forward`, `attrs`, `matched-rules`
+**Convenience shortcuts:** `access-request`, `dom-query`, `describe`, `text`, `styles`, `box`, `click`, `focus`, `type`, `press-key`, `cdp-press-key`, `patch-style`, `patch-text`, `patches`, `rollback`, `screenshot`, `har`, `eval`, `console`, `wait`, `find`, `find-role`, `html`, `hover`, `navigate`, `storage`, `tab-create`, `tab-close`, `page-text`, `network`, `a11y-tree`, `perf`, `scroll`, `resize`, `reload`, `back`, `forward`, `attrs`, `matched-rules`
 
 Newer bridge methods such as `input.scroll_into_view` and `screenshot.capture_full_page` currently use the raw path: `bbx call <method> '{...}'`.
 
@@ -181,7 +199,7 @@ bbx call page.wait_for_load_state '{"url":"/dashboard","urlMatch":"contains","wa
 
 ### page.get_storage
 
-Read `localStorage` or `sessionStorage` entries. Values truncated at 500 chars each.
+Read bounded `localStorage` or `sessionStorage` key/presence metadata. Values are never returned.
 
 ```bash
 bbx storage                        # all localStorage
@@ -189,6 +207,17 @@ bbx storage session token,user     # specific sessionStorage keys
 bbx call page.get_storage '{"type":"session","keys":["token"]}'
 ```
 
+### sensitive.read
+
+Deliberately read one exact Web Storage value after discovering its key. The
+value bypasses token truncation, is never batched or automatically retried, and
+is returned whole or rejected whole. Every attempt creates a Sensitive access
+Recent Activity warning without retaining the key or value.
+
+```bash
+bbx call sensitive.read '{"source":"session_storage","key":"token"}'
+```
+
 ### dom.query
 
 Run a bounded breadth-first DOM summary rooted at a selector or existing ref. Returns `{nodes, revision, truncated, registrySize}` and may also include `_registryPruned: true` when the element registry evicted older refs.
@@ -200,6 +229,23 @@ bbx call dom.query '{"selector":"main","maxNodes":10,"attributeAllowlist":["clas
 
 If `_registryPruned` is true, refresh previously cached refs before reusing them.
 
+### dom.baseline.create, compare, describe, and release
+
+Use an explicit semantic baseline when an action must be verified against a known before-state without returning two full DOM snapshots. Baselines retain bounded structured summaries in extension memory only; they do not add attributes, scripts, or markers to the application page.
+
+```bash
+bbx call dom.baseline.create '{"selector":"main","maxNodes":100,"maxDepth":8,"textBudget":160,"attributeAllowlist":["data-testid"]}'
+bbx call dom.baseline.compare '{"baselineId":"baseline_...","maxChanges":50}'
+bbx call dom.baseline.describe '{"baselineId":"baseline_..."}'
+bbx call dom.baseline.release '{"baselineId":"baseline_..."}'
+```
+
+The create result is a destination-bound opaque handle plus creation/expiry timestamps, window/tab/frame/document/selector/representation scope, effective capture options, and snapshot counts. It never returns retained nodes. `compare` reports exact `added`, `removed`, `changed`, `moved`, `unchanged`, and total counts while bounding returned examples with `maxChanges`; ambiguity and omitted evidence are explicit. `describe` returns the exact descriptor. `release` is idempotent.
+
+Creation and release are stateful and excluded from read-only batch. Compare and describe do not mutate the baseline or extend its five-minute expiry, so they are batch-safe. Navigation, document replacement, tab/window cleanup, access disable, destination disconnect, expiry, quota eviction, or explicit release makes the handle unavailable. Navigation and document replacement return `DOM_BASELINE_INVALIDATED`; missing, expired, released, or evicted handles return `DOM_BASELINE_NOT_FOUND`.
+
+Capture defaults to stable semantic fields and safe attributes. Form values and event-handler attributes are never retained, URL credentials/fragments/query values are removed, opaque URL payloads are redacted, and caller-provided attribute names are canonicalized and bounded. Use a narrow selector for dialogs, forms, lists, or application regions.
+
 ### dom.wait_for
 
 Wait for a DOM condition using MutationObserver + 250 ms polling fallback. A text-only wait searches all elements. `hidden` succeeds when no matching visible element remains, including when it is absent. Returns `{found, elementRef, duration}`.
@@ -359,9 +405,45 @@ bbx call page.get_network '{"source":"cdp","capture":"stop"}'
 
 CDP URL output removes credentials and fragments, replaces every query value with `[redacted]`, and summarizes data/blob URLs. Request/response bodies, cookies, authorization values, and complete headers are not returned. This mode captures all observed resource classes and is materially more expensive and intrusive than fetch/XHR instrumentation; always stop it when finished.
 
+### network.export_har
+
+Export metadata-only HAR 1.2 from a CDP capture that is currently armed. The
+method is a read and does not attach, start, stop, clear, or otherwise change the
+capture. Use this exact sequence:
+
+```bash
+bbx call page.get_network '{"source":"cdp","capture":"start"}'
+# reproduce the activity
+bbx har --limit 100 --url-pattern /api/ reproduction.har
+bbx call page.get_network '{"source":"cdp","capture":"stop"}'
+```
+
+Parameters are `limit` (1-200, default 50), `urlPattern` (at most 2048
+characters; substring match on sanitized URLs), and `delivery` (`auto` default,
+`inline`, or `artifact`). Count and inline byte/token limits retain the newest
+matching entries and remove complete oldest entries; fields are not truncated to
+fit. `auto` uses an artifact above 256 KiB, while explicit `artifact` always
+returns one. Artifacts last five minutes, are readable/deletable only by their
+requesting client, use private daemon files, and expose no browser-host path.
+
+HAR URLs preserve schemes, hosts, paths, and query names, remove credentials and
+fragments, and replace query values with `[redacted]`. `queryString`, headers,
+and cookies are empty; bodies and authorization data are absent. Unsupported
+header/body/content sizes and send/wait/receive timing phases are `-1`.
+`entry.time` is observed total duration. Redirects are separate observed entries;
+`_bbx` reports resource type, failure reason, and memory/disk/prefetch cache and
+service-worker observations. Result counters expose completed-entry loss as
+`dropped`, discarded unfinished activity as `abandoned`, and requests still
+unfinished and omitted from the HAR as `inflight`.
+
+MCP uses `browser_page` with `action: "har"`. `bbx har` accepts the same limit,
+URL pattern, and delivery choices, then uses one client connection to download
+owner-scoped chunks, verify byte length/SHA-256 and HAR shape, delete the
+artifact, and atomically write the output on the CLI host.
+
 ### dom.get_accessibility_tree
 
-Retrieve a depth-limited accessibility tree via CDP. Full reads use `Accessibility.getFullAXTree`; an optional unique `selector` resolves through CDP DOM methods and uses `Accessibility.getPartialAXTree`, retaining only the selected subtree and required ancestor chain. Missing and ambiguous selectors return typed errors instead of selecting an arbitrary candidate. Nodes include `role`, `name`, `description`, `value`, state fields, `interactive`, `semanticInteractive`, `focusable`, `focusableAndEnabled`, `ignored`, and `childIds`. `interactive` is semantic/focusability metadata, not current pointer actionability.
+Retrieve a depth-limited accessibility tree via CDP. Full reads use `Accessibility.getFullAXTree`; an optional unique `selector` resolves through CDP DOM methods, starts with `Accessibility.getPartialAXTree`, and incrementally fetches selected descendant layers with `Accessibility.getChildAXNodes`. Only the selected subtree and required ancestor chain are retained. Missing and ambiguous selectors return typed errors instead of selecting an arbitrary candidate. Nodes include `role`, `name`, `description`, `value`, state fields, `interactive`, `semanticInteractive`, `focusable`, `focusableAndEnabled`, `ignored`, and `childIds`. `interactive` is semantic/focusability metadata, not current pointer actionability.
 
 This is debugger-backed. Prefer `dom.find_by_role`, `dom.find_by_text`, and targeted `dom.query`/`dom.describe` first.
 
@@ -373,7 +455,7 @@ bbx call dom.get_accessibility_tree '{"maxNodes":100,"maxDepth":6,"interactiveOn
 bbx call dom.get_accessibility_tree '{"selector":"[role=dialog]","maxNodes":50,"compact":true}'
 ```
 
-Filtering occurs before `maxNodes`. Compact mode drops ignored, decorative, and empty nodes while reconnecting retained descendants; interactive-only keeps non-ignored semantic interactive roles. Because CDP applies `maxDepth` before Browser Bridge receives the tree, every result truthfully reports `truncated: true`, `partialTopology: true`, depth metadata, missing-child counts, and a continuation hint. No AX node is written into the page DOM or converted directly into an actionable element ref; use role/name with `dom.find_by_role` before input.
+Filtering occurs before `maxNodes`. Compact mode drops ignored, decorative, and empty nodes while reconnecting retained descendants; interactive-only keeps non-ignored semantic interactive roles. Full reads ask CDP for the requested depth, while selector-scoped reads fetch descendant layers up to that same bound. Every result reports `truncated: true`, `partialTopology: true`, depth metadata, missing-child counts, and a continuation hint. No AX node is written into the page DOM or converted directly into an actionable element ref; use role/name with `dom.find_by_role` before input.
 
 ### viewport.resize
 
@@ -389,7 +471,9 @@ bbx call viewport.resize '{"reset":true}'
 
 ### performance.get_metrics
 
-Read Chrome performance counters via CDP `Performance.getMetrics`. Returns a flat `{metrics}` object with keys like `JSHeapUsedSize`, `LayoutCount`, `TaskDuration`, etc.
+Read a browser-maintained point sample of raw Chrome counters via CDP `Performance.getMetrics`. The additive result is `{metrics, measurement}`, where `measurement` identifies the CDP source, `timeTicks` domain, sample timestamp, point-sample observation, and `webVitals: "not_measured"`. Metric names, availability, and units are defined by Chrome/CDP and can vary by browser version.
+
+BBX does not establish a navigation observation window and does not measure LCP, CLS, or INP. Do not interpret the returned counters as Web Vitals or page-load measurements.
 
 Debugger-backed. Use after lighter reads fail to explain a performance symptom.
 
@@ -400,16 +484,40 @@ bbx call performance.get_metrics
 
 ### screenshot.capture_\*
 
-Capture a complete element, a tight viewport region, or a full document. All methods accept `format: "png" | "jpeg" | "webp"`; JPEG and WebP additionally accept integer `quality` from 0 to 100. Results include matching `format`, `mimeType`, `complete`, and `clipped` metadata.
+Capture a complete element, a tight viewport region, or a full document. All methods accept `format: "png" | "jpeg" | "webp"`, `scale` from 0.1 to 4, and `delivery: "inline" | "artifact" | "auto"`; JPEG and WebP additionally accept integer `quality` from 0 to 100. Results include matching `format`, `mimeType`, encoded `byteLength`, actual `dimensions`, `complete`, `clipped`, and `delivery` metadata.
 
 Element capture uses full page-coordinate bounds with CDP capture beyond the viewport. If Browser Bridge cannot guarantee the entire element, or if an element/page exceeds Chrome capture limits, it returns a typed failure rather than a viewport-clipped image labeled complete. Use full-page capture only when element or tight region captures cannot express the issue.
 
-Raw calls return base64 JSON. Prefer `bbx screenshot [--format png|jpeg|webp] [--quality 0-100] <ref> [outPath]` when one element is enough; the CLI chooses or validates the output extension from the encoding.
+Raw calls default to inline base64 for compatibility. `auto` keeps small captures inline and returns a short-lived, daemon-owned opaque artifact handle for large captures; explicit `inline` preserves MCP image content when model vision is needed. Artifact handles expose no browser-host path and support owner-scoped bounded `artifact.read` and `artifact.delete` calls. Each standalone CLI invocation uses a new artifact owner, so raw CLI screenshot calls should keep inline delivery. Prefer `bbx screenshot [--format png|jpeg|webp] [--quality 0-100] <ref> [outPath]` when one element is enough; the CLI downloads, verifies, deletes, and atomically writes the artifact within one process.
+
+Artifact handles expire after five minutes and can be read or deleted only by
+the requesting client. The daemon creates a private artifact directory and
+owner-only files on POSIX hosts, removes artifacts on expiry/teardown, and never
+returns its browser-host filesystem path.
 
 ```bash
-bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75}'
+bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75,"delivery":"inline","scale":0.75}'
 ```
 
+## Recovery Telemetry
+
+Recovery telemetry is process-local and uses fixed five-second buckets over a
+five-minute window. Three failures for the same hidden group within 60 seconds
+set `activeLoop` for that category. Public summaries always use only these fixed
+categories: `automatic_mcp_retry`, `stale_ref_recovery`, `debugger_reattach`,
+`content_script_reinjection`, `native_host_reconnect`, and `request_outcome`.
+They contain attempts/successes/failures/pending, bounded rates, saturation,
+last-event timestamps, and loop flags, but no page data, URL, selector, payload,
+error text, method name, tab identifier, or internal group name.
+
+`health.ping` includes daemon and available routed-extension summaries;
+`daemon.metrics` includes daemon scope. `bbx doctor` combines both, marks active
+loops as issues, and emits fixed guidance. Stop repeated attempts: re-query stale
+refs, close competing debuggers, reload extension/page after reinjection
+failures, restart for native-host reconnect failures, stop automatic MCP retry
+loops, or inspect the first typed error for request failures. Extension data
+resets with the service worker and daemon data resets with the daemon.
+
 ## Request Envelope
 
 ```json
@@ -433,6 +541,9 @@ bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75}'
 | `ELEMENT_NOT_ACTIONABLE`     | Inspect hidden/disabled/inert/zero-size target                 | `retry: false`, use `dom.describe`           |
 | `ELEMENT_OBSCURED`           | Inspect the element blocking the target point                  | `retry: false`, use `layout.hit_test`        |
 | `ELEMENT_NOT_FOUND`          | Correct or narrow the selector                                 | `retry: false`, use `dom.query`              |
+| `DOM_BASELINE_NOT_FOUND`     | Handle expired, released, evicted, or does not exist           | `retry: false`, create a new baseline        |
+| `DOM_BASELINE_INVALIDATED`   | Navigation, document, or access scope changed                  | `retry: false`, create a new baseline        |
+| `DOM_BASELINE_QUOTA_EXCEEDED` | Snapshot or retained-state quota was exceeded                 | `retry: false`, narrow selector or release   |
 | `INPUT_UNSUPPORTED`          | Use DOM execution or a CDP-supported input method              | `retry: false`                               |
 | `INPUT_INVALID_TARGET`       | Choose a control compatible with the input                     | `retry: false`, use `dom.describe`           |
 | `INPUT_FOCUS_CHANGED`        | Inspect focus handlers; do not replay native text blindly      | `retry: false`, use `dom.describe`           |
@@ -442,7 +553,6 @@ bbx call screenshot.capture_full_page '{"format":"jpeg","quality":75}'
 | `NATIVE_HOST_UNAVAILABLE`    | Check daemon: `bbx status`                                     | `retry: false`                               |
 | `EXTENSION_DISCONNECTED`     | Extension not connected to daemon                              | `retry: true` after 3 s, check `health.ping` |
 | `TIMEOUT`                    | Wait/evaluate exceeded `timeoutMs`                             | `retry: true` after 1 s                      |
-| `RATE_LIMITED`               | Too many requests                                              | `retry: true` after 2 s                      |
 
 Timeout on content-script request → use narrower `dom.query` or CDP fallback.
 Timeout on navigation → increase `timeoutMs`, set `waitForLoad:false`, or check `page.get_state`.

package/skills/browser-bridge/references/token-efficiency.md

@@ -14,7 +14,7 @@ These presets are also available at runtime via `bbx skill`.
 
 ## Debugger Policy
 
-Avoid debugger-backed methods until they are clearly necessary. In Browser Bridge, `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, CDP network capture, CDP input execution, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and `cdp.*` attach `chrome.debugger`, which can make Chrome show its native debugging banner across the running browser instance.
+Avoid debugger-backed methods until they are clearly necessary. In Browser Bridge, `page.evaluate`, `page.handle_dialog`, `dom.get_accessibility_tree`, CDP network capture, CDP input execution, `viewport.resize`, `performance.get_metrics`, `screenshot.capture_*`, and `cdp.*` attach `chrome.debugger`, which can make Chrome show its native debugging banner across the running browser instance. `network.export_har` does not attach by itself, but it requires the explicit CDP capture to remain armed.
 
 ## Decision Tree
 
@@ -28,12 +28,13 @@ Avoid debugger-backed methods until they are clearly necessary. In Browser Bridg
 8. **Need article or documentation content?** → `page.extract_content` (removes navigation and repeated chrome)
 9. **Need all visible page UI text?** → `page.get_text` (cheaper than `dom.query` on body)
 10. **Need API call history?** → default `page.get_network` (intercepted fetch/XHR log)
-11. **Need framework/app state and no lighter read can expose it?** → `page.evaluate` (debugger-backed)
-12. **Need semantic structure and role/text queries are insufficient?** → compact or interactive-only `dom.get_accessibility_tree` (debugger-backed)
-13. **Need performance data?** → `performance.get_metrics` (debugger-backed)
-14. **Testing responsive with an exact forced viewport?** → `viewport.resize` (debugger-backed)
-15. **Visual ambiguity after structured reads?** → `screenshot.capture_element` first, or `screenshot.capture_region` with a tight crop when one element is not enough (debugger-backed)
-16. **Content-script blocked?** → `cdp.get_document` or `cdp.get_dom_snapshot` (debugger-backed fallback)
+11. **Need portable all-resource evidence?** → explicitly arm CDP, reproduce, `network.export_har`, then stop capture
+12. **Need framework/app state and no lighter read can expose it?** → `page.evaluate` (debugger-backed)
+13. **Need semantic structure and role/text queries are insufficient?** → compact or interactive-only `dom.get_accessibility_tree` (debugger-backed)
+14. **Need a raw Chrome/CDP counter point sample?** → `performance.get_metrics` (debugger-backed; no BBX navigation window or LCP/CLS/INP measurement)
+15. **Testing responsive with an exact forced viewport?** → `viewport.resize` (debugger-backed)
+16. **Visual ambiguity after structured reads?** → `screenshot.capture_element` first, or `screenshot.capture_region` with a tight crop when one element is not enough (debugger-backed)
+17. **Content-script blocked?** → `cdp.get_document` or `cdp.get_dom_snapshot` (debugger-backed fallback)
 
 ## Allowlist Strategy
 
@@ -70,6 +71,7 @@ Omitting allowlists or leaving the text budget wide open often returns 3–5× t
 | Fetching network via evaluate hacks      | ~400 tok            | Use `page.get_network` (auto-interceptor)                                                    |
 | Full a11y tree with no limits            | ~3000 tok           | Set `maxNodes` ≤ 50, `maxDepth` ≤ 4                                                          |
 | CDP network capture for API-only traffic | debugger lifecycle  | Use default fetch/XHR capture; reserve CDP for all-resource failures                         |
+| Broad inline HAR export                  | token/byte pressure | Narrow `urlPattern`/`limit`, or use `delivery: "artifact"`; bounds remove whole entries      |
 | Repeated page-state polling for a route  | ~500 tok/poll       | Use one event-aware `page.wait_for_load_state` URL condition                                 |
 
 ## Efficient Loop
@@ -133,6 +135,14 @@ The interceptor auto-installs on first call. Before reproducing an event, call `
 
 Only escalate to `source: "cdp"` when fetch/XHR misses the relevant document, asset, socket, cache, redirect, or failed-resource metadata. CDP must be started before reproduction and explicitly stopped afterward; it holds debugger ownership, tracks in-flight state, and returns a larger entry shape. Its URLs redact credentials, fragments, and query values, and it never returns bodies, cookies, authorization values, or complete headers.
 
+For a HAR, export while that capture is still armed, then stop it. Use a narrow
+sanitized-URL `urlPattern` and small `limit` first. Inline delivery removes whole
+oldest entries to meet byte/token bounds rather than truncating fields; inspect
+`truncation`, `dropped`, `abandoned`, and `inflight`. Use `delivery: "artifact"`
+for larger evidence. The five-minute opaque handle is owner-scoped and has no
+browser-host path; `bbx har` downloads, verifies, deletes, and atomically writes
+it on the CLI host through the same client.
+
 ## Accessibility Tree for Semantic Discovery
 
 When you need to understand the page's interactive structure without guessing selectors: