opendevbrowser 0.0.15 → 0.0.16

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

@@ -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?
 
@@ -40,14 +46,17 @@ All core automation flows are available through the CLI command surface and the
 | **Ops + CDP channels** | High-level multi-client `/ops` 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 |
+| **Loop-closure diagnostics** | Console/network polling + unified debug trace snapshots for verification workflows |
+| **8 bundled skill packs** | Best practices plus login, forms, data extraction, research, shopping, and product asset workflows |
+| **48 tools** | Complete browser automation coverage |
 | **97% test coverage** | Production-ready with strict TypeScript |
 
 ---
 
 ## Installation
 
+Requires Node.js `>=18`.
+
 ### For Humans
 
 ```bash
@@ -60,14 +69,45 @@ 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.16.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).
+
 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 +122,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 +179,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 +220,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 +235,15 @@ Use `--output-format json|stream-json` for automation-friendly output.
 
 ## Recent Features
 
-### v0.0.15 (Latest)
+### v0.0.16 (Latest)
+
+- **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 +278,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 +296,9 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 
 ## Tool Reference
 
-OpenDevBrowser provides **41 tools** organized by category:
+OpenDevBrowser provides **48 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` + `/cdp`): [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md).
 
 ### Session Management
 | Tool | Description |
@@ -228,6 +307,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,10 +358,16 @@ 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 |
 |------|-------------|
@@ -302,22 +389,29 @@ 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 task-specific skill packs**:
 
 | 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 |
 
 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.
 
@@ -348,6 +442,8 @@ When pairing is enabled, both `/ops` and `/cdp` require a relay token (`?token=<
 | **`/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` command names, `/cdp` envelope details, and mode/flag matrices, see [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md).
+
 ---
 
 ## Breaking Changes (latest)
@@ -370,7 +466,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 +551,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": {
@@ -498,6 +603,19 @@ All fields are optional. OpenDevBrowser works with sensible defaults.
 The CLI is agent-agnostic and supports the full automation surface (session, navigation, interaction, DOM, targets, pages, export, devtools, and annotate).
 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, 48 tools, `/ops` 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` |
+| 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 +626,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 +649,12 @@ 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 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`.
 
 ---
 
@@ -564,28 +689,85 @@ 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) │
+└────────┘                                        └────────────┘
 ```
 
-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.
+### 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
+│   ├── 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/        # 48 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 packs (8 total)
+├── 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 the full architecture reference.
 
 ---
 
@@ -601,7 +783,7 @@ 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`):
 
@@ -610,10 +792,23 @@ Uniform versioning is required (source of truth: `package.json`):
 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`
+6. Run release audits:
+   - `node scripts/audit-zombie-files.mjs`
+   - `node scripts/docs-drift-check.mjs`
+   - `node scripts/chrome-store-compliance-check.mjs`
+7. Run strict live release gates:
+   - `node scripts/provider-live-matrix.mjs --release-gate --out artifacts/release/v0.0.16/provider-live-matrix.json`
+   - `node scripts/live-regression-matrix.mjs --release-gate`
+8. Run first-time global install dry run checklist from `docs/FIRST_RUN_ONBOARDING.md`.
+9. Run: `npm run extension:pack` (outputs `./opendevbrowser-extension.zip`)
+10. Tag `vX.Y.Z` and let `.github/workflows/release-public.yml` publish npm + GitHub release artifacts.
+11. 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,30 @@
+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;
+    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 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,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;YA4BzE,kBAAkB;IAehC,OAAO,CAAC,gBAAgB;YAKV,aAAa;YAoDb,YAAY;CA+J3B"}