opendevbrowser 0.0.22 → 0.0.23

package/dist/{chunk-OGE5KJ4X.js → chunk-2MG7BRPF.js}

@@ -10,6 +10,7 @@ import {
 import {
   ChallengeOrchestrator,
   buildBlockerArtifacts,
+  buildMacroResolveSuccessHandoff,
   canonicalizeUrl,
   classifyBlockerSignal,
   createDefaultRuntime,
@@ -27,7 +28,7 @@ import {
   runResearchWorkflow,
   runShoppingWorkflow,
   toSnippet
-} from "./chunk-ZE2E7ZGH.js";
+} from "./chunk-K2TEHJCV.js";
 import {
   ProviderRuntimeError
 } from "./chunk-FUSXMW3G.js";
@@ -31375,10 +31376,17 @@ async function resolveMacroExpression(options, config, manager, browserFallbackP
     resolution = parseFallbackMacro(options.expression, options.defaultProvider);
   }
   if (!options.execute) {
+    const handoff2 = buildMacroResolveSuccessHandoff({
+      expression: options.expression,
+      defaultProvider: options.defaultProvider,
+      execute: false,
+      blocked: false
+    });
     return {
       runtime: resolvedRuntime,
       resolution,
-      ...catalog ? { catalog } : {}
+      ...catalog ? { catalog } : {},
+      ...handoff2
     };
   }
   const execution = await executeMacroWithRuntime({
@@ -31390,11 +31398,18 @@ async function resolveMacroExpression(options, config, manager, browserFallbackP
     timeoutMs: options.timeoutMs,
     challengeAutomationMode: options.challengeAutomationMode
   });
+  const handoff = buildMacroResolveSuccessHandoff({
+    expression: options.expression,
+    defaultProvider: options.defaultProvider,
+    execute: true,
+    blocked: Boolean(execution.meta.blocker)
+  });
   return {
     runtime: resolvedRuntime,
     resolution,
     ...catalog ? { catalog } : {},
-    execution
+    execution,
+    ...handoff
   };
 }
 
@@ -32442,7 +32457,7 @@ var buildAnnotateResult = async (payload) => {
 // src/public-surface/generated-manifest.ts
 var PUBLIC_SURFACE_MANIFEST = {
   "schemaVersion": "2026-04-04",
-  "generatedAt": "2026-04-20T04:16:59.279Z",
+  "generatedAt": "2026-04-20T16:29:04.426Z",
   "cli": {
     "groups": [
       {
@@ -32630,6 +32645,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--no-prompt",
           "--quiet"
         ],
+        "examples": [
+          "npx opendevbrowser install --local --with-config --skills-local"
+        ],
+        "notes": [],
         "groupId": "install_lifecycle",
         "groupTitle": "Install & Lifecycle",
         "groupSummary": "Install, remove, and inspect CLI basics."
@@ -32645,6 +32664,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--skills-local",
           "--no-skills"
         ],
+        "examples": [
+          "npx opendevbrowser update --local --skills-local"
+        ],
+        "notes": [],
         "groupId": "install_lifecycle",
         "groupTitle": "Install & Lifecycle",
         "groupSummary": "Install, remove, and inspect CLI basics."
@@ -32660,6 +32683,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--no-prompt",
           "--quiet"
         ],
+        "examples": [
+          "npx opendevbrowser uninstall --local --no-skills --no-prompt"
+        ],
+        "notes": [],
         "groupId": "install_lifecycle",
         "groupTitle": "Install & Lifecycle",
         "groupSummary": "Install, remove, and inspect CLI basics."
@@ -32671,6 +32698,12 @@ var PUBLIC_SURFACE_MANIFEST = {
         "flags": [
           "--help"
         ],
+        "examples": [
+          "npx opendevbrowser --help"
+        ],
+        "notes": [
+          "Generated help is the canonical first-contact discovery surface and should stay source-owned."
+        ],
         "groupId": "install_lifecycle",
         "groupTitle": "Install & Lifecycle",
         "groupSummary": "Install, remove, and inspect CLI basics."
@@ -32682,6 +32715,10 @@ var PUBLIC_SURFACE_MANIFEST = {
         "flags": [
           "--version"
         ],
+        "examples": [
+          "npx opendevbrowser --version"
+        ],
+        "notes": [],
         "groupId": "install_lifecycle",
         "groupTitle": "Install & Lifecycle",
         "groupSummary": "Install, remove, and inspect CLI basics."
@@ -32695,6 +32732,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--token",
           "--stop"
         ],
+        "examples": [
+          "npx opendevbrowser serve --port 8788 --token local-dev-token"
+        ],
+        "notes": [],
         "groupId": "daemon_runtime",
         "groupTitle": "Daemon & Runtime",
         "groupSummary": "Run daemon services and single-process scripts."
@@ -32706,6 +32747,10 @@ var PUBLIC_SURFACE_MANIFEST = {
         "flags": [
           "--output-format"
         ],
+        "examples": [
+          "npx opendevbrowser daemon status --output-format json"
+        ],
+        "notes": [],
         "groupId": "daemon_runtime",
         "groupTitle": "Daemon & Runtime",
         "groupSummary": "Run daemon services and single-process scripts."
@@ -32717,6 +32762,10 @@ var PUBLIC_SURFACE_MANIFEST = {
         "flags": [
           "--output-format"
         ],
+        "examples": [
+          "npx opendevbrowser native status --output-format json"
+        ],
+        "notes": [],
         "groupId": "daemon_runtime",
         "groupTitle": "Daemon & Runtime",
         "groupSummary": "Run daemon services and single-process scripts."
@@ -32734,6 +32783,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--start-url",
           "--flag"
         ],
+        "examples": [
+          "npx opendevbrowser run --script ./workflow.json --headless --output-format json"
+        ],
+        "notes": [
+          "One-shot run uses a temporary profile unless --persist-profile is explicitly enabled."
+        ],
         "groupId": "daemon_runtime",
         "groupTitle": "Daemon & Runtime",
         "groupSummary": "Run daemon services and single-process scripts."
@@ -32755,6 +32810,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--wait-for-extension",
           "--wait-timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser launch --no-extension --headless --start-url https://example.com --output-format json"
+        ],
+        "notes": [
+          "Use --wait-for-extension when you need a clean daemon-extension handshake before the next step."
+        ],
         "groupId": "session_lifecycle",
         "groupTitle": "Session Lifecycle",
         "groupSummary": "Launch, connect, and manage browser session state."
@@ -32770,6 +32831,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--start-url",
           "--extension-legacy"
         ],
+        "examples": [
+          "npx opendevbrowser connect --host 127.0.0.1 --cdp-port 9222 --output-format json"
+        ],
+        "notes": [],
         "groupId": "session_lifecycle",
         "groupTitle": "Session Lifecycle",
         "groupSummary": "Launch, connect, and manage browser session state."
@@ -32782,6 +32847,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--close-browser"
         ],
+        "examples": [
+          "npx opendevbrowser disconnect --session-id s1 --close-browser --output-format json"
+        ],
+        "notes": [],
         "groupId": "session_lifecycle",
         "groupTitle": "Session Lifecycle",
         "groupSummary": "Launch, connect, and manage browser session state."
@@ -32795,6 +32864,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--daemon",
           "--transport"
         ],
+        "examples": [
+          "npx opendevbrowser status --daemon --output-format json"
+        ],
+        "notes": [],
         "groupId": "session_lifecycle",
         "groupTitle": "Session Lifecycle",
         "groupSummary": "Launch, connect, and manage browser session state."
@@ -32809,6 +32882,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--challenge-automation-mode",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser status-capabilities --session-id s1 --target-id page-1 --challenge-automation-mode browser --timeout-ms 30000 --output-format json"
+        ],
+        "notes": [],
         "groupId": "session_lifecycle",
         "groupTitle": "Session Lifecycle",
         "groupSummary": "Launch, connect, and manage browser session state."
