opendevbrowser 0.0.16 → 0.0.18

package/skills/opendevbrowser-best-practices/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: opendevbrowser-best-practices
 description: This skill should be used when the user asks to design or run OpenDevBrowser provider workflows, scraping pipelines, QA/debug automation, parity checks across modes, or resilient browser operations with codified scripts and artifacts.
-version: 2.3.0
+version: 2.6.0
 ---
 
 # OpenDevBrowser Best Practices
@@ -15,6 +15,8 @@ Use this skill when you need:
 - diagnostics for QA/debug (`console`, `network`, trace context),
 - safe write flows with explicit policy notice.
 
+For frontend, design-system, screenshot-to-code, or `/canvas` composition tasks, load `opendevbrowser-design-agent` immediately after this pack so the work is design-contract-first instead of operations-only.
+
 ## Pack Contents
 
 - `artifacts/provider-workflows.md` — canonical provider execution flows.
@@ -23,17 +25,24 @@ Use this skill when you need:
 - `artifacts/fingerprint-tiers.md` — hardening tiers and when to use each.
 - `artifacts/macro-workflows.md` — macro design and expansion standards.
 - `artifacts/browser-agent-known-issues-matrix.md` — known browser-agent failure modes mapped to required controls.
-- `artifacts/command-channel-reference.md` — CLI/tool/`/ops`/`/cdp` surface map plus cross-agent skill-sync targets.
+- `artifacts/command-channel-reference.md` — CLI/tool/`/ops`/`/canvas`/`/cdp` surface map plus cross-agent skill-sync targets.
+- `artifacts/canvas-governance-playbook.md` — `/canvas` preflight, blocker, and feedback-evaluation guidance.
+- `artifacts/skill-runtime-surface-matrix.md` — canonical skill-pack and runtime-family inventory for real-task audits.
 - `assets/templates/mode-flag-matrix.json` — mode + flag verification template.
 - `assets/templates/ops-request-envelope.json` — `/ops` request envelope template.
 - `assets/templates/cdp-forward-envelope.json` — `/cdp` relay envelope template.
 - `assets/templates/robustness-checklist.json` — shared issue-status checklist for workflow robustness audits.
 - `assets/templates/surface-audit-checklist.json` — docs/surface audit checklist template.
+- `assets/templates/skill-runtime-pack-matrix.json` — machine-readable canonical skill/runtime matrix for the audit runner.
+- `assets/templates/canvas-handshake-example.json` — canonical `/canvas` handshake example.
+- `assets/templates/canvas-generation-plan.v1.json` — required `canvas.plan.set` request skeleton.
+- `assets/templates/canvas-feedback-eval.json` — target-attributed feedback evaluation checklist.
+- `assets/templates/canvas-blocker-checklist.json` — machine-readable blocker and warning audit map.
 - `scripts/odb-workflow.sh` — prints codified command sequences by workflow.
 - `scripts/run-robustness-audit.sh` — validates workflow skill coverage against known issue IDs.
 - `scripts/validate-skill-assets.sh` — validates required artifacts/templates.
 
-## Fast Start
+## Quick Start
 
 1. Validate the skill pack:
 
@@ -53,6 +62,7 @@ Use this skill when you need:
 
 ```bash
 npx opendevbrowser --help
+npx opendevbrowser help
 ```
 
 5. Run robustness coverage checks across workflow skills:
@@ -61,6 +71,71 @@ npx opendevbrowser --help
 ./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh
 ```
 
+6. Pair with the dedicated design pack for frontend work:
+
+```bash
+./skills/opendevbrowser-design-agent/scripts/validate-skill-assets.sh
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh contract-first
+```
+
+## Help-Led Surface Discovery
+
+Start every surface audit with generated help so the capability map reflects the currently shipped runtime:
+
+- Browser replay: `screencast-start`, `screencast-stop`
+- Desktop observation: `desktop-status`, `desktop-windows`, `desktop-active-window`, `desktop-capture-desktop`, `desktop-capture-window`, `desktop-accessibility-snapshot`
+- Browser-scoped computer use: `--challenge-automation-mode off|browser|browser_with_helper` plus manager-owned `review`, `session-inspector`, and workflow fallback metadata
+
+Boundary rules:
+- desktop observation is public and read-only
+- the optional helper remains browser-scoped and is not a desktop agent
+- generated help, `docs/CLI.md`, and `docs/SURFACE_REFERENCE.md` must stay aligned whenever this wording changes
+
+## Validated Capability Lanes
+
+Load this section directly with:
+
+```text
+opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"
+```
+
+Current reliable lanes from the April 6 validation pass:
+
+1. Public-first YouTube transcript retrieval.
+
+```bash
+node scripts/youtube-transcript-live-probe.mjs --url "https://www.youtube.com/watch?v=aircAruvnKk" --youtube-mode auto --out artifacts/capability-fix/youtube-transcript-auto.json
+```
+
+Rules:
+- keep transcript runs public-first
+- browser-assisted transcript fallback is opt-in only
+- if browser fallback is enabled, use an isolated automation profile instead of a daily logged-in Google profile
+
+2. Generic topical research without shopping contamination.
+
+```bash
+npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --mode json --output-format json
+```
+
+Rules:
+- use `--source-selection auto` for general research
+- use `--source-selection shopping` or explicit `--sources ...shopping...` only when the task is deliberately commercial
+- in the current contract, `auto` and `all` both resolve to `web`, `community`, and `social`
+
+3. Deterministic shopping reruns with explicit providers.
+
+```bash
+npx opendevbrowser shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json
+npx opendevbrowser shopping run --query "27 inch 4k monitor" --providers shopping/bestbuy,shopping/ebay --budget 350 --sort lowest_price --browser-mode managed --mode json --output-format json
+npx opendevbrowser shopping run --query "wireless earbuds" --providers shopping/amazon --region us --browser-mode managed --mode json --output-format json
+```
+
+Rules:
+- use explicit providers plus `--browser-mode managed` for the most reproducible reruns
+- treat `--region` as advisory unless `meta.selection.region_authoritative=true`
+- inspect `meta.primaryConstraintSummary` and `meta.offerFilterDiagnostics` before calling a no-offer run a provider outage
+
 ## Agent Sync Targets
 
 Skill-pack installation and discovery are synchronized for:
@@ -71,13 +146,15 @@ Skill-pack installation and discovery are synchronized for:
 
 Legacy compatibility aliases `claude` and `amp` are preserved in installer target metadata.
 
+Install and update refresh managed copies of these canonical packs; uninstall removes managed canonical packs and only prunes empty legacy `research` or `shopping` leftovers.
+
 ## Required Operating Rules
 
 - Prefer refs from `opendevbrowser_snapshot` over raw selectors.
 - Use one action per decision loop: snapshot -> action -> snapshot.
 - Keep a single correlation context (`requestId`, `sessionId`) across a run.
 - Run the same workflow shape across all three modes before claiming parity.
-- Default to read/research workflows. Social posting probes remain disabled unless explicitly requested via matrix opt-in (`--include-social-posts`).
+- Default to read/research workflows. Social posting probes remain disabled unless explicitly requested via direct-run opt-in (`--include-social-posts`).
 - Apply rate-limit/backoff discipline (`Retry-After` aware) whenever 429 pressure appears.
 - Re-check extension readiness on resume when a run crosses idle windows.
 
@@ -146,6 +223,14 @@ opendevbrowser_network_poll sessionId="<session-id>" max=100
 opendevbrowser_screenshot sessionId="<session-id>"
 ```
 
+Use browser replay when timing matters:
+
+```text
+opendevbrowser_screencast_start sessionId="<session-id>" outputDir="./artifacts/qa-replay"
+# run the suspect flow
+opendevbrowser_screencast_stop sessionId="<session-id>" screencastId="<screencast-id>"
+```
+
 ### Read-Only Social Validation Workflow
 
 Goal: validate authenticated read/search capability without posting.
@@ -165,11 +250,16 @@ Use the router script to avoid retyping flows:
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh qa-debug
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh social-readonly-check
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh parity-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh release-direct-gates
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh surface-audit
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh ops-channel-check
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh cdp-channel-check
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh mode-flag-matrix
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh robustness-audit
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-preflight
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-feedback-eval
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh skill-runtime-audit
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh validated-capabilities
 ```
 
 ## Modes and Surface Parity
@@ -186,20 +276,107 @@ Parity gate test:
 npm run test -- tests/parity-matrix.test.ts
 ```
 
+Treat `tests/parity-matrix.test.ts` as contract coverage only. Live release proof comes from the direct-run harnesses below.
+This pack is the canonical owner of direct-run release evidence policy; other docs and skill packs should point here instead of restating the full policy.
+
 Real-world provider+mode scenario harness (soak replacement):
 
 ```bash
 npm run build
-node scripts/provider-live-matrix.mjs --use-global-env --skip-live-regression --out artifacts/provider-live-realworld.json
+node scripts/provider-direct-runs.mjs --out artifacts/provider-direct-realworld.json
+node scripts/live-regression-direct.mjs --out artifacts/live-regression-direct.json
 ```
 
 Surface inventory source of truth:
-- `docs/SURFACE_REFERENCE.md` (55 CLI commands, 48 tools, 38 `/ops` commands, `/cdp` envelope contracts)
+- `docs/SURFACE_REFERENCE.md` (72 CLI commands, 65 tools, 59 `/ops` commands, 35 `/canvas` commands, `/cdp` envelope contracts; mirrored by `npx opendevbrowser --help` and `npx opendevbrowser help`)
 - `artifacts/command-channel-reference.md` (skill-pack operational digest)
+- `artifacts/skill-runtime-surface-matrix.md` and `assets/templates/skill-runtime-pack-matrix.json` (canonical pack/runtime audit inventory)
+
+Direct-run release note:
+- `scripts/live-regression-direct.mjs` is the preferred release harness for `/canvas`, annotate, and CLI smoke. It uses temporary managed profiles for managed probes, waits for `/ops` drain before the legacy `/cdp` step, and keeps manual annotation timeouts as explicit `skipped` boundaries in `--release-gate` mode.
+- `scripts/provider-direct-runs.mjs --use-global-env --include-high-friction --include-auth-gated` is the preferred provider release harness. Treat `provider-live-matrix` and `live-regression-matrix` as debug-only helpers, not refreshed release evidence.
+
+## Skill Runtime Audit and Realignment
+
+This pack is the canonical owner of repo-local skill runtime audit policy and skill-pack runtime realignment.
+
+Use these assets when the task is to inventory or validate the full OpenDevBrowser skill/runtime surface:
+- `artifacts/skill-runtime-surface-matrix.md`
+- `assets/templates/skill-runtime-pack-matrix.json`
+- `scripts/skill-runtime-audit.mjs`
+
+Audit runtime rule:
+- `scripts/skill-runtime-audit.mjs` keeps smoke mode isolated and reproducible with temp harnesses, but full mode must reuse the current configured daemon and environment for `provider-direct` and `live-regression` so extension state, cookies, and auth-backed scenarios are exercised for real when available.
+
+Realignment rule:
+- when a pack drifts behind current runtime behavior, update the skill to match the repo reality and strengthen the workflow guidance instead of making the pack merely stop failing validation.
+
+## Canvas Governance Handshake
+
+Use the design-canvas surface when the workflow needs persisted design documents, explicit governance state, preview tabs, or overlay selection.
+
+Recommended command order:
+1. `opendevbrowser_canvas` or `opendevbrowser canvas --command canvas.session.open` to get `canvasSessionId`, `leaseId`, `preflightState`, governance block states, and generation-plan requirements.
+2. Read the handshake before mutating. The handshake is the source of truth for:
+   - `governanceRequirements.requiredBeforeMutation`
+   - `governanceRequirements.requiredBeforeSave`
+   - `generationPlanRequirements.requiredBeforeMutation`
+   - `allowedLibraries`
+   - `mutationPolicy.allowedBeforePlan`
+   - treat `allowedLibraries.components`, `allowedLibraries.icons`, and `allowedLibraries.styling` as separate policy lanes:
+     `components` are reusable UI adapters such as `shadcn`,
+     `icons` are approved icon families,
+     `styling` is for utility/theme adapters such as `tailwindcss`
+3. Submit `canvas.plan.set` with all required non-empty objects:
+   - `targetOutcome`
+   - `visualDirection`
+   - `layoutStrategy`
+   - `contentStrategy`
+   - `componentStrategy`
+   - `motionPosture`
+   - `responsivePosture`
+   - `accessibilityPosture`
+   - `validationTargets`
+4. Only after the plan is accepted, call `canvas.document.patch`.
+5. Use `canvas.preview.render`, `canvas.tab.open`, `canvas.overlay.mount`, and `canvas.overlay.select` when a browser-backed live view is required.
+6. Use `canvas.feedback.poll` for snapshot audits between mutation rounds, and use `canvas.feedback.subscribe` -> `canvas.feedback.next` -> `canvas.feedback.unsubscribe` when a live pull-stream is needed.
+7. Use `canvas.document.save` or `canvas.document.export` to persist artifacts.
+
+Code-sync surface:
+- `canvas.session.attach` joins an existing canvas session as an `observer` or reclaims the write lease with `attachMode=lease_reclaim`.
+- `canvas.code.bind`, `canvas.code.unbind`, `canvas.code.pull`, `canvas.code.push`, `canvas.code.status`, and `canvas.code.resolve` manage TSX-first document bindings when a canvas file is round-tripped to repo code.
+
+Current `/canvas` parity notes:
+- All 35 public `canvas.*` commands are agent-callable through `opendevbrowser_canvas` and `opendevbrowser canvas --command ...`.
+- `canvas.feedback.subscribe` live streaming is public through the CLI only: use `--output-format stream-json` for the built-in polling bridge.
+- Tool-driven agents can achieve the same public streaming behavior by calling `canvas.feedback.subscribe`, then repeating `canvas.feedback.next`, and finally `canvas.feedback.unsubscribe`.
+- `canvas.tab.sync` and `canvas.overlay.sync` are internal extension runtime helpers, not public commands.
+- `canvas_html` is still the default preview/export contract. `bound_app_runtime` is opt-in and only valid when runtime preflight and app-side instrumentation succeed.
+- Component and icon libraries currently render semantically, not package-faithfully. Treat `shadcn`, `tailwindcss`, `tabler`, `microsoft-fluent-ui-system-icons`, `3dicons`, and `@lobehub/fluent-emoji-3d` as metadata and constrained render lanes, not as general library import/export parity.
+- Annotation remains a separate surface today, but popup and canvas both ship per-item and combined `Copy` / `Send` actions. `Send` now delivers directly into the active agent chat when scope is safe and degrades to stored-only `annotate --stored` retrieval when scope is missing, ambiguous, or relay enqueue fails.
+
+Tailwind usage rule:
+- When `allowedLibraries.styling` includes `tailwindcss`, use it for layout, spacing, responsive, and state styling over canonical tokens/theme variables.
+- Do not treat Tailwind as a component inventory source or mix it into `componentStrategy.approvedLibraries`.
+- Preview/export should materialize a deterministic utility-class layer and stay self-contained; do not depend on a remote Tailwind CDN for canvas preview correctness.
+
+Failure handling:
+- `plan_required`: immediately call `canvas.plan.set`.
+- `revision_conflict`: reload with `canvas.document.load` and replay the patch batch against the latest revision.
+- `unsupported_target` or `restricted_url`: move the preview to a normal http(s) tab or fall back to managed mode.
+- If a freshly rebuilt unpacked extension still shows old `/canvas` or popup behavior, reload the extension in Chrome before trusting the live result; stale MV3 runtime state can preserve old service-worker logic after `npm run extension:build`.
+
+Operational references:
+- `artifacts/canvas-governance-playbook.md`
+- `assets/templates/canvas-handshake-example.json`
+- `assets/templates/canvas-generation-plan.v1.json`
+- `assets/templates/canvas-feedback-eval.json`
+- `assets/templates/canvas-blocker-checklist.json`
 
 ## Diagnostics and Traceability
 
 Current diagnostics tools:
+- `opendevbrowser_session_inspector` (session-first summary with relay health, target state, trace proof, and next-action guidance)
 - `opendevbrowser_console_poll`
 - `opendevbrowser_network_poll`
 - `opendevbrowser_debug_trace_snapshot` (combined page + console + network + exception channels)

package/skills/opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md

@@ -27,6 +27,7 @@ This matrix defines the minimum robustness controls for OpenDevBrowser workflow
 - `opendevbrowser-shopping`: `ISSUE-06`, `ISSUE-09`, `ISSUE-10`, `ISSUE-11`, `ISSUE-12`
 - `opendevbrowser-product-presentation-asset`: `ISSUE-10`, `ISSUE-11`, `ISSUE-12`
 - `opendevbrowser-research`: `ISSUE-06`, `ISSUE-09`, `ISSUE-10`, `ISSUE-12`
+- `opendevbrowser-design-agent`: `ISSUE-01`, `ISSUE-07`, `ISSUE-08`, `ISSUE-12`
 
 ## Source Notes
 

package/skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md

@@ -0,0 +1,141 @@
+# Canvas Governance Playbook
+
+## Purpose
+
+Use this playbook before any `/canvas` mutation and during every design-feedback loop. It keeps the runtime handshake, governance state, and evaluation rules aligned with the design-canvas spec.
+
+## Required command order
+
+1. `canvas.session.open`
+2. Read the handshake and confirm `preflightState: "handshake_read"`
+3. `canvas.plan.set`
+4. `canvas.plan.get` or `canvas.capabilities.get` until the runtime reports `plan_accepted`
+5. `canvas.document.patch`
+6. `canvas.preview.render` or `canvas.tab.open`
+7. `canvas.feedback.poll`
+8. `canvas.document.save` or `canvas.document.export`
+
+Mutation is blocked until the handshake has been read and the plan is accepted. A save is still invalid when required governance blocks remain missing in `requiredBeforeSave`.
+
+## Handshake requirements
+
+Every `canvas.session.open` response is the runtime contract. Read these fields before sending a patch:
+
+- `canvasSessionId`
+- `browserSessionId`
+- `documentId`
+- `leaseId`
+- `preflightState`
+- `governanceRequirements.requiredBeforeMutation`
+- `governanceRequirements.requiredBeforeSave`
+- `generationPlanRequirements.requiredBeforeMutation`
+- `allowedLibraries`
+- `allowedBeforePlan`
+
+Interpret `allowedLibraries` by lane:
+- `components` are reusable UI adapters such as `shadcn`
+- `icons` are approved icon families
+- `styling` is for utility/theme adapters such as `tailwindcss`
+- do not mix icon or styling libraries into `componentStrategy.approvedLibraries`
+
+Preflight states:
+- `handshake_read`
+- `plan_submitted`
+- `plan_accepted`
+- `patching_enabled`
+
+## Governance blocks
+
+The document must declare `designGovernance` with at least:
+
+- `intent`
+- `designLanguage`
+- `contentModel`
+- `layoutSystem`
+- `typographySystem`
+- `colorSystem`
+- `surfaceSystem`
+- `iconSystem`
+- `motionSystem`
+- `responsiveSystem`
+- `accessibilityPolicy`
+- `libraryPolicy`
+- `runtimeBudgets`
+
+The first accepted `generationPlan` must include:
+
+- `targetOutcome`
+- `visualDirection`
+- `layoutStrategy`
+- `contentStrategy`
+- `componentStrategy`
+- `motionPosture`
+- `responsivePosture`
+- `accessibilityPosture`
+- `validationTargets`
+
+## Blocker handling
+
+Canonical blocker path:
+
+```json
+{
+  "code": "plan_required",
+  "blockingCommand": "canvas.document.patch",
+  "requiredNextCommands": ["canvas.plan.set"],
+  "details": { "auditId": "CANVAS-01" }
+}
+```
+
+If `canvas.document.patch` or `canvas.document.save` returns a blocker, stop mutating and fix the missing handshake, governance, or plan requirement before retrying.
+
+## Canvas robustness issue classes
+
+| Audit ID | Failure class | Typical signal | Required response |
+|---|---|---|---|
+| `CANVAS-01` | Handshake missing or unread before mutation | `plan_required`, missing `handshake_read` evidence | Re-run `canvas.session.open` or `canvas.capabilities.get`, then `canvas.plan.set` |
+| `CANVAS-02` | Required governance block missing | save blocker, empty `requiredBeforeSave`, validation warning | Fill missing `designGovernance.*` fields before save/export |
+| `CANVAS-03` | Required `generationPlan` field missing or malformed | `canvas.plan.set` rejected or warnings retained | Submit a complete plan and wait for acceptance |
+| `CANVAS-04` | Library or icon-policy violation | validation warning, policy blocker, downgraded export | Adjust component/library choice to match `libraryPolicy` and `iconSystem` |
+| `CANVAS-05` | Unsupported target or overlay mount failure | `unsupported_target`, `restricted_url`, overlay mount error | Move to a normal http(s) preview target or managed mode |
+| `CANVAS-06` | Runtime budget exceeded or preview downgrade ignored | degrade warning, overflowed media/fonts/telemetry budget | Reduce preview cost or accept the downgrade before proceeding |
+| `CANVAS-07` | Feedback missing target attribution or validation metadata | feedback lacks `targetId`, `pageId`, `class`, or `evidenceRefs` | Re-poll or fix the feedback source before trusting the result |
+
+## Feedback evaluation loop
+
+Required categories:
+
+- `render`
+- `console`
+- `network`
+- `validation`
+- `performance`
+- `asset`
+- `export`
+
+Required fields per feedback item:
+
+- `documentId`
+- `pageId`
+- `prototypeId`
+- `targetId`
+- `documentRevision`
+- `severity`
+- `class`
+- `message`
+- `evidenceRefs`
+
+Streaming checks:
+
+- `feedback.item` carries the canonical feedback payload
+- `feedback.heartbeat` proves the subscription is still alive
+- `feedback.complete` explains why the stream ended
+
+## Router and template references
+
+- `scripts/odb-workflow.sh canvas-preflight`
+- `scripts/odb-workflow.sh canvas-feedback-eval`
+- `assets/templates/canvas-handshake-example.json`
+- `assets/templates/canvas-generation-plan.v1.json`
+- `assets/templates/canvas-feedback-eval.json`
+- `assets/templates/canvas-blocker-checklist.json`

