opendevbrowser 0.0.27 → 0.0.29

package/extension/dist/ops/ops-runtime.js

@@ -13,7 +13,10 @@ const MAX_NETWORK_EVENTS = 300;
 const SESSION_TTL_MS = 20_000;
 const SCREENSHOT_TIMEOUT_MS = 8000;
 const TAB_CLOSE_TIMEOUT_MS = 5000;
+const OPS_SESSION_DETACH_TIMEOUT_MS = 3000;
 const POPUP_ATTACH_RETRY_DELAY_MS = 100;
+const ROOT_DETACH_VERIFY_DELAY_MS = 250;
+const ROOT_DETACH_VERIFY_ATTEMPTS = 4;
 const STALE_REF_ERROR_SUFFIX = "Take a new snapshot first.";
 const DOM_OUTER_HTML_DECLARATION = `
   function() {
@@ -305,6 +308,12 @@ export class OpsRuntime {
             });
         }
     }
+    handleRelayDisconnected() {
+        this.cdp.markClientClosed();
+        for (const session of this.sessions.list()) {
+            void this.cleanupSession(session, "ops_session_expired");
+        }
+    }
     handleHello(message) {
         if (message.version !== OPS_PROTOCOL_VERSION) {
             const error = {
@@ -2576,10 +2585,19 @@ export class OpsRuntime {
             await this.cdp.setDiscoverTargetsEnabled?.(true);
         }
         catch (error) {
+            if (isAttachBlockedError(error)) {
+                return;
+            }
             logError("ops.discover_targets", error, {
                 code: "discover_targets_enable_failed",
                 extra: baseDetails
             });
+            if (baseDetails.strict) {
+                throw this.decorateCdpFailure(error, {
+                    ...baseDetails,
+                    enablementStage: "set_discover_targets"
+                });
+            }
         }
     }
     async enableTargetDomainsOnDebuggee(debuggee, baseDetails) {
@@ -4006,7 +4024,7 @@ export class OpsRuntime {
         }
         throw new Error("Wait for selector timed out");
     }
-    cleanupSession(session, event) {
+    async cleanupSession(session, event) {
         this.clearClosingTimer(session.id);
         const waiters = this.parallelWaiters.get(session.id);
         if (waiters) {
@@ -4020,8 +4038,25 @@ export class OpsRuntime {
             this.parallelWaiters.delete(session.id);
         }
         this.sessions.delete(session.id);
-        for (const target of session.targets.values()) {
-            void this.cdp.detachTab(target.tabId).catch(() => undefined);
+        const targets = Array.from(session.targets.values());
+        try {
+            const results = await withTimeout(Promise.allSettled(targets.map(async (target) => this.cdp.detachTab(target.tabId))), OPS_SESSION_DETACH_TIMEOUT_MS, "Ops session detach timed out");
+            const failedTabIds = results.flatMap((result, index) => {
+                const target = targets[index];
+                return result.status === "rejected" && target ? [target.tabId] : [];
+            });
+            if (failedTabIds.length > 0) {
+                logError("ops.session_detach", new Error("One or more ops session targets failed to detach"), {
+                    code: "session_detach_failed",
+                    extra: { sessionId: session.id, event, failedTabIds }
+                });
+            }
+        }
+        catch (error) {
+            logError("ops.session_detach", error, {
+                code: "session_detach_failed",
+                extra: { sessionId: session.id, event }
+            });
         }
         this.emitSessionEvent(session, event);
     }
@@ -4036,7 +4071,7 @@ export class OpsRuntime {
         if (!removedTarget)
             return;
         if (targetId === session.targetId || session.targets.size === 0) {
-            this.cleanupSession(session, event);
+            void this.cleanupSession(session, event);
         }
     }
     async handleDebuggerDetachForTab(tabId) {
@@ -4044,7 +4079,8 @@ export class OpsRuntime {
         if (!session)
             return;
         if (tabId === session.tabId) {
-            // Root tab detach can be transient during child-target shutdown; tab removal handler owns root teardown.
+            // Root tab detach can be transient during child-target shutdown, but it must not retain ownership forever.
+            this.scheduleRootDebuggerDetachVerification(session.id, tabId);
             return;
         }
         const targetId = this.sessions.getTargetIdByTabId(session.id, tabId);
@@ -4064,6 +4100,48 @@ export class OpsRuntime {
         }
         this.handleClosedTarget(tabId, "ops_session_closed");
     }
+    scheduleRootDebuggerDetachVerification(sessionId, tabId) {
+        if (typeof this.cdp.getTabDebuggee !== "function") {
+            return;
+        }
+        setTimeout(() => {
+            void this.verifyRootDebuggerDetach(sessionId, tabId, ROOT_DETACH_VERIFY_ATTEMPTS);
+        }, ROOT_DETACH_VERIFY_DELAY_MS);
+    }
+    async verifyRootDebuggerDetach(sessionId, tabId, attemptsRemaining) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.tabId !== tabId) {
+            return;
+        }
+        if (this.isConcreteDebuggee(this.cdp.getTabDebuggee?.(tabId))) {
+            return;
+        }
+        let liveTab = null;
+        try {
+            liveTab = await this.tabs.getTab(tabId);
+        }
+        catch {
+            liveTab = null;
+        }
+        const current = this.sessions.get(sessionId);
+        if (!current || current.tabId !== tabId) {
+            return;
+        }
+        if (!liveTab) {
+            void this.cleanupSession(current, "ops_session_closed");
+            return;
+        }
+        if (this.isConcreteDebuggee(this.cdp.getTabDebuggee?.(tabId))) {
+            return;
+        }
+        if (attemptsRemaining > 1) {
+            setTimeout(() => {
+                void this.verifyRootDebuggerDetach(sessionId, tabId, attemptsRemaining - 1);
+            }, ROOT_DETACH_VERIFY_DELAY_MS);
+            return;
+        }
+        void this.cleanupSession(current, "ops_session_closed");
+    }
     async closeTabBestEffort(tabId) {
         try {
             await withTimeout(this.tabs.closeTab(tabId), TAB_CLOSE_TIMEOUT_MS, "Ops tab close timed out");
@@ -4081,7 +4159,7 @@ export class OpsRuntime {
             if (!session) {
                 return;
             }
-            this.cleanupSession(session, event);
+            void this.cleanupSession(session, event);
         }, 0);
     }
     sendResponse(message, payload) {
@@ -4159,7 +4237,7 @@ export class OpsRuntime {
             this.closingTimers.delete(session.id);
             const current = this.sessions.get(session.id);
             if (current && current.state === "closing") {
-                this.cleanupSession(current, "ops_session_expired");
+                void this.cleanupSession(current, "ops_session_expired");
             }
         }, SESSION_TTL_MS);
         this.closingTimers.set(session.id, timeoutId);

package/extension/dist/ops/ops-session-store.js

@@ -75,6 +75,9 @@ export class OpsSessionStore {
     listOwnedBy(clientId) {
         return this.coordinator.listOwnedBy(clientId);
     }
+    list() {
+        return this.coordinator.list();
+    }
     delete(sessionId) {
         return this.coordinator.delete(sessionId);
     }

package/extension/dist/ops/target-session-coordinator.js

@@ -44,6 +44,9 @@ export class TargetSessionCoordinator {
     listOwnedBy(clientId) {
         return Array.from(this.sessions.values()).filter((session) => session.ownerClientId === clientId);
     }
+    list() {
+        return Array.from(this.sessions.values());
+    }
     delete(sessionId) {
         const session = this.sessions.get(sessionId) ?? null;
         if (!session) {

package/extension/dist/services/CDPRouter.js

@@ -912,6 +912,9 @@ export class CDPRouter {
                 return;
             }
             catch (error) {
+                if (this.isExpectedDebuggerCleanupError(error)) {
+                    continue;
+                }
                 logError("cdp.restore_root_attach", error, {
                     code: "restore_root_attach_failed",
                     extra: { tabId }
@@ -2021,6 +2024,9 @@ export class CDPRouter {
         const message = error instanceof Error ? error.message : String(error);
         return STALE_TAB_ERROR_MARKERS.some((marker) => message.includes(marker));
     }
+    isExpectedDebuggerCleanupError(error) {
+        return this.isStaleTabError(error);
+    }
     markExpectedRootDetach(tabId) {
         this.expectedRootDetachDeadlines.set(tabId, Date.now() + 1000);
     }
@@ -2074,6 +2080,9 @@ export class CDPRouter {
             });
         }
         catch (error) {
+            if (this.isExpectedDebuggerCleanupError(error)) {
+                return;
+            }
             logError("cdp.safe_detach", error, { code: "detach_failed" });
         }
     }

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "OpenDevBrowser Relay",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "Optional bridge to reuse existing Chrome tabs with OpenDevBrowser.",
   "permissions": [
     "debugger",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opendevbrowser",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "Browser automation runtime with snapshot-refs-actions, browser replay screencasts, public read-only desktop observation, and browser-scoped computer-use orchestration",
   "type": "module",
   "main": "dist/index.js",

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

@@ -100,7 +100,7 @@ Load this section directly with:
 opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"
 ```
 
