fix: surface validated workflow lanes in cli guidance

- forward shared workflow transport timeouts for research, shopping, and product-video commands
- add validated transcript, research, and shopping lanes to help, onboarding, docs, and skill guidance
- extend the best-practices router and CLI help tests to lock the reliable workflows

Co-authored-by: Codex <noreply@openai.com>

Author: freshtechbro

docs/CLI.md

@@ -2,10 +2,10 @@
 
 Command-line interface for installing and managing the OpenDevBrowser plugin, plus automation commands for agents.
 Status: active  
-Last updated: 2026-04-03
+Last updated: 2026-04-06
 
 OpenDevBrowser exposes 57 `opendevbrowser_*` tools; see `README.md` and `docs/SURFACE_REFERENCE.md` for the full inventories.
-Generated help is the primary first-contact inventory and onboarding surface. Agent runs should start with `opendevbrowser_prompting_guide` or `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"` before low-level browser commands. Load `opendevbrowser-design-agent` immediately after that baseline for frontend, screenshot-to-code, or `/canvas` design work. Use continuity guidance only for long-running handoff or compaction.
+Generated help is the primary first-contact inventory and onboarding surface. Agent runs should start with `opendevbrowser_prompting_guide` or `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"` before low-level browser commands, then load `opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"` when they need the currently proven transcript, research, and shopping workflows. Load `opendevbrowser-design-agent` immediately after that baseline for frontend, screenshot-to-code, or `/canvas` design work. Use continuity guidance only for long-running handoff or compaction.
 Tool-only commands `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, and `opendevbrowser_skill_load` run locally via the skill loader. They are onboarding helpers, not browser-runtime commands, and they do not require relay or daemon bootstrap.
 CLI-only power command `rpc` intentionally has no tool equivalent; it is an internal daemon escape hatch behind an explicit safety flag and should be used with extreme caution.
 Public-surface metadata now flows from `src/public-surface/source.ts` through `scripts/generate-public-surface-manifest.mjs` into `src/public-surface/generated-manifest.ts`, which is consumed by `src/cli/help.ts`, `src/cli/args.ts`, and re-exported by `src/tools/index.ts`. Onboarding literals still live in `src/cli/onboarding-metadata.json`, and runtime execution authority remains `src/cli/args.ts` plus `src/tools/index.ts`.
@@ -253,6 +253,7 @@ npx opendevbrowser -v
 
 `--help` and `help` print the same generated first-contact inventory:
 - An `Agent Quick Start` block that tells agents to start with `opendevbrowser_prompting_guide` or `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"` before low-level browser commands.
+- A follow-up `validated_lanes` entry that points agents to `opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"` for the current reliable transcript, research, and shopping runbook.
 - A direct pointer to `opendevbrowser_skill_list` when an agent needs a different local skill lane.
 - The complete generated CLI command, flag, and `opendevbrowser_*` tool inventories.
 - Canonical pointers to `docs/FIRST_RUN_ONBOARDING.md`, `skills/opendevbrowser-best-practices/SKILL.md`, and `docs/SURFACE_REFERENCE.md`.
@@ -396,7 +397,7 @@ The workflow wrappers expose the finalized research/shopping/product-video surfa
 
 ```bash
 npx opendevbrowser research run --topic "browser automation" --days 30 --mode compact
-npx opendevbrowser research run --topic "market map" --from 2026-02-01 --to 2026-02-16 --source-selection all --mode json
+npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --mode json
 npx opendevbrowser research run --topic "creator tools" --sources web,shopping --include-engagement --limit-per-source 5 --mode context
 ```
 
@@ -418,19 +419,26 @@ Flags:
 - `--cookie-policy-override` (`off|auto|required`)
 - `--cookie-policy` (alias of `--cookie-policy-override`)
 
+Notes:
+- Use `--source-selection auto` for generic topical research.
+- In the current contract, `auto` and `all` both stay inside the public topical families (`web`, `community`, `social`).
+- Add shopping only with `--source-selection shopping` or explicit `--sources ...shopping...` when the task is deliberately commercial.
+
 #### Shopping (`shopping run`)
 
 ```bash
 npx opendevbrowser shopping run --query "usb microphone" --mode compact
-npx opendevbrowser shopping run --query "portable monitor" --providers shopping/amazon,shopping/newegg --sort lowest_price --mode md
-npx opendevbrowser shopping run --query "desk chair" --budget 250 --region us --mode path
+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
 ```
 
 Flags:
 - `--query` (required)
 - `--providers` (comma-separated; defaults to all v1 adapters)
 - `--budget`
 - `--region`
+- `--browser-mode` (`auto|extension|managed`)
 - `--sort` (`best_deal|lowest_price|highest_rating|fastest_shipping`)
 - `--mode` (`compact|json|md|context|path`)
 - `--timeout-ms`
@@ -441,6 +449,11 @@ Flags:
 - `--cookie-policy-override` (`off|auto|required`)
 - `--cookie-policy` (alias of `--cookie-policy-override`)
 
+Notes:
+- Use explicit providers plus `--browser-mode managed` for the most reproducible live reruns.
+- Treat `--region` as advisory unless `meta.selection.region_authoritative=true`.
+- When a run returns no final offers, inspect `meta.primaryConstraintSummary` and `meta.offerFilterDiagnostics` before classifying the provider path as broken.
+
 #### Product presentation asset (`product-video run`)
 
 ```bash
@@ -1611,7 +1624,7 @@ When using `--with-config`, a `opendevbrowser.jsonc` is created with documented
       "enableYtdlpAudioAsr": true,
       "enableApify": true,
       "apifyActorId": "streamers/youtube-scraper",
-      "enableBrowserFallback": true,
+      "enableBrowserFallback": false,
       "ytdlpTimeoutMs": 10000
     }
   },
@@ -1624,14 +1637,15 @@ When using `--with-config`, a `opendevbrowser.jsonc` is created with documented
 
 The optional `skills.nudge` section controls the small one-time prompt hint that encourages early `skill(...)` usage on skill-relevant tasks. The optional `continuity` section controls the long-running task nudge and the ledger file path.
 Fingerprint runtime defaults are Tier 1/2/3 enabled, with Tier 2 and Tier 3 driven by continuous signals (debug trace remains readout/reporting).
-Provider runtime anti-bot/transcript controls default to an exhaustive YouTube fallback chain:
+Provider runtime anti-bot/transcript controls default to a public-first YouTube resolver chain:
 - Transcript mode semantics: `auto | web | no-auto | yt-dlp | apify`.
 - Request filter precedence is `filters.youtube_mode > providers.transcript.modeDefault > auto`.
 - No CLI mode flag is introduced in this phase; mode is configured in `providers.transcript.modeDefault` or per-request `youtube_mode` filter.
-- Auto mode fallback chain is `youtubei -> native_caption_parse -> ytdlp_audio_asr -> apify`, with browser-assisted fallback attempted last when browser escalation is available.
+- Auto mode fallback chain is `youtubei -> native_caption_parse -> ytdlp_audio_asr -> apify`.
 - `yt-dlp` audio transcription requires `providers.transcript.enableYtdlpAudioAsr=true`.
 - Apify requires `providers.transcript.enableApify=true`, a valid `APIFY_TOKEN`, and legal checklist approval for `apify`.
-- Browser-assisted fallback requires `providers.transcript.enableBrowserFallback=true` and `providers.antiBotPolicy.allowBrowserEscalation=true`.
+- Browser-assisted fallback is opt-in only and requires `providers.transcript.enableBrowserFallback=true` plus `providers.antiBotPolicy.allowBrowserEscalation=true`.
+- If browser fallback is enabled, run it in an isolated automation profile instead of a daily logged-in Google profile.
 
 Provider workflow and execution outputs now include normalized transcript/anti-bot telemetry:
 - Primary provider follow-up summary: `meta.primaryConstraintSummary`.

docs/FIRST_RUN_ONBOARDING.md

@@ -1,7 +1,7 @@
 # First-Run Onboarding (Pre-Release)
 
 Status: active  
-Last updated: 2026-04-04
+Last updated: 2026-04-06
 
 This guide is the shipping checklist for validating OpenDevBrowser as a new user **before npm distribution is live**.
 
@@ -55,9 +55,29 @@ Expected:
 - help opens with an `Agent Quick Start` block
 - the block explicitly points agents to `opendevbrowser_prompting_guide`
 - the block explicitly points agents to `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"`
