opendevbrowser 0.0.19 → 0.0.21

package/skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json

@@ -4,6 +4,7 @@
   "documentId": "dc_01",
   "leaseId": "lease_01",
   "preflightState": "handshake_read",
+  "planStatus": "missing",
   "attachModes": [
     "observer",
     "lease_reclaim"
@@ -55,7 +56,93 @@
       "responsivePosture",
       "accessibilityPosture",
       "validationTargets"
-    ]
+    ],
+    "allowedValues": {
+      "targetOutcomeModes": [
+        "low-fi-wireframe",
+        "high-fi-live-edit",
+        "dual-track",
+        "document-only"
+      ],
+      "visualDirectionProfiles": [
+        "clean-room",
+        "cinematic-minimal",
+        "product-story",
+        "commerce-system",
+        "control-room",
+        "ops-control",
+        "auth-focused",
+        "settings-system",
+        "documentation"
+      ],
+      "themeStrategies": [
+        "single-theme",
+        "light-dark-parity",
+        "multi-theme-system"
+      ],
+      "navigationModels": [
+        "global-header",
+        "sidebar",
+        "tabbed",
+        "contextual",
+        "immersive"
+      ],
+      "interactionStates": [
+        "default",
+        "hover",
+        "focus",
+        "active",
+        "disabled",
+        "loading",
+        "empty",
+        "error",
+        "success",
+        "selected"
+      ],
+      "viewports": [
+        "desktop",
+        "tablet",
+        "mobile"
+      ],
+      "themes": [
+        "light",
+        "dark"
+      ],
+      "browserValidationModes": [
+        "required",
+        "optional"
+      ],
+      "blockOn": [
+        "missing-generation-plan",
+        "invalid-generation-plan",
+        "missing-governance-block",
+        "missing-intent",
+        "missing-design-language",
+        "missing-content-model",
+        "missing-typography-system",
+        "missing-color-role",
+        "missing-surface-policy",
+        "missing-state-coverage",
+        "missing-reduced-motion-policy",
+        "missing-responsive-policy",
+        "overflow",
+        "token-missing",
+        "broken-asset-reference",
+        "contrast-failure",
+        "hierarchy-weak",
+        "asset-provenance-missing",
+        "font-policy-missing",
+        "font-load-failure",
+        "reduced-motion-violation",
+        "unresolved-component-binding",
+        "icon-policy-violation",
+        "library-policy-violation",
+        "responsive-mismatch",
+        "runtime-budget-exceeded",
+        "unsupported-target",
+        "export-warning"
+      ]
+    }
   },
   "allowedLibraries": {
     "icons": [
@@ -73,23 +160,54 @@
     "motion": [],
     "threeD": []
   },
-  "warningAuditIds": [
-    "CANVAS-01",
-    "CANVAS-02",
-    "CANVAS-03",
-    "CANVAS-04",
-    "CANVAS-05",
-    "CANVAS-06",
-    "CANVAS-07"
-  ],
-  "allowedBeforePlan": [
-    "canvas.capabilities.get",
-    "canvas.plan.get",
-    "canvas.plan.set",
-    "canvas.document.load",
-    "canvas.session.attach",
-    "canvas.session.status"
+  "warningClasses": [
+    "missing-generation-plan",
+    "invalid-generation-plan",
+    "missing-governance-block",
+    "missing-intent",
+    "missing-design-language",
+    "missing-content-model",
+    "missing-typography-system",
+    "missing-color-role",
+    "missing-surface-policy",
+    "missing-state-coverage",
+    "missing-reduced-motion-policy",
+    "missing-responsive-policy",
+    "overflow",
+    "token-missing",
+    "broken-asset-reference",
+    "contrast-failure",
+    "hierarchy-weak",
+    "asset-provenance-missing",
+    "font-policy-missing",
+    "font-load-failure",
+    "reduced-motion-violation",
+    "unresolved-component-binding",
+    "icon-policy-violation",
+    "library-policy-violation",
+    "responsive-mismatch",
+    "runtime-budget-exceeded",
+    "unsupported-target",
+    "export-warning"
   ],
+  "generationPlanIssues": [],
+  "mutationPolicy": {
+    "planRequiredBeforePatch": true,
+    "allowedBeforePlan": [
+      "canvas.capabilities.get",
+      "canvas.plan.get",
+      "canvas.plan.set",
+      "canvas.document.load",
+      "canvas.session.attach",
+      "canvas.session.status"
+    ]
+  },
+  "guidance": {
+    "recommendedNextCommands": [
+      "canvas.plan.set"
+    ],
+    "reason": "Handshake is complete. Submit a complete generationPlan before mutation."
+  },
   "projectionModes": [
     "canvas_html",
     "bound_app_runtime"

package/skills/opendevbrowser-best-practices/assets/templates/skill-runtime-pack-matrix.json

@@ -20,19 +20,45 @@
         "cliCommands": [
           "serve",
           "status",
+          "status-capabilities",
           "launch",
+          "review-desktop",
+          "session-inspector-plan",
+          "session-inspector-audit",
           "research",
           "shopping",
           "product-video",
-          "canvas"
+          "canvas",
+          "inspiredesign",
+          "screencast-start",
+          "screencast-stop",
+          "desktop-status",
+          "desktop-windows",
+          "desktop-active-window",
+          "desktop-capture-desktop",
+          "desktop-capture-window",
+          "desktop-accessibility-snapshot"
         ],
         "tools": [
+          "opendevbrowser_status_capabilities",
+          "opendevbrowser_review_desktop",
+          "opendevbrowser_session_inspector_plan",
+          "opendevbrowser_session_inspector_audit",
           "opendevbrowser_canvas",
           "opendevbrowser_research_run",
           "opendevbrowser_shopping_run",
           "opendevbrowser_product_video_run",
           "opendevbrowser_skill_list",
-          "opendevbrowser_skill_load"
+          "opendevbrowser_skill_load",
+          "opendevbrowser_inspiredesign_run",
+          "opendevbrowser_screencast_start",
+          "opendevbrowser_screencast_stop",
+          "opendevbrowser_desktop_status",
+          "opendevbrowser_desktop_windows",
+          "opendevbrowser_desktop_active_window",
+          "opendevbrowser_desktop_capture_desktop",
+          "opendevbrowser_desktop_capture_window",
+          "opendevbrowser_desktop_accessibility_snapshot"
         ],
         "modes": [
           "managed",
@@ -327,8 +353,9 @@
       "sourceSeams": [
         "skills/opendevbrowser-best-practices/SKILL.md",
         "src/skills/skill-loader.ts",
-        "src/cli/installers/global.ts",
-        "src/cli/installers/local.ts",
+        "src/cli/installers/skills.ts",
+        "src/cli/utils/skills.ts",
+        "src/skills/bundled-skill-directories.ts",
         "src/tools/skill_list.ts",
         "src/tools/skill_load.ts"
       ],
@@ -358,7 +385,11 @@
         "src/cli/help.ts",
         "src/tools/index.ts",
         "src/public-surface/source.ts",
-        "docs/SURFACE_REFERENCE.md"
+        "docs/SURFACE_REFERENCE.md",
+        "src/cli/onboarding-metadata.json",
+        "docs/FIRST_RUN_ONBOARDING.md",
+        "docs/README.md",
+        "skills/opendevbrowser-best-practices/SKILL.md"
       ],
       "targetedRerunCommands": [
         "node scripts/docs-drift-check.mjs",
@@ -388,7 +419,11 @@
         "scripts/skill-runtime-scenarios.mjs",
         "scripts/docs-drift-check.mjs",
         "skills/opendevbrowser-best-practices/scripts/odb-workflow.sh",
-        "skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh"
+        "skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh",
+        "skills/opendevbrowser-best-practices/artifacts/command-channel-reference.md",
+        "skills/opendevbrowser-best-practices/artifacts/skill-runtime-surface-matrix.md",
+        "skills/opendevbrowser-best-practices/assets/templates/skill-runtime-pack-matrix.json",
+        "skills/opendevbrowser-best-practices/assets/templates/surface-audit-checklist.json"
       ],
       "targetedRerunCommands": [
         "./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh",
@@ -511,7 +546,8 @@
       "contractTests": [
         "tests/provider-direct-runs.test.ts",
         "tests/macro-resolve.test.ts",
-        "tests/cli-macro-resolve.test.ts"
+        "tests/cli-macro-resolve.test.ts",
+        "tests/providers-inspiredesign-workflow.test.ts"
       ],
       "sourceSeams": [
         "src/providers/registry.ts",
@@ -519,7 +555,10 @@
         "src/providers/workflows.ts",
         "src/macros/execute.ts",
         "src/tools/macro_resolve.ts",
-        "src/cli/commands/macro-resolve.ts"
+        "src/cli/commands/macro-resolve.ts",
+        "src/cli/commands/inspiredesign.ts",
+        "src/tools/inspiredesign_run.ts",
+        "src/providers/inspiredesign-contract.ts"
       ],
       "targetedRerunCommands": [
         "node scripts/provider-direct-runs.mjs --smoke --out artifacts/skill-runtime-audit/lanes/provider-direct.json",
@@ -638,6 +677,14 @@
         "live-regression"
       ]
     },
+    {
+      "id": "browser-replay-desktop-observation",
+      "label": "Browser replay and desktop observation",
+      "proofLanes": [
+        "docs-drift",
+        "live-regression"
+      ]
+    },
     {
       "id": "workflow-wrappers",
       "label": "Workflow wrappers",

package/skills/opendevbrowser-best-practices/assets/templates/surface-audit-checklist.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0",
   "expectedCounts": {
-    "cliCommands": 72,
-    "tools": 65,
+    "cliCommands": 77,
+    "tools": 70,
     "opsCommands": 59,
     "canvasCommands": 35
   },
@@ -12,13 +12,16 @@
     "docs/ARCHITECTURE.md",
     "docs/SURFACE_REFERENCE.md",
     "AGENTS.md",
-    "skills/opendevbrowser-best-practices/SKILL.md"
+    "skills/opendevbrowser-best-practices/SKILL.md",
+    "docs/README.md",
+    "docs/FIRST_RUN_ONBOARDING.md"
   ],
   "checks": [
     "CLI command names documented by category",
     "Tool names documented by category",
     "Ops command namespaces documented",
     "Session-first diagnostics lane documented and validated",
+    "Desktop-assisted browser review and browser-scoped inspection documented",
     "Browser replay and screencast commands documented",
     "Desktop observation commands documented",
     "Pointer controls documented",
@@ -28,6 +31,17 @@
     "Annotation send/copy semantics documented",
     "CDP envelope contract documented",
     "Global and command-specific flags documented",
-    "Mode semantics documented"
+    "Mode semantics documented",
+    "Generated help first-contact owners documented",
+    "Onboarding metadata owner documented",
+    "First-run onboarding proof owner documented"
+  ],
+  "firstContactOwners": [
+    "src/cli/help.ts",
+    "src/cli/onboarding-metadata.json",
+    "README.md",
+    "docs/README.md",
+    "docs/FIRST_RUN_ONBOARDING.md",
+    "skills/opendevbrowser-best-practices/SKILL.md"
   ]
 }

package/skills/opendevbrowser-best-practices/scripts/odb-workflow.sh

@@ -28,6 +28,7 @@ Usage:
 Workflows:
   provider-search
   provider-crawl
+  inspiredesign
   parallel-multipage-safe
   qa-debug
   social-readonly-check
@@ -69,6 +70,12 @@ opendevbrowser_wait sessionId="<session-id>" until="networkidle"
 opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
 opendevbrowser_scroll sessionId="<session-id>" dy=1000
 opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+EOF
+    ;;
+  inspiredesign)
+    cat <<EOF
+# Pair with opendevbrowser-design-agent when the contract will flow into implementation or /canvas work.
+$CLI_PREFIX 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
 EOF
     ;;
   parallel-multipage-safe)
@@ -115,11 +122,13 @@ EOF
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json
 $CLI_PREFIX canvas --command canvas.session.open --params '{"requestId":"req_open_01","browserSessionId":"<browser-session-id>","documentId":null,"repoPath":null,"mode":"dual-track"}'
-# Read handshake before any mutation. Require preflightState=handshake_read.
+# Read handshake before any mutation. Inspect planStatus, preflightState, generationPlanRequirements.allowedValues, generationPlanIssues, and guidance.recommendedNextCommands.
 $CLI_PREFIX canvas --command canvas.plan.set --params-file skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json
 # Replace placeholders in the plan file with canvasSessionId, leaseId, and documentId from the open response.
-$CLI_PREFIX canvas --command canvas.plan.get --params '{"requestId":"req_plan_get_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","documentId":"<document-id>"}'
-# Require planStatus=accepted or preflightState=plan_accepted before canvas.document.patch.
+# If canvas.plan.set succeeds with planStatus=accepted or preflightState=plan_accepted, follow the returned guidance into canvas.document.patch.
+# Optional diagnostics after generation_plan_invalid:
+# $CLI_PREFIX canvas --command canvas.plan.get --params '{"requestId":"req_plan_get_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","documentId":"<document-id>"}'
+# or re-read with canvas.capabilities.get to inspect generationPlanIssues before resubmitting canvas.plan.set.
 EOF
     ;;
   canvas-feedback-eval)
