chromex-mcp 1.6.0 → 1.8.0

package/README.md

@@ -4,14 +4,26 @@
 [![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Chromex is a zero-dependency Chrome DevTools Protocol toolkit for AI agents. It connects directly to Chrome, Brave, Edge, Chromium, and Vivaldi through CDP, exposing a token-efficient CLI and an optional MCP server with 73 typed tools.
+Chromex is an agent-first browser automation and DevTools toolkit that connects directly to Chrome, Brave, Edge, Chromium, and Vivaldi through CDP. It exposes the complete capability set through a token-efficient CLI and 85 typed MCP tools, with zero runtime dependencies.
 
-Use Chromex when an agent needs to inspect pages, take screenshots, navigate, click, fill forms, read console/network activity, emulate devices, throttle network/CPU, export PDFs, or run browser diagnostics without pulling in Puppeteer or Playwright.
+Use Chromex when an agent needs to automate a real logged-in browser, inspect page and Application state, debug console/network failures, profile performance or memory, test extensions and WebMCP, or collect reproducible evidence without pulling in a heavy browser automation runtime.
+
+## Quick Start
+
+```bash
+npm install -g chromex-mcp
+chromex --version
+chromex launch --pipe --url https://example.com
+chromex list
+chromex snap <target> --refs
+```
+
+`launch --pipe` is the recommended path for repeatable AI sessions: it starts an isolated Chromex profile and avoids Chrome's recurring debugging approval prompt. Use the normal WebSocket mode only when access to an already-running personal browser is intentional.
 
 ## Why Chromex
 
 - **CLI-first for lower token usage**: terminal commands return compact plain text and avoid MCP tool-schema overhead.
-- **Optional MCP server**: 73 typed tools for Claude Code and other MCP clients when tool discovery, typed parameters, and inline screenshots matter more than token budget.
+- **Optional MCP server**: 85 typed tools in the full set, plus focused `core` and `devtools` toolsets for sessions where schema cost matters.
 - **No runtime dependencies**: Node.js 22+ built-ins only, including native WebSocket support.
 - **Agent-friendly page model**: accessibility snapshots, `@eN` refs, incremental diffs, query filters, auto-snapshots, and contextual hints.
 - **Persistent per-tab daemons**: one CDP session per tab, held open through an authenticated Unix socket.
@@ -21,13 +33,29 @@ Use Chromex when an agent needs to inspect pages, take screenshots, navigate, cl
 ## What You Can Do Today
 
 - Inspect and automate real logged-in browser sessions, not only fresh headless test contexts.
+- Use `--raw` and `--json` for stable pipes, CI, MCP wrappers, and agent-to-agent integrations.
+- Create named sessions with isolated browser contexts, reusable targets, and local session dashboards.
 - Read page state through compact accessibility snapshots, filtered snapshots, DOM snapshots, HTML, screenshots, and highlighted elements.
 - Act on UI through refs, CSS selectors, coordinates, keyboard input, forms, uploads, drag and drop, touch gestures, dialogs, and load-more loops.
 - Debug production behavior with console history, network request details, response bodies, HAR export, request blocking, API mocking, throttling, and offline mode.
 - Test browser conditions with device presets, viewport resizing, DPR, geolocation, timezone, locale, CPU throttling, incognito contexts, proxies, and custom Chrome flags.
 - Diagnose performance and quality with Core Web Vitals, transfer size, DOM/memory counters, Lighthouse audits, JS/CSS coverage, Chrome traces, and heap snapshots.
-- Validate modern browser flows such as passkey/WebAuthn registration and login, downloads, cookies, storage, PDF export, and isolated profiles.
+- Inspect Browser Issues, computed and matched CSS, event listeners, box models, prioritized runtime diagnoses, CPU profiles, heap retaining paths, duplicate strings, and trace insights.
+- Capture bounded screencasts with a local replay, manage extensions in trusted pipe mode, and discover or execute WebMCP and page-exposed developer tools.
+- Build evidence packs with screenshots, snapshots, HTML, console, network timeline, action timeline, and replay HTML.
+- Validate modern browser flows such as passkey/WebAuthn registration and login, downloads, cookies, portable storage state, PDF export, and isolated profiles.
 - Inspect Application panel state from the terminal: origin quota, storage usage breakdown, Cache Storage entries/bodies, IndexedDB schemas/rows, and Service Worker registrations.
+- Turn `@eN` refs into locators and optional `chromex-test` action code.
+
+The CLI and the default MCP `full` toolset expose the same capability families. CLI commands group related operations into subcommands, while MCP presents 85 individually typed tools.
+
+| Capability | CLI | MCP `full` |
+|------------|-----|------------|
+| Input, navigation, forms, uploads, dialogs, and emulation | Yes | Yes |
+| Console, network, Application state, interception, HAR, and audits | Yes | Yes |
+| Browser Issues, CSS/listener/box inspection, and runtime diagnosis | Yes | Yes |
+| Web Vitals, CPU profiles, heap sampling, traces, and heap analysis | Yes | Yes |
+| Screencasts, extensions, page developer tools, and WebMCP | Yes | Yes |
 
 ## Positioning
 
@@ -36,7 +64,7 @@ Chromex is a direct CDP layer for coding agents. It sits between raw Chrome DevT
 | Alternative | Trade-off | Chromex angle |
 |-------------|-----------|---------------|
 | Raw CDP WebSocket | Maximum browser power, but too verbose for agents. | Compact commands, refs, snapshots, and safety defaults. |
-| Puppeteer or Playwright libraries | Excellent automation frameworks, but they add dependencies and framework-level abstractions. | Zero-runtime-dependency CLI/MCP that talks to your existing Chromium browser. |
+| Heavy browser automation libraries | Excellent automation frameworks, but they add dependencies and framework-level abstractions. | Zero-runtime-dependency CLI/MCP that talks to your existing Chromium browser. |
 | Browser MCP only | Easy tool discovery, but tool schemas and structured responses add token cost. | CLI-first for cheap agent loops, MCP when typed tools are worth the overhead. |
 | Manual DevTools | Great for humans, not scriptable enough for agents. | DevTools-grade inspection exposed as terminal and MCP commands. |
 
@@ -48,7 +76,7 @@ Chromex is a direct CDP layer for coding agents. It sits between raw Chrome DevT
 
 ## Zero-Dependency Boundary
 
-The core runtime uses only Node.js built-in modules. Chromex does not install Puppeteer, Playwright, Selenium, browser drivers, telemetry SDKs, update checkers, or bundled browsers.
+The core runtime uses only Node.js built-in modules. Chromex does not install heavy browser automation runtimes, Selenium, browser drivers, telemetry SDKs, update checkers, or bundled browsers.
 
 The only exception is the optional `audit` command: it shells out to Lighthouse with `npx --yes lighthouse` when you explicitly run an audit. All other CLI and MCP commands run through Chromex's own CDP client.
 
@@ -73,11 +101,16 @@ chromex launch --browser brave --url https://example.com
 chromex launch --profile testing --url https://example.com
 chromex launch --incognito --browser chrome
 chromex launch --headless --url https://example.com
+chromex launch --pipe --url https://example.com
+chromex launch --extension-tools --url about:blank
+chromex launch --webmcp --url https://example.com
 chromex launch --browser-path "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"
 ```
 
 Named profiles are stored under `~/.chromex/profiles/` and keep test sessions isolated from your daily browser profile.
 
+`chromex launch --pipe` is the preferred mode for repeated AI sessions. It uses one permission-protected local Unix-socket broker over Chrome's remote-debugging pipe, avoids approval modals, and lets CLI and MCP clients share the same browser connection. `--extension-tools` implies pipe mode because Chrome restricts extension lifecycle APIs to trusted debugging sessions. WebMCP requires a visible supported Chrome build, so do not combine `--webmcp` with `--headless` when the page tools must execute.
+
 Chrome for Testing also works well with Chromex. Download it manually from Google's official Chrome for Testing channel, then point Chromex at the executable with `--browser-path` or `CHROMEX_BROWSER_PATH`. Chromex does not download or bundle a browser.
 
 ### Option B: Connect to an Already-Running Browser
@@ -97,7 +130,9 @@ Important notes:
 
 - Without remote debugging enabled, Chromex cannot discover or control your open tabs.
 - The browser setting is usually persistent across restarts.
-- The first command that attaches to a tab may show an "Allow debugging" prompt. Accept it once for that tab; Chromex keeps the daemon session alive after that.
+- Chrome may show an "Allow debugging" prompt for each new DevTools WebSocket connection to a normal browser profile. This is browser security behavior, so reconnecting from a new CLI or agent process can show it again.
+- Per-tab daemons and the persistent MCP connection reduce reconnections, but they do not bypass Chrome's protection for a personal browser profile.
+- Use `chromex launch --pipe` with a Chromex-managed isolated profile when a modal-free persistent AI connection is required.
 
 If your browser uses a custom profile or a non-standard `DevToolsActivePort` location, set:
 
@@ -129,6 +164,15 @@ npm install -g chromex-mcp
 bun add -g chromex-mcp
 ```
 
+Verify which installation every terminal and agent session will use:
+
+```bash
+command -v chromex
+chromex --version
+```
+
+Cloning the repository does not replace an existing global installation. To test the current checkout directly, run `node bin/chromex.mjs`. To deliberately install the current checkout globally, run `npm install -g .` from the repository root and verify the path and version again.
+
 The package installs three binaries:
 
 | Binary | Purpose |
@@ -163,12 +207,22 @@ chromex click 6BE8 @e3
 # 5. Inspect browser state.
 chromex console 6BE8 list
 chromex net 6BE8
-chromex shot 6BE8 /tmp/page.png
+chromex shot 6BE8
 chromex app 6BE8
 ```
 
 `<target>` is a unique prefix of the tab target ID returned by `chromex list`. If a prefix is ambiguous, Chromex rejects it and asks for more characters.
 
+For repeatable agent workflows, use named sessions instead of carrying target IDs manually:
+
+```bash
+chromex -s auth open https://github.com/login
+chromex -s auth snap --refs
+chromex -s auth fill @e1 "user@example.com"
+chromex -s auth state save ~/.chromex/storage/auth.json
+chromex sessions
+```
+
 ## Token-Efficient Agent Workflow
 
 Chromex is optimized for agents that need to act on browser state without wasting context.
@@ -180,6 +234,8 @@ Chromex is optimized for agents that need to act on browser state without wastin
 5. Let auto-snapshot show post-action state after interactive commands.
 6. Add `--no-snap` only for fast scripted batches where you do not need immediate page state.
 7. Add `--no-hints` when another program parses output strictly.
+8. Use `--raw` for pipes and `--json` when another tool needs the stable envelope.
+9. Save large snapshots with `--filename` when they are better as artifacts than inline text.
 
 Examples:
 
@@ -188,6 +244,11 @@ chromex snap 6BE8 --query=login --refs
 chromex click 6BE8 @e4
 chromex wait 6BE8 networkidle
 chromex snap 6BE8 --query=error
+chromex --raw eval 6BE8 "document.title"
+chromex list --json
+chromex snap 6BE8 --filename=~/.chromex/snapshots/login.yml --boxes
+chromex locator 6BE8 @e4 --format=chromex-test
+chromex click 6BE8 @e4 --code=chromex-test
 ```
 
 ## MCP Server
@@ -200,23 +261,48 @@ Global, available in all projects:
 
 ```bash
 # npm
-claude mcp add chromex -s user npx chromex-mcp@latest
+claude mcp add chromex --scope user -- npx -y chromex-mcp@latest
 
 # Bun
-claude mcp add chromex -s user bunx chromex-mcp@latest
+claude mcp add chromex --scope user -- bunx chromex-mcp@latest
 ```
 
 Project-only:
 
 ```bash
 # npm
-claude mcp add chromex npx chromex-mcp@latest
+claude mcp add chromex -- npx -y chromex-mcp@latest
 
 # Bun
-claude mcp add chromex bunx chromex-mcp@latest
+claude mcp add chromex -- bunx chromex-mcp@latest
+```
+
+For MCP clients that accept a standard stdio configuration, point the client at the installed binary:
+
+```json
+{
+  "mcpServers": {
+    "chromex": {
+      "command": "chromex-mcp",
+      "args": []
+    }
+  }
+}
 ```
 
-After setup, the MCP client can call tools such as `chromex_list`, `chromex_snapshot`, `chromex_click`, `chromex_fill`, `chromex_screenshot`, `chromex_console`, `chromex_network`, `chromex_app_summary`, `chromex_cache_entries`, and `chromex_indexeddb_rows`.
+After setup, the MCP client can call tools such as `chromex_list`, `chromex_snapshot`, `chromex_click`, `chromex_fill`, `chromex_network`, `chromex_issues`, `chromex_inspect`, `chromex_diagnose`, `chromex_perf`, `chromex_trace`, `chromex_heap`, `chromex_screencast`, `chromex_extensions`, `chromex_third_party`, `chromex_webmcp`, `chromex_app_summary`, `chromex_cache_entries`, `chromex_indexeddb_rows`, and `chromex_evidence`.
+
+Tools that produce machine-readable data or artifacts also include MCP `structuredContent`, so agents can read paths and metadata without parsing the human text block.
+
+The default `full` toolset exposes all 85 tools. Use a focused toolset when the MCP client sends every schema into the model context:
+
+```bash
+chromex-mcp --toolset=core
+chromex-mcp --toolset=devtools
+CHROMEX_TOOLSET=full chromex-mcp
+```
+
+`core` exposes 24 navigation, inspection, input, form, and emulation tools. `devtools` exposes 26 browser-diagnostics, performance, trace, heap, Application, and audit tools. This selection changes discovery only; the complete CLI and the default MCP toolset retain every capability.
 
 ### Claude Code Auto-Approve
 
@@ -271,12 +357,20 @@ claude mcp remove chromex
 
 ```bash
 chromex list
+chromex list --include-sensitive
 chromex open "https://example.com"
+chromex -s auth open "https://example.com/login"
+chromex -s auth snap --refs
+chromex sessions
+chromex show --annotate
 chromex close <target>
 chromex focus <target>
 chromex launch --url https://example.com
 chromex launch --browser brave --incognito
 chromex launch --headless --url https://example.com
+chromex launch --pipe --url https://example.com
+chromex launch --extension-tools --url about:blank
+chromex launch --webmcp --url https://example.com
 chromex launch --browser-path /path/to/chrome --url https://example.com
 chromex doctor
 chromex incognito https://example.com
@@ -288,14 +382,25 @@ chromex stop
 ```bash
 chromex snap <target> --refs
 chromex snap <target> --query=login
+chromex snap <target> --filename=~/.chromex/snapshots/login.yml --boxes
 chromex html <target> "#main"
-chromex shot <target> /tmp/page.png
-chromex shot <target> /tmp/full.png --full
+chromex shot <target>
+chromex shot <target> ~/.chromex/screenshots/full.png --full
 chromex shot <target> @e5
 chromex console <target> list
 chromex net <target>
+chromex net <target> <requestId> --include-sensitive
+chromex net <target> <requestId> --body-limit=100000
 chromex perf <target>
 chromex domsnapshot <target> --styles
+chromex issues <target> enable
+chromex issues <target> list
+chromex inspect <target> all "#checkout"
+chromex diagnose <target>
+chromex evidence <target> start checkout-flow
+chromex evidence <target> mark "after login"
+chromex evidence <target> stop
+chromex evidence <target> replay
 ```
 
 ### Navigate and Wait
@@ -317,6 +422,8 @@ chromex clickxy <target> 100 200
 chromex key <target> Enter
 chromex type <target> "hello world"
 chromex hover <target> @e12
+chromex locator <target> @e12 --format=chromex-test
+chromex click <target> @e12 --code=chromex-test
 chromex drag <target> "#source" "#dest"
 chromex dialog <target> accept
 ```
@@ -340,6 +447,8 @@ chromex cookies <target> set '{"name":"token","value":"abc"}'
 chromex storage <target> local
 chromex storage <target> session
 chromex storage <target> usage
+chromex state <target> save ~/.chromex/storage/auth.json
+chromex state <target> load ~/.chromex/storage/auth.json
 chromex app <target> summary
 chromex sw <target>
 chromex cache <target> list
@@ -347,7 +456,7 @@ chromex cache <target> entries <cacheId> --query=/api
 chromex idb <target> list
 chromex idb <target> schema <databaseName>
 chromex idb <target> rows <databaseName> <objectStoreName> --limit=20
-chromex pdf <target> /tmp/page.pdf
+chromex pdf <target>
 ```
 
 ### Network, Emulation, and Diagnostics
@@ -355,8 +464,12 @@ chromex pdf <target> /tmp/page.pdf
 ```bash
 chromex throttle <target> 3g
 chromex intercept <target> block "*.analytics.*"
+chromex intercept <target> mock "/api/user" --status=200 --content-type=application/json --body='{"ok":true}'
+chromex intercept <target> mock "/api/slow" --delay=750 --status=503 --body='unavailable'
+chromex intercept <target> block "*.tracker.*" --abort=blockedbyclient
+chromex intercept <target> on --remove-header=authorization
 chromex har <target> start
-chromex har <target> stop /tmp/trace.har
+chromex har <target> stop ~/.chromex/har/trace.har
 chromex emulate <target> iphone-15-pro
 chromex resize <target> 1280 720
 chromex geo <target> -23.55 -46.63
@@ -372,10 +485,16 @@ chromex stats <target> --full
 chromex eval <target> "document.title"
 chromex evalraw <target> "Page.getLayoutMetrics"
 chromex inject <target> "window.DEBUG=true"
-chromex download <target> allow /tmp/downloads
+chromex download <target> allow ~/.chromex/downloads
 chromex coverage <target> start
 chromex trace <target> start
-chromex heap <target> snapshot /tmp/heap.heapsnapshot
+chromex trace <target> insights
+chromex heap <target> snapshot ~/.chromex/heap/heap.heapsnapshot
+chromex heap <target> summary
+chromex screencast <target> start --max-frames=120
+chromex extensions <target> list
+chromex third-party <target> list
+chromex webmcp <target> list
 chromex webauthn <target> enable
 ```
 
@@ -433,9 +552,77 @@ help[3]:
 
 Disable hints with `--no-hints`.
 
+### Stable Output and Artifacts
+
+Chromex keeps plain text as the default output, but also supports stable modes for scripts:
+
+```bash
+chromex --raw eval <target> "document.title"
+chromex list --json
+chromex snap <target> --filename=~/.chromex/snapshots/home.yml --boxes
+```
+
+`--raw` prints only the primary command output and suppresses hints and auto-snapshot noise. `--json` returns a stable envelope with `ok`, `command`, `target`, `text`, `data`, `artifacts`, and `error`.
+
+Generated artifacts are written under `~/.chromex/artifacts/<workspace>/` by default. Paths in the Chromex namespace, such as `.chromex/storage/auth.json` or `~/.chromex/storage/auth.json`, resolve to `~/.chromex/...`. Other explicit absolute or relative file paths are respected as provided. Set `CHROMEX_ARTIFACT_ROOT` to override the default artifact root for CI or tests.
+
+### Named Sessions
+
+Named sessions let agents reuse isolated browser contexts without carrying target IDs:
+
+```bash
+chromex -s auth open https://example.com/login
+chromex -s auth snap --refs
+chromex -s auth click @e3
+chromex sessions
+chromex show --annotate
+chromex close-all
+chromex delete-data auth
+```
+
+`CHROMEX_SESSION=auth` can replace `-s auth` for shell scripts.
+`chromex show` opens the generated dashboard in the default browser during normal CLI usage; set `CHROMEX_NO_OPEN=1` or use `--json`/`--raw` to only write the artifact.
+
+Named sessions keep a private storage-state file under `~/.chromex/session-data/<name>/storage-state.json`. Chromex restores it when the named session is reopened and refreshes it after state-changing session commands.
+
+`chromex show --annotate` generates a local dashboard with screenshot previews, region/point marking, per-mark notes, and JSON export. Browsers with File System Access support can save the exported pack directly; other browsers download the JSON file.
+
+### Storage State and Locators
+
+Storage state captures cookies plus localStorage for the current origin:
+
+```bash
+chromex state <target> save ~/.chromex/storage/auth.json
+chromex state <target> load ~/.chromex/storage/auth.json
+```
+
+Refs can also be converted into reusable locator output or starter action code:
+
+```bash
+chromex locator <target> @e5 --format=chromex-test
+chromex locator <target> @e5 --format=css
+chromex locator <target> @e5 --format=testing-library
+chromex fill <target> @e1 "user@example.com" --code=chromex-test
+```
+
+### Evidence Packs
+
+Evidence packs collect browser evidence without recording video:
+
+```bash
+chromex evidence <target> start checkout-flow
+chromex click <target> @e3
+chromex fill <target> @e5 "user@example.com"
+chromex evidence <target> mark "after login"
+chromex evidence <target> stop
+chromex evidence <target> replay
+```
+
+Each pack is written under `~/.chromex/artifacts/<workspace>/evidence/` and includes screenshots, accessibility snapshots with boxes, HTML captures, console JSON, network JSON, action timeline, `evidence.json`, and `index.html` for local replay. Values passed to `fill`, `type`, and `form` are redacted from the action timeline.
+
 ## Application State Suite
 
-Chromex exposes browser Application panel state without Puppeteer, Playwright, or extra packages. This is useful for debugging PWAs, offline behavior, stale caches, local database migrations, authentication state, and quota issues from the same logged-in browser session an agent is already using.
+Chromex exposes browser Application panel state without heavy browser automation runtimes or extra packages. This is useful for debugging PWAs, offline behavior, stale caches, local database migrations, authentication state, and quota issues from the same logged-in browser session an agent is already using.
 
 ```bash
 # One-line overview for the current origin
@@ -475,7 +662,24 @@ Chromex creates `~/.chromex/config.json` on first run:
   "idleTimeout": 1200000,
   "allowedDomains": [],
   "blockedDomains": [],
-  "blockedCdpMethods": ["Browser.close", "Storage.getCookies"],
+  "blockedCdpMethods": [
+    "Network.enable",
+    "Network.setRequestInterception",
+    "Network.setCacheDisabled",
+    "Page.setDocumentContent",
+    "Security.disable",
+    "Security.setIgnoreCertificateErrors",
+    "Fetch.enable",
+    "Fetch.fulfillRequest",
+    "Fetch.continueRequest",
+    "Browser.close",
+    "Browser.crashGpuProcess",
+    "Target.disposeBrowserContext",
+    "SystemInfo.getProcessInfo",
+    "Storage.clearDataForOrigin",
+    "Storage.getCookies",
+    "IndexedDB.requestData"
+  ],
   "auditLog": true,
   "socketAuth": true
 }
@@ -489,18 +693,21 @@ Recommended security practices:
 - Keep `auditLog` enabled and review `~/.chromex/audit.log` when needed.
 - Prefer `chromex launch --profile testing` for isolated browser state.
 
+Page URLs, network, console, extension-storage, third-party, and WebMCP outputs redact secret-shaped headers and fields by default. The browser still sends and receives the original values. Use CLI `--include-sensitive` or MCP `includeSensitive: true` only on the specific live call that needs exact values. Audit logs, page caches, stats, HAR, and structured evidence timelines, network data, and console data remain redacted even when a live response is revealed. Screenshots, screencasts, snapshots, HTML, traces, heap snapshots, and raw page content can still contain sensitive information and should be handled accordingly.
+
 See [docs/security.md](docs/security.md) for the full security model.
 
 ## How It Works
 
 ```text
 CLI or MCP client -> authenticated Unix socket -> per-tab daemon -> CDP WebSocket -> browser
+                                                        \-> pipe broker -> Chrome debugging pipe
 ```
 
-1. Chromex finds the browser DevTools endpoint from `DevToolsActivePort` or `CDP_PORT_FILE`.
+1. Chromex finds a browser DevTools endpoint or a Chromex pipe-broker marker.
 2. The first tab command starts a detached daemon for that tab.
 3. The daemon attaches once through CDP and keeps the session open.
-4. CLI and MCP commands talk to the daemon through an authenticated Unix socket.
+4. CLI and MCP commands talk to the daemon through an authenticated Unix socket; pipe mode multiplexes CDP through a second local socket restricted to the current OS user.
 5. Daemons exit after the configured idle timeout.
 
 See [docs/architecture.md](docs/architecture.md) for implementation details.
@@ -510,15 +717,16 @@ See [docs/architecture.md](docs/architecture.md) for implementation details.
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](docs/getting-started.md) | Installation, browser setup, first commands. |
-| [Inspect and Debug](docs/inspect.md) | Screenshots, accessibility tree, refs, HTML, eval, network, performance, console. |
+| [Inspect and Debug](docs/inspect.md) | Screenshots, accessibility tree, refs, Browser Issues, CSS/listener inspection, diagnostics, performance, and console. |
 | [Navigate and Interact](docs/navigate.md) | Navigation, clicking, typing, scrolling, drag and drop, touch, dialogs. |
 | [Form Filling](docs/forms.md) | Fill, clear, select, check, upload, batch form examples. |
 | [Data Access](docs/data.md) | Cookies, localStorage, sessionStorage, Application state, Cache Storage, IndexedDB, Service Workers, PDF export. |