+- the block explicitly points agents to `opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"`
 - the block explicitly points agents to `opendevbrowser_skill_list` for alternate local workflow lanes
 - the block points to `docs/FIRST_RUN_ONBOARDING.md` for proof and `skills/opendevbrowser-best-practices/SKILL.md` as the canonical bundled runbook
 
+## 2c) Validate the currently reliable workflow lanes
+
+These are the most repeatable capability checks from the April 6 validation pass.
+
+```bash
+npx --no-install opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --mode json --output-format json
+npx --no-install opendevbrowser shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json
+npx --no-install 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
+```
+
+Use the bundled best-practices runbook for the full current lane set, including the public-first YouTube transcript probe:
+
+```bash
+opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"
+```
+
+Region note:
+- treat `--region` as advisory unless workflow output reports `meta.selection.region_authoritative=true`
+
 ## 3) Isolate config/cache to avoid daemon collisions
 
 For onboarding tests on machines that already run OpenDevBrowser, isolate runtime state:

docs/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Status: active  
-Last updated: 2026-03-20
+Last updated: 2026-04-06
 
 ## Hub daemon status
 
@@ -207,9 +207,9 @@ Where to inspect:
 
 Transcript controls checklist:
 
-1. Default behavior is exhaustive chain-on (`enableYtdlpAudioAsr=true`, `enableApify=true`, `enableBrowserFallback=true`).
+1. Default behavior is public-first (`enableYtdlpAudioAsr=true`, `enableApify=true`, `enableBrowserFallback=false`).
 2. Mode precedence is `filters.youtube_mode > providers.transcript.modeDefault > auto`; no new CLI mode flag is added in this phase.
-3. Keep the progressive fallback chain enabled for non-forced modes: `youtubei -> native_caption_parse -> ytdlp_audio_asr -> apify`.
+3. Keep the progressive resolver chain enabled for non-forced modes: `youtubei -> native_caption_parse -> ytdlp_audio_asr -> apify`.
 4. Enable Apify only when all are true:
    - `providers.transcript.enableApify`
    - `providers.transcript.apifyActorId` is configured
@@ -220,7 +220,8 @@ Transcript controls checklist:
 7. Enable browser fallback only when all are true:
    - `providers.transcript.enableBrowserFallback`
    - `providers.antiBotPolicy.allowBrowserEscalation`
-8. If `env_limited` appears for browser fallback, disable browser fallback and continue with deterministic resolver strategies.
+8. If browser fallback is enabled, use an isolated automation profile instead of a daily logged-in Google profile.
+9. If `env_limited` appears for browser fallback, disable browser fallback and continue with deterministic resolver strategies.
 
 Strategy-specific quick checks:
 
@@ -237,6 +238,13 @@ Strategy-specific quick checks:
    - confirm `APIFY_TOKEN` and legal approval for `apify`
 5. `transcript_strategy_detail=browser_assisted` failures:
    - verify browser escalation policy and fallback enablement settings
+   - rerun in an isolated automation profile before treating the failure as a resolver regression
+
+### Shopping region trust quick check
+
+1. Treat `--region` as advisory unless `meta.selection.region_authoritative=true`.
+2. Inspect `meta.selection.region_support` and `meta.alerts` for `reasonCode=region_unenforced`.
+3. If `meta.primaryConstraintSummary` says the requested region was not enforced or that offers were filtered by the currency heuristic, do not present the run as a trustworthy regional comparison.
 
 Reliability promotion and rollback criteria:
 

skills/opendevbrowser-best-practices/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: opendevbrowser-best-practices
 description: This skill should be used when the user asks to design or run OpenDevBrowser provider workflows, scraping pipelines, QA/debug automation, parity checks across modes, or resilient browser operations with codified scripts and artifacts.