@@ -128,7 +137,7 @@ cat skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-feedback-eval.json
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-blocker-checklist.json
 $CLI_PREFIX canvas --command canvas.feedback.poll --params '{"requestId":"req_feedback_01","canvasSessionId":"<canvas-session-id>","documentId":"<document-id>","targetId":"<target-id>","afterCursor":null}'
-# Verify every feedback item is target-attributed and uses approved categories.
+# Verify every feedback item is target-attributed and uses approved categories. If feedback returns preflight-blocker, return to canvas.plan.set first.
 $CLI_PREFIX canvas --command canvas.preview.refresh --params '{"requestId":"req_refresh_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","targetId":"<target-id>","refreshMode":"full"}'
 $CLI_PREFIX canvas --command canvas.document.save --params '{"requestId":"req_save_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","documentId":"<document-id>","repoPath":null}'
 # Save should fail or warn when requiredBeforeSave governance blocks remain unresolved.
@@ -186,6 +195,9 @@ $CLI_PREFIX research run --topic "Chrome extension debugging workflows" --days 3
 $CLI_PREFIX shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json
 $CLI_PREFIX 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
 
+# Public-reference inspiredesign contract synthesis
+$CLI_PREFIX 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
+
 # Region note: advisory unless output reports meta.selection.region_authoritative=true
 $CLI_PREFIX shopping run --query "wireless earbuds" --providers shopping/amazon --region us --browser-mode managed --mode json --output-format json
 EOF