-Current reliable lanes:
+Current validated lanes:
 
 1. Public-first YouTube transcript retrieval.
 
@@ -113,23 +113,25 @@ Rules:
 - browser-assisted transcript fallback is opt-in only
 - if browser fallback is enabled, use an isolated automation profile instead of a daily logged-in Google profile
 
-2. Generic topical research without shopping contamination.
+2. Evidence-gated research primitive with explicit public source families.
 
 ```bash
-npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --mode json --output-format json
+npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --sources web,community --browser-mode managed --mode json --output-format json
 ```
 
 Rules:
-- use `--source-selection auto` for general research
-- use `--source-selection shopping` or explicit `--sources ...shopping...` only when the task is deliberately commercial
-- in the current contract, `auto` and `all` both resolve to `web`, `community`, and `social`
+- load `opendevbrowser-research` before research tasks so planning, evidence review, confidence, and limitations stay skill-guided
+- treat `research run` as provider-constrained and low-level; inspect `summary.md`, `report.md`, `records.json`, `context.json`, `meta.json`, and `bundle-manifest.json` before publishing claims
+- use `--source-selection` only to explain selector semantics; use explicit `--sources web,community` for public topical examples
+- add shopping only with `--source-selection shopping` or explicit `--sources ...shopping...` when the task is deliberately commercial
+- in the current contract, `auto` and `all` both resolve to `web`, `community`, and `social`, but neither value guarantees reliability
 
 3. Deterministic shopping reruns with explicit providers.
 
 ```bash
-npx opendevbrowser shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json
-npx opendevbrowser shopping run --query "27 inch 4k monitor" --providers shopping/bestbuy,shopping/ebay --budget 350 --sort lowest_price --browser-mode managed --mode json --output-format json
-npx opendevbrowser shopping run --query "wireless earbuds" --providers shopping/amazon --region us --browser-mode managed --mode json --output-format json
+npx opendevbrowser shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --use-cookies --challenge-automation-mode browser_with_helper --mode json --output-format json
+npx opendevbrowser shopping run --query "27 inch 4k monitor" --providers shopping/bestbuy,shopping/ebay --budget 350 --sort lowest_price --browser-mode managed --use-cookies --challenge-automation-mode browser_with_helper --mode json --output-format json
+npx opendevbrowser shopping run --query "wireless earbuds" --providers shopping/amazon --region us --browser-mode managed --use-cookies --challenge-automation-mode browser_with_helper --mode json --output-format json
 ```
 
 Rules:
@@ -142,7 +144,7 @@ Rules:
 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" --include-prototype-guidance --mode json --output-format json
+npx opendevbrowser inspiredesign run --brief "Design a premium docs workspace" --url "https://example.com/reference-a" --url "https://example.com/reference-b" --browser-mode managed --use-cookies --challenge-automation-mode browser_with_helper --include-prototype-guidance --mode json --output-format json
 ```
 
 Rules:
@@ -308,7 +310,7 @@ Surface inventory source of truth:
 
 Direct-run release note:
 - `scripts/live-regression-direct.mjs` is the preferred release harness for `/canvas`, annotate, and CLI smoke. It uses temporary managed profiles for managed probes, waits for `/ops` drain before the legacy `/cdp` step, and keeps manual annotation timeouts as explicit `skipped` boundaries in `--release-gate` mode.
-- `scripts/provider-direct-runs.mjs --use-global-env --include-high-friction --include-auth-gated` is the preferred provider release harness. Treat `provider-live-matrix` and `live-regression-matrix` as debug-only helpers, not refreshed release evidence.
+- `scripts/provider-direct-runs.mjs --include-high-friction --include-auth-gated` is the preferred provider release harness. Treat `provider-live-matrix` and `live-regression-matrix` as debug-only helpers, not refreshed release evidence.
 
 ## Skill Runtime Audit and Realignment
 

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

@@ -13,7 +13,7 @@ Canonical inventory of repo-local OpenDevBrowser skill packs and the audit evide
 | `opendevbrowser-form-testing` | `workflow` | `./skills/opendevbrowser-form-testing/scripts/validate-skill-assets.sh` | snapshot -> type/click -> validation loop, multi-step forms, challenge checkpoints, network correlation | `node scripts/cli-smoke-test.mjs` plus `node scripts/login-fixture-live-probe.mjs` for invalid-submit, MFA, and persistence branches | extension unavailable at start if extension mode is audited separately |
 | `opendevbrowser-login-automation` | `workflow` | `./skills/opendevbrowser-login-automation/scripts/validate-skill-assets.sh` | login branching, invalid credential handling, MFA step-up, session validation | `node scripts/login-fixture-live-probe.mjs` | none; proof lane is repo-local |
 | `opendevbrowser-product-presentation-asset` | `workflow` | `./skills/opendevbrowser-product-presentation-asset/scripts/validate-skill-assets.sh` | `product-video run`, asset-pack assembly, screenshots, evidence mapping | `node scripts/product-video-fixture-live-probe.mjs` | none; proof lane is repo-local |
-| `opendevbrowser-research` | `workflow` | `./skills/opendevbrowser-research/scripts/validate-skill-assets.sh` | `research run`, timebox resolution, multi-source artifact generation | `opendevbrowser research run --topic "<topic>" --source-selection auto --mode json` via `scripts/skill-runtime-audit.mjs` | auth walls, rate limits, upstream source failure |
+| `opendevbrowser-research` | `workflow` | `./skills/opendevbrowser-research/scripts/validate-skill-assets.sh` | `research run`, timebox resolution, multi-source artifact generation | `opendevbrowser research run --topic "<topic>" --sources web,community --mode json` via `scripts/skill-runtime-audit.mjs` | auth walls, rate limits, upstream source failure |
 | `opendevbrowser-shopping` | `workflow` | `./skills/opendevbrowser-shopping/scripts/validate-skill-assets.sh` | `shopping run`, offer normalization, market analysis, direct provider workflows | `node scripts/provider-direct-runs.mjs` | auth walls, anti-bot challenges, rate limits, upstream outage |
 
 ## Shared runtime families

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

@@ -188,8 +188,9 @@ 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
 
-# Generic topical research without shopping contamination
-$CLI_PREFIX research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --mode json --output-format json
+# Evidence-gated research primitive with explicit public source families
+# Load opendevbrowser-research first, then inspect records.json, context.json, meta.json, and report.md before publishing claims.
+$CLI_PREFIX research run --topic "Chrome extension debugging workflows" --days 30 --sources web,community --mode json --output-format json
 
 # Deterministic shopping reruns with explicit providers
 $CLI_PREFIX shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json

package/skills/opendevbrowser-best-practices/scripts/validator-fixture-cli.sh

@@ -118,7 +118,29 @@ if (domain === "research" && command === "run") {
     );
     fs.writeFileSync(
       path.join(bundleDir, "report.md"),
-      `# Research Report\n\n- Topic: ${topic}\n- Days: ${days}\n- Source selection: ${sourceSelection}\n- Sources: ${sources}\n`
+      [
+        "# Research Report",
+        "",
+        `- Topic: ${topic}`,
+        `- Days: ${days}`,
+        `- Source selection: ${sourceSelection}`,
+        `- Sources: ${sources}`,
+        "",
+        "## Search Direction",
+        "Fixture provider pass suggested destination follow-up.",
+        "",
+        "## Candidate Triage",
+        "Accepted fixture destination and rejected shell candidates.",
+        "",
+        "## Rejected Candidates",
+        "Rejected privacy, login, and search shell examples.",
+        "",
+        "## Deep Dives",
+        "Opened the fixture destination page.",
+        "",
+        "## Synthesis Feedback",
+        "Remaining gap is independent corroboration."
+      ].join("\n")
     );
     fs.writeFileSync(
       path.join(bundleDir, "compact.md"),
@@ -148,7 +170,22 @@ if (domain === "research" && command === "run") {
       `- Days: ${days}`,
       `- Source selection: ${sourceSelection}`,
       `- Sources: ${sources}`,
-      "- Finding: ISSUE-09 pagination/result drift across sources"
+      "- Finding: ISSUE-09 pagination/result drift across sources",
+      "",
+      "## Search Direction",
+      "Fixture provider pass suggested destination follow-up.",
+      "",
+      "## Candidate Triage",
+      "Accepted fixture destination and rejected shell candidates.",
+      "",
+      "## Rejected Candidates",
+      "Rejected privacy, login, and search shell examples.",
+      "",
+      "## Deep Dives",
+      "Opened the fixture destination page.",
+      "",
+      "## Synthesis Feedback",
+      "Remaining gap is independent corroboration."
     ]);
     process.exit(0);
   }

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