-version: 2.5.0
+version: 2.6.0
 ---
 
 # OpenDevBrowser Best Practices
@@ -78,6 +78,51 @@ npx opendevbrowser help
 ./skills/opendevbrowser-design-agent/scripts/design-workflow.sh contract-first
 ```
 
+## Validated Capability Lanes
+
+Load this section directly with:
+
+```text
+opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"
+```
+
+Current reliable lanes from the April 6 validation pass:
+
+1. Public-first YouTube transcript retrieval.
+
+```bash
+node scripts/youtube-transcript-live-probe.mjs --url "https://www.youtube.com/watch?v=aircAruvnKk" --youtube-mode auto --out artifacts/capability-fix/youtube-transcript-auto.json
+```
+
+Rules:
+- keep transcript runs public-first
+- 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.
+
+```bash
+npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --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`
+
+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
+```
+
+Rules:
+- use explicit providers plus `--browser-mode managed` for the most reproducible reruns
+- treat `--region` as advisory unless `meta.selection.region_authoritative=true`
+- inspect `meta.primaryConstraintSummary` and `meta.offerFilterDiagnostics` before calling a no-offer run a provider outage
+
 ## Agent Sync Targets
 
 Skill-pack installation and discovery are synchronized for:
@@ -193,6 +238,7 @@ Use the router script to avoid retyping flows:
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-preflight
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-feedback-eval
 ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh skill-runtime-audit
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh validated-capabilities
 ```
 
 ## Modes and Surface Parity

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

@@ -15,6 +15,8 @@ render_cli_prefix() {
 }
 
 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_help() {
   cat <<'EOF'
@@ -34,6 +36,7 @@ Workflows:
   parity-check
   release-direct-gates
   skill-runtime-audit
+  validated-capabilities
   surface-audit
   ops-channel-check
   cdp-channel-check
@@ -149,10 +152,14 @@ EOF
     cat <<'EOF'
 npm run build
 node scripts/docs-drift-check.mjs
+# Discovery, lifecycle, and help parity
 npm run test -- tests/skill-loader.test.ts tests/skill-list-tool.test.ts tests/cli-skills-installer.test.ts
 npm run test -- tests/cli-help.test.ts tests/cli-help-parity.test.ts tests/skill-runtime-audit.test.ts tests/skill-workflow-packs.test.ts
 npx opendevbrowser --help
 npx opendevbrowser help
+WORKDIR=$(mktemp -d /tmp/odb-skill-audit-XXXXXX)
+OPENCODE_CONFIG_DIR="$WORKDIR/config" CODEX_HOME="$WORKDIR/codex-home" CLAUDECODE_HOME="$WORKDIR/claude-home" AMP_CLI_HOME="$WORKDIR/amp-home" npx opendevbrowser --global --full --no-prompt
+OPENCODE_CONFIG_DIR="$WORKDIR/config" CODEX_HOME="$WORKDIR/codex-home" CLAUDECODE_HOME="$WORKDIR/claude-home" AMP_CLI_HOME="$WORKDIR/amp-home" npx opendevbrowser --uninstall --global --no-prompt
 ./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh
 ./skills/opendevbrowser-continuity-ledger/scripts/validate-skill-assets.sh
@@ -165,6 +172,22 @@ npx opendevbrowser help
 ./skills/opendevbrowser-shopping/scripts/validate-skill-assets.sh
 node scripts/skill-runtime-audit.mjs --smoke --out artifacts/skill-runtime-audit/smoke.json
 node scripts/skill-runtime-audit.mjs --out artifacts/skill-runtime-audit/full.json
+EOF
+    ;;
+  validated-capabilities)
+    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
+
+# 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
+
+# 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
+$CLI_PREFIX shopping run --query "27 inch 4k monitor" --providers shopping/bestbuy,shopping/ebay --budget 350 --sort lowest_price --browser-mode managed --mode json --output-format json
+
+# 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
     ;;
   surface-audit)