package/skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh

@@ -96,8 +96,10 @@ check_canvas_pack() {
     const robustness = JSON.parse(fs.readFileSync(robustnessPath, "utf8"));
     const feedbackIds = new Set(feedback.requiredIssueClasses || []);
     const blockerIds = new Set((blockers.blockers || []).map((entry) => entry.auditId));
+    const reviewIds = new Set((blockers.reviewChecks || []).map((entry) => entry.auditId));
+    const checklistIds = new Set([...blockerIds, ...reviewIds]);
     const robustnessIds = new Set((((robustness.canvas || {}).issueClasses) || []).map((entry) => entry.auditId));
-    const missing = expected.filter((id) => !feedbackIds.has(id) || !blockerIds.has(id) || !robustnessIds.has(id));
+    const missing = expected.filter((id) => !feedbackIds.has(id) || !checklistIds.has(id) || !robustnessIds.has(id));
     if (missing.length > 0) {
       console.error(`[canvas-pack] missing canvas audit ids in JSON templates: ${missing.join(", ")}`);
       process.exit(1);

package/skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh

@@ -64,6 +64,9 @@ const executableScripts = [
 ];
 
 const workflowMarkers = [
+  "inspiredesign)",
+  "inspiredesign run",
+  "--include-prototype-guidance",
   "canvas-preflight",
   "canvas-feedback-eval",
   "release-direct-gates",
@@ -100,10 +103,24 @@ const canvasPlaybookMarkers = [
   "canvas.session.open",
   "canvas.plan.set",
   "canvas.feedback.poll",
+  "guidance.recommendedNextCommands",
+  "generationPlanIssues",
+  "plan_invalid",
+  "generation_plan_invalid",
   "CANVAS-01",
   "CANVAS-07"
 ];
 
+const canvasHandshakeMarkers = [
+  "\"planStatus\": \"missing\"",
+  "\"allowedValues\"",
+  "\"warningClasses\"",
+  "\"generationPlanIssues\"",
+  "\"mutationPolicy\"",
+  "\"recommendedNextCommands\"",
+  "\"reason\": \"Handshake is complete. Submit a complete generationPlan before mutation.\""
+];
+
 const canvasTemplateMarkers = [
   "CANVAS-01",
   "CANVAS-02",
@@ -128,11 +145,14 @@ const readUtf8 = (relPath) => fs.readFileSync(path.join(skillRoot, relPath), "ut
 const hasMarker = (content, marker) => content.includes(marker);
 (async () => {
   const { getSurfaceCounts } = await import(pathToFileURL(path.join(repoRoot, "scripts", "docs-drift-check.mjs")).href);
+  const { getBundledSkillDirectoryPackIds } = await import(pathToFileURL(path.join(repoRoot, "scripts", "skill-runtime-scenarios.mjs")).href);
   const { commandCount, toolCount, opsCommandCount, canvasCommandCount } = getSurfaceCounts();
 
   const skillDocMarkers = [
     "npx opendevbrowser --help",
     "npx opendevbrowser help",
+    "npx opendevbrowser inspiredesign run",
+    "./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh inspiredesign",
     `${commandCount} CLI commands, ${toolCount} tools, ${opsCommandCount} \`/ops\` commands, ${canvasCommandCount} \`/canvas\` commands`,
     "Treat `tests/parity-matrix.test.ts` as contract coverage only.",
     "canonical owner of direct-run release evidence policy",
@@ -140,6 +160,11 @@ const hasMarker = (content, marker) => content.includes(marker);
     "artifacts/skill-runtime-surface-matrix.md",
     "assets/templates/skill-runtime-pack-matrix.json",
     "mutationPolicy.allowedBeforePlan",
+    "planStatus",
+    "plan_invalid",
+    "generationPlanIssues",
+    "guidance.recommendedNextCommands",
+    "generation_plan_invalid",
     "canvas.code.bind",
     "canvas.code.resolve",
     "bound_app_runtime",
@@ -169,7 +194,14 @@ const hasMarker = (content, marker) => content.includes(marker);
     "feedback.heartbeat",
     "governanceRequirements",
     "generationPlanRequirements",
+    "allowedValues",
     "mutationPolicy",
+    "planStatus",
+    "plan_invalid",
+    "generationPlanIssues",
+    "warningClasses",
+    "recommendedNextCommands",
+    "generation_plan_invalid",
     "code-sync",
     "parity",
     "plan_required",
@@ -188,11 +220,17 @@ const hasMarker = (content, marker) => content.includes(marker);
     `"tools": ${toolCount}`,
     `"opsCommands": ${opsCommandCount}`,
     `"canvasCommands": ${canvasCommandCount}`,
+    "\"docs/README.md\"",
+    "\"docs/FIRST_RUN_ONBOARDING.md\"",
+    "\"firstContactOwners\"",
     "Pointer controls documented",
     "Ops pointer and preview namespaces documented",
     "Canvas command names documented",
     "Canvas code-sync surface documented",
-    "Annotation send/copy semantics documented"
+    "Annotation send/copy semantics documented",
+    "Generated help first-contact owners documented",
+    "Onboarding metadata owner documented",
+    "First-run onboarding proof owner documented"
   ];
 
   for (const relPath of requiredPaths) {
@@ -233,15 +271,23 @@ const hasMarker = (content, marker) => content.includes(marker);
       ? packMatrix.canonicalPacks.map((entry) => entry?.packId).filter((value) => typeof value === "string")
       : [];
     const uniquePackIds = new Set(packIds);
+    const bundledSkillNames = getBundledSkillDirectoryPackIds();
+    const bundledSkillNameSet = new Set(bundledSkillNames);
     const auditDomainIds = Array.isArray(packMatrix.auditDomains)
       ? packMatrix.auditDomains.map((entry) => entry?.id).filter((value) => typeof value === "string")
       : [];
     const uniqueAuditDomainIds = new Set(auditDomainIds);
-    if (packIds.length !== 9 || uniquePackIds.size !== 9) {
-      failures.push(`Skill runtime pack matrix must contain 9 unique canonical packs; found ${uniquePackIds.size}.`);
+    if (packIds.length === 0 || uniquePackIds.size !== packIds.length) {
+      failures.push(`Skill runtime pack matrix must contain non-empty unique canonical packs; found ${uniquePackIds.size}/${packIds.length}.`);
+    }
+    if (bundledSkillNames.length === 0) {
+      failures.push("Bundled skill registry did not expose any canonical pack names.");
+    }
+    if (packIds.some((packId) => !bundledSkillNameSet.has(packId)) || bundledSkillNames.some((packId) => !uniquePackIds.has(packId))) {
+      failures.push("Skill runtime pack matrix canonical packs must match src/skills/bundled-skill-directories.ts.");
     }
-    if (auditDomainIds.length !== 9 || uniqueAuditDomainIds.size !== 9) {
-      failures.push(`Skill runtime pack matrix must contain 9 unique audit domains; found ${uniqueAuditDomainIds.size}.`);
+    if (auditDomainIds.length === 0 || uniqueAuditDomainIds.size !== auditDomainIds.length) {
+      failures.push(`Skill runtime pack matrix must contain non-empty unique audit domains; found ${uniqueAuditDomainIds.size}/${auditDomainIds.length}.`);
     }
     if (!Array.isArray(packMatrix.runtimeFamilies) || packMatrix.runtimeFamilies.length === 0) {
       failures.push("Skill runtime pack matrix missing runtimeFamilies.");
@@ -263,28 +309,15 @@ const hasMarker = (content, marker) => content.includes(marker);
   const runtimeMatrixPath = "artifacts/skill-runtime-surface-matrix.md";
   if (fs.existsSync(path.join(skillRoot, runtimeMatrixPath))) {
     const runtimeMatrix = readUtf8(runtimeMatrixPath);
-    for (const marker of [
-      "opendevbrowser-best-practices",
-      "opendevbrowser-continuity-ledger",
-      "opendevbrowser-data-extraction",
-      "opendevbrowser-design-agent",
-      "opendevbrowser-form-testing",
-      "opendevbrowser-login-automation",
-      "opendevbrowser-product-presentation-asset",
-      "opendevbrowser-research",
-      "opendevbrowser-shopping",
+    const packMatrix = JSON.parse(fs.readFileSync(path.join(skillRoot, "assets/templates/skill-runtime-pack-matrix.json"), "utf8"));
+    const runtimeMatrixMarkers = [
+      ...packMatrix.canonicalPacks.map((entry) => entry.packId),
       "Shared runtime families",
+      ...packMatrix.runtimeFamilies.map((entry) => entry.label),
       "Audit domains",
-      "skills-assets-discovery",
-      "cli-tools-surface",
-      "scripts-and-governance",
-      "browser-snapshot-interaction",
-      "canvas-annotate-design",
-      "extension-relay-cdp",
-      "providers-macros-workflows",
-      "challenges-and-guardrails",
-      "runtime-infrastructure"
-    ]) {
+      ...packMatrix.auditDomains.map((entry) => entry.id)
+    ];
+    for (const marker of runtimeMatrixMarkers) {
       if (!hasMarker(runtimeMatrix, marker)) {
         failures.push(`Skill runtime surface matrix missing marker: ${marker}`);
       }
@@ -339,6 +372,16 @@ const hasMarker = (content, marker) => content.includes(marker);
     }
   }
 
+  const canvasHandshakePath = "assets/templates/canvas-handshake-example.json";
+  if (fs.existsSync(path.join(skillRoot, canvasHandshakePath))) {
+    const canvasHandshake = readUtf8(canvasHandshakePath);
+    for (const marker of canvasHandshakeMarkers) {
+      if (!hasMarker(canvasHandshake, marker)) {
+        failures.push(`Canvas handshake example missing marker: ${marker}`);
+      }
+    }
+  }
+
   if (fs.existsSync(path.join(skillRoot, surfaceAuditPath))) {
     const surfaceAudit = readUtf8(surfaceAuditPath);
     for (const marker of surfaceAuditMarkers) {

package/skills/opendevbrowser-design-agent/SKILL.md

@@ -42,7 +42,7 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 - Shared robustness matrix: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
 - Shared canvas workflow baseline: `../opendevbrowser-best-practices/SKILL.md`
 
-## Fast Start
+## Quick Start
 
 1. Validate pack integrity.
 
@@ -92,6 +92,7 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 - Prefer real content, realistic states, and explicit user journeys over placeholder copy.
 - Preserve the repo's existing design system when one already exists. Only introduce a new direction when the brief or product gap justifies it.
 - Treat `/canvas` governance as the strongest contract in the repo: read the handshake, respect `generationPlanRequirements`, and do not mutate before the plan is accepted.
+- Treat `preflightState="handshake_read"` as the required ready state for the first post-open decision loop unless the handshake is already reporting an invalid-plan repair path.
 - For non-canvas frontend work, still fill the same design-contract fields before coding so decisions stay consistent across code, preview, and docs.
 - Use one owner for overlays, drawers, sheets, and detail panels; prefer item-backed state over boolean sprawl.
 - If motion depends on scroll or viewport progress, define the driver and reduced-motion fallback before implementation.
@@ -176,13 +177,17 @@ Use when starting from screenshots, mocks, or an existing page.
 Use when the task should run through the design canvas.
 
 - Start with `canvas.session.open` or `canvas.capabilities.get`.
-- Read the handshake and confirm mutation is allowed.
+- Read the handshake and inspect `planStatus`, `preflightState`, `generationPlanRequirements.allowedValues`, `generationPlanIssues`, and `guidance.recommendedNextCommands` before choosing the next command.
+- Treat `preflightState="handshake_read"` as the normal first-step checkpoint before `canvas.plan.set`; if the handshake already reports `plan_invalid`, repair the plan instead of mutating.
 - Fill the full design contract and extract the `generationPlan`.
-- Submit `canvas.plan.set`, then mutate with `canvas.document.patch`.
+- Submit `canvas.plan.set`.
+- If `canvas.plan.set` succeeds with `planStatus="accepted"` or `preflightState="plan_accepted"`, follow the returned `guidance.recommendedNextCommands`, then mutate with `canvas.document.patch`.
+- If `canvas.plan.set` fails with `generation_plan_invalid`, inspect `details.missingFields`, `details.issues`, and `generationPlanIssues`, then optionally re-read with `canvas.plan.get` or `canvas.capabilities.get` before resubmitting.
+- 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 choosing the next step.
 - Validate extension-stage history controls against public `canvas.history.undo` and `canvas.history.redo`; design-tab clicks emit the internal `canvas_history_requested` event, but acceptance is still on the public command outcomes.
 - When token work is in scope, validate collection or mode authoring, token value or alias edits, selected-node binding, and token usage inspection in the extension stage.
 - If annotation send is part of the workflow, record whether the design tab returned `Delivered to agent` or `Stored only; fetch with annotate --stored`.
-- Use `canvas.feedback.poll`, `canvas.preview.render`, `canvas.preview.refresh`, and `canvas.document.save` as the validation loop.
+- Use `canvas.preview.render`, `canvas.feedback.poll`, `canvas.preview.refresh`, and `canvas.document.save` as the validation loop in that order. If `canvas.feedback.poll` returns a `preflight-blocker`, return to `canvas.plan.set` before continuing.
 
 ### `real-surface-validation`