package/skills/opendevbrowser-best-practices/artifacts/command-channel-reference.md

@@ -2,21 +2,23 @@
 
 ## Purpose
 
-Provide a compact, operationally useful map of OpenDevBrowser command surfaces and relay channels for parity checks.
+Compact operational map of the current OpenDevBrowser surfaces, with the `/canvas` handshake and blocker paths called out explicitly for preflight audits.
 
 ## Current coverage snapshot
 
-- CLI commands: `55`
-- Plugin tools: `48`
-- `/ops` command names: `38`
+- CLI commands: `72`
+- Plugin tools: `65`
+- `/ops` command names: `59`
+- `/canvas` command names: `35`
 - Legacy `/cdp` relay: generic CDP forwarding (method-level)
 
 Canonical exhaustive reference: `docs/SURFACE_REFERENCE.md`.
-CLI help mirror: `npx opendevbrowser --help` (surfaces CLI + tools + `/ops` + `/cdp` controls).
+CLI help mirror: `npx opendevbrowser --help` and `npx opendevbrowser help` (identical inventories).
+Help-led highlights: browser replay (`screencast-start`, `screencast-stop`), public desktop observation (`desktop-*`), and browser-scoped computer use (`--challenge-automation-mode off|browser|browser_with_helper`); the helper is not a desktop agent.
 
 ## Agent skill-sync coverage
 
-Skill-pack installation/discovery is synchronized for:
+Skill-pack installation and discovery are synchronized for:
 - `opencode`: `~/.config/opencode/skill` and `./.opencode/skill`
 - `codex`: `$CODEX_HOME/skills` (fallback `~/.codex/skills`) and `./.codex/skills`
 - `claudecode`: `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (fallback `~/.claude/skills`) and `./.claude/skills`
@@ -26,19 +28,23 @@ Legacy aliases `claude` and `amp` remain present in installer target metadata fo
 
 ## CLI surface categories
 
-- 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/runtime: `install`, `update`, `uninstall`, `help`, `version`, `serve`, `daemon`, `native`, `run`, `artifacts`
+- Session/connection/workflow: `launch`, `connect`, `disconnect`, `status`, `cookie-import`, `cookie-list`, `research`, `shopping`, `product-video`
+- Navigation/interaction: `goto`, `wait`, `snapshot`, `click`, `hover`, `press`, `check`, `uncheck`, `type`, `select`, `scroll`, `scroll-into-view`, `upload`
+- Pointer controls: `pointer-move`, `pointer-down`, `pointer-up`, `pointer-drag`
+- Targets/pages/DOM: `targets-list`, `target-use`, `target-new`, `target-close`, `page`, `pages`, `page-close`, `dom-html`, `dom-text`, `dom-attr`, `dom-value`, `dom-visible`, `dom-enabled`, `dom-checked`
+- Temporal capture: `screenshot`, `screencast-start`, `screencast-stop`
+- Desktop observation: `desktop-status`, `desktop-windows`, `desktop-active-window`, `desktop-capture-desktop`, `desktop-capture-window`, `desktop-accessibility-snapshot`
+- Browser-scoped computer-use control: `--challenge-automation-mode` on workflow and macro execute lanes, surfaced through manager-owned review, session-inspector, and fallback metadata rather than a standalone command family
+- Design canvas: `canvas`
+- Export/diagnostics/power: `clone-page`, `clone-component`, `perf`, `dialog`, `console-poll`, `network-poll`, `debug-trace-snapshot`, `session-inspector`, `macro-resolve`, `annotate`, `rpc`
 
 ## Tool surface categories
 
-- Runtime parity tools map to the CLI runtime categories.
+- Runtime parity tools map to the CLI runtime categories, including `opendevbrowser_canvas` and `opendevbrowser_session_inspector`.
+- Additional parity tools cover temporal browser capture (`opendevbrowser_screencast_start`, `opendevbrowser_screencast_stop`) and sibling desktop observation (`opendevbrowser_desktop_status`, `opendevbrowser_desktop_windows`, `opendevbrowser_desktop_active_window`, `opendevbrowser_desktop_capture_desktop`, `opendevbrowser_desktop_capture_window`, `opendevbrowser_desktop_accessibility_snapshot`).
 - Tool-only: `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, `opendevbrowser_skill_load`.
