opendevbrowser 0.0.17 → 0.0.18

package/skills/opendevbrowser-login-automation/scripts/validate-skill-assets.sh

@@ -16,6 +16,16 @@ required=(
 
 status=0
 
+require_marker() {
+  local label="$1"
+  local output="$2"
+  local marker="$3"
+  if [[ "$output" != *"$marker"* ]]; then
+    echo "$label missing marker: $marker" >&2
+    status=1
+  fi
+}
+
 for rel in "${required[@]}"; do
   if [[ ! -f "$root/$rel" ]]; then
     echo "Missing required asset: $rel" >&2
@@ -43,6 +53,129 @@ for rel in assets/templates/login-scenario-matrix.json assets/templates/auth-sig
   fi
 done
 
+list_output="$("$root/scripts/run-login-workflow.sh" list)"
+for workflow_name in \
+  password \
+  mfa \
+  sso-popup \
+  challenge-checkpoint \
+  pointer-checkpoint \
+  challenge-loop-guard \
+  lockout-recovery \
+  session-persistence
+do
+  require_marker "workflow list" "$list_output" "$workflow_name"
+done
+
+password_output="$("$root/scripts/run-login-workflow.sh" password)"
+require_marker "password workflow" "$password_output" "opendevbrowser_type"
+require_marker "password workflow" "$password_output" "opendevbrowser_network_poll"
+
+mfa_output="$("$root/scripts/run-login-workflow.sh" mfa)"
+require_marker "mfa workflow" "$mfa_output" "opendevbrowser_type"
+require_marker "mfa workflow" "$mfa_output" "mfa-input-ref"
+
+challenge_output="$("$root/scripts/run-login-workflow.sh" challenge-checkpoint)"
+require_marker "challenge-checkpoint workflow" "$challenge_output" "manual checkpoint required"
+require_marker "challenge-checkpoint workflow" "$challenge_output" "opendevbrowser_click"
+
+pointer_output="$("$root/scripts/run-login-workflow.sh" pointer-checkpoint)"
+require_marker "pointer-checkpoint workflow" "$pointer_output" "opendevbrowser_pointer_drag"
+require_marker "pointer-checkpoint workflow" "$pointer_output" "steps=12"
+
+challenge_loop_output="$("$root/scripts/run-login-workflow.sh" challenge-loop-guard)"
+require_marker "challenge-loop-guard workflow" "$challenge_loop_output" "Retry-After"
+require_marker "challenge-loop-guard workflow" "$challenge_loop_output" "opendevbrowser_network_poll"
+
+lockout_output="$("$root/scripts/run-login-workflow.sh" lockout-recovery)"
+require_marker "lockout-recovery workflow" "$lockout_output" "lockout/rate-limit banner"
+require_marker "lockout-recovery workflow" "$lockout_output" "opendevbrowser_network_poll"
+
+session_persistence_output="$("$root/scripts/run-login-workflow.sh" session-persistence)"
+require_marker "session-persistence workflow" "$session_persistence_output" "persistProfile=true"
+require_marker "session-persistence workflow" "$session_persistence_output" "profile=\"auth-test\""
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+signals_output="$tmpdir/auth-signals.json"
+"$root/scripts/record-auth-signals.sh" "$root/examples/sample-auth-signals.json" "$signals_output" >/dev/null
+if ! cmp -s "$root/examples/sample-auth-signals.json" "$signals_output"; then
+  echo "record-auth-signals.sh did not preserve the auth-signals fixture." >&2
+  status=1
+fi
+
+if ! node - "$root" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+
+const [root] = process.argv.slice(2);
+const failures = [];
+
+const matrix = JSON.parse(fs.readFileSync(path.join(root, "assets/templates/login-scenario-matrix.json"), "utf8"));
+const authSignals = JSON.parse(fs.readFileSync(path.join(root, "assets/templates/auth-signals.json"), "utf8"));
+const sampleSignals = JSON.parse(fs.readFileSync(path.join(root, "examples/sample-auth-signals.json"), "utf8"));
+
+if (!Array.isArray(matrix.issue_ids) || matrix.issue_ids.length < 7) {
+  failures.push("login-scenario-matrix.json must enumerate the workflow issue ids.");
+}
+for (const marker of ["url_changed", "auth_shell_visible", "auth_network_success", "pointer_gate_complete_when_required"]) {
+  if (!Array.isArray(matrix.expected_signals) || !matrix.expected_signals.includes(marker)) {
+    failures.push(`login-scenario-matrix.json missing expected signal: ${marker}`);
+  }
+}
+for (const marker of ["invalid_credentials_ui_or_network", "anti_bot_challenge", "rate_limited", "lockout"]) {
+  if (!Array.isArray(matrix.failure_signals) || !matrix.failure_signals.includes(marker)) {
+    failures.push(`login-scenario-matrix.json missing failure signal: ${marker}`);
+  }
+}
+if (matrix.max_automated_retries !== 2) {
+  failures.push("login-scenario-matrix.json must cap automated retries at 2.");
+}
+if (typeof matrix.requires_manual_checkpoint !== "boolean") {
+  failures.push("login-scenario-matrix.json must define requires_manual_checkpoint as a boolean.");
+}
+
+for (const key of [
+  "invalid_credentials_ui_seen",
+  "invalid_credentials_network_seen",
+  "pointer_gate_detected",
+  "pointer_gate_completed",
+  "challenge_checkpoint_count",
+  "mfa_detected",
+  "issue_ids",
+  "result"
+]) {
+  if (!(key in authSignals)) {
+    failures.push(`auth-signals.json missing key: ${key}`);
+  }
+}
+if (!authSignals.network || typeof authSignals.network.retry_after_seconds !== "number") {
+  failures.push("auth-signals.json must define network.retry_after_seconds.");
+}
+if (!Array.isArray(authSignals.network?.status_codes)) {
+  failures.push("auth-signals.json must define network.status_codes as an array.");
+}
+if (!Array.isArray(sampleSignals.network?.status_codes) || sampleSignals.network.status_codes[0] !== 200) {
+  failures.push("sample-auth-signals.json must retain a successful login status code example.");
+}
+if (sampleSignals.result !== "authenticated") {
+  failures.push("sample-auth-signals.json must demonstrate an authenticated result.");
+}
+if (sampleSignals.mfa_detected !== true) {
+  failures.push("sample-auth-signals.json must preserve the MFA branch example.");
+}
+
+if (failures.length > 0) {
+  for (const failure of failures) {
+    console.error(failure);
+  }
+  process.exit(1);
+}
+NODE
+then
+  status=1
+fi
+
 if [[ $status -ne 0 ]]; then
   exit $status
 fi

package/skills/opendevbrowser-product-presentation-asset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opendevbrowser-product-presentation-asset
-description: Collects product screenshots, images, copy, and metadata into a local folder pack for video workflows.
+description: Collects product metadata, copy, and optional visual assets into a local folder pack for video workflows.
 version: 2.0.0
 ---
 
@@ -36,16 +36,26 @@ Use this skill to build complete product-video input packs and assembly instruct
 ./skills/opendevbrowser-product-presentation-asset/scripts/render-video-brief.sh /path/to/manifest.json /tmp/product-video-brief
 ```
 
+## Supporting Surfaces
+
+- Use browser replay (`screencast-start` / `screencast-stop`) when a product flow needs temporal UI proof before you decide which screenshots to keep.
+- Use desktop observation only for read-only evidence around external windows or OS-owned dialogs that affected capture.
+- Use `--challenge-automation-mode off|browser|browser_with_helper` for bounded browser-scoped computer use on provider or auth walls; it is not a desktop agent.
+
 ## Final Assets Produced
 
-Expected output pack includes:
+Expected output pack always includes:
 - `manifest.json` with canonical product metadata
 - `product.json` and `pricing.json`
-- `images/` for product stills
-- `screenshots/` for page context and UI proof
 - `copy.md` and `features.md`
 - `raw/source-record.json` for auditability
 
+When visual capture succeeds, the pack may also include:
+- `images/` for product stills
+- `screenshots/` for page context and UI proof
+
+Metadata-first packs with `0` images and `0` screenshots are still valid intermediate outputs when the workflow captured canonical product data, copy, and pricing. Those packs need additional visual sourcing before final video publication.
+
 The `render-video-brief.sh` helper adds:
 - `video-brief.md`
 - `shot-list.md`
@@ -56,9 +66,10 @@ The `render-video-brief.sh` helper adds:
 
 1. Pick product URL or product name.
 2. Run collection workflow and confirm output pack path.
-3. Review generated manifest/copy/features for accuracy.
-4. Run `render-video-brief.sh` to generate production instructions.
-5. Hand the brief and assets to editor/creator pipeline.
+3. Review generated manifest/copy/features for accuracy and check whether the pack is visual-ready or metadata-first.
+4. Run `render-video-brief.sh` to generate production instructions and visual sourcing notes.
+	Canonical helper path: `scripts/render-video-brief.sh`.
+5. If no visuals were captured, source or capture visuals before handing the brief to the editor/creator pipeline.
 
 ## Parallel Multitab Alignment
 
@@ -70,10 +81,11 @@ The `render-video-brief.sh` helper adds:
 
 1. Use `manifest.json` as source of truth.
 2. Build hooks and claims from `copy.md` + `features.md`.
-3. Pair each claim with supporting asset (`images` or `screenshots`).
-4. Sequence assets using `shot-list.md`.
-5. Validate pricing/availability freshness before publishing.
-6. Validate every claim appears in `claims-evidence-map.md` before publish.
+3. Pair each claim with supporting asset (`images` or `screenshots`) when available.
+4. If the pack is metadata-first, source visuals before final edit and update `shot-list.md` plus `claims-evidence-map.md` with the new asset paths.
+5. Sequence assets using `shot-list.md`.
+6. Validate pricing/availability freshness before publishing.
+7. Validate every claim appears in `claims-evidence-map.md` before publish.
 
 ## Robustness Coverage (Known-Issue Matrix)
 

package/skills/opendevbrowser-product-presentation-asset/artifacts/asset-pack-assembly.md

@@ -9,15 +9,17 @@
 ## Build sequence
 
 1. Collect base product pack (`collect-product.sh`)
-2. Ensure screenshots/images exist
+2. Inspect the capture summary and classify the pack as visual-ready or metadata-first
 3. Validate manifest schema fields
 4. Generate video brief (`render-video-brief.sh`)
 5. Review claim-to-evidence mapping (`claims-evidence-map.md`)
-6. Review shot sequence and CTA consistency
+6. If visuals are missing, source or capture them before final publication
+7. Review shot sequence and CTA consistency
 
 ## Release checks
 
 - pricing timestamp is recent
-- screenshot/image files are present and readable
+- screenshot/image files are readable when present
+- metadata-first packs are marked for additional visual sourcing before publish
 - copy claims map to feature evidence
 - every promoted claim is backed by a concrete asset path

package/skills/opendevbrowser-product-presentation-asset/assets/templates/shot-list.md

@@ -1,5 +1,7 @@
 # Shot List
 
+Use captured screenshots or images when present. For metadata-first packs, replace the sample asset paths with sourced visuals before publishing.
+
 | Scene | Goal | Asset | Voiceover | Duration |
 |---|---|---|---|---:|
 | 1 | Hook | screenshots/screenshot-01.png | | 2s |

package/skills/opendevbrowser-product-presentation-asset/assets/templates/video-assembly.md

@@ -6,13 +6,14 @@
 - Product metadata: `product.json`
 - Pricing: `pricing.json`
 - Copy and features: `copy.md`, `features.md`
-- Visuals: `images/*`, `screenshots/*`
+- Visuals: `images/*`, `screenshots/*` when capture succeeds
 - Claim evidence map: `claims-evidence-map.md`
 
 ## Assembly Steps
 
 1. Build script from top 3 verified benefits.
-2. Match each line to one visual asset.
+2. Match each line to one visual asset when visuals exist.
 3. Create sequence: hook -> proof -> CTA.
 4. Verify all price/discount statements against `pricing.json`.
 5. Mark `claims-evidence-map.md` rows as verified before publishing.
+6. If the pack is metadata-first, source visuals and update the shot list before final edit.

package/skills/opendevbrowser-product-presentation-asset/scripts/capture-screenshots.sh

@@ -6,4 +6,8 @@ if [[ $# -lt 1 ]]; then
   exit 1
 fi
 
-opendevbrowser product-video run --product-url "$1" --include-screenshots --include-all-images=false
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh
+source "$script_dir/../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh"
+
+"${ODB_CLI[@]}" product-video run --product-url "$1" --include-screenshots --include-all-images=false

package/skills/opendevbrowser-product-presentation-asset/scripts/collect-product.sh

@@ -7,8 +7,12 @@ if [[ $# -lt 1 ]]; then
 fi
 
 VALUE="$1"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh
+source "$script_dir/../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh"
+
 if [[ "$VALUE" == http* ]]; then
-  opendevbrowser product-video run --product-url "$VALUE"
+  "${ODB_CLI[@]}" product-video run --product-url "$VALUE"
 else
-  opendevbrowser product-video run --product-name "$VALUE"
+  "${ODB_CLI[@]}" product-video run --product-name "$VALUE"
 fi

package/skills/opendevbrowser-product-presentation-asset/scripts/download-images.sh

@@ -6,4 +6,8 @@ if [[ $# -lt 1 ]]; then
   exit 1
 fi
 
-opendevbrowser product-video run --product-url "$1" --include-all-images --include-screenshots=false
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh
+source "$script_dir/../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh"
+
+"${ODB_CLI[@]}" product-video run --product-url "$1" --include-all-images --include-screenshots=false

package/skills/opendevbrowser-product-presentation-asset/scripts/render-video-brief.sh

@@ -29,9 +29,18 @@ const features = Array.isArray(product.features) ? product.features.slice(0, 5)
 const copy = typeof product.copy === "string" ? product.copy.trim().slice(0, 600) : "";
 const images = Array.isArray(data?.assets?.images) ? data.assets.images : [];
 const screenshots = Array.isArray(data?.assets?.screenshots) ? data.assets.screenshots : [];
+const noVisualAsset = "metadata-only-pack:no-captured-visual";
+const hasVisuals = images.length > 0 || screenshots.length > 0;
+const featureClaims = features.length > 0
+  ? features
+  : ["Review manifest data and add only evidence-backed feature claims"];
 
-const claimRows = (features.length ? features : ["Add verified feature claims"]).map((claim, index) => {
-  const evidence = screenshots[index] || images[index] || images[0] || screenshots[0] || "<asset>";
+function pickVisual(...candidates) {
+  return candidates.find((entry) => typeof entry === "string" && entry.length > 0) || noVisualAsset;
+}
+
+const claimRows = featureClaims.map((claim, index) => {
+  const evidence = pickVisual(screenshots[index], images[index], images[0], screenshots[0]);
   return `| ${claim} | ${evidence} | product.features[${index}] | no |`;
 });
 
@@ -41,12 +50,15 @@ const videoBrief = [
   `- Product: ${title}`,
   `- Brand: ${brand}`,
   `- Price: ${amount} ${currency}`,
+  `- Visual capture status: ${hasVisuals ? "visual-ready" : "metadata-first"}`,
   "",
   "## Verified Features",
-  ...(features.length ? features.map((entry) => `- ${entry}`) : ["- Add verified feature bullets"]),
+  ...featureClaims.map((entry) => `- ${entry}`),
   "",
   "## Suggested Hook",
-  `- "${title} solves <problem> faster with <core benefit>."`,
+  hasVisuals
+    ? `- "${title} from ${brand} should open on its strongest verified benefit and immediate proof."`
+    : `- "${title} from ${brand}: finalize visuals first, then lead with the strongest verified benefit."`,
   "",
   "## Copy Input",
   copy ? copy : "(No copy captured)",
@@ -54,6 +66,7 @@ const videoBrief = [
   "## Assets",
   `- Images: ${images.length}`,
   `- Screenshots: ${screenshots.length}`,
+  `- Additional visual sourcing required: ${hasVisuals ? "no" : "yes"}`,
   "- Claims evidence map: claims-evidence-map.md"
 ].join("\n");
 
@@ -62,9 +75,9 @@ const shotList = [
   "",
   "| Scene | Goal | Asset | Voiceover | Duration |",
   "|---|---|---|---|---:|",
-  `| 1 | Hook | ${screenshots[0] || images[0] || "<asset>"} | Problem + promise | 2s |`,
-  `| 2 | Feature demo | ${images[0] || screenshots[0] || "<asset>"} | Show proof | 4s |`,
-  `| 3 | Outcome + CTA | ${images[1] || screenshots[1] || images[0] || "<asset>"} | Benefit + CTA | 4s |`
+  `| 1 | Hook | ${pickVisual(screenshots[0], images[0])} | Problem + promise | 2s |`,
+  `| 2 | Feature demo | ${pickVisual(images[0], screenshots[0])} | Show proof | 4s |`,
+  `| 3 | Outcome + CTA | ${pickVisual(images[1], screenshots[1], images[0], screenshots[0])} | Benefit + CTA | 4s |`
 ].join("\n");
 
 const ugcBrief = [

package/skills/opendevbrowser-product-presentation-asset/scripts/validate-skill-assets.sh

@@ -24,6 +24,16 @@ required=(
 )
 
 status=0
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+metadata_manifest="$tmpdir/metadata-only-manifest.json"
+node -e '
+const fs = require("fs");
+const input = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+input.assets = { images: [], screenshots: [], raw: input.assets?.raw || [] };
+fs.writeFileSync(process.argv[2], JSON.stringify(input, null, 2));
+' "$root/examples/sample-manifest.json" "$metadata_manifest"
 for rel in "${required[@]}"; do
   if [[ ! -f "$root/$rel" ]]; then
     echo "Missing required asset: $rel" >&2
@@ -42,6 +52,19 @@ for rel in scripts/collect-product.sh scripts/capture-screenshots.sh scripts/dow
   fi
 done
 
+for rel in scripts/collect-product.sh scripts/capture-screenshots.sh scripts/download-images.sh scripts/write-manifest.sh; do
+  if [[ -f "$root/$rel" ]]; then
+    if ! grep -Fq "resolve-odb-cli.sh" "$root/$rel"; then
+      echo "Workflow wrapper missing shared CLI resolver: $rel" >&2
+      status=1
+    fi
+    if ! grep -Fq "ODB_CLI" "$root/$rel"; then
+      echo "Workflow wrapper missing ODB_CLI invocation: $rel" >&2
+      status=1
+    fi
+  fi
+done
+
 if [[ -f "$root/assets/templates/manifest.schema.json" ]]; then
   if ! node -e 'const fs=require("fs"); JSON.parse(fs.readFileSync(process.argv[1], "utf8"));' "$root/assets/templates/manifest.schema.json" >/dev/null 2>&1; then
     echo "Invalid JSON template: assets/templates/manifest.schema.json" >&2
@@ -49,6 +72,22 @@ if [[ -f "$root/assets/templates/manifest.schema.json" ]]; then
   fi
 fi
 
+"$root/scripts/render-video-brief.sh" "$metadata_manifest" "$tmpdir/brief" >/dev/null
+for generated in video-brief.md shot-list.md ugc-brief.md claims-evidence-map.md; do
+  if [[ ! -f "$tmpdir/brief/$generated" ]]; then
+    echo "render-video-brief.sh missing generated file: $generated" >&2
+    status=1
+  fi
+done
+if [[ -f "$tmpdir/brief/video-brief.md" ]] && ! grep -Fq "metadata-first" "$tmpdir/brief/video-brief.md"; then
+  echo "render-video-brief.sh did not preserve metadata-first output when visuals are absent." >&2
+  status=1
+fi
+if [[ -f "$tmpdir/brief/claims-evidence-map.md" ]] && ! grep -Fq "metadata-only-pack:no-captured-visual" "$tmpdir/brief/claims-evidence-map.md"; then
+  echo "render-video-brief.sh did not emit the metadata-only evidence placeholder." >&2
+  status=1
+fi
+
 if [[ $status -ne 0 ]]; then
   exit $status
 fi

package/skills/opendevbrowser-product-presentation-asset/scripts/write-manifest.sh

@@ -10,7 +10,11 @@ VALUE="$1"
 OUTDIR="$2"
 mkdir -p "$OUTDIR"
 
-cmd=(opendevbrowser product-video run --output-dir "$OUTDIR" --output-format json)
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh
+source "$script_dir/../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh"
+
+cmd=("${ODB_CLI[@]}" product-video run --output-dir "$OUTDIR" --output-format json)
 if [[ "$VALUE" == http* ]]; then
   cmd+=(--product-url "$VALUE")
 else

package/skills/opendevbrowser-research/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: opendevbrowser-research
 description: Deterministic multi-source research workflow with strict timebox and artifact outputs.
-version: 2.0.0
+version: 2.1.0
 ---
 
 # Research Skill
 
-Use this skill when you need benchmark-style research across `web|community|social|shopping` with strict timebox semantics and stable output modes.
+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.
 
 ## Pack Contents
 
@@ -28,6 +28,12 @@ Use this skill when you need benchmark-style research across `web|community|soci
 ./skills/opendevbrowser-research/scripts/render-output.sh "browser automation" compact
 ```
 
+## Supporting Surfaces
+
+- Use browser replay (`screencast-start` / `screencast-stop`) when claim review needs temporal UI evidence or parity proof from browser-backed runs.
+- Use desktop observation only for read-only external-window or native-dialog evidence that materially affects the research artifact chain.
+- Use `--challenge-automation-mode off|browser|browser_with_helper` for bounded browser-scoped computer use in research workflows; it is not a desktop agent.
+
 ## Core Rules
 
 - Define timebox first (`--days` or `--from/--to`).
@@ -61,13 +67,15 @@ Matrix source: `../opendevbrowser-best-practices/artifacts/browser-agent-known-i
 ## Commands
 
 ```bash
-opendevbrowser research run --topic "<topic>" --days 30 --mode context
-opendevbrowser research run --topic "<topic>" --source-selection all --mode json
+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>" --sources web,shopping --mode md
 ```
 
 ## Notes
 
-- `auto` resolves to `web|community|social` in v1.
-- Use `--source-selection all` or `--sources shopping,...` to include shopping.
+- `auto` is the recommended default for topical research.
+- In the current contract, both `auto` and `all` resolve to `web|community|social`.
+- 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`.

package/skills/opendevbrowser-research/scripts/render-output.sh

@@ -9,4 +9,8 @@ fi
 TOPIC="$1"
 MODE="$2"
 
-opendevbrowser research run --topic "$TOPIC" --mode "$MODE"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh
+source "$script_dir/../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh"
+
+"${ODB_CLI[@]}" research run --topic "$TOPIC" --mode "$MODE"

package/skills/opendevbrowser-research/scripts/run-research.sh

@@ -12,7 +12,11 @@ MODE="${3:-context}"
 SOURCE_SELECTION="${4:-}"
 SOURCES="${5:-}"
 
-cmd=(opendevbrowser research run --topic "$TOPIC" --days "$DAYS" --mode "$MODE")
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh
+source "$script_dir/../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh"
+
+cmd=("${ODB_CLI[@]}" research run --topic "$TOPIC" --days "$DAYS" --mode "$MODE")
 if [[ -n "$SOURCE_SELECTION" ]]; then
   cmd+=(--source-selection "$SOURCE_SELECTION")
 fi

package/skills/opendevbrowser-research/scripts/validate-skill-assets.sh

@@ -16,6 +16,18 @@ required=(
 )
 
 status=0
+validator_cli="$root/../opendevbrowser-best-practices/scripts/validator-fixture-cli.sh"
+export ODB_CLI_VALIDATOR_OVERRIDE="$validator_cli"
+
+require_marker() {
+  local label="$1"
+  local output="$2"
+  local marker="$3"
+  if [[ "$output" != *"$marker"* ]]; then
+    echo "$label missing marker: $marker" >&2
+    status=1
+  fi
+}
 for rel in "${required[@]}"; do
   if [[ ! -f "$root/$rel" ]]; then
     echo "Missing required asset: $rel" >&2
@@ -34,6 +46,19 @@ for rel in scripts/run-research.sh scripts/render-output.sh scripts/write-artifa
   fi
 done
 
+for rel in scripts/run-research.sh scripts/render-output.sh scripts/write-artifacts.sh; do
+  if [[ -f "$root/$rel" ]]; then
+    if ! grep -Fq "resolve-odb-cli.sh" "$root/$rel"; then
+      echo "Workflow wrapper missing shared CLI resolver: $rel" >&2
+      status=1
+    fi
+    if ! grep -Fq "ODB_CLI" "$root/$rel"; then
+      echo "Workflow wrapper missing ODB_CLI invocation: $rel" >&2
+      status=1
+    fi
+  fi
+done
+
 if [[ -f "$root/assets/templates/context.json" ]]; then
   if ! node -e 'const fs=require("fs"); JSON.parse(fs.readFileSync(process.argv[1], "utf8"));' "$root/assets/templates/context.json" >/dev/null 2>&1; then
     echo "Invalid JSON template: assets/templates/context.json" >&2
@@ -41,6 +66,26 @@ if [[ -f "$root/assets/templates/context.json" ]]; then
   fi
 fi
 
+context_output="$("$root/scripts/run-research.sh" "ai browser automation" 30 context auto "web,docs")"
+require_marker "run-research context" "$context_output" "# Research Context"
+require_marker "run-research context" "$context_output" "ISSUE-09"
+
+report_output="$("$root/scripts/render-output.sh" "ai browser automation" report)"
+require_marker "render-output report" "$report_output" "# Research Report"
+require_marker "render-output report" "$report_output" "Source selection"
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+artifact_output="$("$root/scripts/write-artifacts.sh" "ai browser automation" "$tmpdir")"
+artifact_path="$(printf '%s\n' "$artifact_output" | node -e 'const fs=require("fs");const lines=fs.readFileSync(0,"utf8").split(/\r?\n/).map((line)=>line.trim()).filter(Boolean);let payload=null;for(const line of lines){try{payload=JSON.parse(line);}catch{}}const value=payload?.data?.path; if(typeof value==="string") process.stdout.write(value);')"
+if [[ -z "$artifact_path" || ! -d "$artifact_path" ]]; then
+  echo "write-artifacts.sh did not produce a valid artifact directory." >&2
+  status=1
+elif [[ ! -f "$artifact_path/bundle-manifest.json" || ! -f "$artifact_path/report.md" ]]; then
+  echo "write-artifacts.sh did not write the expected research bundle files." >&2
+  status=1
+fi
+
 if [[ $status -ne 0 ]]; then
   exit $status
 fi

package/skills/opendevbrowser-research/scripts/write-artifacts.sh

@@ -9,7 +9,11 @@ fi
 TOPIC="$1"
 OUTDIR="$2"
 
-json_output="$(opendevbrowser research run --topic "$TOPIC" --mode path --output-dir "$OUTDIR" --output-format json)"
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh
+source "$script_dir/../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh"
+
+json_output="$("${ODB_CLI[@]}" research run --topic "$TOPIC" --mode path --output-dir "$OUTDIR" --output-format json)"
 printf '%s\n' "$json_output"
 
 artifact_path="$(printf '%s\n' "$json_output" | node -e 'const fs=require("fs");const lines=fs.readFileSync(0,"utf8").split(/\r?\n/).map((line)=>line.trim()).filter(Boolean);let payload=null;for(const line of lines){try{payload=JSON.parse(line);}catch{}}const p=payload?.data?.path; if(typeof p==="string") process.stdout.write(p);')"

package/skills/opendevbrowser-shopping/SKILL.md

@@ -1,13 +1,18 @@
 ---
 name: opendevbrowser-shopping
 description: Deterministic multi-provider shopping and deal-comparison workflow.
-version: 2.0.0
+version: 2.1.0
 ---
 
 # Shopping Skill
 
 Use this skill for robust deal hunting across providers with market-baseline validation and savings analysis.
 
+Reliable defaults:
+- start with explicit providers for reproducible reruns
+- prefer `--browser-mode managed` unless relay-backed session state is required
+- treat `--region` as advisory unless workflow output reports `meta.selection.region_authoritative=true`
+
 ## Pack Contents
 
 - `artifacts/deal-hunting-workflows.md`
@@ -31,6 +36,12 @@ Use this skill for robust deal hunting across providers with market-baseline val
 ./skills/opendevbrowser-shopping/scripts/run-deal-hunt.sh "wireless earbuds" "shopping/amazon,shopping/walmart"
 ```
 
+## Supporting Surfaces
+
+- Use browser replay (`screencast-start` / `screencast-stop`) when offer churn, price changes, or challenge timing needs temporal evidence.
+- Use desktop observation only for read-only evidence around sibling desktop surfaces; provider collection stays browser-first.
+- Use `--challenge-automation-mode off|browser|browser_with_helper` for bounded browser-scoped computer use on provider challenge branches; it is not desktop automation.
+
 ## Deal-Hunting Model
 
 Use a two-layer check for each offer:
@@ -48,6 +59,7 @@ Use a two-layer check for each offer:
 - Apply shared concurrency policy from `../opendevbrowser-best-practices/SKILL.md` ("Parallel Operations").
 - Validate shopping workflows across `managed`, `extension`, and `cdpConnect` when browser-backed provider paths are exercised.
 - Keep one session per worker for parallel offer collection and avoid session-level target contention.
+- For browser-backed release proof and mode sweeps, follow the canonical direct-run evidence policy in `../opendevbrowser-best-practices/SKILL.md`.
 
 ## Savings Math
 
@@ -85,8 +97,15 @@ Matrix source: `../opendevbrowser-best-practices/artifacts/browser-agent-known-i
 
 ```bash
 opendevbrowser shopping run --query "<query>" --providers shopping/amazon,shopping/walmart --mode json --output-format json
+opendevbrowser shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json
+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
 ```
 
+Diagnostics rules:
+- inspect `meta.primaryConstraintSummary` before classifying a zero-offer run as a provider failure
+- inspect `meta.offerFilterDiagnostics` to see whether zero price, budget, or region-currency filters removed the candidate offers
+- if `meta.alerts` includes `reasonCode=region_unenforced`, do not present the output as a trustworthy regional comparison
+
 ## Classification Heuristics
 
 Default tags from analysis script: