opendevbrowser 0.0.31 → 0.0.33

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

@@ -172,6 +172,45 @@
         "figma_token_missing"
       ]
     },
+    {
+      "packId": "opendevbrowser-motion-design",
+      "packType": "browser_surface",
+      "docOnly": false,
+      "validatorCommands": [
+        "./skills/opendevbrowser-motion-design/scripts/validate-skill-assets.sh"
+      ],
+      "sharedEvidenceIds": [
+        "live-regression",
+        "canvas-competitive",
+        "skill-discovery"
+      ],
+      "runtimeSurfaces": {
+        "cliCommands": [
+          "canvas",
+          "screenshot",
+          "debug-trace-snapshot",
+          "screencast-start",
+          "screencast-stop"
+        ],
+        "tools": [
+          "opendevbrowser_canvas",
+          "opendevbrowser_screenshot",
+          "opendevbrowser_debug_trace_snapshot",
+          "opendevbrowser_screencast_start",
+          "opendevbrowser_screencast_stop"
+        ],
+        "modes": [
+          "managed",
+          "extension",
+          "cdpConnect"
+        ]
+      },
+      "allowsEnvLimited": true,
+      "envLimitedReasons": [
+        "extension_unavailable",
+        "reduced_motion_emulation_unavailable"
+      ]
+    },
     {
       "packId": "opendevbrowser-form-testing",
       "packType": "workflow",
@@ -335,6 +374,7 @@
         "opendevbrowser-continuity-ledger",
         "opendevbrowser-data-extraction",
         "opendevbrowser-design-agent",
+        "opendevbrowser-motion-design",
         "opendevbrowser-form-testing",
         "opendevbrowser-login-automation",
         "opendevbrowser-product-presentation-asset",
@@ -361,6 +401,7 @@
       ],
       "targetedRerunCommands": [
         "./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh",
+        "./skills/opendevbrowser-motion-design/scripts/validate-skill-assets.sh",
         "node scripts/skill-runtime-audit.mjs --smoke --out artifacts/skill-runtime-audit/smoke.json"
       ]
     },
@@ -470,7 +511,8 @@
       "label": "Canvas, annotate, and design surfaces",
       "priority": 5,
       "packIds": [
-        "opendevbrowser-design-agent"
+        "opendevbrowser-design-agent",
+        "opendevbrowser-motion-design"
       ],
       "proofLanes": [
         "live-regression",
@@ -488,13 +530,16 @@
         "src/tools/index.ts",
         "src/public-surface/source.ts",
         "extension/src/canvas/canvas-runtime.ts",
-        "extension/src/annotate-content.ts"
+        "extension/src/annotate-content.ts",
+        "skills/opendevbrowser-motion-design/SKILL.md",
+        "skills/opendevbrowser-motion-design/artifacts/open-dev-browser-motion-evidence.md"
       ],
       "targetedRerunCommands": [
         "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",
         "node scripts/canvas-live-workflow.mjs --surface managed-headless",
-        "node scripts/annotate-live-probe.mjs --transport direct"
+        "node scripts/annotate-live-probe.mjs --transport direct",
+        "./skills/opendevbrowser-motion-design/scripts/validate-skill-assets.sh"
       ]
     },
     {
@@ -504,6 +549,7 @@
       "packIds": [
         "opendevbrowser-best-practices",
         "opendevbrowser-design-agent",
+        "opendevbrowser-motion-design",
         "opendevbrowser-shopping"
       ],
       "proofLanes": [

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

@@ -18,6 +18,14 @@ CLI_PREFIX="$(render_cli_prefix)"
 PACKAGE_ROOT="$(cd "$script_dir/../../.." && pwd)"
 TRANSCRIPT_PROBE_PATH="$(printf '%q' "$PACKAGE_ROOT/scripts/youtube-transcript-live-probe.mjs")"
 
+print_daemon_preflight() {
+  cat <<EOF
+# Daemon preflight for daemon-backed workflows:
+$CLI_PREFIX status --daemon --output-format json
+# Continue only when data.fingerprintCurrent === true.
+EOF
+}
+
 print_help() {
   cat <<'EOF'
 OpenDevBrowser workflow router
@@ -73,9 +81,13 @@ opendevbrowser_wait sessionId="<session-id>" until="networkidle"
 EOF
     ;;
   inspiredesign)
+    print_daemon_preflight
     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
+$CLI_PREFIX inspiredesign harvest --brief "Premium digital photography studio landing page" --query "Pinterest premium digital photography studio landing page cinematic parallax portfolio" --provider social/pinterest --max-references 5 --visual-evidence required --browser-mode extension --use-cookies --cookie-policy required --challenge-automation-mode browser_with_helper --mode json --output-format json
+# Inspect nextStepGuidance.readiness and doNotProceedIf before Canvas continuation. For non-ready evidence, follow recovery-first guidance.
+# Review visual-evidence.json, screenshot-index.json, ranked-references.json, and meta-prompt.md before design or Canvas work.
 EOF
     ;;
   parallel-multipage-safe)
@@ -118,6 +130,7 @@ opendevbrowser_network_poll sessionId="<session-id>" max=100
 EOF
     ;;
   canvas-preflight)