@@ -32823,6 +32900,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--cookies-file",
           "--strict"
         ],
+        "examples": [
+          "npx opendevbrowser cookie-import --session-id s1 --cookies-file ./cookies.json --strict true --output-format json"
+        ],
+        "notes": [],
         "groupId": "session_lifecycle",
         "groupTitle": "Session Lifecycle",
         "groupSummary": "Launch, connect, and manage browser session state."
@@ -32835,6 +32916,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--url"
         ],
+        "examples": [
+          "npx opendevbrowser cookie-list --session-id s1 --url https://example.com --output-format json"
+        ],
+        "notes": [],
         "groupId": "session_lifecycle",
         "groupTitle": "Session Lifecycle",
         "groupSummary": "Launch, connect, and manage browser session state."
@@ -32861,6 +32946,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--cookie-policy-override",
           "--cookie-policy"
         ],
+        "examples": [
+          'npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --mode json --output-format json'
+        ],
+        "notes": [
+          "Generic topical research is currently safest with --source-selection auto; add shopping only for deliberate commercial comparison."
+        ],
         "groupId": "provider_workflows",
         "groupTitle": "Provider Workflows",
         "groupSummary": "Run research, shopping, media, and artifact workflows."
@@ -32885,6 +32976,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--cookie-policy-override",
           "--cookie-policy"
         ],
+        "examples": [
+          'npx opendevbrowser shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json'
+        ],
+        "notes": [
+          "Treat --region as advisory unless the workflow output reports region_authoritative=true."
+        ],
         "groupId": "provider_workflows",
         "groupTitle": "Provider Workflows",
         "groupSummary": "Run research, shopping, media, and artifact workflows."
@@ -32908,6 +33005,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--output-dir",
           "--ttl-hours"
         ],
+        "examples": [
+          'npx opendevbrowser product-video run --product-url "https://example.com/p/1" --include-screenshots --output-format json'
+        ],
+        "notes": [
+          "Confirm whether the returned pack is visual-ready or metadata-first before briefing production."
+        ],
         "groupId": "provider_workflows",
         "groupTitle": "Provider Workflows",
         "groupSummary": "Run research, shopping, media, and artifact workflows."
@@ -32930,6 +33033,13 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--cookie-policy-override",
           "--cookie-policy"
         ],
+        "examples": [
+          'npx opendevbrowser inspiredesign run --brief "Extract a reusable dashboard design contract from live references" --url https://linear.app --capture-mode deep --include-prototype-guidance --output-dir /tmp/inspiredesign --output-format json'
+        ],
+        "notes": [
+          "--capture-mode defaults to off; opt into deep only when live DOM or layout evidence is required.",
+          "Repeat --url for multiple references. There is no --urls alias."
+        ],
         "groupId": "provider_workflows",
         "groupTitle": "Provider Workflows",
         "groupSummary": "Run research, shopping, media, and artifact workflows."
@@ -32942,6 +33052,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--expired-only",
           "--output-dir"
         ],
+        "examples": [
+          "npx opendevbrowser artifacts cleanup --expired-only --output-dir /tmp/opendevbrowser --output-format json"
+        ],
+        "notes": [],
         "groupId": "provider_workflows",
         "groupTitle": "Provider Workflows",
         "groupSummary": "Run research, shopping, media, and artifact workflows."
@@ -32958,6 +33072,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--timeout-ms",
           "--challenge-automation-mode"
         ],
+        "examples": [
+          `npx opendevbrowser macro-resolve --expression '@community.search("browser automation failures", 4)' --execute --challenge-automation-mode browser --output-format json`
+        ],
+        "notes": [
+          "When --execute is enabled, inspect execution.meta.blocker before trusting a blocked result as complete."
+        ],
         "groupId": "provider_workflows",
         "groupTitle": "Provider Workflows",
         "groupSummary": "Run research, shopping, media, and artifact workflows."
@@ -32972,6 +33092,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--params-file",
           "--timeout-ms"
         ],
+        "examples": [
+          `npx opendevbrowser canvas --command canvas.session.open --params '{"label":"design review"}' --timeout-ms 120000 --output-format json`
+        ],
+        "notes": [
+          "Use --params-file for strict request envelopes such as canvas.plan.set or governance handoff payloads."
+        ],
         "groupId": "design_canvas",
         "groupTitle": "Design Canvas",
         "groupSummary": "Execute typed /canvas commands for session, document, preview, and code-sync flows."
@@ -32986,6 +33112,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--wait-until",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser goto --session-id s1 --url https://example.com --wait-until networkidle --output-format json"
+        ],
+        "notes": [],
         "groupId": "navigation",
         "groupTitle": "Navigation",
         "groupSummary": "Move through pages and capture fresh refs."
@@ -33001,6 +33131,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--until",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser wait --session-id s1 --state networkidle --timeout-ms 30000 --output-format json"
+        ],
+        "notes": [],
         "groupId": "navigation",
         "groupTitle": "Navigation",
         "groupSummary": "Move through pages and capture fresh refs."