-- CLI-only: `rpc`.
+- CLI-only: `install`, `update`, `uninstall`, `help`, `version`, `serve`, `daemon`, `native`, `artifacts`, `rpc`.
 
 ## Relay channels
 
@@ -51,11 +57,14 @@ Namespace groups:
 - `page.*`
 - `nav.*`
 - `interact.*`
+- `pointer.*`
 - `dom.*`
+- `canvas.overlay.*`
+- `canvas.applyRuntimePreviewBridge`
 - `export.*`
 - `devtools.*`
 
-Handshake/liveness envelope types:
+Envelope types:
 - `ops_hello`, `ops_hello_ack`
 - `ops_ping`, `ops_pong`
 - `ops_request`, `ops_response`, `ops_error`
@@ -64,14 +73,111 @@ Handshake/liveness envelope types:
 Concurrency policy:
 - `/ops` supports multiple clients and multiple sessions.
 - Reliable parallel execution is session-scoped (`session-per-worker`).
-- Avoid concurrent independent streams that switch targets inside one session (`targets.use` races can cross-wire active target state).
+- Avoid concurrent independent streams that switch targets inside one session.
+
+### `/canvas`
+
+Core command families:
+- Session and governance: `canvas.session.open`, `canvas.session.attach`, `canvas.session.status`, `canvas.session.close`, `canvas.capabilities.get`, `canvas.plan.set`, `canvas.plan.get`
+- Document: `canvas.document.load`, `canvas.document.import`, `canvas.document.patch`, `canvas.document.save`, `canvas.document.export`
+- History, inventory, and starters: `canvas.history.undo`, `canvas.history.redo`, `canvas.inventory.list`, `canvas.inventory.insert`, `canvas.starter.list`, `canvas.starter.apply`
+- Live targets and overlay: `canvas.tab.open`, `canvas.tab.close`, `canvas.overlay.mount`, `canvas.overlay.unmount`, `canvas.overlay.select`
+- Preview and feedback: `canvas.preview.render`, `canvas.preview.refresh`, `canvas.feedback.poll`, `canvas.feedback.subscribe`, `canvas.feedback.next`, `canvas.feedback.unsubscribe`
+- Code sync: `canvas.code.bind`, `canvas.code.unbind`, `canvas.code.pull`, `canvas.code.push`, `canvas.code.status`, `canvas.code.resolve`
+
+Extension runtime subset:
+- `canvas.tab.open`, `canvas.tab.close`, `canvas.tab.sync`
+- `canvas.overlay.mount`, `canvas.overlay.unmount`, `canvas.overlay.select`, `canvas.overlay.sync`
+
+Envelope types:
+- `canvas_request`, `canvas_response`, `canvas_error`
+- `canvas_event`, `canvas_chunk`
+- `canvas_ping`, `canvas_pong`
+
+Minimum handshake payload shape:
+
+```json
+{
+  "canvasSessionId": "canvas_session_01",
+  "browserSessionId": "browser_session_01",
+  "documentId": "dc_01",
+  "leaseId": "lease_01",
+  "preflightState": "handshake_read",
+  "attachModes": ["observer", "lease_reclaim"],
+  "governanceRequirements": {
+    "requiredBeforeMutation": ["intent", "generationPlan", "designLanguage"],
+    "requiredBeforeSave": ["intent", "generationPlan", "runtimeBudgets"]
+  },
+  "generationPlanRequirements": {
+    "requiredBeforeMutation": ["targetOutcome", "visualDirection", "layoutStrategy"]
+  },
+  "allowedLibraries": {
+    "components": ["shadcn"],
+    "icons": ["lucide"],
+    "styling": ["tailwindcss"]
+  },
+  "mutationPolicy": {
+    "planRequiredBeforePatch": true,
+    "allowedBeforePlan": [
+      "canvas.capabilities.get",
+      "canvas.plan.get",
+      "canvas.plan.set",
+      "canvas.document.load",
+      "canvas.session.attach",
+      "canvas.session.status"
+    ]
+  }
+}
+```
+
+Preflight state machine:
+- `handshake_read`
+- `plan_submitted`
+- `plan_accepted`
+- `patching_enabled`
+
+The first mutation path must stay blocked until `canvas.plan.set` has been accepted. The canonical blocker is `plan_required` and should carry `details.auditId: "CANVAS-01"`.
+
+Recommended blocker envelope:
+
+```json
+{
+  "code": "plan_required",
+  "blockingCommand": "canvas.document.patch",
+  "requiredNextCommands": ["canvas.plan.set"],
+  "message": "generationPlan must be accepted before mutation.",
+  "details": { "auditId": "CANVAS-01" }
+}
+```
+
+Feedback contract markers:
+- Poll categories: `render`, `console`, `network`, `validation`, `performance`, `asset`, `export`, `code-sync`, `parity`
+- Feedback items must preserve `documentId`, `pageId`, `prototypeId`, `targetId`, `documentRevision`, `severity`, `class`, and `evidenceRefs`
+- Subscribe event types: `feedback.item`, `feedback.heartbeat`, `feedback.complete`
+
+Current operational constraints:
+- `canvas.feedback.subscribe` returns the initial payload on every public surface. For ongoing events:
+  - CLI: use `opendevbrowser canvas --command canvas.feedback.subscribe --output-format stream-json`
+  - tool/daemon loops: call `canvas.feedback.next` repeatedly, then `canvas.feedback.unsubscribe` when complete
+- Extension design-tab history clicks emit the internal `canvas_history_requested` event; the actual mutation still runs through public `canvas.history.undo` or `canvas.history.redo`, with `plan_required`, `history_empty`, or `history_invalidated` remaining the operator-facing outcomes.
+- `canvas.tab.sync` and `canvas.overlay.sync` are internal extension runtime helpers only.
+- `canvas_html` remains the default preview/export contract; `bound_app_runtime` is valid only when the binding explicitly opts in and runtime preflight succeeds.
+- Library metadata is preserved, but rendered output is still semantic rather than package-faithful.
+- Popup and canvas both ship per-item and combined annotation `Copy` / `Send` actions. `Send` dispatches `annotation:sendPayload`, posts `/annotation` `store_agent_payload`, and resolves through the shared `AgentInbox` when scope is safe; it degrades to stored-only `annotate --stored` retrieval when scope or relay conditions fail.
+- `/ops` pointer commands (`pointer.move`, `pointer.down`, `pointer.up`, `pointer.drag`) are part of the public default relay inventory and should be included in surface audits when low-level gesture coverage matters.
+- `/ops` preview/runtime bridge coverage includes `canvas.applyRuntimePreviewBridge` alongside overlay commands because extension runtime preview parity depends on both.
+
+Operational rule:
+- Read `canvas.session.open` or `canvas.capabilities.get` before mutation.
+- Use `canvas.feedback.poll` after each patch/render loop.
+- Do not save if `governanceRequirements.requiredBeforeSave` still reports missing governance blocks.
 
 ### `/cdp` (legacy)
 
 - Opt-in via `--extension-legacy`.
