opendevbrowser 0.0.19 → 0.0.21

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

@@ -84,7 +84,8 @@ Start every surface audit with generated help so the capability map reflects the
 
 - 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
+- Desktop-assisted browser review: `review-desktop`
+- Browser-scoped computer use: `--challenge-automation-mode off|browser|browser_with_helper`, `status-capabilities`, `session-inspector-plan`, `session-inspector-audit`, plus manager-owned `review`, `session-inspector`, and workflow fallback metadata
 
 Boundary rules:
 - desktop observation is public and read-only
@@ -99,7 +100,7 @@ Load this section directly with:
 opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"
 ```
 
-Current reliable lanes from the April 6 validation pass:
+Current reliable lanes:
 
 1. Public-first YouTube transcript retrieval.
 
@@ -134,17 +135,28 @@ npx opendevbrowser shopping run --query "wireless earbuds" --providers shopping/
 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
+- inspect `meta.primaryConstraintSummary` first on no-offer runs
+- if `meta.primaryConstraint.guidance` is present, follow `meta.primaryConstraint.guidance.reason` and `meta.primaryConstraint.guidance.recommendedNextCommands[]`
+- if guidance is absent, inspect `meta.offerFilterDiagnostics` before calling a no-offer run a provider outage
+
+4. Design-contract synthesis with repeated public references.
+
+```bash
+npx opendevbrowser inspiredesign run --brief "Design a premium docs workspace" --url "https://example.com/reference-a" --url "https://example.com/reference-b" --capture-mode off --include-prototype-guidance --mode json --output-format json
+```
+
+Rules:
+- keep inspiredesign references public-first unless the task explicitly requires deeper browser capture
+- use repeated `--url` flags instead of packed URL strings
+- pair this lane with `opendevbrowser-design-agent` when the brief moves from contract synthesis into implementation or `/canvas`
 
 ## Agent Sync Targets
 
 Skill-pack installation and discovery are synchronized for:
 - `opencode` (`~/.config/opencode/skill`, project `./.opencode/skill`)
 - `codex` (`$CODEX_HOME/skills` fallback `~/.codex/skills`, project `./.codex/skills`)
-- `claudecode` (`$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` fallback `~/.claude/skills`, project `./.claude/skills`)
-- `ampcli` (`$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` fallback `~/.amp/skills`, project `./.amp/skills`)
-
-Legacy compatibility aliases `claude` and `amp` are preserved in installer target metadata.
+- `claudecode` (`$CLAUDECODE_HOME/skills` fallback `~/.claude/skills`, project `./.claude/skills`)
+- `ampcli` (`$AMP_CLI_HOME/skills` fallback `~/.amp/skills`, project `./.amp/skills`)
 
 Install and update refresh managed copies of these canonical packs; uninstall removes managed canonical packs and only prunes empty legacy `research` or `shopping` leftovers.
 
@@ -247,6 +259,7 @@ Use the router script to avoid retyping flows:
 ```bash
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-search
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-crawl
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh inspiredesign
 ./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
@@ -288,7 +301,7 @@ node scripts/live-regression-direct.mjs --out artifacts/live-regression-direct.j
 ```
 
 Surface inventory source of truth:
-- `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`)
+- `docs/SURFACE_REFERENCE.md` (77 CLI commands, 70 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)
 
@@ -316,18 +329,25 @@ Realignment rule:
 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.
+1. `opendevbrowser_canvas` or `opendevbrowser canvas --command canvas.session.open` to get `canvasSessionId`, `leaseId`, `preflightState`, `planStatus`, governance block states, generation-plan requirements, and `guidance.recommendedNextCommands`.
 2. Read the handshake before mutating. The handshake is the source of truth for:
+   - `planStatus`
+   - `preflightState`
    - `governanceRequirements.requiredBeforeMutation`
    - `governanceRequirements.requiredBeforeSave`
    - `generationPlanRequirements.requiredBeforeMutation`
+   - `generationPlanRequirements.allowedValues`
+   - `generationPlanIssues`
    - `allowedLibraries`
    - `mutationPolicy.allowedBeforePlan`
+   - `guidance.recommendedNextCommands`
+   - `guidance.reason`
    - 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:
+3. Require `preflightState="handshake_read"` or inspect the returned invalid-plan state before moving on. If the response already carries `guidance.recommendedNextCommands`, follow that list instead of guessing.
+4. Submit `canvas.plan.set` with all required non-empty objects:
    - `targetOutcome`
    - `visualDirection`
    - `layoutStrategy`
@@ -337,10 +357,24 @@ Recommended command order:
    - `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.
+   Minimum nested fields that commonly cause `generation_plan_invalid` if omitted:
+   - `visualDirection.themeStrategy`
+   - `layoutStrategy.navigationModel`
+   - `componentStrategy.interactionStates`
+   - `motionPosture.reducedMotion`
+   - `responsivePosture.requiredViewports`
+   - `accessibilityPosture.keyboardNavigation`
+   - `validationTargets.requiredThemes`
+   - `validationTargets.browserValidation`
+   - `validationTargets.maxInteractionLatencyMs`
+5. Immediately inspect the `canvas.plan.set` response.
+   - If `planStatus="accepted"` or `preflightState="plan_accepted"`, follow the returned `guidance.recommendedNextCommands`.
+   - If the command fails with `generation_plan_invalid`, inspect `details.missingFields`, `details.issues`, and the handshake `generationPlanIssues`, then optionally re-read with `canvas.plan.get` or `canvas.capabilities.get` before resubmitting.
+6. Only after the plan is accepted, call `canvas.document.patch`.
+7. After every successful `canvas.document.patch`, `canvas.preview.render`, `canvas.preview.refresh`, `canvas.feedback.poll`, `canvas.document.save`, or `canvas.document.export`, read `guidance.recommendedNextCommands` and `guidance.reason` before deciding the next command.
+8. Use `canvas.preview.render`, `canvas.tab.open`, `canvas.overlay.mount`, and `canvas.overlay.select` when a browser-backed live view is required.
+9. Use `canvas.feedback.poll` for snapshot audits between mutation rounds. When the plan is still missing or invalid, expect a synthetic `preflight-blocker` item instead of normal stage feedback. Use `canvas.feedback.subscribe` -> `canvas.feedback.next` -> `canvas.feedback.unsubscribe` when a live pull-stream is needed.
+10. 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`.
@@ -357,11 +391,12 @@ Current `/canvas` parity notes:
 
 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`.
+- Do not treat Tailwind as a component inventory source or invent generation-plan allowlists for it; keep styling policy in `allowedLibraries` / `libraryPolicy`.
 - 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`.
+- `generation_plan_invalid`: resubmit `canvas.plan.set` with every required non-empty generation-plan block present, using `generationPlanIssues` plus `details.missingFields` and `details.issues` as the repair checklist.
 - `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`.

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

@@ -7,15 +7,16 @@ Use this playbook before any `/canvas` mutation and during every design-feedback
 ## 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`
+2. Read the handshake and inspect `planStatus`, `preflightState`, `generationPlanRequirements.allowedValues`, `generationPlanIssues`, `guidance.recommendedNextCommands`, and `guidance.reason`
+3. Follow `guidance.recommendedNextCommands` from the handshake before choosing the next command
+4. `canvas.plan.set`
+5. If the response is accepted, follow the returned guidance into `canvas.document.patch`
+6. If the response fails with `generation_plan_invalid`, inspect `details.missingFields`, `details.issues`, and `generationPlanIssues`, then optionally re-read with `canvas.plan.get` or `canvas.capabilities.get`
+7. `canvas.preview.render` or `canvas.tab.open`
+8. `canvas.feedback.poll`
+9. `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`.
+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`. `canvas.plan.get` is a diagnostics path after invalid-plan responses or attach, not a required success-path checkpoint.
 
 ## Handshake requirements
 
@@ -26,21 +27,27 @@ Every `canvas.session.open` response is the runtime contract. Read these fields
 - `documentId`
 - `leaseId`
 - `preflightState`
+- `planStatus`
 - `governanceRequirements.requiredBeforeMutation`
 - `governanceRequirements.requiredBeforeSave`
 - `generationPlanRequirements.requiredBeforeMutation`
+- `generationPlanRequirements.allowedValues`
+- `generationPlanIssues`
 - `allowedLibraries`
-- `allowedBeforePlan`
+- `mutationPolicy.allowedBeforePlan`
+- `guidance.recommendedNextCommands`
+- `guidance.reason`
 
 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`
+- do not invent extra library allowlists inside `generationPlan`; keep icon and styling policy in `allowedLibraries` / `libraryPolicy`
 
 Preflight states:
 - `handshake_read`
 - `plan_submitted`
+- `plan_invalid`
 - `plan_accepted`
 - `patching_enabled`
 
@@ -74,6 +81,18 @@ The first accepted `generationPlan` must include:
 - `accessibilityPosture`
 - `validationTargets`
 
+Minimum nested fields to confirm before resubmitting an invalid plan:
+
+- `visualDirection.themeStrategy`
+- `layoutStrategy.navigationModel`
+- `componentStrategy.interactionStates`
+- `motionPosture.reducedMotion`
+- `responsivePosture.requiredViewports`
+- `accessibilityPosture.keyboardNavigation`
+- `validationTargets.requiredThemes`
+- `validationTargets.browserValidation`
+- `validationTargets.maxInteractionLatencyMs`
+
 ## Blocker handling
 
 Canonical blocker path:
@@ -95,11 +114,11 @@ If `canvas.document.patch` or `canvas.document.save` returns a blocker, stop mut
 |---|---|---|---|
 | `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-03` | Required `generationPlan` field missing or malformed | `canvas.plan.set` rejected with `generation_plan_invalid`, plus `generationPlanIssues` or issue details | 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 |
+| `CANVAS-07` | Feedback loop blocked before stage validation is ready | `canvas.feedback.poll` returns `preflight-blocker` for `plan_required` or `generation_plan_invalid` | Return to `canvas.plan.set`, then re-enter the preview/feedback loop |
 
 ## Feedback evaluation loop
 

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

@@ -6,8 +6,8 @@ Compact operational map of the current OpenDevBrowser surfaces, with the `/canva
 
 ## Current coverage snapshot
 
-- CLI commands: `72`
-- Plugin tools: `65`
+- CLI commands: `77`
+- Plugin tools: `70`
 - `/ops` command names: `59`
 - `/canvas` command names: `35`
 - Legacy `/cdp` relay: generic CDP forwarding (method-level)
@@ -21,27 +21,25 @@ Help-led highlights: browser replay (`screencast-start`, `screencast-stop`), pub
 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`
-- `ampcli`: `$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` (fallback `~/.amp/skills`) and `./.amp/skills`
-
-Legacy aliases `claude` and `amp` remain present in installer target metadata for compatibility.
+- `claudecode`: `$CLAUDECODE_HOME/skills` (fallback `~/.claude/skills`) and `./.claude/skills`
+- `ampcli`: `$AMP_CLI_HOME/skills` (fallback `~/.amp/skills`) and `./.amp/skills`
 
 ## CLI surface categories
 
 - 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`
+- Session/connection/workflow: `launch`, `connect`, `disconnect`, `status`, `status-capabilities`, `cookie-import`, `cookie-list`, `research`, `shopping`, `product-video`, `inspiredesign`
+- Navigation/interaction: `goto`, `wait`, `snapshot`, `review`, `review-desktop`, `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`
+- Export/diagnostics/power: `clone-page`, `clone-component`, `perf`, `dialog`, `console-poll`, `network-poll`, `debug-trace-snapshot`, `session-inspector`, `session-inspector-plan`, `session-inspector-audit`, `macro-resolve`, `annotate`, `rpc`
 
 ## Tool surface categories
 
-- Runtime parity tools map to the CLI runtime categories, including `opendevbrowser_canvas` and `opendevbrowser_session_inspector`.
+- Runtime parity tools map to the CLI runtime categories, including `opendevbrowser_status_capabilities`, `opendevbrowser_review_desktop`, `opendevbrowser_session_inspector`, `opendevbrowser_session_inspector_plan`, `opendevbrowser_session_inspector_audit`, and `opendevbrowser_canvas`.
 - 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: `install`, `update`, `uninstall`, `help`, `version`, `serve`, `daemon`, `native`, `artifacts`, `rpc`.
@@ -103,19 +101,63 @@ Minimum handshake payload shape:
   "documentId": "dc_01",
   "leaseId": "lease_01",
   "preflightState": "handshake_read",
+  "planStatus": "missing",
   "attachModes": ["observer", "lease_reclaim"],
   "governanceRequirements": {
-    "requiredBeforeMutation": ["intent", "generationPlan", "designLanguage"],
-    "requiredBeforeSave": ["intent", "generationPlan", "runtimeBudgets"]
+    "requiredBeforeMutation": [
+      "intent",
+      "generationPlan",
+      "designLanguage",
+      "contentModel",
+      "layoutSystem",
+      "typographySystem",
+      "motionSystem",
+      "responsiveSystem",
+      "accessibilityPolicy"
+    ],
+    "requiredBeforeSave": [
+      "intent",
+      "generationPlan",
+      "designLanguage",
+      "contentModel",
+      "layoutSystem",
+      "typographySystem",
+      "colorSystem",
+      "surfaceSystem",
+      "iconSystem",
+      "motionSystem",
+      "responsiveSystem",
+      "accessibilityPolicy",
+      "libraryPolicy",
+      "runtimeBudgets"
+    ]
   },
   "generationPlanRequirements": {
-    "requiredBeforeMutation": ["targetOutcome", "visualDirection", "layoutStrategy"]
+    "requiredBeforeMutation": [
+      "targetOutcome",
+      "visualDirection",
+      "layoutStrategy",
+      "contentStrategy",
+      "componentStrategy",
+      "motionPosture",
+      "responsivePosture",
+      "accessibilityPosture",
+      "validationTargets"
+    ],
+    "allowedValues": {
+      "targetOutcomeModes": ["low-fi-wireframe", "high-fi-live-edit", "dual-track", "document-only"],
+      "themeStrategies": ["single-theme", "light-dark-parity", "multi-theme-system"],
+      "navigationModels": ["global-header", "sidebar", "tabbed", "contextual", "immersive"],
+      "browserValidationModes": ["required", "optional"]
+    }
   },
   "allowedLibraries": {
     "components": ["shadcn"],
-    "icons": ["lucide"],
+    "icons": ["3dicons", "tabler", "microsoft-fluent-ui-system-icons", "@lobehub/fluent-emoji-3d"],
     "styling": ["tailwindcss"]
   },
+  "warningClasses": ["missing-generation-plan", "invalid-generation-plan", "missing-governance-block"],
+  "generationPlanIssues": [],
   "mutationPolicy": {
     "planRequiredBeforePatch": true,
     "allowedBeforePlan": [
@@ -126,6 +168,10 @@ Minimum handshake payload shape:
       "canvas.session.attach",
       "canvas.session.status"
     ]
+  },
+  "guidance": {
+    "recommendedNextCommands": ["canvas.plan.set"],
+    "reason": "Handshake is complete. Submit a complete generationPlan before mutation."
   }
 }
 ```