@@ -33016,6 +33150,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--cursor",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser snapshot --session-id s1 --mode actionables --max-chars 4000 --output-format json"
+        ],
+        "notes": [],
         "groupId": "navigation",
         "groupTitle": "Navigation",
         "groupSummary": "Move through pages and capture fresh refs."
@@ -33031,6 +33169,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--cursor",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser review --session-id s1 --target-id page-1 --output-format json"
+        ],
+        "notes": [],
         "groupId": "navigation",
         "groupTitle": "Navigation",
         "groupSummary": "Move through pages and capture fresh refs."
@@ -33047,6 +33189,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--cursor",
           "--timeout-ms"
         ],
+        "examples": [
+          'npx opendevbrowser review-desktop --session-id s1 --reason "trace challenge state" --output-format json'
+        ],
+        "notes": [],
         "groupId": "navigation",
         "groupTitle": "Navigation",
         "groupSummary": "Move through pages and capture fresh refs."
@@ -33061,6 +33207,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--target-id",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser click --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33073,6 +33223,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser hover --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33086,6 +33240,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--key",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser press --session-id s1 --key Enter --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33098,6 +33256,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser check --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33110,6 +33272,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser uncheck --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33125,6 +33291,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--clear",
           "--submit"
         ],
+        "examples": [
+          'npx opendevbrowser type --session-id s1 --ref r12 --text "agent@example.com" --clear --output-format json'
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33138,6 +33308,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--ref",
           "--values"
         ],
+        "examples": [
+          "npx opendevbrowser select --session-id s1 --ref r12 --values us,ca --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33151,6 +33325,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--dy",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser scroll --session-id s1 --dy 1000 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33163,6 +33341,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser scroll-into-view --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33177,6 +33359,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--files",
           "--target-id"
         ],
+        "examples": [
+          "npx opendevbrowser upload --session-id s1 --ref r12 --files ./draft.pdf,./hero.png --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33192,6 +33378,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--steps",
           "--target-id"
         ],
+        "examples": [
+          "npx opendevbrowser pointer-move --session-id s1 --x 320 --y 240 --steps 12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33208,6 +33398,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--click-count",
           "--target-id"
         ],
+        "examples": [
+          "npx opendevbrowser pointer-down --session-id s1 --x 320 --y 240 --button left --click-count 1 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33224,6 +33418,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--click-count",
           "--target-id"
         ],
+        "examples": [
+          "npx opendevbrowser pointer-up --session-id s1 --x 320 --y 240 --button left --click-count 1 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33241,6 +33439,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--steps",
           "--target-id"
         ],
+        "examples": [
+          "npx opendevbrowser pointer-drag --session-id s1 --from-x 320 --from-y 240 --to-x 640 --to-y 240 --steps 18 --output-format json"
+        ],
+        "notes": [],
         "groupId": "interaction",
         "groupTitle": "Interaction",
         "groupSummary": "Perform ref-based interactions in the active page."
@@ -33253,6 +33455,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--include-urls"
         ],
+        "examples": [
+          "npx opendevbrowser targets-list --session-id s1 --include-urls --output-format json"
+        ],
+        "notes": [],
         "groupId": "targets_pages",
         "groupTitle": "Targets & Pages",
         "groupSummary": "Manage tabs, targets, and named pages."
@@ -33265,6 +33471,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--target-id"
         ],
+        "examples": [
+          "npx opendevbrowser target-use --session-id s1 --target-id page-2 --output-format json"
+        ],
+        "notes": [],
         "groupId": "targets_pages",
         "groupTitle": "Targets & Pages",
         "groupSummary": "Manage tabs, targets, and named pages."
@@ -33277,6 +33487,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--url"
         ],
+        "examples": [
+          "npx opendevbrowser target-new --session-id s1 --url https://example.com/docs --output-format json"
+        ],
+        "notes": [],
         "groupId": "targets_pages",
         "groupTitle": "Targets & Pages",
         "groupSummary": "Manage tabs, targets, and named pages."
@@ -33289,6 +33503,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--target-id"
         ],
+        "examples": [
+          "npx opendevbrowser target-close --session-id s1 --target-id page-2 --output-format json"
+        ],
+        "notes": [],
         "groupId": "targets_pages",
         "groupTitle": "Targets & Pages",
         "groupSummary": "Manage tabs, targets, and named pages."
@@ -33302,6 +33520,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--name",
           "--url"
         ],
+        "examples": [
+          "npx opendevbrowser page --session-id s1 --name settings --url https://example.com/settings --output-format json"
+        ],
+        "notes": [],
         "groupId": "targets_pages",
         "groupTitle": "Targets & Pages",
         "groupSummary": "Manage tabs, targets, and named pages."
@@ -33313,6 +33535,10 @@ var PUBLIC_SURFACE_MANIFEST = {
         "flags": [
           "--session-id"
         ],
+        "examples": [
+          "npx opendevbrowser pages --session-id s1 --output-format json"
+        ],
+        "notes": [],
         "groupId": "targets_pages",
         "groupTitle": "Targets & Pages",
         "groupSummary": "Manage tabs, targets, and named pages."
@@ -33325,6 +33551,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--name"
         ],
+        "examples": [
+          "npx opendevbrowser page-close --session-id s1 --name settings --output-format json"
+        ],
+        "notes": [],
         "groupId": "targets_pages",
         "groupTitle": "Targets & Pages",
         "groupSummary": "Manage tabs, targets, and named pages."
@@ -33338,6 +33568,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--ref",
           "--max-chars"
         ],
+        "examples": [
+          "npx opendevbrowser dom-html --session-id s1 --ref r12 --max-chars 2000 --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33351,6 +33585,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--ref",
           "--max-chars"
         ],
+        "examples": [
+          "npx opendevbrowser dom-text --session-id s1 --ref r12 --max-chars 500 --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33364,6 +33602,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--ref",
           "--attr"
         ],
+        "examples": [
+          "npx opendevbrowser dom-attr --session-id s1 --ref r12 --attr aria-label --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33376,6 +33618,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser dom-value --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33388,6 +33634,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser dom-visible --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33400,6 +33650,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser dom-enabled --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33412,6 +33666,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--session-id",
           "--ref"
         ],