-- Forwards raw CDP commands through relay command envelopes (`id`, `method`, `params`, optional `sessionId`).
+- Forwards raw CDP command envelopes (`id`, `method`, `params`, optional `sessionId`).
 - Use for compatibility-specific paths only.
-- Treat as a legacy/single-writer path; do not use as the primary route for concurrent automation.
+- Treat as a legacy single-writer route, not the primary concurrent path.
 
 ## Mode and flag checkpoints
 
@@ -79,11 +185,13 @@ Concurrency policy:
 - Extension default: `launch` or relay-normalized `connect`
 - Extension legacy: `launch --extension-legacy` or `connect --extension-legacy`
 - Direct CDP: `connect --ws-endpoint ...` or `connect --host ... --cdp-port ...`
+- Direct release harnesses (`live-regression-direct`, `provider-direct-runs`) are the shipping evidence path; broad matrix wrappers are debug-only and should not replace fresh direct-run artifacts.
 
 Required readiness/status checks:
 - `extensionConnected`
 - `extensionHandshakeComplete`
 - `opsConnected`
+- `canvasConnected`
 - `cdpConnected`
 - `pairingRequired`
 
@@ -91,5 +199,7 @@ Required readiness/status checks:
 
 ```bash
 npm run test -- tests/parity-matrix.test.ts
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-preflight
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-feedback-eval
 ./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
 ```