@@ -72,6 +72,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.
+- 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.
 
@@ -97,6 +98,8 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 - 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.
+- 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.
 - Validate new patterns in isolation or `/canvas` preview with `artifacts/isolated-preview-validation.md`, including deterministic fixtures and installed dependencies, before declaring the integrated screen finished.
 - Verify default, hover, focus, empty, loading, success, and error states when they are relevant.
@@ -139,6 +142,8 @@ The `generationPlan` block must include:
 - `accessibilityPosture`
 - `validationTargets`
 
+Optional `designVectors` may carry advanced motion advisories, but it must not change the required CanvasGenerationPlan fields or imply shader, WebGL, Spline, or 3D runtime support.
+
 Use `scripts/extract-canvas-plan.sh` when the full contract already exists and only the `/canvas` payload is needed.
 
 ## Recommended Workflow Modes

package/skills/opendevbrowser-design-agent/artifacts/design-contract-playbook.md

@@ -90,6 +90,8 @@ Motion must help comprehension.
 - where motion is allowed
 - reduced-motion posture
 - whether depth, 3D, or parallax are justified
+- advisory-only shader, WebGL, Spline-style, or spatial cues when references suggest them
+- confirmation that motion cues do not authorize `libraryPolicy.motion` or `libraryPolicy.threeD`
 
 ## 9. Performance Model
 