-| [Network Control](docs/network.md) | Throttling, interception, mocking, HAR recording. |
+| [Network Control](docs/network.md) | Live request history and bodies, filtering, redaction, throttling, interception, mocking, and HAR. |
 | [Device Emulation](docs/emulation.md) | Responsive testing, geolocation, timezone, CPU throttling. |
 | [Security](docs/security.md) | Domain filtering, CDP blocklist, audit log, best practices. |
-| [Advanced](docs/advanced.md) | Script injection, code coverage, tracing, heap snapshots, WebAuthn. |
+| [Advanced](docs/advanced.md) | CPU and heap profiles, trace insights, heap graph analysis, screencasts, extensions, page tools, WebMCP, and WebAuthn. |
 | [Architecture](docs/architecture.md) | Daemon model, connection modes, and file layout. |
+| [Troubleshooting](docs/troubleshooting.md) | Installation drift, connection failures, debugging prompts, Node warnings, extensions, and WebMCP. |
 
 ## Development
 
@@ -531,6 +739,14 @@ bun run test
 
 The runtime package has no dependencies. Development dependencies are used only for tests and token benchmarks.
 
+Run the browser-backed smoke flow explicitly when validating a release candidate:
+
+```bash
+bun run test:smoke
+```
+
+The smoke script launches a temporary headless Chromium profile through `CDP_PORT_FILE`, exercises named sessions, snapshots, locators, storage state, annotation dashboard artifacts, and then stops the launched process.
+
 To reproduce the token-format comparison:
 
 ```bash