+        "examples": [
+          "npx opendevbrowser dom-checked --session-id s1 --ref r12 --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33425,6 +33683,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--target-id",
           "--path"
         ],
+        "examples": [
+          "npx opendevbrowser clone-page --session-id s1 --target-id page-1 --path ./exports/page.tsx --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33439,6 +33701,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--target-id",
           "--path"
         ],
+        "examples": [
+          "npx opendevbrowser clone-component --session-id s1 --ref r12 --path ./exports/component.tsx --output-format json"
+        ],
+        "notes": [],
         "groupId": "dom_export",
         "groupTitle": "DOM & Export",
         "groupSummary": "Read DOM state and export page or component code."
@@ -33456,6 +33722,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--max",
           "--request-id"
         ],
+        "examples": [
+          "npx opendevbrowser session-inspector --session-id s1 --include-urls --max 20 --output-format json"
+        ],
+        "notes": [],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33470,6 +33740,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--challenge-automation-mode",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser session-inspector-plan --session-id s1 --target-id page-1 --challenge-automation-mode browser --output-format json"
+        ],
+        "notes": [
+          "Inspect browser-scoped challenge automation before enabling browser_with_helper on a live rerun."
+        ],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33493,6 +33769,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--challenge-automation-mode",
           "--timeout-ms"
         ],
+        "examples": [
+          'npx opendevbrowser session-inspector-audit --session-id s1 --target-id page-1 --reason "trace challenge state" --include-urls --request-id req-session-audit-001 --challenge-automation-mode browser_with_helper --output-format json'
+        ],
+        "notes": [
+          "Audit mode is the quickest correlated proof lane when you need desktop evidence plus browser trace state."
+        ],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33504,6 +33786,10 @@ var PUBLIC_SURFACE_MANIFEST = {
         "flags": [
           "--session-id"
         ],
+        "examples": [
+          "npx opendevbrowser perf --session-id s1 --output-format json"
+        ],
+        "notes": [],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33520,6 +33806,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--full-page",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser screenshot --session-id s1 --path ./artifacts/page.png --full-page --output-format json"
+        ],
+        "notes": [],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33535,6 +33825,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--prompt-text",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser dialog --session-id s1 --action status --output-format json"
+        ],
+        "notes": [],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33548,6 +33842,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--since-seq",
           "--max"
         ],
+        "examples": [
+          "npx opendevbrowser console-poll --session-id s1 --max 50 --output-format json"
+        ],
+        "notes": [],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33561,6 +33859,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--since-seq",
           "--max"
         ],
+        "examples": [
+          "npx opendevbrowser network-poll --session-id s1 --max 50 --output-format json"
+        ],
+        "notes": [],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33577,6 +33879,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--max",
           "--request-id"
         ],
+        "examples": [
+          "npx opendevbrowser debug-trace-snapshot --session-id s1 --max 50 --request-id req-trace-001 --output-format json"
+        ],
+        "notes": [],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33598,6 +33904,12 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--include-screenshots",
           "--timeout-ms"
         ],
+        "examples": [
+          'npx opendevbrowser annotate --session-id s1 --transport auto --context "review call to action spacing" --include-screenshots true --output-format json'
+        ],
+        "notes": [
+          "Use --stored when you want the last delivered annotation payload without starting a new capture."
+        ],
         "groupId": "diagnostics_annotation",
         "groupTitle": "Diagnostics & Annotation",
         "groupSummary": "Collect session-centric diagnostics, trace proof, and annotation payloads."
@@ -33614,6 +33926,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--max-frames",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser screencast-start --session-id s1 --output-dir ./artifacts/replay --interval-ms 750 --max-frames 40 --output-format json"
+        ],
+        "notes": [],
         "groupId": "browser_replay",
         "groupTitle": "Browser Replay",
         "groupSummary": "Capture temporal replay artifacts through the public browser replay lane for a browser target."
@@ -33627,6 +33943,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--screencast-id",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser screencast-stop --session-id s1 --screencast-id cast-1 --output-format json"
+        ],
+        "notes": [],
         "groupId": "browser_replay",
         "groupTitle": "Browser Replay",
         "groupSummary": "Capture temporal replay artifacts through the public browser replay lane for a browser target."
@@ -33638,6 +33958,10 @@ var PUBLIC_SURFACE_MANIFEST = {
         "flags": [
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser desktop-status --timeout-ms 5000 --output-format json"
+        ],
+        "notes": [],
         "groupId": "desktop_observation",
         "groupTitle": "Desktop Observation",
         "groupSummary": "Inspect the public read-only sibling desktop observation plane on macOS; availability, window inventory, and accessibility probes use the local swift command, while screenshots use macOS screencapture outside extension relay."
@@ -33650,6 +33974,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--reason",
           "--timeout-ms"
         ],
+        "examples": [
+          'npx opendevbrowser desktop-windows --reason "inventory browser-adjacent windows" --output-format json'
+        ],
+        "notes": [],
         "groupId": "desktop_observation",
         "groupTitle": "Desktop Observation",
         "groupSummary": "Inspect the public read-only sibling desktop observation plane on macOS; availability, window inventory, and accessibility probes use the local swift command, while screenshots use macOS screencapture outside extension relay."
@@ -33662,6 +33990,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--reason",
           "--timeout-ms"
         ],
+        "examples": [
+          'npx opendevbrowser desktop-active-window --reason "capture active browser context" --output-format json'
+        ],
+        "notes": [],
         "groupId": "desktop_observation",
         "groupTitle": "Desktop Observation",
         "groupSummary": "Inspect the public read-only sibling desktop observation plane on macOS; availability, window inventory, and accessibility probes use the local swift command, while screenshots use macOS screencapture outside extension relay."
@@ -33674,6 +34006,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--reason",
           "--timeout-ms"
         ],
+        "examples": [
+          'npx opendevbrowser desktop-capture-desktop --reason "capture login checkpoint state" --output-format json'
+        ],
+        "notes": [],
         "groupId": "desktop_observation",
         "groupTitle": "Desktop Observation",
         "groupSummary": "Inspect the public read-only sibling desktop observation plane on macOS; availability, window inventory, and accessibility probes use the local swift command, while screenshots use macOS screencapture outside extension relay."
@@ -33687,6 +34023,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--reason",
           "--timeout-ms"
         ],