@@ -139,6 +141,8 @@ Required keys:
 - `accessibilityPosture`
 - `validationTargets`
 
+Optional `designVectors` can carry advanced motion advisories when references suggest shader-like, WebGL-style, Spline-style, or spatial behavior. Keep those values descriptive. They do not add runtime support, change the required plan shape, or approve new motion or 3D libraries.
+
 Use `scripts/extract-canvas-plan.sh` to derive this from the full contract.
 
 ## Review Questions
@@ -154,4 +158,5 @@ Before implementation, answer:
 7. Where is the canonical theme or token source?
 8. Which list, grid, or pane is most likely to become render-heavy under realistic data?
 9. What part of the design is most likely to regress on mobile?
-10. What evidence will prove the design works on a real browser surface?
+10. Are advanced motion cues advisory only, with no runtime or library-policy authorization implied?
+11. What evidence will prove the design works on a real browser surface?

package/skills/opendevbrowser-design-agent/assets/templates/design-contract.v1.json

@@ -128,7 +128,13 @@
       "section reveal",
       "primary CTA feedback"
     ],
-    "parallaxPolicy": "off unless explicitly justified"
+    "parallaxPolicy": "off unless explicitly justified",
+    "advancedMotionAdvisory": [
+      "Advisory shader-like gradient depth: describe intent only; implement with approved runtime primitives unless a separate runtime change authorizes more.",
+      "Advisory WebGL-style spatial reveal: document depth and hierarchy without implying WebGL runtime support.",
+      "Advisory Spline-style product orbit: document scene posture and static fallback without approving custom 3D runtime dependencies.",
+      "Runtime boundary: libraryPolicy.motion and libraryPolicy.threeD stay empty unless separately approved."
+    ]
   },
   "performanceModel": {
     "renderHotspots": [
@@ -221,6 +227,14 @@
         "spinner-stacking",
         "scan-surface-jank"
       ]
+    },
+    "designVectors": {
+      "advancedMotionAdvisory": [
+        "Advisory shader-like gradient depth",
+        "Advisory WebGL-style spatial reveal",
+        "Advisory Spline-style product orbit",
+        "Runtime support: none. Library policy authorization: none."
+      ]
     }
   }
 }

package/skills/opendevbrowser-design-agent/assets/templates/inspiredesign-advanced-brief.v1.json

@@ -4,11 +4,14 @@
   "commonRules": [
     "Preserve only the product, brand, audience, platform, and tone cues that are explicitly present in the source brief.",
     "Treat missing details as open constraints instead of inventing brand facts or user needs.",
-    "Use inspiration references to extract transferable design logic rather than copying a single layout, visual treatment, or narrative beat literally."
+    "Use inspiration references to extract transferable design logic rather than copying a single layout, visual treatment, or narrative beat literally.",
+    "Treat shader, WebGL, Spline-style, and 3D motion ideas as advisory design cues only, not as runtime support or dependency approval.",
+    "Carry accepted advanced motion cues in designVectors and motionSystem as intent, and keep libraryPolicy authorization separate."
   ],
   "outputRequirements": [
     "Return a reusable design contract that can drive design.md, implementation-plan artifacts, and a Canvas-ready prototype path.",
-    "Keep the direction premium, specific, and implementable instead of generic or template-driven."
+    "Keep the direction premium, specific, and implementable instead of generic or template-driven.",
+    "Keep libraryPolicy.motion and libraryPolicy.threeD empty in generated samples unless a separate runtime change explicitly approves those libraries."
   ],
   "formats": [
     {

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

@@ -15,6 +15,7 @@
       "contentHierarchy": [],
       "componentFamilies": [],
       "motionPosture": "",
+      "advancedMotionAdvisory": [],
       "loadingStrategy": "",
       "tokenNotes": [],
       "patternsToBorrow": [],
@@ -26,6 +27,7 @@
     "dominantDirection": "",
     "sharedStrengths": [],
     "sharedFailuresToAvoid": [],
+    "motionContractDeltas": [],
     "contractDeltas": []
   }
 }