+    print_daemon_preflight
     cat <<EOF
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json
@@ -126,12 +139,14 @@ $CLI_PREFIX canvas --command canvas.session.open --params '{"requestId":"req_ope
 $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.
 # If canvas.plan.set succeeds with planStatus=accepted or preflightState=plan_accepted, follow the returned guidance into canvas.document.patch.
+# If canvas.plan.set returns generation_plan_invalid, read guidance.nextStepGuidance, guidance.paramsExamples, guidance.fieldExamples, guidance.validationChecks, and guidance.doNotProceedIf, then repair the params file and retry.
 # 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)
+    print_daemon_preflight
     cat <<EOF
 cat skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-feedback-eval.json
@@ -151,6 +166,7 @@ npm run test -- tests/tools.test.ts tests/daemon-commands.integration.test.ts
 EOF
     ;;
   release-direct-gates)
+    print_daemon_preflight
     cat <<'EOF'
 mkdir -p artifacts/release/vX.Y.Z
 node scripts/provider-direct-runs.mjs --release-gate --out artifacts/release/vX.Y.Z/provider-direct-runs.json
@@ -158,6 +174,7 @@ node scripts/live-regression-direct.mjs --release-gate --out artifacts/release/v
 EOF
     ;;
   skill-runtime-audit)
+    print_daemon_preflight
     cat <<'EOF'
 npm run build
 node scripts/docs-drift-check.mjs
@@ -174,6 +191,7 @@ OPENCODE_CONFIG_DIR="$WORKDIR/config" CODEX_HOME="$WORKDIR/codex-home" CLAUDECOD
 ./skills/opendevbrowser-continuity-ledger/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-data-extraction/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-design-agent/scripts/validate-skill-assets.sh
+./skills/opendevbrowser-motion-design/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-form-testing/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-login-automation/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-product-presentation-asset/scripts/validate-skill-assets.sh
@@ -184,6 +202,7 @@ node scripts/skill-runtime-audit.mjs --out artifacts/skill-runtime-audit/full.js
 EOF
     ;;
   validated-capabilities)
+    print_daemon_preflight
     cat <<EOF
 # Public-first YouTube transcript probe
 node $TRANSCRIPT_PROBE_PATH --url "https://www.youtube.com/watch?v=aircAruvnKk" --youtube-mode auto --out artifacts/capability-fix/youtube-transcript-auto.json
@@ -199,6 +218,9 @@ $CLI_PREFIX shopping run --query "27 inch 4k monitor" --providers shopping/bestb
 # 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
 
+# Browser-native Pinterest recipe. Continue only when nextStepGuidance.readiness is ready.
+$CLI_PREFIX inspiredesign harvest --brief "Premium digital photography studio landing page" --query "Pinterest premium digital photography studio landing page cinematic parallax portfolio" --provider social/pinterest --max-references 5 --visual-evidence required --browser-mode extension --use-cookies --cookie-policy required --challenge-automation-mode browser_with_helper --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
@@ -214,22 +236,29 @@ EOF
   ops-channel-check)
     cat <<EOF
 $CLI_PREFIX serve
+# Daemon preflight for daemon-backed workflows:
+$CLI_PREFIX status --daemon --output-format json
+# Continue only when data.fingerprintCurrent === true.
 $CLI_PREFIX launch --extension-only --wait-for-extension --output-format json
 $CLI_PREFIX status --daemon --output-format json
-# Verify opsConnected=true and extensionHandshakeComplete=true
+# Verify fingerprintCurrent=true, opsConnected=true, and extensionHandshakeComplete=true
 cat skills/opendevbrowser-best-practices/assets/templates/ops-request-envelope.json
 EOF
     ;;
   cdp-channel-check)
     cat <<EOF
 $CLI_PREFIX serve
+# Daemon preflight for daemon-backed workflows:
+$CLI_PREFIX status --daemon --output-format json
+# Continue only when data.fingerprintCurrent === true.
 $CLI_PREFIX launch --extension-only --extension-legacy --wait-for-extension --output-format json
 $CLI_PREFIX status --daemon --output-format json
-# Verify cdpConnected=true while legacy session is active
+# Verify fingerprintCurrent=true and cdpConnected=true while legacy session is active
 cat skills/opendevbrowser-best-practices/assets/templates/cdp-forward-envelope.json
 EOF
     ;;
   mode-flag-matrix)
+    print_daemon_preflight
     cat <<EOF
 cat skills/opendevbrowser-best-practices/assets/templates/mode-flag-matrix.json
 $CLI_PREFIX launch --no-extension --output-format json

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

@@ -66,6 +66,10 @@ const executableScripts = [
 const workflowMarkers = [
   "inspiredesign)",
   "inspiredesign run",
+  "inspiredesign harvest",
+  "social/pinterest",
+  "nextStepGuidance.readiness",
+  "visual-evidence.json",
   "--include-prototype-guidance",
   "canvas-preflight",
   "canvas-feedback-eval",
@@ -79,6 +83,7 @@ const workflowMarkers = [
   "npx opendevbrowser help",
   "./skills/opendevbrowser-continuity-ledger/scripts/validate-skill-assets.sh",
   "resolve-odb-cli.sh",
+  "./skills/opendevbrowser-motion-design/scripts/validate-skill-assets.sh",
   "CLI_PREFIX"
 ];
 
@@ -104,6 +109,8 @@ const canvasPlaybookMarkers = [
   "canvas.plan.set",
   "canvas.feedback.poll",
   "guidance.recommendedNextCommands",
+  "guidance.nextStepGuidance",
+  "guidance.paramsExamples",
   "generationPlanIssues",
   "plan_invalid",
   "generation_plan_invalid",

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

@@ -40,6 +40,7 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 - `scripts/design-workflow.sh`
 - `scripts/extract-canvas-plan.sh`
 - `scripts/validate-skill-assets.sh`
+- Motion authority: `../opendevbrowser-motion-design/SKILL.md`
 - Shared robustness matrix: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
 - Shared canvas workflow baseline: `../opendevbrowser-best-practices/SKILL.md`
 
@@ -72,6 +73,7 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 ## Supporting Surfaces
 
 - Use browser replay (`screencast-start` / `screencast-stop`) during real-surface validation when motion, sequencing, or transition timing matters.
+- Load `opendevbrowser-motion-design` when motion-heavy work needs terminology, pattern catalog decisions, platform/framework policy, device posture, reduced-motion rules, performance budgets, or temporal proof.
 - Treat shader, WebGL, Spline-style, and custom 3D motion references as advisory cues unless current runtime evidence proves support.
 - Desktop observation stays read-only and is only for external window or OS-level evidence around the workflow; it is not a design-surface control lane.
 - Browser-scoped computer use remains a challenge posture knob via `--challenge-automation-mode`, not a desktop-agent capability.
@@ -79,7 +81,7 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 ## Core Rules
 
 - Start with a design contract, not ad-hoc implementation.
-- Build a reference pattern board before locking a new direction when external inspiration matters.
+- Build a reference pattern board before locking a new direction when external inspiration matters, and inspect `nextStepGuidance.readiness` before treating a harvest as design-ready.
 - Choose a component family from `artifacts/component-pattern-index.md` before inventing a new screen structure.
 - Start from the closest shipped OpenDevBrowser example in `artifacts/opendevbrowser-ui-example-map.md` when the repo already has a related surface.
 - Route repo-first redesigns through `artifacts/existing-surface-adaptation.md` before changing shells or component anatomy.
@@ -93,11 +95,12 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 - Keep one visual direction per task. Do not mix unrelated design languages.
 - 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 `/canvas` governance as the strongest contract in the repo: read the handshake, respect `generationPlanRequirements`, inspect typed repair examples, 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.
+- For animation systems, route the motion-specific decisions through `../opendevbrowser-motion-design/artifacts/motion-pattern-catalog.md`, `../opendevbrowser-motion-design/artifacts/platform-framework-guide.md`, `../opendevbrowser-motion-design/artifacts/performance-frame-budget.md`, and `../opendevbrowser-motion-design/artifacts/open-dev-browser-motion-evidence.md`.
 - Carry advanced motion cues through `designVectors` and `motionSystem` as design intent only; they do not authorize new runtime libraries.
 - Keep `libraryPolicy.motion` and `libraryPolicy.threeD` empty in samples unless a separate runtime change explicitly approves those lanes.
 - Use `artifacts/scroll-reveal-surface-planning.md` whenever the design depends on pinned sections, reveal stages, or viewport-driven sequencing.
@@ -165,7 +168,9 @@ Use when a redesign needs external references or when the brief explicitly asks
 
 - Start with `artifacts/research-harvest-workflow.md`.
 - Capture `3` to `5` live references with OpenDevBrowser.
-- Record them in `assets/templates/reference-pattern-board.v1.json`.
+- For Pinterest, use the browser-native `social/pinterest` recipe with extension mode and cookies instead of treating Pinterest as a default full provider.
+- Inspect `nextStepGuidance.readiness`, `doNotProceedIf`, and recovery commands before using the bundle.
+- Record ready evidence in `assets/templates/reference-pattern-board.v1.json`.
 - Turn the synthesis into contract deltas before implementation.
 
 ### `screenshot-audit`
@@ -182,13 +187,13 @@ 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 inspect `planStatus`, `preflightState`, `generationPlanRequirements.allowedValues`, `generationPlanIssues`, and `guidance.recommendedNextCommands` before choosing the next command.
+- Start with `canvas.session.open`; use `canvas.capabilities.get` only after you have a `canvasSessionId`.
+- Read the handshake and inspect `planStatus`, `preflightState`, `generationPlanRequirements.allowedValues`, `generationPlanIssues`, `guidance.recommendedNextCommands`, `guidance.nextStepGuidance`, params examples, field examples, validation checks, and do-not-proceed blockers 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`.
 - 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.
+- If `canvas.plan.set` fails with `generation_plan_invalid`, inspect `details.missingFields`, `details.issues`, `guidance.paramsExamples`, `guidance.fieldExamples`, `guidance.validationChecks`, `guidance.doNotProceedIf`, and `generationPlanIssues`, then repair and resubmit the params file. Use `canvas.plan.get` or `canvas.capabilities.get` only when diagnostics are still needed after reading repair examples.
 - 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.

package/skills/opendevbrowser-design-agent/artifacts/design-workflows.md

@@ -77,22 +77,23 @@ Use when the work should flow through the OpenDevBrowser design canvas.
 
 1. Open a canvas session.
 2. Read the handshake and document context.
-3. Inspect `planStatus`, `preflightState`, `generationPlanRequirements.allowedValues`, `generationPlanIssues`, and `guidance.recommendedNextCommands` before moving on.
+3. Inspect `planStatus`, `preflightState`, `generationPlanRequirements.allowedValues`, `generationPlanIssues`, `guidance.recommendedNextCommands`, `guidance.nextStepGuidance`, params examples, field examples, validation checks, and do-not-proceed blockers before moving on.
 4. Treat `preflightState="handshake_read"` as the normal first-step checkpoint; if the handshake is already reporting `plan_invalid`, repair the plan instead of mutating.
 5. Fill the full design contract.
 6. Extract the `generationPlan`.
 7. Send `canvas.plan.set`.
 8. If the response is accepted, read `guidance.recommendedNextCommands` again and mutate with `canvas.document.patch`.
-9. 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`.
+9. If the response fails with `generation_plan_invalid`, inspect `details.missingFields`, `details.issues`, `generationPlanIssues`, and typed repair examples, then fix the params file before retrying.
 10. Render preview, poll feedback, and save or export until the contract and runtime match.
 
 Canonical command order:
 
 ```bash
 npx opendevbrowser canvas --command canvas.session.open --params '{"requestId":"req_open_01","browserSessionId":"<browser-session-id>","documentId":null,"repoPath":null,"mode":"dual-track"}'
-# Inspect planStatus, preflightState, generationPlanRequirements.allowedValues, generationPlanIssues, and guidance.recommendedNextCommands before continuing.
+# Inspect planStatus, preflightState, generationPlanRequirements.allowedValues, generationPlanIssues, guidance.recommendedNextCommands, guidance.nextStepGuidance, guidance.paramsExamples, guidance.fieldExamples, guidance.validationChecks, and guidance.doNotProceedIf before continuing.
 npx opendevbrowser canvas --command canvas.plan.set --params-file ./tmp/canvas-plan.json
 # If canvas.plan.set succeeds with planStatus=accepted or preflightState=plan_accepted, follow the returned guidance into canvas.document.patch.
+# If canvas.plan.set returns generation_plan_invalid, repair ./tmp/canvas-plan.json from guidance.paramsExamples before retrying.
 # Optional diagnostics after generation_plan_invalid:
 # npx opendevbrowser 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.

package/skills/opendevbrowser-design-agent/artifacts/research-harvest-workflow.md

@@ -4,44 +4,119 @@ Use this workflow before design direction is locked, when the brief references c
 
 ## Goal
 
-Turn live product references into a deterministic pattern board instead of vague inspiration.
+Turn live product references into a deterministic ranked pattern board and motion-aware design brief instead of vague inspiration.
 
 ## Inputs
 
 - A focused brief or design question
-- `3` to `5` reference products or pages
+- `3` to `5` reference products or pages, or a bounded public discovery query
 - The target surface in this repo
 - Constraints that must not be violated:
   - existing design system rules
   - supported libraries and runtime budgets
   - accessibility and responsive requirements
+  - provider policy boundaries for blocked, auth-required, challenge, or rate-limited references
 
-## Evidence Loop
-
-1. Pick reference pages that match the product shape:
-   - dashboard
-   - marketing landing page
-   - onboarding flow
-   - editor
-   - auth/settings surface
-2. Capture the surface with OpenDevBrowser:
-   - `launch`
-   - `goto`
-   - `snapshot`
-   - `screenshot`
-   - `debug-trace-snapshot` when motion, loading, or layout churn matters
-3. Record each page in `assets/templates/reference-pattern-board.v1.json`.
-4. For each reference, extract:
-   - layout recipe
-   - content hierarchy
-   - component families
-   - motion posture
-   - loading and empty-state strategy
-   - token and theming clues
-   - patterns to borrow
-   - patterns to reject
-5. Synthesize only the patterns that fit the repo's current surface, libraries, and runtime budgets.
-6. Translate the synthesis into the design contract before touching `/canvas` or code.
+## Primary Harvest Loop
+
+Prefer the dedicated InspireDesign harvest entrypoint for visual-first research:
+
+```bash
+npx opendevbrowser inspiredesign harvest \
+  --brief "Synthesize a premium docs workspace" \
+  --query "best docs product landing pages" \
+  --provider web/default \
+  --max-references 5 \
+  --visual-evidence required \
+  --browser-mode managed \
+  --mode json
+```
+
+Use the browser-native Pinterest site recipe when the brief specifically needs logged-in Pinterest search. Pinterest is not a default full social provider, and the workflow should not widen to unrelated sources without user confirmation:
+
+```bash
+npx opendevbrowser inspiredesign harvest \
+  --brief "Premium digital photography studio landing page" \
+  --query "Pinterest premium digital photography studio landing page cinematic parallax portfolio" \
+  --provider social/pinterest \
+  --max-references 5 \
+  --visual-evidence required \
+  --browser-mode extension \
+  --use-cookies \
+  --cookie-policy required \
+  --challenge-automation-mode browser_with_helper \
+  --mode json \
+  --output-format json
+```
+
+Use explicit references when the team already knows the right examples:
+
+```bash
+npx opendevbrowser inspiredesign harvest \
+  --brief "Extract reusable dashboard patterns" \
+  --url https://example.com/reference-a \
+  --url https://example.com/reference-b \
+  --visual-evidence required \
+  --mode json
+```
+
+Harvest defaults:
+
+- `mode=path`
+- `visualEvidence=required`
+- `maxReferences=5`
+- explicit `--url` references rank before query-discovered candidates during collection
+- the daemon method remains `inspiredesign.run`
+
+## Required Artifact Review
+
+After every harvest, inspect `nextStepGuidance` before `/canvas` or code changes:
+
+- `readiness="ready"`: continue only after artifact review.
+- `readiness="needs_recovery"`, `"blocked"`, or `"diagnostic_only"`: follow the primary recovery action first.
+- `doNotProceedIf`: treat each matching condition as a hard stop for Canvas continuation.
+- `paramsExamples` and `validationChecks`: use these as the next command and proof checklist.
+
+Then inspect these files before `/canvas` or code changes:
+
+1. `advanced-brief.md` for the reference-first creative brief.
+2. `ranked-references.json` for rank, score, confidence, visual strengths, visual risks, rejected references, and selection reasons.
+3. `visual-evidence.json` and `screenshot-index.json` for artifact-relative PNG paths, hashes, byte counts, viewport metadata when available, provenance, and warnings.
+4. PNG files under `visual-evidence/<referenceId>/viewport.png` for actual visual review.
+5. `meta-prompt.md` for borrow guidance, reject guidance, motion posture, accessibility constraints, no-copy warning, and validation gates.
+6. `canvas-plan.request.json` and `design-agent-handoff.json` only after the visual synthesis is accepted and `nextStepGuidance.readiness` is `ready`.
+
+JSON files are metadata-only. They must not contain base64 screenshots, absolute temp paths, full DOM, or full snapshot text.
+
+## Manual Evidence Fallback
+
+Use the lower-level browser loop only when harvest cannot run or when a single reference needs debugging:
+
+```bash
+npx opendevbrowser launch --no-extension --start-url https://example.com
+npx opendevbrowser goto --session-id <session-id> --url <reference-url>
+npx opendevbrowser snapshot --session-id <session-id>
+npx opendevbrowser screenshot --session-id <session-id> --path ./artifacts/reference.png
+npx opendevbrowser debug-trace-snapshot --session-id <session-id>
+```
+
+Record manual evidence in `assets/templates/reference-pattern-board.v1.json` using the same ranking and screenshot metadata fields as harvest.
+
+## What To Extract
+
+For each accepted reference, extract:
+
+- layout recipe
+- content hierarchy
+- component families
+- motion posture
+- loading and empty-state strategy
+- token and theming clues
+- visual strengths to borrow
+- visual risks and patterns to reject
+- screenshot path, hash, viewport, and warning metadata when available
+
+Synthesize only the patterns that fit the repo's current surface, libraries, runtime budgets, and accessibility policy.
 
 ## What To Borrow From External Patterns
 
@@ -61,21 +136,15 @@ These cues should stay explicit in the pattern board:
   - inspect current stack and assets first
   - combine aesthetics, accessibility, and implementation practicality in one review loop
 
-## OpenDevBrowser Command Pattern
-
-```bash
-npx opendevbrowser launch --no-extension --start-url https://example.com
-npx opendevbrowser goto --session-id <session-id> --url <reference-url>
-npx opendevbrowser snapshot --session-id <session-id>
-npx opendevbrowser screenshot --session-id <session-id>
-npx opendevbrowser debug-trace-snapshot --session-id <session-id>
-```
+## Motion Follow-through
 
-Repeat this for each selected reference. Keep the resulting notes in one pattern board so the design contract has a visible source of truth.
+Load `opendevbrowser-motion-design` before translating harvest motion posture into timing tokens, scroll choreography, gesture motion, reduced-motion behavior, or temporal proof. Harvest motion cues are design intent only; they do not authorize new runtime dependencies or shader, WebGL, Spline, or 3D lanes.
 
 ## Exit Criteria
 
-- The pattern board lists at least `3` live references.
+- The pattern board lists at least `3` live references unless provider policy, browser-native recipe diagnostics, or recovery guidance explain the smaller set.
 - Borrowed and rejected patterns are both explicit.
-- The chosen design direction is justified by evidence, not taste alone.
-- The resulting design contract names component families, state ownership, and validation targets before implementation starts.
+- Rank 1 justifies the dominant direction.
+- Screenshot metadata points to existing PNG artifacts or explains skipped or failed visual evidence.
+- The chosen design direction is justified by ready evidence, not taste alone or diagnostic-only artifacts.
+- The resulting design contract names component families, state ownership, motion posture, and validation targets before implementation starts.

package/skills/opendevbrowser-design-agent/artifacts/scroll-reveal-surface-planning.md

@@ -2,6 +2,8 @@
 
 Use this when narrative sequencing, pinned sections, or viewport-driven motion is part of the design instead of decorative afterthought.
 
+For broader motion language, pattern selection, device posture, reduced-motion rules, performance budgets, and temporal proof, also load `../opendevbrowser-motion-design/SKILL.md`.
+
 ## 1. Declare The Driver First
 
 Choose one progress owner before writing animation code:

package/skills/opendevbrowser-design-agent/assets/templates/reference-pattern-board.v1.json

@@ -4,30 +4,46 @@
   "references": [
     {
       "id": "ref-001",
+      "rank": 1,
+      "score": 86,
+      "confidence": 0.86,
       "name": "Example product page",
       "url": "https://example.com",
       "surfaceType": "marketing",
       "capturedVia": [
+        "fetch",
         "snapshot",
-        "screenshot"
+        "clone",
+        "dom",
+        "visual"
       ],
+      "intentMatched": true,
       "layoutRecipe": "",
       "contentHierarchy": [],
       "componentFamilies": [],
-      "motionPosture": "",
-      "advancedMotionAdvisory": [],
-      "loadingStrategy": "",
+      "motionPosture": [],
       "tokenNotes": [],
+      "visualStrengths": [],
+      "visualRisks": [],
+      "selectionReason": "",
       "patternsToBorrow": [],
       "patternsToReject": [],
       "whyItWorks": ""
     }
   ],
+  "rejectedReferences": [
+    {
+      "id": "ref-rejected-001",
+      "url": "https://example.com/rejected",
+      "reason": "policy_blocked|auth_required|challenge_detected|rate_limited|not_relevant|duplicate",
+      "fetchStatus": "failed",
+      "captureStatus": "off"
+    }
+  ],
   "synthesis": {
     "dominantDirection": "",
     "sharedStrengths": [],
     "sharedFailuresToAvoid": [],
-    "motionContractDeltas": [],
     "contractDeltas": []
   }
 }

package/skills/opendevbrowser-design-agent/scripts/design-workflow.sh

@@ -67,12 +67,14 @@ cat skills/opendevbrowser-design-agent/assets/templates/reference-pattern-board.
 cat skills/opendevbrowser-design-agent/artifacts/external-pattern-synthesis.md
 cat skills/opendevbrowser-design-agent/artifacts/component-pattern-index.md
 cat skills/opendevbrowser-design-agent/artifacts/existing-surface-adaptation.md
+$CLI_PREFIX inspiredesign harvest --brief "Premium digital photography studio landing page" --query "Pinterest premium digital photography studio landing page cinematic parallax portfolio" --provider social/pinterest --max-references 5 --visual-evidence required --browser-mode extension --use-cookies --cookie-policy required --challenge-automation-mode browser_with_helper --mode json --output-format json
+# Inspect nextStepGuidance.readiness and doNotProceedIf first. Use recovery-first guidance unless readiness is ready.
 $CLI_PREFIX launch --no-extension --start-url https://example.com
 $CLI_PREFIX goto --session-id <session-id> --url <reference-url>
 $CLI_PREFIX snapshot --session-id <session-id>
 $CLI_PREFIX screenshot --session-id <session-id>
 $CLI_PREFIX debug-trace-snapshot --session-id <session-id>
-# Repeat for 3-5 live references, then turn the synthesis into contract deltas before implementation.
+# Repeat for 3-5 live references, then turn ready synthesis into contract deltas before implementation.
 EOF
     ;;
   screenshot-audit)
@@ -101,10 +103,11 @@ cat skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json
 ./skills/opendevbrowser-design-agent/scripts/extract-canvas-plan.sh ./tmp/design-contract.json > ./tmp/canvas-plan.json
 $CLI_PREFIX canvas --command canvas.session.open --params '{"requestId":"req_open_01","browserSessionId":"<browser-session-id>","documentId":null,"repoPath":null,"mode":"dual-track"}'
-# Inspect planStatus, preflightState, generationPlanRequirements.allowedValues, generationPlanIssues, and guidance.recommendedNextCommands before continuing.
+# Inspect planStatus, preflightState, generationPlanRequirements.allowedValues, generationPlanIssues, guidance.recommendedNextCommands, guidance.nextStepGuidance, guidance.paramsExamples, guidance.fieldExamples, guidance.validationChecks, and guidance.doNotProceedIf before continuing.
 # Treat preflightState=handshake_read as the normal first-step checkpoint before canvas.plan.set.
 $CLI_PREFIX canvas --command canvas.plan.set --params-file ./tmp/canvas-plan.json
 # If canvas.plan.set succeeds with planStatus=accepted or preflightState=plan_accepted, follow the returned guidance into canvas.document.patch.
+# If canvas.plan.set returns generation_plan_invalid, repair ./tmp/canvas-plan.json from guidance.paramsExamples before retrying.
 # 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.