+        "examples": [
+          'npx opendevbrowser desktop-capture-window --window-id 101 --reason "capture browser window" --output-format json'
+        ],
+        "notes": [],
         "groupId": "desktop_observation",
         "groupTitle": "Desktop Observation",
         "groupSummary": "Inspect the public read-only sibling desktop observation plane on macOS; availability, window inventory, and accessibility probes use the local swift command, while screenshots use macOS screencapture outside extension relay."
@@ -33700,6 +34040,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--window-id",
           "--timeout-ms"
         ],
+        "examples": [
+          'npx opendevbrowser desktop-accessibility-snapshot --reason "inspect current browser-adjacent labels" --window-id 101 --output-format json'
+        ],
+        "notes": [],
         "groupId": "desktop_observation",
         "groupTitle": "Desktop Observation",
         "groupSummary": "Inspect the public read-only sibling desktop observation plane on macOS; availability, window inventory, and accessibility probes use the local swift command, while screenshots use macOS screencapture outside extension relay."
@@ -33715,6 +34059,10 @@ var PUBLIC_SURFACE_MANIFEST = {
           "--params-file",
           "--timeout-ms"
         ],
+        "examples": [
+          "npx opendevbrowser rpc --unsafe-internal --name browser.status --params-file ./rpc-params.json --output-format json"
+        ],
+        "notes": [],
         "groupId": "power",
         "groupTitle": "Power",
         "groupSummary": "Unsafe internal daemon passthrough."