package/skills/opendevbrowser-research/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: opendevbrowser-research
-description: Deterministic multi-source research workflow with strict timebox and artifact outputs.
+description: Skill-guided, evidence-gated research workflow for provider-constrained public source gathering and auditable artifact review.
 version: 2.1.0
 ---
 
 # Research Skill
 
-Use this skill when you need benchmark-style research across public `web|community|social` sources by default, with explicit shopping opt-in only for commercial comparison tasks.
+Load this skill before research tasks. Use it to plan source families, gather provider-constrained evidence, review artifacts, and publish only claims that survive the evidence gate.
+
+`opendevbrowser research run` is a low-level, best-effort primitive. It can collect and render provider results, but the skill owns source planning, blocker review, confidence, limitations, and final synthesis.
 
 ## Pack Contents
 
@@ -24,7 +26,7 @@ Use this skill when you need benchmark-style research across public `web|communi
 
 ```bash
 ./skills/opendevbrowser-research/scripts/validate-skill-assets.sh
-./skills/opendevbrowser-research/scripts/run-research.sh "browser automation" 30 context
+./skills/opendevbrowser-research/scripts/run-research.sh "browser automation" 30 context "web,community"
 ./skills/opendevbrowser-research/scripts/render-output.sh "browser automation" compact
 ```
 
@@ -37,11 +39,59 @@ Use this skill when you need benchmark-style research across public `web|communi
 ## Core Rules
 
 - Define timebox first (`--days` or `--from/--to`).
-- Prefer explicit sources for high-stakes claims.
+- Choose explicit source families before invoking the CLI primitive: `web`, `community`, `social`, `shopping`, or a deliberate combination such as `web,community`.
+- Treat `auto` as a source-family selector, not a reliability guarantee.
 - Persist artifacts and return reproducible paths.
-- Mark unsupported claims as tentative; do not overstate certainty.
+- Mark unsupported claims as tentative or exclude them from the final answer.
 - Honor bounded retries and backoff windows under 429 pressure.
 
+## Evidence Gate
+
+Review artifacts before publishing claims. A successful command exit or rendered report is not enough.
+
+Preserved artifact files:
+
+- `summary.md`
+- `report.md`
+- `records.json`
+- `context.json`
+- `meta.json`
+- `bundle-manifest.json`
+
+Required review:
+
+1. Read `records.json` for fetched source records, timestamps, providers, extraction quality, and blockers.
+2. Read `context.json` for source ledger, evidence gaps, unsupported claims, staleness checks, and search-engine provenance when used.
+3. Read `meta.json` for provider limits, warnings, no-evidence failures, cookie diagnostics, challenge/auth/token failures, and artifact generation details.
+4. When gated providers such as Reddit block evidence, rerun with user-authorized recovery only after candidate triage has exhausted relevant public destination pages: `--browser-mode extension` for an existing signed-in relay session, `--use-cookies` only when legitimate cookies are available, and `--challenge-automation-mode browser_with_helper` for browser-scoped assistance.
+5. Use `report.md` and `summary.md` only after confirming claims map back to accepted evidence.
+6. Do not use shell-only, stale-only, login-only, not-found-only, or zero-source-evidence runs to support final claims.
+
+## Guided Research Loop
+
+Research is iterative. Do not stop at the first provider page or SERP shell.
+
+1. Start with provider or search-engine direction: query, capture candidate URLs, rank, title, and blocker notes.
+2. Reject navigation dead ends before treating them as evidence: login routes, privacy or cookie preference pages, consent gates, search result shells, not-found pages, and JavaScript-only shells.
+3. Open destination pages from the candidate set, not account, privacy, cookie, or login links. For Reddit, prefer concrete `/r/.../comments/...` result URLs over `/login`, `/search`, `/account`, `/submit`, or root navigation.
+4. If a destination is blocked, record the blocker and choose the next candidate from the same result set before escalating to cookies or an authenticated browser.
+5. Escalate to `--browser-mode extension`, `--use-cookies`, or `--challenge-automation-mode browser_with_helper` only when the selected evidence page itself needs authorized browser recovery and the user has legitimate access.
+6. Continue until you have enough accepted destination evidence for the claims, or every relevant candidate is blocked, stale, irrelevant, or unsupported.
+7. Synthesize only after the loop produces accepted evidence. If no destination evidence survives, return limitations and next-step options instead of a research answer.
+
+## Search Engine Discovery Lane
+
+This lane is optional, skill-guided, provider-constrained, and discovery-only. It can improve breadth, but it is not a reliable default and does not replace `opendevbrowser research run` or the evidence gate.
+
+1. Choose up to five engines based on topic and availability. Candidate set: Google, Bing, Brave, DuckDuckGo or Yahoo for overlap checks, Yandex for regional or index diversity, Baidu for China-specific topics, and Kagi only when the user has account access.
+2. Record engine choice rationale, query variants, region and language assumptions, auth or cookie needs, and blockers.
+3. Collect up to 10 result URLs per selected engine. Preserve engine, query, rank, URL, title if available, and retrieval notes.
+4. Dedupe canonical URLs, then select the strongest 5 to 10 destination pages for extraction.
+5. Extract selected destination pages through OpenDevBrowser browsing primitives when useful, including DOM interaction and screenshots. Use cookies or authenticated browsing only after destination-candidate triage shows the selected evidence page itself requires authorized access.
+6. Do not violate robots restrictions, login walls, consent gates, CAPTCHAs, rate limits, anti-bot controls, or access controls. Stand down and record limitations instead.
+7. Keep SERPs discovery-only. SERP snippets, result pages, shells, and blocked pages cannot be final evidence.
+8. Final claims must cite destination pages or other fetched evidence that survived review.
+
 ## Parallel Multitab Alignment
 
 - Apply shared concurrency policy from `../opendevbrowser-best-practices/SKILL.md` ("Parallel Operations").