@@ -133,10 +179,11 @@ Minimum handshake payload shape:
 Preflight state machine:
 - `handshake_read`
 - `plan_submitted`
+- `plan_invalid`
 - `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"`.
+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"`. Invalid governance payloads should fail with `generation_plan_invalid`, `details.auditId: "CANVAS-03"`, plus `details.missingFields` and `details.issues`. Successful handshake, plan, patch, preview, feedback, and persistence responses should also carry `guidance.recommendedNextCommands` plus `guidance.reason` so agents know the next valid step without inferring it from raw state alone. `canvas.plan.get` is a diagnostics path after invalid-plan responses or attach, not a required checkpoint after a successful `canvas.plan.set`.
 
 Recommended blocker envelope:
 
@@ -169,6 +216,8 @@ Current operational constraints:
 
 Operational rule:
 - Read `canvas.session.open` or `canvas.capabilities.get` before mutation.
+- Inspect `planStatus`, `preflightState`, `generationPlanRequirements.allowedValues`, `generationPlanIssues`, and `guidance.recommendedNextCommands` before choosing the next command.
+- After every successful handshake, plan, patch, preview, feedback, save, or export response, inspect `guidance.recommendedNextCommands` before choosing the next command.
 - Use `canvas.feedback.poll` after each patch/render loop.
 - Do not save if `governanceRequirements.requiredBeforeSave` still reports missing governance blocks.
 

package/skills/opendevbrowser-best-practices/artifacts/provider-workflows.md

@@ -62,6 +62,8 @@ Expected output:
 
 Expected output:
 - `readResult` + `authBlockerDiagnostics`
+- `meta.primaryConstraintSummary` for the canonical follow-up summary
+- `meta.primaryConstraint.guidance.reason` and `meta.primaryConstraint.guidance.recommendedNextCommands[]` when the workflow knows the next provider recovery step
 
 ## Workflow E: Parallel Multipage (Reliable As-Is)
 
@@ -87,9 +89,11 @@ Expected output:
 - Use `node scripts/provider-direct-runs.mjs --release-gate --out artifacts/release/vX.Y.Z/provider-direct-runs.json` for provider live release proof.
 - Use `node scripts/live-regression-direct.mjs --release-gate --out artifacts/release/vX.Y.Z/live-regression-direct.json` for cross-surface live release proof.
 - Treat parity matrix tests as contract coverage, not live release proof.
+- Read `data.guidanceReason` and `data.recommendedNextCommand` in the provider-direct report before escalating a provider failure to manual follow-up.
 
 ## Failure Policy
 
 - stale refs: re-snapshot and retry once
 - repeated 403/429: stop and cooldown
 - inconsistent mode behavior: flag parity failure
+- workflow/provider follow-up: inspect `meta.primaryConstraintSummary` first, then `meta.primaryConstraint.guidance.reason`, then `meta.primaryConstraint.guidance.recommendedNextCommands[]`

package/skills/opendevbrowser-best-practices/artifacts/skill-runtime-surface-matrix.md

@@ -1,12 +1,12 @@
 # Skill Runtime Surface Matrix
 
-Canonical inventory of repo-local OpenDevBrowser skill packs and the runtime surfaces they must prove with real workflow execution.
+Canonical inventory of repo-local OpenDevBrowser skill packs and the audit evidence lanes that currently cover their surfaced runtime contracts.
 
 ## Canonical skill packs
 