@@ -34313,349 +34661,428 @@ var PUBLIC_SURFACE_MANIFEST = {
       {
         "name": "opendevbrowser_launch",
         "description": "Launch a managed browser session.",
-        "cliEquivalent": "launch"
+        "cliEquivalent": "launch",
+        "example": "npx opendevbrowser launch --no-extension --headless --start-url https://example.com --output-format json"
       },
       {
         "name": "opendevbrowser_connect",
         "description": "Connect to an existing browser session.",
-        "cliEquivalent": "connect"
+        "cliEquivalent": "connect",
+        "example": "npx opendevbrowser connect --host 127.0.0.1 --cdp-port 9222 --output-format json"
       },
       {
         "name": "opendevbrowser_disconnect",
         "description": "Disconnect a managed or connected session.",
-        "cliEquivalent": "disconnect"
+        "cliEquivalent": "disconnect",
+        "example": "npx opendevbrowser disconnect --session-id s1 --close-browser --output-format json"
       },
       {
         "name": "opendevbrowser_status",
         "description": "Inspect session and relay status.",
-        "cliEquivalent": "status"
+        "cliEquivalent": "status",
+        "example": "npx opendevbrowser status --daemon --output-format json"
       },
       {
         "name": "opendevbrowser_status_capabilities",
         "description": "Inspect runtime capability discovery for the host and an optional session.",
-        "cliEquivalent": "status-capabilities"
+        "cliEquivalent": "status-capabilities",
+        "example": "npx opendevbrowser status-capabilities --session-id s1 --target-id page-1 --challenge-automation-mode browser --timeout-ms 30000 --output-format json"
       },
       {
         "name": "opendevbrowser_session_inspector",
         "description": "Capture a session-first diagnostic bundle with relay health, trace proof, and a suggested next action.",
-        "cliEquivalent": "session-inspector"
+        "cliEquivalent": "session-inspector",
+        "example": "npx opendevbrowser session-inspector --session-id s1 --include-urls --max 20 --output-format json"
       },
       {
         "name": "opendevbrowser_session_inspector_plan",
         "description": "Inspect browser-scoped computer-use policy, eligibility, and safe suggested steps.",
-        "cliEquivalent": "session-inspector-plan"
+        "cliEquivalent": "session-inspector-plan",
+        "example": "npx opendevbrowser session-inspector-plan --session-id s1 --target-id page-1 --challenge-automation-mode browser --output-format json"
       },
       {
         "name": "opendevbrowser_session_inspector_audit",
         "description": "Capture a correlated audit bundle across desktop evidence, browser review, and policy state.",
-        "cliEquivalent": "session-inspector-audit"
+        "cliEquivalent": "session-inspector-audit",
+        "example": 'npx opendevbrowser session-inspector-audit --session-id s1 --target-id page-1 --reason "trace challenge state" --include-urls --request-id req-session-audit-001 --challenge-automation-mode browser_with_helper --output-format json'
       },
       {
         "name": "opendevbrowser_targets_list",
         "description": "List available page targets/tabs.",
-        "cliEquivalent": "targets-list"
+        "cliEquivalent": "targets-list",
+        "example": "npx opendevbrowser targets-list --session-id s1 --include-urls --output-format json"
       },
       {
         "name": "opendevbrowser_target_use",
         "description": "Switch the active target by id.",
-        "cliEquivalent": "target-use"
+        "cliEquivalent": "target-use",
+        "example": "npx opendevbrowser target-use --session-id s1 --target-id page-2 --output-format json"
       },
       {
         "name": "opendevbrowser_target_new",
         "description": "Create a new target or tab.",
-        "cliEquivalent": "target-new"
+        "cliEquivalent": "target-new",
+        "example": "npx opendevbrowser target-new --session-id s1 --url https://example.com/docs --output-format json"
       },
       {
         "name": "opendevbrowser_target_close",
         "description": "Close a target or tab by id.",
-        "cliEquivalent": "target-close"
+        "cliEquivalent": "target-close",
+        "example": "npx opendevbrowser target-close --session-id s1 --target-id page-2 --output-format json"
       },
       {
         "name": "opendevbrowser_page",
         "description": "Open or focus a named page.",
-        "cliEquivalent": "page"
+        "cliEquivalent": "page",
+        "example": "npx opendevbrowser page --session-id s1 --name settings --url https://example.com/settings --output-format json"
       },
       {
         "name": "opendevbrowser_list",
         "description": "List named pages in the session.",
-        "cliEquivalent": "pages"
+        "cliEquivalent": "pages",
+        "example": "npx opendevbrowser pages --session-id s1 --output-format json"
       },
       {
         "name": "opendevbrowser_close",
         "description": "Close a named page.",
-        "cliEquivalent": "page-close"
+        "cliEquivalent": "page-close",
+        "example": "npx opendevbrowser page-close --session-id s1 --name settings --output-format json"
       },
       {
         "name": "opendevbrowser_goto",
         "description": "Navigate to a URL.",
-        "cliEquivalent": "goto"
+        "cliEquivalent": "goto",
+        "example": "npx opendevbrowser goto --session-id s1 --url https://example.com --wait-until networkidle --output-format json"
       },
       {
         "name": "opendevbrowser_wait",
         "description": "Wait for load, ref, or state conditions.",
-        "cliEquivalent": "wait"
+        "cliEquivalent": "wait",
+        "example": "npx opendevbrowser wait --session-id s1 --state networkidle --timeout-ms 30000 --output-format json"
       },
       {
         "name": "opendevbrowser_snapshot",
         "description": "Capture AX-tree refs for actions.",
-        "cliEquivalent": "snapshot"
+        "cliEquivalent": "snapshot",
+        "example": "npx opendevbrowser snapshot --session-id s1 --mode actionables --max-chars 4000 --output-format json"
       },
       {
         "name": "opendevbrowser_review",
         "description": "Capture a first-class review payload with status and actionables.",
-        "cliEquivalent": "review"
+        "cliEquivalent": "review",
+        "example": "npx opendevbrowser review --session-id s1 --target-id page-1 --output-format json"
       },
       {
         "name": "opendevbrowser_review_desktop",
         "description": "Capture desktop-assisted browser review with read-only desktop evidence and browser-owned verification.",
-        "cliEquivalent": "review-desktop"
+        "cliEquivalent": "review-desktop",
+        "example": 'npx opendevbrowser review-desktop --session-id s1 --reason "trace challenge state" --output-format json'
       },
       {
         "name": "opendevbrowser_click",
         "description": "Click an element by ref.",
-        "cliEquivalent": "click"
+        "cliEquivalent": "click",
+        "example": "npx opendevbrowser click --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_hover",
         "description": "Hover an element by ref.",
-        "cliEquivalent": "hover"
+        "cliEquivalent": "hover",
+        "example": "npx opendevbrowser hover --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_press",
         "description": "Send a keyboard key.",
-        "cliEquivalent": "press"
+        "cliEquivalent": "press",
+        "example": "npx opendevbrowser press --session-id s1 --key Enter --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_check",
         "description": "Check a checkbox or radio by ref.",
-        "cliEquivalent": "check"
+        "cliEquivalent": "check",
+        "example": "npx opendevbrowser check --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_uncheck",
         "description": "Uncheck a checkbox or radio by ref.",
-        "cliEquivalent": "uncheck"
+        "cliEquivalent": "uncheck",
+        "example": "npx opendevbrowser uncheck --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_type",
         "description": "Type text into an input by ref.",
-        "cliEquivalent": "type"
+        "cliEquivalent": "type",
+        "example": 'npx opendevbrowser type --session-id s1 --ref r12 --text "agent@example.com" --clear --output-format json'
       },
       {
         "name": "opendevbrowser_select",
         "description": "Set select values by ref.",
-        "cliEquivalent": "select"
+        "cliEquivalent": "select",
+        "example": "npx opendevbrowser select --session-id s1 --ref r12 --values us,ca --output-format json"
       },
       {
         "name": "opendevbrowser_scroll",
         "description": "Scroll a page or element.",
-        "cliEquivalent": "scroll"
+        "cliEquivalent": "scroll",
+        "example": "npx opendevbrowser scroll --session-id s1 --dy 1000 --output-format json"
       },
       {
         "name": "opendevbrowser_scroll_into_view",
         "description": "Scroll a target element into view.",
-        "cliEquivalent": "scroll-into-view"
+        "cliEquivalent": "scroll-into-view",
+        "example": "npx opendevbrowser scroll-into-view --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_upload",
         "description": "Upload files to a file input or chooser by ref.",
-        "cliEquivalent": "upload"
+        "cliEquivalent": "upload",
+        "example": "npx opendevbrowser upload --session-id s1 --ref r12 --files ./draft.pdf,./hero.png --output-format json"
       },
       {
         "name": "opendevbrowser_pointer_move",
         "description": "Move the pointer to viewport coordinates.",
-        "cliEquivalent": "pointer-move"
+        "cliEquivalent": "pointer-move",
+        "example": "npx opendevbrowser pointer-move --session-id s1 --x 320 --y 240 --steps 12 --output-format json"
       },
       {
         "name": "opendevbrowser_pointer_down",
         "description": "Press a mouse button at viewport coordinates.",
-        "cliEquivalent": "pointer-down"
+        "cliEquivalent": "pointer-down",
+        "example": "npx opendevbrowser pointer-down --session-id s1 --x 320 --y 240 --button left --click-count 1 --output-format json"
       },
       {
         "name": "opendevbrowser_pointer_up",
         "description": "Release a mouse button at viewport coordinates.",
-        "cliEquivalent": "pointer-up"
+        "cliEquivalent": "pointer-up",
+        "example": "npx opendevbrowser pointer-up --session-id s1 --x 320 --y 240 --button left --click-count 1 --output-format json"
       },
       {
         "name": "opendevbrowser_pointer_drag",
         "description": "Drag the pointer between viewport coordinates.",
-        "cliEquivalent": "pointer-drag"
+        "cliEquivalent": "pointer-drag",
+        "example": "npx opendevbrowser pointer-drag --session-id s1 --from-x 320 --from-y 240 --to-x 640 --to-y 240 --steps 18 --output-format json"
       },
       {
         "name": "opendevbrowser_dom_get_html",
         "description": "Get HTML for a page or ref.",
-        "cliEquivalent": "dom-html"
+        "cliEquivalent": "dom-html",
+        "example": "npx opendevbrowser dom-html --session-id s1 --ref r12 --max-chars 2000 --output-format json"
       },
       {
         "name": "opendevbrowser_dom_get_text",
         "description": "Get text for a page or ref.",
-        "cliEquivalent": "dom-text"
+        "cliEquivalent": "dom-text",
+        "example": "npx opendevbrowser dom-text --session-id s1 --ref r12 --max-chars 500 --output-format json"
       },
       {
         "name": "opendevbrowser_get_attr",
         "description": "Read a DOM attribute by ref.",
-        "cliEquivalent": "dom-attr"
+        "cliEquivalent": "dom-attr",
+        "example": "npx opendevbrowser dom-attr --session-id s1 --ref r12 --attr aria-label --output-format json"
       },
       {
         "name": "opendevbrowser_get_value",
         "description": "Read a form or control value by ref.",
-        "cliEquivalent": "dom-value"
+        "cliEquivalent": "dom-value",
+        "example": "npx opendevbrowser dom-value --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_is_visible",
         "description": "Check ref visibility.",
-        "cliEquivalent": "dom-visible"
+        "cliEquivalent": "dom-visible",
+        "example": "npx opendevbrowser dom-visible --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_is_enabled",
         "description": "Check ref enabled state.",
-        "cliEquivalent": "dom-enabled"
+        "cliEquivalent": "dom-enabled",
+        "example": "npx opendevbrowser dom-enabled --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_is_checked",
         "description": "Check ref checked state.",
-        "cliEquivalent": "dom-checked"
+        "cliEquivalent": "dom-checked",
+        "example": "npx opendevbrowser dom-checked --session-id s1 --ref r12 --output-format json"
       },
       {
         "name": "opendevbrowser_run",
         "description": "Execute multi-action automation scripts.",
-        "cliEquivalent": "run"
+        "cliEquivalent": "run",
+        "example": "npx opendevbrowser run --script ./workflow.json --headless --output-format json"
       },
       {
         "name": "opendevbrowser_prompting_guide",
-        "description": "Start here for first-contact OpenDevBrowser guidance and the bundled best-practices quick start."
+        "description": "Start here for first-contact OpenDevBrowser guidance and the bundled best-practices quick start.",
+        "example": '{"topic":"quick start"}',
+        "notes": [
+          "Tool-only helper. Use it before low-level browser commands when an agent needs the canonical quick start."
+        ]
       },
       {
         "name": "opendevbrowser_console_poll",
         "description": "Poll redacted console events.",
-        "cliEquivalent": "console-poll"
+        "cliEquivalent": "console-poll",
+        "example": "npx opendevbrowser console-poll --session-id s1 --max 50 --output-format json"
       },
       {
         "name": "opendevbrowser_network_poll",
         "description": "Poll redacted network events.",
-        "cliEquivalent": "network-poll"
+        "cliEquivalent": "network-poll",
+        "example": "npx opendevbrowser network-poll --session-id s1 --max 50 --output-format json"
       },
       {
         "name": "opendevbrowser_debug_trace_snapshot",
         "description": "Capture page, console, and network diagnostics.",
-        "cliEquivalent": "debug-trace-snapshot"
+        "cliEquivalent": "debug-trace-snapshot",
+        "example": "npx opendevbrowser debug-trace-snapshot --session-id s1 --max 50 --request-id req-trace-001 --output-format json"
       },
       {
         "name": "opendevbrowser_cookie_import",
         "description": "Import validated cookies into a session.",
-        "cliEquivalent": "cookie-import"
+        "cliEquivalent": "cookie-import",
+        "example": "npx opendevbrowser cookie-import --session-id s1 --cookies-file ./cookies.json --strict true --output-format json"
       },
       {
         "name": "opendevbrowser_cookie_list",
         "description": "List cookies in a session with optional URL filters.",
-        "cliEquivalent": "cookie-list"
+        "cliEquivalent": "cookie-list",
+        "example": "npx opendevbrowser cookie-list --session-id s1 --url https://example.com --output-format json"
       },
       {
         "name": "opendevbrowser_macro_resolve",
         "description": "Resolve or execute provider macro expressions.",
-        "cliEquivalent": "macro-resolve"
+        "cliEquivalent": "macro-resolve",
+        "example": `npx opendevbrowser macro-resolve --expression '@community.search("browser automation failures", 4)' --execute --challenge-automation-mode browser --output-format json`
       },
       {
         "name": "opendevbrowser_research_run",
         "description": "Run the research workflow directly.",
-        "cliEquivalent": "research"
+        "cliEquivalent": "research",
+        "example": 'npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --source-selection auto --mode json --output-format json'
       },
       {
         "name": "opendevbrowser_shopping_run",
         "description": "Run the shopping workflow directly.",
-        "cliEquivalent": "shopping"
+        "cliEquivalent": "shopping",
+        "example": 'npx opendevbrowser shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --mode json --output-format json'
       },
       {
         "name": "opendevbrowser_product_video_run",
         "description": "Run the product-video asset workflow directly.",
-        "cliEquivalent": "product-video"
+        "cliEquivalent": "product-video",
+        "example": 'npx opendevbrowser product-video run --product-url "https://example.com/p/1" --include-screenshots --output-format json'
       },
       {
         "name": "opendevbrowser_inspiredesign_run",
         "description": "Run the inspiredesign workflow directly.",
-        "cliEquivalent": "inspiredesign"
+        "cliEquivalent": "inspiredesign",
+        "example": 'npx opendevbrowser inspiredesign run --brief "Extract a reusable dashboard design contract from live references" --url https://linear.app --capture-mode deep --include-prototype-guidance --output-dir /tmp/inspiredesign --output-format json'
       },
       {
         "name": "opendevbrowser_canvas",
         "description": "Execute a typed design-canvas command surface call.",
-        "cliEquivalent": "canvas"
+        "cliEquivalent": "canvas",
+        "example": `npx opendevbrowser canvas --command canvas.session.open --params '{"label":"design review"}' --timeout-ms 120000 --output-format json`
       },
       {
         "name": "opendevbrowser_clone_page",
         "description": "Export the active page into React code.",
-        "cliEquivalent": "clone-page"
+        "cliEquivalent": "clone-page",
+        "example": "npx opendevbrowser clone-page --session-id s1 --target-id page-1 --path ./exports/page.tsx --output-format json"
       },
       {
         "name": "opendevbrowser_clone_component",
         "description": "Export a component by ref into React code.",
-        "cliEquivalent": "clone-component"
+        "cliEquivalent": "clone-component",
+        "example": "npx opendevbrowser clone-component --session-id s1 --ref r12 --path ./exports/component.tsx --output-format json"
       },
       {
         "name": "opendevbrowser_perf",
         "description": "Collect browser performance metrics.",
-        "cliEquivalent": "perf"
+        "cliEquivalent": "perf",
+        "example": "npx opendevbrowser perf --session-id s1 --output-format json"
       },
       {
         "name": "opendevbrowser_screenshot",
         "description": "Capture a page screenshot.",
-        "cliEquivalent": "screenshot"
+        "cliEquivalent": "screenshot",
+        "example": "npx opendevbrowser screenshot --session-id s1 --path ./artifacts/page.png --full-page --output-format json"
       },
       {
         "name": "opendevbrowser_screencast_start",
         "description": "Start a browser replay screencast capture.",
-        "cliEquivalent": "screencast-start"
+        "cliEquivalent": "screencast-start",
+        "example": "npx opendevbrowser screencast-start --session-id s1 --output-dir ./artifacts/replay --interval-ms 750 --max-frames 40 --output-format json"
       },
       {
         "name": "opendevbrowser_screencast_stop",
         "description": "Stop a browser replay screencast capture.",
-        "cliEquivalent": "screencast-stop"
+        "cliEquivalent": "screencast-stop",
+        "example": "npx opendevbrowser screencast-stop --session-id s1 --screencast-id cast-1 --output-format json"
       },
       {
         "name": "opendevbrowser_dialog",
         "description": "Inspect or handle a JavaScript dialog.",
-        "cliEquivalent": "dialog"
+        "cliEquivalent": "dialog",
+        "example": "npx opendevbrowser dialog --session-id s1 --action status --output-format json"
       },
       {
         "name": "opendevbrowser_desktop_status",
         "description": "Inspect public read-only desktop observation availability.",
-        "cliEquivalent": "desktop-status"
+        "cliEquivalent": "desktop-status",
+        "example": "npx opendevbrowser desktop-status --timeout-ms 5000 --output-format json"
       },
       {
         "name": "opendevbrowser_desktop_windows",
         "description": "List windows exposed by the public read-only desktop observation plane.",
-        "cliEquivalent": "desktop-windows"
+        "cliEquivalent": "desktop-windows",
+        "example": 'npx opendevbrowser desktop-windows --reason "inventory browser-adjacent windows" --output-format json'
       },
       {
         "name": "opendevbrowser_desktop_active_window",
         "description": "Inspect the active window through the public read-only desktop observation plane.",
-        "cliEquivalent": "desktop-active-window"
+        "cliEquivalent": "desktop-active-window",
+        "example": 'npx opendevbrowser desktop-active-window --reason "capture active browser context" --output-format json'
       },
       {
         "name": "opendevbrowser_desktop_capture_desktop",
         "description": "Capture the current desktop surface through the public read-only desktop observation plane.",
-        "cliEquivalent": "desktop-capture-desktop"
+        "cliEquivalent": "desktop-capture-desktop",
+        "example": 'npx opendevbrowser desktop-capture-desktop --reason "capture login checkpoint state" --output-format json'
       },
       {
         "name": "opendevbrowser_desktop_capture_window",
         "description": "Capture a specific window through the public read-only desktop observation plane.",
-        "cliEquivalent": "desktop-capture-window"
+        "cliEquivalent": "desktop-capture-window",
+        "example": 'npx opendevbrowser desktop-capture-window --window-id 101 --reason "capture browser window" --output-format json'
       },
       {
         "name": "opendevbrowser_desktop_accessibility_snapshot",
         "description": "Capture desktop accessibility state through the public read-only desktop observation plane.",
-        "cliEquivalent": "desktop-accessibility-snapshot"
+        "cliEquivalent": "desktop-accessibility-snapshot",
+        "example": 'npx opendevbrowser desktop-accessibility-snapshot --reason "inspect current browser-adjacent labels" --window-id 101 --output-format json'
       },
       {
         "name": "opendevbrowser_annotate",
         "description": "Capture interactive annotations.",
-        "cliEquivalent": "annotate"
+        "cliEquivalent": "annotate",
+        "example": 'npx opendevbrowser annotate --session-id s1 --transport auto --context "review call to action spacing" --include-screenshots true --output-format json'
       },
       {
         "name": "opendevbrowser_skill_list",
-        "description": "List bundled and discovered skill packs before choosing a local onboarding or workflow lane."
+        "description": "List bundled and discovered skill packs before choosing a local onboarding or workflow lane.",
+        "example": "{}",
+        "notes": [
+          "Tool-only helper. Use it to inspect local workflow lanes before loading a pack."
+        ]
       },
       {
         "name": "opendevbrowser_skill_load",
-        "description": "Load a specific skill pack locally, especially the bundled best-practices quick start."
+        "description": "Load a specific skill pack locally, especially the bundled best-practices quick start.",
+        "example": '{"name":"opendevbrowser-best-practices","topic":"quick start"}',
+        "notes": [
+          "Tool-only helper. Use it to load opendevbrowser-best-practices or design-agent guidance directly into the current agent context."
+        ]
       }
     ],
     "cliToolPairs": [
@@ -34944,18 +35371,22 @@ var CLI_COMMAND_HELP_DETAILS = Object.fromEntries(
     {
       description: command.description,
       usage: command.usage,
-      flags: [...command.flags]
+      flags: [...command.flags],
+      examples: [...command.examples],
+      notes: [...command.notes]
     }
   ])
 );
-var COMMANDS_BY_GROUP = new Map(
+var COMMANDS_BY_GROUP = Object.fromEntries(
   PUBLIC_SURFACE_MANIFEST.cli.groups.map((group) => [
     group.id,
     PUBLIC_SURFACE_MANIFEST.cli.commands.filter((command) => command.groupId === group.id).map((command) => ({
       name: command.name,
       description: command.description,
       usage: command.usage,
-      flags: [...command.flags]
+      flags: [...command.flags],
+      examples: [...command.examples],
+      notes: [...command.notes]
     }))
   ])
 );
@@ -34963,12 +35394,14 @@ var PUBLIC_CLI_COMMAND_GROUPS = PUBLIC_SURFACE_MANIFEST.cli.groups.map((group) =
   id: group.id,
   title: group.title,
   summary: group.summary,
-  commands: COMMANDS_BY_GROUP.get(group.id) ?? []
+  commands: COMMANDS_BY_GROUP[group.id]
 }));
 var TOOL_SURFACE_ENTRIES = PUBLIC_SURFACE_MANIFEST.tools.entries.map((entry) => ({
   name: entry.name,
   description: entry.description,
-  ...entry.cliEquivalent ? { cliEquivalent: entry.cliEquivalent } : {}
+  ...entry.cliEquivalent ? { cliEquivalent: entry.cliEquivalent } : {},
+  example: entry.example,
+  ...entry.notes ? { notes: [...entry.notes] } : {}
 }));
 
 export {
@@ -35019,4 +35452,4 @@ export {
   TOOL_SURFACE_ENTRIES
 };
 /* v8 ignore next -- @preserve */
-//# sourceMappingURL=chunk-OGE5KJ4X.js.map
+//# sourceMappingURL=chunk-2MG7BRPF.js.map