@@ -60,22 +110,24 @@ Matrix source: `../opendevbrowser-best-practices/artifacts/browser-agent-known-i
 ## Workflow
 
 1. Resolve timebox (`days` or `from/to`).
-2. Choose sources (`auto|web|community|social|shopping|all`).
-3. Run `opendevbrowser research run`.
-4. Return requested mode output and artifact path.
+2. Choose explicit source families and document why they fit the topic.
+3. Optionally run the search-engine discovery lane to find destination candidates.
+4. Run `opendevbrowser research run` as a low-level best-effort primitive.
+5. Review `records.json`, `context.json`, and `meta.json` before trusting `report.md`.
+6. If `meta.json` shows auth, token, challenge, or cookie-gated providers, make the next run skill-first only after the candidate queue has no relevant public destination evidence left: use the existing signed-in browser session when authorized, cookies only when legitimate cookies are available, and browser-scoped challenge assistance only for that browser session.
+7. Return final claims only when they are supported by accepted evidence.
 
 ## Commands
 
 ```bash
-opendevbrowser research run --topic "<topic>" --days 30 --source-selection auto --mode context
-opendevbrowser research run --topic "<topic>" --source-selection auto --mode json
+opendevbrowser research run --topic "<topic>" --days 30 --sources web,community --mode context
+opendevbrowser research run --topic "<topic>" --sources web --mode json
 opendevbrowser research run --topic "<topic>" --sources web,shopping --mode md
 ```
 
 ## Notes
 
-- `auto` is the recommended default for topical research.
-- In the current contract, both `auto` and `all` resolve to `web|community|social`.
+- `auto` and `all` are selector values in the current source-family contract, not promises of reliable coverage.
 - Use `--source-selection shopping` or explicit `--sources ...shopping...` to include shopping only when commercial intent is explicit.
 - Use `--mode path` with `scripts/write-artifacts.sh` when you need replayable handoff bundles.
 - For browser-backed release proof and mode sweeps, follow the canonical direct-run evidence policy in `../opendevbrowser-best-practices/SKILL.md`.