-| Pack | Type | Validator | Runtime surfaces | Real workflow proof lane | External boundary |
+| Pack | Type | Validator | Runtime surfaces | Audit evidence lanes | External boundary |
 |---|---|---|---|---|---|
-| `opendevbrowser-best-practices` | `governance` | `./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh` | surface docs, workflow router, release evidence policy, CLI or tool or `/ops` or `/canvas` inventory | `node scripts/docs-drift-check.mjs`, `./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh`, `node scripts/cli-smoke-test.mjs`, `node scripts/provider-direct-runs.mjs`, `node scripts/live-regression-direct.mjs`, `node scripts/canvas-competitive-validation.mjs` | extension unavailable at start, auth walls, anti-bot pressure, rate limits, upstream outage |
+| `opendevbrowser-best-practices` | `governance` | `./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh` | first-contact help/onboarding inventory, inspiredesign operator lane, browser replay, desktop observation, surface docs, workflow router, release evidence policy, CLI or tool or `/ops` or `/canvas` inventory | `node scripts/docs-drift-check.mjs`, `./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh`, `node scripts/cli-smoke-test.mjs`, `node scripts/provider-direct-runs.mjs`, `node scripts/live-regression-direct.mjs`, `node scripts/canvas-competitive-validation.mjs` | extension unavailable at start, auth walls, anti-bot pressure, rate limits, upstream outage |
 | `opendevbrowser-continuity-ledger` | `doc_only` | `./skills/opendevbrowser-continuity-ledger/scripts/validate-skill-assets.sh` | continuity ownership, ledger template, reply protocol | validator output plus `skill-discovery` and `docs-drift`; no live browser probe | not applicable |
 | `opendevbrowser-data-extraction` | `workflow` | `./skills/opendevbrowser-data-extraction/scripts/validate-skill-assets.sh` | snapshot, DOM text/html extraction, pagination, quality gates, structured extraction | `node scripts/cli-smoke-test.mjs` plus `node scripts/product-video-fixture-live-probe.mjs` for structured extraction on a repo-local product page | extension unavailable at start if extension mode is audited separately |
 | `opendevbrowser-design-agent` | `browser_surface` | `./skills/opendevbrowser-design-agent/scripts/validate-skill-assets.sh` | `/canvas`, annotate send/stored semantics, design contract workflow, real-surface validation | `node scripts/live-regression-direct.mjs`, `node scripts/canvas-competitive-validation.mjs` | extension unavailable at start, optional Figma live smoke |
@@ -18,7 +18,7 @@ Canonical inventory of repo-local OpenDevBrowser skill packs and the runtime sur
 
 ## Shared runtime families
 
-| Runtime family | Representative CLI surface | Representative tool surface | Real task | Proof lane |
+| Runtime family | Representative CLI surface | Representative tool surface | Real task | Mapped audit lanes |
 |---|---|---|---|---|
 | Session lifecycle and daemon control | `serve`, `status`, `launch`, `disconnect` | `opendevbrowser_launch`, `opendevbrowser_status`, `opendevbrowser_disconnect` | start a session, inspect state, then close it cleanly | `node scripts/cli-smoke-test.mjs`, `node scripts/live-regression-direct.mjs` |
 | Navigation and interaction | `goto`, `wait`, `click`, `hover`, `press`, `type`, `select`, `scroll`, `scroll-into-view` | matching `opendevbrowser_*` interaction tools | move through an interactive page and complete an action loop | `node scripts/cli-smoke-test.mjs`, `node scripts/login-fixture-live-probe.mjs` |
@@ -26,10 +26,10 @@ Canonical inventory of repo-local OpenDevBrowser skill packs and the runtime sur
 | DOM and extraction | `dom-html`, `dom-text`, `dom-attr`, `dom-value`, `dom-visible`, `dom-enabled`, `dom-checked` | matching `opendevbrowser_dom_*` tools | extract structured fields and validate state transitions | `node scripts/cli-smoke-test.mjs`, `node scripts/product-video-fixture-live-probe.mjs` |
 | Targets and pages | `targets-list`, `target-use`, `target-new`, `target-close`, `page`, `pages`, `page-close` | matching `opendevbrowser_target_*` tools | switch tabs/pages during a real flow | `node scripts/cli-smoke-test.mjs` |
 | Diagnostics and export | `perf`, `screenshot`, `console-poll`, `network-poll`, `clone-page`, `clone-component`, `debug-trace-snapshot` | matching diagnostics/export tools | capture browser evidence after a real workflow step | `node scripts/cli-smoke-test.mjs`, `node scripts/live-regression-direct.mjs` |
