opendevbrowser 0.0.15 → 0.0.16

package/scripts/native/install.ps1

@@ -0,0 +1,73 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [string]$ExtensionId
+)
+
+if ([string]::IsNullOrWhiteSpace($ExtensionId)) {
+  Write-Error "Usage: install.ps1 <extension-id>"
+  exit 2
+}
+
+if ($ExtensionId -notmatch "^[a-p]{32}$") {
+  Write-Error "Invalid extension ID format. Expected 32 characters (a-p)."
+  exit 2
+}
+
+$localAppData = $env:LOCALAPPDATA
+if (-not $localAppData -and $env:USERPROFILE) {
+  $localAppData = Join-Path $env:USERPROFILE "AppData\\Local"
+}
+if (-not $localAppData) {
+  Write-Error "LOCALAPPDATA is not set. Unable to locate NativeMessagingHosts directory."
+  exit 3
+}
+
+$manifestDir = Join-Path $localAppData "Google\\Chrome\\User Data\\NativeMessagingHosts"
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$hostScript = Join-Path $scriptDir "host.cjs"
+
+if (-not (Test-Path $hostScript)) {
+  Write-Error "Native host script not found at $hostScript"
+  exit 4
+}
+
+$nodePath = (Get-Command node -ErrorAction SilentlyContinue).Source
+if (-not $nodePath) {
+  $candidates = @(
+    "C:\\Program Files\\nodejs\\node.exe",
+    "C:\\Program Files (x86)\\nodejs\\node.exe"
+  )
+  foreach ($candidate in $candidates) {
+    if (Test-Path $candidate) {
+      $nodePath = $candidate
+      break
+    }
+  }
+}
+if (-not $nodePath) {
+  Write-Error "Node.js not found in PATH."
+  exit 4
+}
+
+New-Item -ItemType Directory -Path $manifestDir -Force | Out-Null
+
+$wrapperPath = Join-Path $manifestDir "com.opendevbrowser.native.cmd"
+$wrapperContent = "@echo off`r`n""$nodePath"" ""$hostScript""`r`n"
+Set-Content -Path $wrapperPath -Value $wrapperContent -Encoding ASCII
+
+$manifestPath = Join-Path $manifestDir "com.opendevbrowser.native.json"
+$manifest = @{
+  name = "com.opendevbrowser.native"
+  description = "OpenDevBrowser native messaging host"
+  path = $wrapperPath
+  type = "stdio"
+  allowed_origins = @("chrome-extension://$ExtensionId/")
+} | ConvertTo-Json -Depth 3
+
+Set-Content -Path $manifestPath -Value $manifest -Encoding ASCII
+
+$regPath = "HKCU:\\Software\\Google\\Chrome\\NativeMessagingHosts\\com.opendevbrowser.native"
+New-Item -Path $regPath -Force | Out-Null
+New-ItemProperty -Path $regPath -Name "(Default)" -Value $manifestPath -PropertyType String -Force | Out-Null
+
+Write-Output "Native host installed at $manifestPath"

