opendevbrowser 0.0.15 → 0.0.17

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 OpenDevBrowser contributors
+Copyright (c) 2024-2026 OpenDevBrowser contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/opendevbrowser.svg?style=flat-square)](https://registry.npmjs.org/opendevbrowser)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
 [![OpenCode Plugin](https://img.shields.io/badge/OpenCode-Plugin-green.svg?style=flat-square)](https://opencode.ai)
 [![CLI](https://img.shields.io/badge/Interface-CLI-orange.svg?style=flat-square)](docs/CLI.md)
 [![Chrome Extension](https://img.shields.io/badge/Chrome-Extension-blue.svg?style=flat-square)](docs/EXTENSION.md)
@@ -10,10 +10,10 @@
 
 > **Script-first browser automation for AI agents.** Snapshot → Refs → Actions.
 
-OpenDevBrowser is an agent-agnostic browser automation runtime. You can use it as an [OpenCode](https://opencode.ai) plugin, as a standalone CLI, or through the Chrome extension relay for logged-in browser sessions. It supports managed sessions, direct CDP attach, and extension-backed Ops sessions.
+OpenDevBrowser is an agent-agnostic browser automation runtime. You can use it as an [OpenCode](https://opencode.ai) plugin, as a standalone CLI, or through the Chrome extension relay for logged-in browser sessions. It supports managed sessions, direct CDP attach, and extension-backed Ops sessions. Frontend website source and deployment are maintained in the private repo `opendevbrowser-website-deploy`.
 
 <p align="center">
-  <img src="assets/readme-image-candidates/2026-02-08/04-annotation-automation-scene.jpg" alt="OpenDevBrowser hero image showing AI-assisted annotation and browser automation workflow" width="920" />
+  <img src="assets/hero-image.png" alt="OpenDevBrowser hero image showing AI-assisted annotation and browser automation workflow" width="920" />
   <br />
   <em>AI-assisted annotation and browser automation workflow</em>
 </p>
@@ -25,8 +25,14 @@ OpenDevBrowser is an agent-agnostic browser automation runtime. You can use it a
 | **CLI (`npx opendevbrowser ...`)** | No | Any agent/workflow that can run shell commands |
 | **Chrome Extension + Relay** | No | Reusing existing logged-in tabs without launching a new browser |
 | **OpenCode Plugin Tools** | Yes | Native tool-calling inside OpenCode (`opendevbrowser_*`) |
+| **Frontend Website (private repo)** | No | Product website and generated docs routes |
 
 All core automation flows are available through the CLI command surface and the plugin tool surface.
+Private website docs routes are generated from public repository source-of-truth docs and skill packs.
+
+Distribution split (current target state):
+- Public repo (`opendevbrowser`): runtime, CLI, extension, docs, npm, release artifacts.
+- Private repo (`opendevbrowser-website-deploy`): website deployment (`website-production` branch).
 
 ## Why OpenDevBrowser?
 
@@ -37,17 +43,21 @@ All core automation flows are available through the CLI command surface and the
 | **Stable refs** | Elements identified by `backendNodeId`, not fragile selectors |
 | **Security by default** | CDP localhost-only, timing-safe auth, HTML sanitization |
 | **3 browser modes** | Managed, CDP connect, or extension relay for logged-in sessions |
-| **Ops + CDP channels** | High-level multi-client `/ops` plus legacy `/cdp` compatibility |
+| **Ops + Canvas + CDP channels** | High-level multi-client `/ops`, dedicated `/canvas`, plus legacy `/cdp` compatibility |
 | **Relay Hub (FIFO leases)** | Single-owner CDP binding with a FIFO queue for multi-client safety |
 | **Flat-session routing** | Extension relay uses DebuggerSession sessionId routing (Chrome 125+) |
-| **5 bundled skill packs** | Best practices for login, forms, data extraction |
-| **41 tools** | Complete browser automation coverage |
+| **Design canvas + code sync** | Persist repo-native design documents, attach same-session observers, round-trip bound TSX files, and drive preview tabs with `canvas_html` or opted-in `bound_app_runtime` reconciliation |
+| **Loop-closure diagnostics** | Console/network polling + unified debug trace snapshots for verification workflows |
+| **10 bundled skill directories** | Best practices plus login, forms, data extraction, research, shopping, and product asset workflows |
+| **49 tools** | Complete browser automation coverage, including the design-canvas command surface |
 | **97% test coverage** | Production-ready with strict TypeScript |
 
 ---
 
 ## Installation
 
+Requires Node.js `>=18`.
+
 ### For Humans
 
 ```bash
@@ -60,14 +70,46 @@ npx opendevbrowser --local    # ./opencode.json
 
 # Full install (config + extension assets)
 npx opendevbrowser --full
+
+# Optional: persistent global CLI
+npm install -g opendevbrowser
+opendevbrowser --version
 ```
 
+### Pre-release Local Package (No npm publish required)
+
+Use this path to validate first-run onboarding before public distribution:
+
+```bash
+cd <public-repo-root>
+npm pack
+
+WORKDIR=$(mktemp -d /tmp/opendevbrowser-first-run-XXXXXX)
+cd "$WORKDIR"
+npm init -y
+npm install <public-repo-root>/opendevbrowser-0.0.17.tgz
+npx --no-install opendevbrowser --help
+npx --no-install opendevbrowser help
+```
+
+Full validated flow: [`docs/FIRST_RUN_ONBOARDING.md`](docs/FIRST_RUN_ONBOARDING.md).
+Dependency/runtime inventory: [`docs/DEPENDENCIES.md`](docs/DEPENDENCIES.md).
+Live CLI inventory/help surface: `npx opendevbrowser --help` or `npx opendevbrowser help`.
+
 Use OpenCode only if you want plugin tools. CLI and extension workflows work without OpenCode.
 
 On first successful install, the CLI attempts to install daemon auto-start on supported platforms so the relay is available on login.
 You can remove it later with `npx opendevbrowser daemon uninstall`.
 
-OpenCode discovers skills in `.opencode/skill` (project) and `~/.config/opencode/skill` (global) first; `.claude/skills` is compatibility-only. The CLI installs bundled skills into the OpenCode-native locations by default.
+During install, bundled skills are synced for **OpenCode, Codex, ClaudeCode, and AmpCLI**.
+Default `--skills-global` targets:
+- `~/.config/opencode/skill` (OpenCode)
+- `$CODEX_HOME/skills` (fallback `~/.codex/skills`)
+- `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (fallback `~/.claude/skills`)
+- `$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` (fallback `~/.amp/skills`)
+
+Use `--skills-local` for project-local targets:
+- `./.opencode/skill`, `./.codex/skills`, `./.claude/skills`, `./.amp/skills`
 
 ### CLI + Extension (No OpenCode)
 
@@ -82,6 +124,22 @@ npx opendevbrowser launch --extension-only --wait-for-extension
 npx opendevbrowser launch --no-extension
 ```
 
+Unpacked extension load path after local install:
+- `<WORKDIR>/node_modules/opendevbrowser/extension`
+
+### Frontend Website (Private Repo)
+
+```bash
+git clone https://github.com/freshtechbro/opendevbrowser-website-deploy.git
+cd opendevbrowser-website-deploy/frontend
+npm install
+npm run dev
+```
+
+Website build/data pipeline lives in the private repo:
+- `npm run sync:assets` copies mirrored assets into private `frontend/public/brand`.
+- `npm run generate:docs` regenerates docs, metrics, and roadmap JSON consumed by `/docs`.
+
 ### Agent Installation (OpenCode)
 
 Recommended (CLI, installs plugin + config + bundled skills + extension assets):
@@ -123,6 +181,11 @@ OpenDevBrowser uses the same automation model across plugin tools and CLI comman
 5. Re-snapshot after navigation
 ```
 
+Shipping checklist for first-time users (local-package install, daemon, extension, first task, multi-tab auth/cookies):
+- [`docs/FIRST_RUN_ONBOARDING.md`](docs/FIRST_RUN_ONBOARDING.md)
+
+Parallel execution is target-scoped (`ExecutionKey = (sessionId,targetId)`): same target is FIFO, different targets can run concurrently up to the governor cap. `session-per-worker` remains the safest baseline for strict isolation. See [`docs/CLI.md`](docs/CLI.md) (Concurrency semantics) and [`skills/opendevbrowser-best-practices/artifacts/provider-workflows.md`](skills/opendevbrowser-best-practices/artifacts/provider-workflows.md) (Workflow E).
+
 ### Core Workflow (Plugin Tools)
 
 | Step | Tool | Purpose |
@@ -159,6 +222,9 @@ npx opendevbrowser snapshot --session-id <session-id>
 npx opendevbrowser click --session-id <session-id> --ref r12
 ```
 
+`opendevbrowser serve` includes stale-daemon preflight cleanup by default, so orphan daemon processes are terminated automatically
+before startup while preserving the active daemon on the requested port.
+
 For single-shot scripts:
 
 ```bash
@@ -171,7 +237,21 @@ Use `--output-format json|stream-json` for automation-friendly output.
 
 ## Recent Features
 
-### v0.0.15 (Latest)
+### v0.0.17 (Latest)
+
+- **Design canvas runtime is now shipped end-to-end** across core, CLI, tool, relay, and extension surfaces, including `canvas.html`, overlay control, preview feedback, and repo-backed code sync.
+- **Canvas surface governance and skill-pack coverage** now include current `/canvas` inventories, handshake/blocker templates, and feedback-evaluation artifacts.
+- **Release packaging/docs were refreshed for v0.0.17**, including current tarball examples, extension version sync, release evidence, and public/private cutover guidance.
+
+### v0.0.16
+
+- **Release-gate hardening** with dedicated audit/compliance scripts (`audit-zombie-files`, `docs-drift-check`, `chrome-store-compliance-check`) and grouped release-gate tests.
+- **Live matrix robustness upgrades** across `live-regression-matrix` and `provider-live-matrix` (strict `--release-gate`, extension/CDP recovery paths, deterministic strict-mode semantics).
+- **CLI/runtime reliability fixes** including launch RPC timeout derivation from wait hints, bounded macro execute timeouts, and stale extension `/cdp` attach retry handling.
+- **Version/distribution integrity checks** now enforce parity across `package.json`, `extension/manifest.json`, and `extension/package.json`.
+- **Dependency and docs refresh** for v0.0.16 release readiness, onboarding parity, and public/private distribution operations.
+
+### v0.0.15
 
 - **Documentation and release readiness refresh** across README/CLI/extension guidance.
 - **Extension mode stabilization** with stronger native host flow and recovery paths.
@@ -206,9 +286,15 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 ### DevTools Integration
 - **Console Capture** - Monitor console.log, errors, warnings
 - **Network Tracking** - Request/response metadata (method, url, status)
+- **Debug Trace Snapshot** - Combined page/console/network/exception diagnostics with blocker metadata
 - **Screenshot** - Viewport PNG screenshot (file or base64)
 - **Performance** - Page load metrics
 
+### Session & Macro Utilities
+- **Cookie Import** - Validate and import cookies into active sessions
+- **Cookie List** - First-class cookie inspection with optional URL filters
+- **Macro Resolve/Execute** - Expand macro expressions into provider actions with optional execution
+
 ### Export & Clone
 - **DOM Capture** - Extract sanitized HTML with inline styles
 - **React Emitter** - Generate React component code from pages
@@ -218,8 +304,9 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 
 ## Tool Reference
 
-OpenDevBrowser provides **41 tools** organized by category:
+OpenDevBrowser provides **49 tools** organized by category:
 Most runtime actions also have CLI command equivalents (see [docs/CLI.md](docs/CLI.md)).
+Complete source-accurate inventory (tools + CLI + `/ops` + `/canvas` + `/cdp`): [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md).
 
 ### Session Management
 | Tool | Description |
@@ -228,6 +315,8 @@ Most runtime actions also have CLI command equivalents (see [docs/CLI.md](docs/C
 | `opendevbrowser_connect` | Connect to existing Chrome CDP endpoint (or relay `/ops`; legacy `/cdp` via `--extension-legacy`) |
 | `opendevbrowser_disconnect` | Disconnect browser session |
 | `opendevbrowser_status` | Get session status and connection info (daemon status in hub mode) |
+| `opendevbrowser_cookie_import` | Import validated cookies into the current session |
+| `opendevbrowser_cookie_list` | List session cookies with optional URL filters |
 
 ### Tab/Target Management
 | Tool | Description |
@@ -277,14 +366,25 @@ Most runtime actions also have CLI command equivalents (see [docs/CLI.md](docs/C
 |------|-------------|
 | `opendevbrowser_console_poll` | Poll console logs since sequence |
 | `opendevbrowser_network_poll` | Poll network requests since sequence |
+| `opendevbrowser_debug_trace_snapshot` | Capture a unified page + console + network + exception diagnostic bundle |
 | `opendevbrowser_screenshot` | Capture page screenshot |
 | `opendevbrowser_perf` | Get page performance metrics |
 | `opendevbrowser_prompting_guide` | Get best-practice prompting guidance |
 
+### Macro Workflows
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_macro_resolve` | Resolve macro expressions into provider action/provenance (optionally execute) |
+
 ### Annotation
 | Tool | Description |
 |------|-------------|
-| `opendevbrowser_annotate` | Capture interactive annotations via extension relay |
+| `opendevbrowser_annotate` | Capture interactive annotations via direct (CDP) or relay transport |
+
+### Design Canvas
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_canvas` | Execute typed design-canvas session, attach, code-sync, preview, feedback, and overlay commands |
 
 ### Export & Cloning
 | Tool | Description |
@@ -302,22 +402,32 @@ Most runtime actions also have CLI command equivalents (see [docs/CLI.md](docs/C
 
 ## Bundled Skills
 
-OpenDevBrowser includes **5 task-specific skill packs**:
+OpenDevBrowser includes **8 OpenDevBrowser-specific skill packs** plus shared `research` and `shopping` compatibility directories that are synced by the installer:
 
 | Skill | Purpose |
 |-------|---------|
 | `opendevbrowser-best-practices` | Core prompting patterns and workflow guidance |
 | `opendevbrowser-continuity-ledger` | Long-running task state management |
-| `login-automation` | Authentication flow patterns |
-| `form-testing` | Form validation and submission workflows |
-| `data-extraction` | Structured data scraping patterns |
+| `opendevbrowser-login-automation` | Authentication flow patterns |
+| `opendevbrowser-form-testing` | Form validation and submission workflows |
+| `opendevbrowser-data-extraction` | Structured data scraping patterns |
+| `opendevbrowser-research` | Deterministic multi-source research workflows |
+| `opendevbrowser-shopping` | Deterministic multi-provider deal comparison workflows |
+| `opendevbrowser-product-presentation-asset` | Product screenshot/copy asset collection for presentation pipelines |
+
+Installer note:
+- `--skills-global` and `--skills-local` copy every directory under `skills/`, including the shared `research/` and `shopping/` packs.
 
 Skills are discovered from (priority order):
 1. `.opencode/skill/` (project)
 2. `~/.config/opencode/skill/` (global)
-3. `.claude/skills/` (compatibility)
-4. `~/.claude/skills/` (compatibility)
-5. Custom paths via `skillPaths` config
+3. `.codex/skills/` (project compatibility)
+4. `$CODEX_HOME/skills` (global compatibility; fallback `~/.codex/skills`)
+5. `.claude/skills/` (ClaudeCode project compatibility)
+6. `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (ClaudeCode global compatibility; fallback `~/.claude/skills`)
+7. `.amp/skills/` (AmpCLI project compatibility)
+8. `$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` (AmpCLI global compatibility; fallback `~/.amp/skills`)
+9. Custom paths via `skillPaths` config
 
 Load a skill: `opendevbrowser_skill_load` with `name` and optional `topic` filter.
 
@@ -337,17 +447,21 @@ Extension relay relies on **flat CDP sessions (Chrome 125+)** and uses DebuggerS
 
 Relay ops endpoint: `ws://127.0.0.1:<relayPort>/ops`.
 The connect command also accepts base relay WS URLs (`ws://127.0.0.1:<relayPort>` or `ws://localhost:<relayPort>`) and normalizes them to `/ops`.
+Relay canvas endpoint: `ws://127.0.0.1:<relayPort>/canvas` for design-canvas editor, session attach/lease flow, code-sync, preview, feedback, and overlay flows.
 Legacy relay `/cdp` remains available with explicit opt-in (`--extension-legacy`).
-When pairing is enabled, both `/ops` and `/cdp` require a relay token (`?token=<relayToken>`). Tools and the CLI auto-fetch relay config and tokens.
+When pairing is enabled, `/ops`, `/canvas`, and `/cdp` require a relay token (`?token=<relayToken>`). Tools and the CLI auto-fetch relay config and tokens.
 
-## Ops vs CDP
+## Relay Channels
 
 | Channel | What It Does | When to Use It |
 |---------|---------------|----------------|
 | **`/ops` (default)** | High-level automation protocol with session ownership, event streaming, and multi-client handling | Preferred extension relay path for modern workflows |
+| **`/canvas`** | Typed design-canvas protocol for session handshakes/attach, live editor sync, TSX code sync, preview tabs, feedback streams, and overlay selection | Use with `opendevbrowser_canvas` or `opendevbrowser canvas` during design-canvas workflows |
 | **`/cdp` (legacy)** | Low-level CDP relay path with compatibility-focused behavior | Opt-in compatibility mode (`--extension-legacy`) |
 | **Direct CDP connect** | Attach to Chrome started with `--remote-debugging-port` | Existing debug/browser setups without extension relay |
 
+For full `/ops` and `/canvas` command names, `/cdp` envelope details, and mode/flag matrices, see [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md).
+
 ---
 
 ## Breaking Changes (latest)
@@ -370,7 +484,7 @@ The runtime (plugin or CLI daemon) and extension can automatically pair:
 3. Extension fetches relay port from discovery, then fetches token from the relay server
 4. Connection established with color indicator (green = connected)
 
-**Auto-connect** and **Auto-pair** are enabled by default for a seamless setup. The extension badge shows status (ON/OFF).
+**Auto-connect** and **Auto-pair** are enabled by default for a seamless setup. The extension badge shows a small status dot (green = connected, red = disconnected).
 If the relay is unavailable, the background worker retries `/config` + `/pair` with exponential backoff (using `chrome.alarms`).
 
 ### Default Settings (Extension)
@@ -455,6 +569,15 @@ Optional config file: `~/.config/opencode/opendevbrowser.jsonc`
     "allowUnsafeExport": false
   },
 
+  // Provider workflow cookie defaults (optional)
+  "providers": {
+    "cookiePolicy": "auto",
+    "cookieSource": {
+      "type": "file",
+      "value": "~/.config/opencode/opendevbrowser.provider-cookies.json"
+    }
+  },
+
   // Skills configuration
   "skills": {
     "nudge": {
@@ -495,9 +618,23 @@ All fields are optional. OpenDevBrowser works with sensible defaults.
 
 ## CLI Commands
 
-The CLI is agent-agnostic and supports the full automation surface (session, navigation, interaction, DOM, targets, pages, export, devtools, and annotate).
+The CLI is agent-agnostic and supports the full automation surface (session, navigation, interaction, DOM, targets, pages, export, devtools, annotate, and canvas).
 All commands listed in the CLI reference are implemented and available in the current codebase.
 See [docs/CLI.md](docs/CLI.md) for the full command and flag matrix.
+See [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md) for the source-accurate inventory matrix (CLI commands, 49 tools, `/ops`, `/canvas`, and `/cdp` channel contracts).
+
+### CLI Category Matrix (core command groups)
+
+| Category | Commands |
+|---------|----------|
+| Install/runtime | `install`, `update`, `uninstall`, `help`, `version`, `serve`, `daemon`, `native`, `run` |
+| Session/connection | `launch`, `connect`, `disconnect`, `status`, `cookie-import`, `cookie-list` |
+| Navigation | `goto`, `wait`, `snapshot` |
+| Interaction | `click`, `hover`, `press`, `check`, `uncheck`, `type`, `select`, `scroll`, `scroll-into-view` |
+| Targets/pages | `targets-list`, `target-use`, `target-new`, `target-close`, `page`, `pages`, `page-close` |
+| DOM | `dom-html`, `dom-text`, `dom-attr`, `dom-value`, `dom-visible`, `dom-enabled`, `dom-checked` |
+| Design canvas | `canvas` |
+| Export/diagnostics/macro/annotation/power | `clone-page`, `clone-component`, `perf`, `screenshot`, `console-poll`, `network-poll`, `debug-trace-snapshot`, `macro-resolve`, `annotate`, `rpc` |
 
 ### Install/Management
 
@@ -508,6 +645,7 @@ See [docs/CLI.md](docs/CLI.md) for the full command and flag matrix.
 | `npx opendevbrowser --local` | Install to project config |
 | `npx opendevbrowser --with-config` | Also create opendevbrowser.jsonc |
 | `npx opendevbrowser --full` | Full install (config + extension assets) |
+| `npm install -g opendevbrowser` | Install persistent global CLI |
 | `npx opendevbrowser --update` | Clear cache, trigger reinstall |
 | `npx opendevbrowser --uninstall` | Remove from config |
 | `npx opendevbrowser --version` | Show version |
@@ -530,6 +668,13 @@ Start the daemon with `npx opendevbrowser serve`, then use:
 | `npx opendevbrowser select` | Select dropdown option by ref |
 | `npx opendevbrowser scroll` | Scroll page or element |
 | `npx opendevbrowser run` | Run a JSON script |
+| `npx opendevbrowser canvas --command canvas.session.open --params '{...}'` | Start or continue a design-canvas workflow through the daemon |
+| `npx opendevbrowser macro-resolve --expression '@media.search("youtube transcript parity", "youtube", 5)' --execute --timeout-ms 120000` | Execute macro plans with extended timeout for slow runs |
+
+Workflow cookie controls (`research run`, `shopping run`, `product-video run`):
+- Defaults come from `providers.cookiePolicy` (`off|auto|required`) and `providers.cookieSource` (`file|env|inline`).
+- Per-run overrides: `--use-cookies`, `--cookie-policy-override` (alias `--cookie-policy`).
+- `auto` is non-blocking when cookies are unavailable; `required` fails fast with `reasonCode=auth_required`.
 
 ---
 
@@ -541,7 +686,7 @@ OpenDevBrowser is **secure by default** with defense-in-depth protections:
 |------------|---------|
 | **CDP Localhost-Only** | Remote endpoints blocked; hostname normalized to prevent bypass |
 | **Timing-Safe Auth** | `crypto.timingSafeEqual()` for token comparison |
-| **Origin Validation** | `/extension` requires `chrome-extension://` origin; `/ops`, `/cdp`, `/annotation`, and `/config`/`/status`/`/pair` allow loopback no-Origin requests |
+| **Origin Validation** | `/extension` requires `chrome-extension://` origin; `/ops`, `/canvas`, `/cdp`, `/annotation`, and `/config`/`/status`/`/pair` allow loopback no-Origin requests |
 | **PNA Preflights** | HTTP preflights include `Access-Control-Allow-Private-Network: true` when requested |
 | **Rate Limiting** | 5 handshake attempts/minute per IP, plus HTTP rate limiting for `/config`, `/status`, `/pair` |
 | **Data Redaction** | Tokens, API keys, sensitive paths auto-redacted |
@@ -564,28 +709,86 @@ npx opendevbrowser --update
 
 Architecture overview: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 Release checklist: [docs/DISTRIBUTION_PLAN.md](docs/DISTRIBUTION_PLAN.md)
+Documentation index: [docs/README.md](docs/README.md)
+Frontend docs: [docs/FRONTEND.md](docs/FRONTEND.md)
+Dependency inventory: [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md)
 
 ---
 
 ## Architecture
 
 ```
-src/
-├── browser/      # BrowserManager, TargetManager, CDP lifecycle
-├── cli/          # CLI commands and installers
-├── core/         # Bootstrap, runtime wiring
-├── devtools/     # Console/network trackers with redaction
-├── export/       # DOM capture, React emitter, CSS extraction
-├── relay/        # Extension relay server, protocol types
-├── skills/       # SkillLoader for skill pack discovery
-├── snapshot/     # AX-tree snapshots, ref management
-├── tools/        # 41 opendevbrowser_* tool definitions
-└── utils/        # Shared utilities
+┌─────────────────────────────────────────────────────────────────┐
+│                      Distribution Layer                         │
+├──────────────────┬──────────────────┬──────────────────┬──────────────────────────┤
+│  OpenCode Plugin │       CLI        │    Hub Daemon    │    Chrome Extension       │
+│  (src/index.ts)  │ (src/cli/index)  │ (opendevbrowser  │   (extension/src/)        │
+│                  │                  │      serve)     │                           │
+└────────┬─────────┴────────┬─────────┴─────────┬────────┴──────────────┬────────────┘
+         │                  │                  │                       │
+         ▼                  ▼                  ▼                       ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Core Runtime (src/core/)                    │
+│  bootstrap.ts → wires managers, injects ToolDeps              │
+└────────┬────────────────────────────────────────────────────────┘
+         │
+    ┌────┴────┬─────────────┬──────────────┬──────────────┬──────────────┐
+    ▼         ▼             ▼              ▼              ▼              ▼
+┌────────┐ ┌────────┐ ┌──────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
+│Browser │ │Script  │ │Snapshot  │ │ Annotation │ │  Relay     │ │  Skills    │
+│Manager │ │Runner  │ │Pipeline  │ │  Manager   │ │  Server    │ │  Loader    │
+└───┬────┘ └────────┘ └──────────┘ └────────────┘ └─────┬──────┘ └────────────┘
+    │                                                  │
+    ▼                                                  ▼
+┌────────┐                                        ┌────────────┐
+│Target  │                                        │ Extension  │
+│Manager │                                        │ (WS relay) │
+└────────┘                                        └────────────┘
+```
+
+### Data Flow
+
+```
+Tool Call → Zod Validation → Manager/Runner → CDP/Playwright → Response
+                                   ↓
+                            Snapshot (AX-tree → refs)
+                                   ↓
+                            Action (ref → backendNodeId → DOM)
+```
+
+### System Workflow (Happy Path)
+
+1. `launch` (extension or managed) -> `sessionId`
+2. `snapshot` -> refs
+3. Action commands (`click`, `type`, `press`, `hover`, `check`, etc.) -> repeat snapshot
+4. `disconnect` on completion
+
+### Repository Layout
+
+```
+.
+├── src/              # Plugin implementation
+│   ├── browser/      # BrowserManager, TargetManager, CDP lifecycle
+│   ├── cache/        # Chrome executable resolution
+│   ├── cli/          # CLI commands, daemon, installers
+│   ├── core/         # Bootstrap, runtime wiring, ToolDeps
+│   ├── canvas/       # Design-canvas document store, repo IO, export helpers
+│   ├── devtools/     # Console/network trackers with redaction
+│   ├── export/       # DOM capture, React emitter, CSS extraction
+│   ├── relay/        # Extension relay server, protocol types
+│   ├── skills/       # SkillLoader for skill pack discovery
+│   ├── snapshot/     # AX-tree snapshots, ref management
+│   ├── tools/        # 49 opendevbrowser_* tool definitions
+│   ├── annotate/     # Annotation transports + output shaping
+│   └── utils/        # Shared utilities
+├── extension/        # Chrome extension (relay client)
+├── scripts/          # Operational scripts (build/sync/smoke)
+├── skills/           # Bundled skill directories (10 total; 8 canonical OpenDevBrowser packs + 2 shared compatibility packs)
+├── tests/            # Vitest tests (97% coverage required)
+└── docs/             # Architecture, CLI, extension, distribution plans
 ```
 
-Extension relay uses flat CDP sessions (Chrome 125+) with DebuggerSession `sessionId` routing for multi-tab support.
-When hub mode is enabled, the hub daemon is the sole relay owner and enforces a FIFO lease queue for multi-client safety.
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed component diagrams.
+Extension relay uses flat CDP sessions (Chrome 125+) with DebuggerSession `sessionId` routing for multi-tab support. When hub mode is enabled, the hub daemon is the sole relay owner and enforces a FIFO lease queue for multi-client safety. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture reference.
 
 ---
 
@@ -601,19 +804,35 @@ npm run version:check    # Verify package/extension version alignment
 npm run extension:pack   # Build extension zip for releases
 ```
 
-### Packaging & Distribution (NPM + GitHub + Extension)
+### Packaging & Distribution (Public + Private)
 
 Uniform versioning is required (source of truth: `package.json`):
 
 1. Bump `package.json` version.
 2. Run: `npm run extension:sync`
 3. Run: `npm run version:check`
-4. Run: `npm run build`
-5. Run: `npm run extension:build`
-6. Run: `npm run extension:pack` (outputs `./opendevbrowser-extension.zip`)
-7. Publish to NPM and attach the zip to the GitHub release tag (`vX.Y.Z`).
-
-Release checklist: `docs/DISTRIBUTION_PLAN.md`
+4. Run: `npm run test:release-gate`
+5. Run: `npm run build`
+6. Run: `npm run extension:build`
+7. Run release audits:
+   - `node scripts/audit-zombie-files.mjs`
+   - `node scripts/docs-drift-check.mjs`
+   - `node scripts/chrome-store-compliance-check.mjs`
+   - `./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh`
+8. Run strict live release gates:
+   - `node scripts/provider-live-matrix.mjs --release-gate --out artifacts/release/vX.Y.Z/provider-live-matrix.json`
+   - `node scripts/live-regression-matrix.mjs --release-gate`
+9. Run first-time global install dry run checklist from `docs/FIRST_RUN_ONBOARDING.md`.
+10. Run: `npm run extension:pack` (outputs `./opendevbrowser-extension.zip`)
+11. Run: `npm pack`
+12. Tag `vX.Y.Z` and let `.github/workflows/release-public.yml` publish npm + GitHub release artifacts.
+13. Dispatch website content sync to private repo through `.github/workflows/dispatch-private-sync.yml`.
+
+Runbooks:
+- `docs/DISTRIBUTION_PLAN.md`
+- `docs/RELEASE_RUNBOOK.md`
+- `docs/EXTENSION_RELEASE_RUNBOOK.md`
+- `docs/CUTOVER_CHECKLIST.md`
 
 ---
 

package/dist/annotate/direct-annotator.d.ts

@@ -0,0 +1,22 @@
+import type { BrowserManagerLike } from "../browser/manager-types";
+import type { AnnotationResponse, AnnotationScreenshotMode } from "../relay/protocol";
+export type DirectAnnotateAssets = {
+    scriptPath: string;
+    stylePath: string;
+};
+export type DirectAnnotateRequest = {
+    sessionId: string;
+    targetId?: string;
+    url?: string;
+    screenshotMode?: AnnotationScreenshotMode;
+    debug?: boolean;
+    context?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export declare function resolveDirectAnnotateAssets(resolvePath?: () => string | null): {
+    assets?: DirectAnnotateAssets;
+    error?: string;
+};
+export declare function runDirectAnnotate(manager: BrowserManagerLike, assets: DirectAnnotateAssets, request: DirectAnnotateRequest): Promise<AnnotationResponse>;
+//# sourceMappingURL=direct-annotator.d.ts.map

package/dist/annotate/direct-annotator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-annotator.d.ts","sourceRoot":"","sources":["../../src/annotate/direct-annotator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,EAGV,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAeF,wBAAgB,2BAA2B,CACzC,WAAW,GAAE,MAAM,MAAM,GAAG,IAAuB,GAClD;IAAE,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAWnD;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA4E7B"}

package/dist/annotate/output.d.ts

@@ -0,0 +1,10 @@
+import type { AnnotationPayload } from "../relay/protocol";
+export declare const buildAnnotateResult: (payload: AnnotationPayload) => Promise<{
+    message: string;
+    details: AnnotationPayload;
+    screenshots: Array<{
+        id: string;
+        path: string;
+    }>;
+}>;
+//# sourceMappingURL=output.d.ts.map

package/dist/annotate/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/annotate/output.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAwC,MAAM,mBAAmB,CAAC;AA+HjG,eAAO,MAAM,mBAAmB,GAC9B,SAAS,iBAAiB,KACzB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAS3G,CAAC"}

package/dist/browser/annotation-manager.d.ts

@@ -0,0 +1,33 @@
+import type { OpenDevBrowserConfig } from "../config";
+import type { RelayLike } from "../relay/relay-types";
+import type { BrowserManagerLike } from "./manager-types";
+import type { AnnotationResponse, AnnotationScreenshotMode, AnnotationTransport } from "../relay/protocol";
+export type AnnotationRequestOptions = {
+    sessionId?: string;
+    targetId?: string;
+    tabId?: number;
+    transport?: AnnotationTransport;
+    stored?: boolean;
+    includeScreenshots?: boolean;
+    url?: string;
+    screenshotMode?: AnnotationScreenshotMode;
+    debug?: boolean;
+    context?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export declare class AnnotationManager {
+    private relay;
+    private config;
+    private manager?;
+    constructor(relay: RelayLike | undefined, config: OpenDevBrowserConfig, manager?: BrowserManagerLike);
+    setRelay(relay: RelayLike | undefined): void;
+    setBrowserManager(manager?: BrowserManagerLike): void;
+    requestAnnotation(options: AnnotationRequestOptions): Promise<AnnotationResponse>;
+    private requestStored;
+    private canFallbackToRelay;
+    private getRelayEndpoint;
+    private requestDirect;
+    private requestRelay;
+}
+//# sourceMappingURL=annotation-manager.d.ts.map

package/dist/browser/annotation-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-manager.d.ts","sourceRoot":"","sources":["../../src/browser/annotation-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAEV,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EAIpB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,OAAO,CAAC,CAAqB;gBAEzB,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,kBAAkB;IAMpG,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IAI5C,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI;IAI/C,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;YA+BzE,aAAa;YAmBb,kBAAkB;IAehC,OAAO,CAAC,gBAAgB;YAKV,aAAa;YAoDb,YAAY;CAoM3B"}