-| Browser replay and desktop observation | `screencast-start`, `screencast-stop`, `desktop-status`, `desktop-capture-desktop` | matching replay/desktop tools | capture time-based browser evidence or read-only sibling desktop state during an investigation | `node scripts/live-regression-direct.mjs`, `node scripts/docs-drift-check.mjs` |
-| Workflow wrappers | `research run`, `shopping run`, `product-video run` | `opendevbrowser_research_run`, `opendevbrowser_shopping_run`, `opendevbrowser_product_video_run` | run end-to-end research, shopping, and product asset workflows | `scripts/skill-runtime-audit.mjs`, `scripts/provider-direct-runs.mjs`, `scripts/product-video-fixture-live-probe.mjs` |
+| Workflow wrappers | `research run`, `shopping run`, `product-video run`, `inspiredesign run` | `opendevbrowser_research_run`, `opendevbrowser_shopping_run`, `opendevbrowser_product_video_run`, `opendevbrowser_inspiredesign_run` | run end-to-end research, shopping, and product asset workflows, plus inspiredesign contract synthesis coverage | `scripts/skill-runtime-audit.mjs`, `scripts/provider-direct-runs.mjs`, `scripts/product-video-fixture-live-probe.mjs`, `tests/providers-inspiredesign-workflow.test.ts` |
+| Browser replay and desktop observation | `screencast-start`, `screencast-stop`, `desktop-status`, `desktop-capture-desktop` | `opendevbrowser_screencast_start`, `opendevbrowser_screencast_stop`, `opendevbrowser_desktop_status`, `opendevbrowser_desktop_capture_desktop` | capture time-based browser evidence or read-only sibling desktop state during an investigation | `node scripts/docs-drift-check.mjs`, `node scripts/live-regression-direct.mjs` |
 | Canvas and design relay | `canvas` CLI and `/canvas` commands | `opendevbrowser_canvas` | open a canvas session, mutate safely, render preview, and validate feedback | `node scripts/live-regression-direct.mjs`, `node scripts/canvas-competitive-validation.mjs` |
-| Extension `/ops` relay | `/ops` session, target, nav, interact, pointer, DOM, overlay, preview bridge envelopes | extension-backed tool parity via daemon | attach the extension, verify `/ops` readiness, and run real command loops | `node scripts/live-regression-direct.mjs`, `node scripts/docs-drift-check.mjs` |
+| Extension /ops relay | `/ops` session, target, nav, interact, pointer, DOM, overlay, preview bridge envelopes | extension-backed tool parity via daemon | attach the extension, verify `/ops` readiness, and run real command loops | `node scripts/live-regression-direct.mjs`, `node scripts/docs-drift-check.mjs` |
 | Skill discovery and loading | bundled `skills/` directories and loader search paths | `opendevbrowser_skill_list`, `opendevbrowser_skill_load` | enumerate and load the canonical packs | `node scripts/skill-runtime-audit.mjs` |
 
 ## Audit domains
@@ -37,12 +37,12 @@ Canonical inventory of repo-local OpenDevBrowser skill packs and the runtime sur
 | Audit domain | Covers | Proof lanes | Contract tests | Targeted reruns |
 |---|---|---|---|---|
 | `skills-assets-discovery` | bundled skills, validator assets, loader discovery, install targets | `skill-discovery`, `docs-drift` | `tests/skill-loader.test.ts`, `tests/skill-workflow-packs.test.ts`, `tests/cli-skills-installer.test.ts` | `./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh`, `node scripts/skill-runtime-audit.mjs --smoke --out artifacts/skill-runtime-audit/smoke.json` |
-| `cli-tools-surface` | CLI args/help, tool registry, surface inventory docs | `docs-drift`, `cli-smoke` | `tests/cli-help.test.ts`, `tests/cli-help-parity.test.ts`, `tests/daemon-commands.integration.test.ts` | `node scripts/docs-drift-check.mjs`, `node scripts/cli-smoke-test.mjs` |
-| `scripts-and-governance` | audit scripts, workflow router, drift and robustness policy | `docs-drift`, `best-practices-robustness`, `skill-discovery` | `tests/docs-drift-check.test.ts`, `tests/skill-runtime-audit.test.ts`, `tests/audit-zombie-files.test.ts` | `./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh`, `node scripts/docs-drift-check.mjs` |
+| `cli-tools-surface` | CLI args/help, tool registry, surface inventory docs, generated help, onboarding metadata, and first-contact owners | `docs-drift`, `cli-smoke` | `tests/cli-help.test.ts`, `tests/cli-help-parity.test.ts`, `tests/daemon-commands.integration.test.ts` | `node scripts/docs-drift-check.mjs`, `node scripts/cli-smoke-test.mjs` |
+| `scripts-and-governance` | audit scripts, workflow router, drift and robustness policy, machine matrix, prose mirror, and surface-audit checklist | `docs-drift`, `best-practices-robustness`, `skill-discovery` | `tests/docs-drift-check.test.ts`, `tests/skill-runtime-audit.test.ts`, `tests/audit-zombie-files.test.ts` | `./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh`, `node scripts/docs-drift-check.mjs` |
 | `browser-snapshot-interaction` | browser lifecycle, snapshot refs, DOM reads, click/type flows | `cli-smoke`, `login-fixture`, `product-video-fixture` | `tests/tools-workflows.test.ts`, `tests/tools-workflows-branches.test.ts`, `tests/browser-manager.test.ts` | `node scripts/cli-smoke-test.mjs`, `node scripts/login-fixture-live-probe.mjs --out artifacts/skill-runtime-audit/lanes/login-fixture.json` |
 | `canvas-annotate-design` | `/canvas`, annotate delivery, design-agent workflow, extension canvas runtime | `live-regression`, `canvas-competitive` | `tests/canvas-command-inventory.test.ts`, `tests/canvas-live-workflow-script.test.ts`, `tests/annotate-live-probe-script.test.ts` | `node scripts/live-regression-direct.mjs --out artifacts/skill-runtime-audit/lanes/live-regression.json`, `node scripts/canvas-competitive-validation.mjs --out artifacts/skill-runtime-audit/lanes/canvas-competitive.json` |
 | `extension-relay-cdp` | extension `/ops`, relay contracts, legacy CDP, target-session routing | `live-regression`, `docs-drift` | `tests/parity-matrix.test.ts`, `tests/relay-server.test.ts`, `tests/ops-browser-manager.test.ts` | `node scripts/live-regression-direct.mjs --out artifacts/skill-runtime-audit/lanes/live-regression.json`, `./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh cdp-channel-check` |
-| `providers-macros-workflows` | providers, workflow wrappers, macro resolve or execute, product-video | `provider-direct`, `research-live`, `product-video-fixture` | `tests/provider-direct-runs.test.ts`, `tests/macro-resolve.test.ts`, `tests/cli-macro-resolve.test.ts` | `node scripts/provider-direct-runs.mjs --smoke --out artifacts/skill-runtime-audit/lanes/provider-direct.json`, `npm run test -- tests/macro-resolve.test.ts tests/cli-macro-resolve.test.ts` |
+| `providers-macros-workflows` | providers, workflow wrappers, inspiredesign contract synthesis, macro resolve or execute, product-video | `provider-direct`, `research-live`, `product-video-fixture` | `tests/provider-direct-runs.test.ts`, `tests/macro-resolve.test.ts`, `tests/cli-macro-resolve.test.ts`, `tests/providers-inspiredesign-workflow.test.ts` | `node scripts/provider-direct-runs.mjs --smoke --out artifacts/skill-runtime-audit/lanes/provider-direct.json`, `npm run test -- tests/macro-resolve.test.ts tests/cli-macro-resolve.test.ts tests/providers-inspiredesign-workflow.test.ts` |
 | `challenges-and-guardrails` | challenge coordinator, browser-scoped `challengeAutomationMode` computer-use boundary, login/form challenge branches, blocker envelopes | `login-fixture`, `provider-direct`, `research-live`, `live-regression` | `tests/challenges-capability-matrix.test.ts`, `tests/browser-manager-challenge-runtime-handle.test.ts`, `tests/ops-browser-manager-challenge-runtime-handle.test.ts` | `node scripts/login-fixture-live-probe.mjs --out artifacts/skill-runtime-audit/lanes/login-fixture.json`, `node scripts/provider-direct-runs.mjs --smoke --out artifacts/skill-runtime-audit/lanes/provider-direct.json` |
 | `runtime-infrastructure` | bootstrap, runtime factory, daemon client, shared hub utilities | `cli-smoke`, `live-regression` | `tests/core-bootstrap.test.ts`, `tests/providers-runtime-factory.test.ts`, `tests/daemon-client.test.ts` | `npm run test -- tests/core-bootstrap.test.ts tests/providers-runtime-factory.test.ts tests/daemon-client.test.ts`, `node scripts/cli-smoke-test.mjs` |
 
@@ -54,5 +54,6 @@ Canonical inventory of repo-local OpenDevBrowser skill packs and the runtime sur
 - Full-mode `provider-direct` and `live-regression` lanes must reuse the current configured daemon/environment so extension and auth-backed coverage is real when available.
 - Non-release provider-direct profiles may emit skipped coverage-gap advisories when reduced mode coverage omits provider ids; release-gate mode upgrades the same gap to a failure.
 - A shared runtime family is considered covered only when at least one live proof lane exercised that family during the same audit pass.
+- Inspiredesign remains a surfaced contract workflow; the current audit model maps it through domain/test coverage and does not compute a dedicated inspiredesign live-proof lane.
 - An audit domain is `fail` when any mapped proof lane or mapped pack reports a repo-owned defect.
 - An audit domain is `env_limited` when it has no repo defects but a mapped proof lane hit real external blockers.

package/skills/opendevbrowser-best-practices/assets/templates/canvas-blocker-checklist.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "1.0",
+  "schemaVersion": "1.1",
   "canvasSessionId": "<canvas-session-id>",
   "documentId": "<document-id>",
   "blockers": [
@@ -14,10 +14,11 @@
     },
     {
       "auditId": "CANVAS-02",
-      "code": "governance_required",
+      "code": "policy_violation",
       "blockingCommand": "canvas.document.save",
       "requiredNextCommands": [
-        "canvas.capabilities.get"
+        "canvas.plan.get",
+        "canvas.document.load"
       ],
       "status": "pending"
     },
@@ -26,16 +27,8 @@
       "code": "generation_plan_invalid",
       "blockingCommand": "canvas.plan.set",
       "requiredNextCommands": [
-        "canvas.plan.set"
-      ],
-      "status": "pending"
-    },
-    {
-      "auditId": "CANVAS-04",
-      "code": "policy_violation",
-      "blockingCommand": "canvas.document.patch",
-      "requiredNextCommands": [
-        "canvas.capabilities.get"
+        "canvas.plan.set",
+        "canvas.plan.get"
       ],
       "status": "pending"
     },
@@ -47,24 +40,37 @@
         "canvas.tab.open"
       ],
       "status": "pending"
+    }
+  ],
+  "reviewChecks": [
+    {
+      "auditId": "CANVAS-04",
+      "classes": [
+        "library-policy-violation",
+        "icon-policy-violation"
+      ],
+      "reviewCommand": "canvas.feedback.poll",
+      "status": "pending"
     },
     {
       "auditId": "CANVAS-06",
-      "code": "budget_exceeded",
-      "blockingCommand": "canvas.preview.render",
-      "requiredNextCommands": [
-        "canvas.preview.refresh"
+      "classes": [
+        "runtime-budget-exceeded",
+        "overflow"
       ],
+      "reviewCommand": "canvas.preview.refresh",
       "status": "pending"
     },
     {
       "auditId": "CANVAS-07",
-      "code": "feedback_metadata_missing",
-      "blockingCommand": "canvas.feedback.poll",
-      "requiredNextCommands": [
-        "canvas.feedback.poll"
+      "classes": [
+        "preflight-blocker"
       ],
-      "status": "pending"
+      "reviewCommand": "canvas.feedback.poll",
+      "status": "pending",
+      "notes": [
+        "feedback.item responses should preserve targetId, pageId, class, and evidenceRefs once the live loop is active"
+      ]
     }
   ]
 }

package/skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json

@@ -5,33 +5,32 @@
   "documentId": "<document-id>",
   "generationPlan": {
     "targetOutcome": {
-      "mode": "high-fi-live-edit",
+      "mode": "dual-track",
       "summary": "Refine hero hierarchy and CTA clarity"
     },
     "visualDirection": {
       "profile": "cinematic-minimal",
-      "styleAxes": {
-        "contrast": "high",
-        "density": "airy"
-      }
+      "themeStrategy": "single-theme"
     },
     "layoutStrategy": {
-      "approach": "hero-led-grid"
+      "approach": "hero-led-grid",
+      "navigationModel": "global-header"
     },
     "contentStrategy": {
       "source": "document-context"
     },
     "componentStrategy": {
       "mode": "reuse-first",
-      "approvedLibraries": [
-        "shadcn"
+      "interactionStates": [
+        "default",
+        "hover",
+        "focus",
+        "disabled"
       ]
     },
     "motionPosture": {
       "level": "subtle",
-      "allow3D": false,
-      "allowParallax": false,
-      "allowCustomSmoothScroll": false
+      "reducedMotion": "respect-user-preference"
     },
     "responsivePosture": {
       "primaryViewport": "desktop",
@@ -43,16 +42,18 @@
     },
     "accessibilityPosture": {
       "target": "WCAG_2_2_AA",
-      "reducedMotion": "required",
-      "keyboardParity": true
+      "keyboardNavigation": "full"
     },
     "validationTargets": {
       "blockOn": [
-        "contrast-failure"
-      ],
-      "warnOn": [
+        "contrast-failure",
         "responsive-mismatch"
-      ]
+      ],
+      "requiredThemes": [
+        "light"
+      ],
+      "browserValidation": "required",
+      "maxInteractionLatencyMs": 180
     }
   },
   "requiredIssueClasses": [