package/scripts/native/install.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+EXTENSION_ID="${1:-}"
+if [[ -z "${EXTENSION_ID}" ]]; then
+  echo "Usage: install.sh <extension-id>" >&2
+  exit 2
+fi
+
+if [[ ! "${EXTENSION_ID}" =~ ^[a-p]{32}$ ]]; then
+  echo "Invalid extension ID format. Expected 32 characters (a-p)." >&2
+  exit 2
+fi
+
+OS="$(uname -s)"
+if [[ "${OS}" == "Darwin" ]]; then
+  MANIFEST_DIR="${HOME}/Library/Application Support/Google/Chrome/NativeMessagingHosts"
+elif [[ "${OS}" == "Linux" ]]; then
+  MANIFEST_DIR="${HOME}/.config/google-chrome/NativeMessagingHosts"
+else
+  echo "Unsupported platform: ${OS}" >&2
+  exit 3
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOST_SCRIPT="${SCRIPT_DIR}/host.cjs"
+if [[ ! -f "${HOST_SCRIPT}" ]]; then
+  echo "Native host script not found at ${HOST_SCRIPT}" >&2
+  exit 4
+fi
+
+NODE_PATH="$(command -v node || true)"
+if [[ -z "${NODE_PATH}" && "${OS}" == "Darwin" ]]; then
+  if [[ -x "/opt/homebrew/bin/node" ]]; then
+    NODE_PATH="/opt/homebrew/bin/node"
+  elif [[ -x "/usr/local/bin/node" ]]; then
+    NODE_PATH="/usr/local/bin/node"
+  fi
+fi
+if [[ -z "${NODE_PATH}" ]]; then
+  echo "Node.js not found in PATH." >&2
+  exit 4
+fi
+
+mkdir -p "${MANIFEST_DIR}"
+
+WRAPPER_PATH="${MANIFEST_DIR}/com.opendevbrowser.native.sh"
+cat > "${WRAPPER_PATH}" <<EOF
+#!/usr/bin/env bash
+exec "${NODE_PATH}" "${HOST_SCRIPT}"
+EOF
+chmod 0755 "${WRAPPER_PATH}"
+
+MANIFEST_PATH="${MANIFEST_DIR}/com.opendevbrowser.native.json"
+cat > "${MANIFEST_PATH}" <<EOF
+{
+  "name": "com.opendevbrowser.native",
+  "description": "OpenDevBrowser native messaging host",
+  "path": "${WRAPPER_PATH}",
+  "type": "stdio",
+  "allowed_origins": ["chrome-extension://${EXTENSION_ID}/"]
+}
+EOF
+chmod 0644 "${MANIFEST_PATH}"
+
+echo "Native host installed at ${MANIFEST_PATH}"

package/scripts/native/uninstall.ps1

@@ -0,0 +1,25 @@
+$localAppData = $env:LOCALAPPDATA
+if (-not $localAppData -and $env:USERPROFILE) {
+  $localAppData = Join-Path $env:USERPROFILE "AppData\\Local"
+}
+if (-not $localAppData) {
+  Write-Error "LOCALAPPDATA is not set. Unable to locate NativeMessagingHosts directory."
+  exit 3
+}
+
+$manifestDir = Join-Path $localAppData "Google\\Chrome\\User Data\\NativeMessagingHosts"
+$manifestPath = Join-Path $manifestDir "com.opendevbrowser.native.json"
+$wrapperPath = Join-Path $manifestDir "com.opendevbrowser.native.cmd"
+
+Remove-Item -Path $manifestPath -Force -ErrorAction SilentlyContinue | Out-Null
+Remove-Item -Path $wrapperPath -Force -ErrorAction SilentlyContinue | Out-Null
+
+$regPath = "HKCU:\\Software\\Google\\Chrome\\NativeMessagingHosts\\com.opendevbrowser.native"
+Remove-Item -Path $regPath -Recurse -Force -ErrorAction SilentlyContinue | Out-Null
+
+$tempDir = [System.IO.Path]::GetTempPath()
+Get-ChildItem -Path $tempDir -Filter "opendevbrowser-*.token" -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
+Get-ChildItem -Path $tempDir -Filter "opendevbrowser-*.sock" -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
+Remove-Item -Path (Join-Path $tempDir "opendevbrowser-native.log") -Force -ErrorAction SilentlyContinue | Out-Null
+
+Write-Output "Native host uninstalled."

package/scripts/native/uninstall.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OS="$(uname -s)"
+if [[ "${OS}" == "Darwin" ]]; then
+  MANIFEST_DIR="${HOME}/Library/Application Support/Google/Chrome/NativeMessagingHosts"
+elif [[ "${OS}" == "Linux" ]]; then
+  MANIFEST_DIR="${HOME}/.config/google-chrome/NativeMessagingHosts"
+else
+  echo "Unsupported platform: ${OS}" >&2
+  exit 3
+fi
+
+MANIFEST_PATH="${MANIFEST_DIR}/com.opendevbrowser.native.json"
+WRAPPER_PATH="${MANIFEST_DIR}/com.opendevbrowser.native.sh"
+
+if [[ -f "${MANIFEST_PATH}" ]]; then
+  rm -f "${MANIFEST_PATH}"
+fi
+if [[ -f "${WRAPPER_PATH}" ]]; then
+  rm -f "${WRAPPER_PATH}"
+fi
+
+rm -f /tmp/opendevbrowser-*.sock /tmp/opendevbrowser-*.token 2>/dev/null || true
+
+echo "Native host uninstalled."

package/skills/AGENTS.md

@@ -1,16 +1,19 @@
 # skills/ — Agent Guidelines
 
-Bundled skill packs. Extends root `AGENTS.md`.
+Bundled canonical skill packs (8 total). Extends root `AGENTS.md`.
 
 ## Structure
 
 ```
 skills/
-├── opendevbrowser-best-practices/SKILL.md   # Core prompting guide
+├── opendevbrowser-best-practices/SKILL.md
 ├── opendevbrowser-continuity-ledger/SKILL.md
-├── login-automation/SKILL.md
-├── form-testing/SKILL.md
-└── data-extraction/SKILL.md
+├── opendevbrowser-login-automation/SKILL.md
+├── opendevbrowser-form-testing/SKILL.md
+├── opendevbrowser-data-extraction/SKILL.md
+├── opendevbrowser-research/SKILL.md
+├── opendevbrowser-shopping/SKILL.md
+└── opendevbrowser-product-presentation-asset/SKILL.md
 ```
 
 ## SKILL.md Format
@@ -32,9 +35,13 @@ Content organized by topic for filtering.
 
 1. `.opencode/skill/` (project-local)
 2. `~/.config/opencode/skill/` (global)
-3. `.claude/skills/` (compatibility)
-4. `~/.claude/skills/` (compatibility)
-5. `skillPaths` config (custom)
+3. `.codex/skills/` (project compatibility)
+4. `$CODEX_HOME/skills` (global compatibility; fallback `~/.codex/skills`)
+5. `.claude/skills/` (ClaudeCode project compatibility)
+6. `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (ClaudeCode global compatibility; fallback `~/.claude/skills`)
+7. `.amp/skills/` (AmpCLI project compatibility)
+8. `$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` (AmpCLI global compatibility; fallback `~/.amp/skills`)
+9. `skillPaths` config (custom)
 
 ## Constraints
 
@@ -42,9 +49,11 @@ Content organized by topic for filtering.
 - Keep guidance short, script-first, snapshot-first
 - Examples must use `opendevbrowser_*` tool names
 - Never include secrets or page data in content
+- Keep canonical guidance in `opendevbrowser-*` packs; do not add legacy alias directories.
 - Match the snapshot → refs → actions flow in `docs/ARCHITECTURE.md` and tool list in `docs/CLI.md`.
 - Note that extension relay requires Chrome 125+ and uses hub-only relay ownership when enabled.
 - Refer to root `AGENTS.md` for connection flag/status semantics (extensionConnected, handshake, cdpConnected, pairingRequired).
+- Keep skill operational guidance aligned with release-gate scripts in `docs/CLI.md` (`provider-live-matrix --release-gate`, `live-regression-matrix --release-gate`).
 
 ## Adding Skills
 

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

@@ -1,122 +1,228 @@
 ---
 name: opendevbrowser-best-practices
-description: This skill should be used when the user asks to "automate a browser flow", "write an OpenDevBrowser script", "use snapshot refs", "extract page content", or "debug browser automation".
-version: 1.1.0
+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.3.0
 ---
 
 # OpenDevBrowser Best Practices
 
-Use this guide to produce reliable, script-first automation with minimal retries and predictable output.
+This is the primary battery pack for OpenDevBrowser operations.
+
+Use this skill when you need:
+- provider-oriented workflows (`web`, `community`, `social`),
+- script-first runbooks,
+- parity across `managed`, `extension`, `cdpConnect`,
+- diagnostics for QA/debug (`console`, `network`, trace context),
+- safe write flows with explicit policy notice.
+
+## Pack Contents
+
+- `artifacts/provider-workflows.md` — canonical provider execution flows.
+- `artifacts/parity-gates.md` — mode/surface parity matrix and acceptance gates.
+- `artifacts/debug-trace-playbook.md` — diagnostics workflow and trace bundle model.
+- `artifacts/fingerprint-tiers.md` — hardening tiers and when to use each.
+- `artifacts/macro-workflows.md` — macro design and expansion standards.
+- `artifacts/browser-agent-known-issues-matrix.md` — known browser-agent failure modes mapped to required controls.
+- `artifacts/command-channel-reference.md` — CLI/tool/`/ops`/`/cdp` surface map plus cross-agent skill-sync targets.
+- `assets/templates/mode-flag-matrix.json` — mode + flag verification template.
+- `assets/templates/ops-request-envelope.json` — `/ops` request envelope template.
+- `assets/templates/cdp-forward-envelope.json` — `/cdp` relay envelope template.
+- `assets/templates/robustness-checklist.json` — shared issue-status checklist for workflow robustness audits.
+- `assets/templates/surface-audit-checklist.json` — docs/surface audit checklist template.
+- `scripts/odb-workflow.sh` — prints codified command sequences by workflow.
+- `scripts/run-robustness-audit.sh` — validates workflow skill coverage against known issue IDs.
+- `scripts/validate-skill-assets.sh` — validates required artifacts/templates.
+
+## Fast Start
+
+1. Validate the skill pack:
+
+```bash
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+```
 
-## Core Operating Model
+2. Pick a workflow:
 
-Follow the loop strictly:
+```bash
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-crawl
+```
 
-1. Establish or attach a session.
-2. Capture `opendevbrowser_snapshot`.
-3. Select refs from that snapshot.
-4. Execute one or more actions using refs.
-5. Re-snapshot after navigation or major DOM change.
+3. Execute the printed sequence with session-specific values.
 
-Prefer refs over raw selectors. Refs are more stable across dynamic UI changes.
+4. Surface full controls directly from CLI help when auditing runtime accessibility:
 
-## Session Strategy
+```bash
+npx opendevbrowser --help
+```
 
-Choose mode deliberately:
+5. Run robustness coverage checks across workflow skills:
 
-- Use managed mode for deterministic, isolated runs.
-- Use extension mode when existing logged-in tabs or profile state are required.
-- Use CDP connect mode only when attaching to a pre-launched browser is required.
+```bash
+./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh
+```
 
-Example launch patterns:
+## Agent Sync Targets
 
-```text
-opendevbrowser_launch noExtension=true
-opendevbrowser_launch waitForExtension=true
-opendevbrowser_connect wsEndpoint="ws://127.0.0.1:9222/devtools/browser/<id>"
-```
+Skill-pack installation and discovery are synchronized for:
+- `opencode` (`~/.config/opencode/skill`, project `./.opencode/skill`)
+- `codex` (`$CODEX_HOME/skills` fallback `~/.codex/skills`, project `./.codex/skills`)
+- `claudecode` (`$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` fallback `~/.claude/skills`, project `./.claude/skills`)
+- `ampcli` (`$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` fallback `~/.amp/skills`, project `./.amp/skills`)
+
+Legacy compatibility aliases `claude` and `amp` are preserved in installer target metadata.
+
+## Required Operating Rules
+
+- Prefer refs from `opendevbrowser_snapshot` over raw selectors.
+- Use one action per decision loop: snapshot -> action -> snapshot.
+- Keep a single correlation context (`requestId`, `sessionId`) across a run.
+- Run the same workflow shape across all three modes before claiming parity.
+- Default to read/research workflows. Social posting probes remain disabled unless explicitly requested via matrix opt-in (`--include-social-posts`).
+- Apply rate-limit/backoff discipline (`Retry-After` aware) whenever 429 pressure appears.
+- Re-check extension readiness on resume when a run crosses idle windows.
+
+## Parallel Operations (Reliable As-Is)
 
-## Snapshot Discipline
+- Safe parallelism today is `session-per-worker` (one session per page/tab command stream).
+- Keep each session single-writer for target/page actions; run commands serially inside that session.
+- Do not run independent concurrent streams that alternate `target-use` within one session.
+- Use default extension `/ops` for relay-backed concurrency; use `/cdp` only for legacy compatibility paths.
+- For managed parallel runs with persisted profiles, use unique profile paths per session (or disable persistence) to avoid profile lock collisions.
+- Treat extension headless attempts (`--extension-only --headless`) as expected `unsupported_mode`; route headless workloads through managed/cdpConnect instead.
+- Before extension-mode runs, preflight `npx opendevbrowser status --daemon` and require `extensionConnected=true` plus `extensionHandshakeComplete=true`.
 
-Capture snapshots in the format needed by the current task:
+Operational references:
+- `artifacts/provider-workflows.md` (see Workflow E)
+- `scripts/odb-workflow.sh parallel-multipage-safe`
+- `docs/CLI.md` (concurrency semantics)
+- `docs/SURFACE_REFERENCE.md` (transport and policy constraints)
+- `docs/TROUBLESHOOTING.md` (parallel crosstalk and profile-lock remediation)
 
-- Use `format="outline"` for broad page state.
-- Use `format="actionables"` for interaction planning.
-- Use `maxChars` and `cursor` to page large pages instead of requesting oversized snapshots.
+## Known-Issue Robustness Baseline
+
+- Source matrix: `artifacts/browser-agent-known-issues-matrix.md`
+- Reusable checklist: `assets/templates/robustness-checklist.json`
+- Coverage validator: `scripts/run-robustness-audit.sh`
+
+Use issue IDs from the matrix in each workflow skill (`ISSUE-01` ... `ISSUE-12`) so robustness checks stay machine-verifiable and DRY.
+
+## Provider Workflows (Codified)
+
+### Provider Search Workflow
+
+Goal: deterministic query + extraction from one provider.
 
 ```text
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<provider-search-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
 opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+# extract targeted results using refs
+opendevbrowser_network_poll sessionId="<session-id>" max=50
 ```
 
-## Action Sequencing
-
-Stabilize before interacting:
+### Provider Crawl Workflow
 
-- After `goto` or click-driven navigation, run `opendevbrowser_wait`.
-- Wait on `until="networkidle"` for API-heavy pages.
-- Wait on `ref` + `state` for specific element readiness.
+Goal: multipage fetch + extraction with bounded depth.
 
 ```text
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<seed-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+# capture links/data, enqueue next pages in host logic
+opendevbrowser_scroll sessionId="<session-id>" dy=1000
 opendevbrowser_wait sessionId="<session-id>" until="networkidle"
-opendevbrowser_wait sessionId="<session-id>" ref="<target-ref>" state="visible"
 ```
 
-For multi-step interactions, batch deterministic steps with `opendevbrowser_run`.
+### QA Debug Workflow
+
+Goal: isolate frontend regressions quickly.
 
 ```text
-opendevbrowser_run sessionId="<session-id>" steps=[{"action":"goto","args":{"url":"https://example.com"}},{"action":"wait","args":{"until":"networkidle"}},{"action":"snapshot","args":{"format":"actionables"}}]
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+opendevbrowser_console_poll sessionId="<session-id>" max=100
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+opendevbrowser_screenshot sessionId="<session-id>"
 ```
 
-## Extraction and Output Control
+### Read-Only Social Validation Workflow
 
-Keep output scoped and cheap:
+Goal: validate authenticated read/search capability without posting.
 
-- Extract only the needed node text with `opendevbrowser_dom_get_text`.
-- Use `opendevbrowser_dom_get_html` only for small targeted fragments.
-- Use `opendevbrowser_get_attr` and `opendevbrowser_get_value` for structured field data.
+1. Connect and verify extension readiness (`extensionConnected` + handshake).
+2. Navigate/search target social surface.
+3. Capture `debug-trace-snapshot` and `network-poll` evidence.
+4. Record blocker/auth status only (no write action).
 
-```text
-opendevbrowser_dom_get_text sessionId="<session-id>" ref="<content-ref>"
-opendevbrowser_get_attr sessionId="<session-id>" ref="<input-ref>" name="aria-invalid"
+## Workflow Router Script
+
+Use the router script to avoid retyping flows:
+
+```bash
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-search
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-crawl
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh qa-debug
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh social-readonly-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh parity-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh surface-audit
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh ops-channel-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh cdp-channel-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh mode-flag-matrix
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh robustness-audit
 ```
 
-## Lightweight Diagnostics
+## Modes and Surface Parity
 
-Inspect runtime behavior only when required:
+Always run acceptance on:
+- Modes: `managed`, `extension`, `cdpConnect`
+- Surfaces: tool API, CLI, daemon RPC
 
-- Use `opendevbrowser_console_poll` to detect script/runtime errors.
-- Use `opendevbrowser_network_poll` to verify request outcomes.
-- Use `opendevbrowser_screenshot` for visual debugging artifacts.
+Reference: `artifacts/parity-gates.md`
 
-```text
-opendevbrowser_console_poll sessionId="<session-id>"
-opendevbrowser_network_poll sessionId="<session-id>" max=50
+Parity gate test:
+
+```bash
+npm run test -- tests/parity-matrix.test.ts
 ```
 
-## Failure Recovery Order
+Real-world provider+mode scenario harness (soak replacement):
 
-When a step fails, recover in this order:
+```bash
+npm run build
+node scripts/provider-live-matrix.mjs --use-global-env --skip-live-regression --out artifacts/provider-live-realworld.json
+```
 
-1. Re-snapshot to refresh refs.
-2. Re-wait for load or element state.
-3. Retry action once with fresh refs.
-4. Change mode (managed vs extension) only if failure is mode-specific.
+Surface inventory source of truth:
+- `docs/SURFACE_REFERENCE.md` (55 CLI commands, 48 tools, 38 `/ops` commands, `/cdp` envelope contracts)
+- `artifacts/command-channel-reference.md` (skill-pack operational digest)
 
-Avoid blind repeated retries against stale refs.
+## Diagnostics and Traceability
 
-## Security and Safety Defaults
+Current diagnostics tools:
+- `opendevbrowser_console_poll`
+- `opendevbrowser_network_poll`
+- `opendevbrowser_debug_trace_snapshot` (combined page + console + network + exception channels)
 
-- Keep CDP and relay endpoints local-only by default.
-- Do not place secrets in scripts, skill files, or logs.
-- Prefer minimal extraction over full-page dumps when handling sensitive pages.
+Reference: `artifacts/debug-trace-playbook.md`
 
-## Ready-to-Use Flow Template
+## Fingerprint Hardening
 
-```text
-opendevbrowser_launch noExtension=true
-opendevbrowser_goto sessionId="<session-id>" url="https://example.com"
-opendevbrowser_wait sessionId="<session-id>" until="networkidle"
-opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
-# interact with refs
-opendevbrowser_snapshot sessionId="<session-id>" format="outline"
-```
+Apply the minimum tier that meets reliability goals.
+
+- Tier 0: baseline deterministic automation.
+- Tier 1: coherence profile (default recommended).
+- Tier 2: runtime hardening.
+- Tier 3: adaptive managed hardening (optional).
+
+Reference: `artifacts/fingerprint-tiers.md`
+
+## Macro Guidance
+
+Use macros as normalized entrypoints for provider workflows.
+
+- Keep macro definitions declarative and typed.
+- Expand macros to canonical provider queries.
+- Emit provenance metadata (`macro`, `resolvedQuery`, `provider`).
+
+Reference: `artifacts/macro-workflows.md`

package/skills/opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md

@@ -0,0 +1,44 @@
+# Browser Agent Known-Issues Matrix
+
+This matrix defines the minimum robustness controls for OpenDevBrowser workflow skills.
+
+## Issue Controls
+
+| ID | Known issue | Typical signals | Required controls | Evidence to capture |
+|---|---|---|---|---|
+| `ISSUE-01` | DOM churn invalidates refs | action fails after render, detached/stale element behavior, missing ref | enforce `snapshot -> one action -> snapshot`, retry once after fresh snapshot, avoid reusing refs across navigation | before/after snapshots + failing action + retry outcome |
+| `ISSUE-02` | Frame/iframe boundaries hide interactive targets | expected refs not found in top document, challenge widget rendered in iframe | detect frame context before action, route frame-specific steps, checkpoint when cross-origin challenge frame blocks continuation | snapshot outline showing frame branch + checkpoint note |
+| `ISSUE-03` | Popup/new-tab auth flows break linear scripts | click triggers new tab/popup, current tab loses focus | detect target/page changes, rebind to active auth target, verify post-auth return target | target/page list before and after auth click |
+| `ISSUE-04` | Step-up auth and session expiry alter login path | MFA/passkey prompt appears, unexpected redirect to reauth | branch login state machine explicitly, validate >=2 independent auth success signals, validate reauth policy separately | auth signal log with URL, element, network confirmation |
+| `ISSUE-05` | Anti-bot challenge loops stall automation | repeated challenge pages/widgets, repeated 403/429 around auth/submit | treat as checkpoint, never bypass, set loop budget, escalate after repeated challenge loops | challenge checkpoint log with timestamps and outcome |
+| `ISSUE-06` | Rate-limit pressure and server backoff ignored | 429 responses, throttle banners, `Retry-After` headers | stop aggressive retries, honor `Retry-After`, bounded retry budget with cooldown windows | network poll evidence with status + backoff decision |
+| `ISSUE-07` | MV3 extension service worker suspends state | extension relay disconnects after idle, handshake drop | re-check extension readiness before critical steps, include reconnect path and resumed snapshot checkpoint | daemon status (`extensionConnected`, `extensionHandshakeComplete`) before resume |
+| `ISSUE-08` | Restricted origins and policy blocks | `chrome://` / extension pages blocked, unsupported origin errors | validate URL/domain eligibility before workflow, fail fast with actionable reason | blocked-origin decision in run log |
+| `ISSUE-09` | Pagination drift and duplicate extraction | duplicate records across pages, endless loop/no page delta | canonical dedupe keys, terminal conditions, positive delta gate, checkpoint/resume metadata | pagination state + quality-gate report |
+| `ISSUE-10` | Locale/currency parsing inconsistency | mixed currency symbols, malformed numbers | normalize currency/amount explicitly, avoid cross-currency comparison without conversion context | normalized records with currency and parse confidence |
+| `ISSUE-11` | Discount anchor is weak or misleading | anchor price missing/untrusted, “sale” not below market | separate anchor discount from market discount, tag anchor confidence, require market-baseline confirmation | market analysis with anchor coverage and warnings |
+| `ISSUE-12` | Stale price or unsupported claims in presentation assets | captured price outdated, marketing claims not traceable | enforce freshness checks, claim-to-evidence mapping, block unsupported superlatives | claims-evidence map + pricing timestamp |
+
+## Skill Coverage Targets
+
+- `opendevbrowser-login-automation`: `ISSUE-01`, `ISSUE-02`, `ISSUE-03`, `ISSUE-04`, `ISSUE-05`, `ISSUE-06`, `ISSUE-07`
+- `opendevbrowser-form-testing`: `ISSUE-01`, `ISSUE-02`, `ISSUE-05`, `ISSUE-06`, `ISSUE-08`
+- `opendevbrowser-data-extraction`: `ISSUE-01`, `ISSUE-06`, `ISSUE-08`, `ISSUE-09`, `ISSUE-10`
+- `opendevbrowser-shopping`: `ISSUE-06`, `ISSUE-09`, `ISSUE-10`, `ISSUE-11`, `ISSUE-12`
+- `opendevbrowser-product-presentation-asset`: `ISSUE-10`, `ISSUE-11`, `ISSUE-12`
+- `opendevbrowser-research`: `ISSUE-06`, `ISSUE-09`, `ISSUE-10`, `ISSUE-12`
+
+## Source Notes
+
+- Playwright best practices (locator and timing stability): https://playwright.dev/docs/best-practices
+- Playwright frames guidance: https://playwright.dev/docs/frames
+- Playwright pages/popups guidance: https://playwright.dev/docs/pages
+- Chrome extension MV3 service worker lifecycle: https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle
+- HTTP 429 semantics and `Retry-After`: https://www.rfc-editor.org/rfc/rfc6585
+- OWASP Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+- WCAG 2.2 (accessible authentication): https://www.w3.org/TR/WCAG22/
+- Cloudflare Turnstile testing keys: https://developers.cloudflare.com/turnstile/tutorials/testing/
+- reCAPTCHA testing keys: https://developers.google.com/recaptcha/docs/faq
+- hCaptcha docs: https://docs.hcaptcha.com/
+- RFC 9309 robots protocol: https://www.rfc-editor.org/rfc/rfc9309
+- FTC deceptive pricing guide: https://www.ecfr.gov/current/title-16/chapter-I/subchapter-B/part-233