browser-pilot 0.0.16 → 0.0.17

package/dist/cli.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env bun
+import "./chunk-MIJ7UIKB.mjs";
+import "./chunk-OIHU7OFY.mjs";
 import {
   BrowserEndpointResolutionError,
   connect,
   resolveBrowserEndpoint
-} from "./chunk-TJ5B56NV.mjs";
+} from "./chunk-IRLHCVNH.mjs";
 import "./chunk-LCNFBXB5.mjs";
 import {
   DEEP_QUERY_SCRIPT,
-  LiveTraceCollector,
   SENSITIVE_AUTOCOMPLETE_TOKENS,
   TRACE_BINDING_NAME,
   TRACE_SCRIPT,
@@ -17,13 +18,17 @@ import {
   canonicalizeRecordingArtifact,
   createRecordingManifest,
   createTraceId,
+  formatConsoleArg,
   fuzzyMatchElements,
+  globToRegex,
   grantAudioPermissions,
   normalizeTraceEvent,
   pcmToWav,
+  readString,
+  readStringOr,
   redactValueForRecording,
   validateSteps
-} from "./chunk-6GBYX7C2.mjs";
+} from "./chunk-MRY3HRFJ.mjs";
 import {
   isRecord
 } from "./chunk-DTVRFXKI.mjs";
@@ -32,6 +37,68 @@ import {
   DAEMON_READY_TIMEOUT_MS
 } from "./chunk-LUGLEMVR.mjs";
 
+// src/cli/command-registry.ts
+var CLI_COMMANDS = [
+  { name: "quickstart", description: "Getting started guide", showInRootHelp: true },
+  { name: "connect", description: "Create or resume a browser session", showInRootHelp: true },
+  { name: "exec", description: "Execute high-level actions", showInRootHelp: true },
+  { name: "eval", description: "Run raw JavaScript as an escape hatch", showInRootHelp: true },
+  { name: "snapshot", description: "Inspect current page with refs", showInRootHelp: true },
+  { name: "text", description: "Extract readable page text", showInRootHelp: true },
+  { name: "page", description: "Compact page overview", showInRootHelp: true },
+  { name: "forms", description: "List form controls", showInRootHelp: true },
+  { name: "targets", description: "List available browser tabs", showInRootHelp: true },
+  { name: "diagnose", description: "Debug selectors and targeting failures", showInRootHelp: true },
+  { name: "review", description: "Structured business state after actions", showInRootHelp: true },
+  { name: "screenshot", description: "Capture a page screenshot", showInRootHelp: true },
+  { name: "run", description: "Run a workflow file", showInRootHelp: true },
+  {
+    name: "record",
+    description: "Record a human workflow and derive replayable output",
+    showInRootHelp: true
+  },
+  { name: "trace", description: "Inspect and analyze behavior over time", showInRootHelp: true },
+  {
+    name: "audio",
+    description: "Set up, validate, and drive voice pipelines",
+    showInRootHelp: true
+  },
+  { name: "env", description: "Session and browser-environment controls", showInRootHelp: true },
+  { name: "daemon", description: "Manage session daemon", showInRootHelp: true },
+  { name: "list", description: "List sessions", showInRootHelp: true },
+  { name: "close", description: "Close session", showInRootHelp: true },
+  { name: "clean", description: "Clean old sessions and artifacts", showInRootHelp: true },
+  { name: "actions", description: "Complete action reference", showInRootHelp: true }
+];
+var ROOT_HELP_COMMANDS = CLI_COMMANDS.filter((command) => command.showInRootHelp);
+var CLI_ROUTE_GROUPS = [
+  {
+    label: "Inspect page state",
+    commands: ["snapshot", "page", "forms", "review", "text", "targets", "diagnose"]
+  },
+  {
+    label: "Act in the browser",
+    commands: ["exec", "run"]
+  },
+  {
+    label: "Capture a human demo",
+    commands: ["record"]
+  },
+  {
+    label: "Analyze behavior over time",
+    commands: ["trace"],
+    note: "(listen is a compatibility alias)"
+  },
+  {
+    label: "Exercise voice/media",
+    commands: ["audio"]
+  },
+  {
+    label: "Change browser conditions",
+    commands: ["env"]
+  }
+];
+
 // src/cli/commands/actions.ts
 var ACTIONS_HELP = `
 bp actions - Complete action reference
@@ -232,7 +299,7 @@ EXAMPLES
   ]'
 
   # Use ref from snapshot
-  bp snapshot --format text  # Note the refs
+  bp snapshot -i  # Note the refs
   bp exec '{"action":"click","selector":"ref:e4"}'
 
   # Scroll and wait
@@ -359,6 +426,268 @@ Content-Type: ${contentType}\r
   parts.push(data);
 }
 
+// src/trace/live.ts
+var LiveTraceCollector = class {
+  cdp;
+  options;
+  handlers = [];
+  wsUrls = /* @__PURE__ */ new Map();
+  httpUrls = /* @__PURE__ */ new Map();
+  events = [];
+  startTime = Date.now();
+  matchRegex;
+  constructor(cdp, options = {}) {
+    this.cdp = cdp;
+    this.options = options;
+    this.matchRegex = options.match ? globToRegex(options.match) : null;
+  }
+  async start() {
+    await this.cdp.send("Runtime.enable");
+    await this.cdp.send("Page.enable");
+    await this.cdp.send("Network.enable");
+    await this.cdp.send("Runtime.addBinding", { name: TRACE_BINDING_NAME });
+    await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: TRACE_SCRIPT });
+    await this.cdp.send("Runtime.evaluate", { expression: TRACE_SCRIPT, awaitPromise: false });
+    if ((this.options.mode ?? "all") !== "http") {
+      this.subscribe("Network.webSocketCreated", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const url = readStringOr(params["url"]);
+        if (!this.matchesUrl(url)) {
+          return;
+        }
+        this.wsUrls.set(requestId, url);
+        void this.emit({
+          channel: "ws",
+          event: "ws.connection.created",
+          summary: `WebSocket opened ${url}`,
+          connectionId: requestId,
+          requestId,
+          url,
+          data: { url }
+        });
+      });
+      this.subscribe("Network.webSocketFrameSent", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const response = params["response"];
+        const payload = this.formatPayload(response?.payloadData, response?.opcode ?? 1);
+        const url = this.wsUrls.get(requestId);
+        if (this.matchRegex && !this.matchRegex.test(url ?? "") && !this.matchRegex.test(payload)) {
+          return;
+        }
+        void this.emit({
+          channel: "ws",
+          event: "ws.frame.sent",
+          summary: `WebSocket frame sent ${requestId}`,
+          connectionId: requestId,
+          requestId,
+          url,
+          data: {
+            opcode: response?.opcode ?? 1,
+            payload,
+            length: response?.payloadData?.length ?? 0
+          }
+        });
+      });
+      this.subscribe("Network.webSocketFrameReceived", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const response = params["response"];
+        const payload = this.formatPayload(response?.payloadData, response?.opcode ?? 1);
+        const url = this.wsUrls.get(requestId);
+        if (this.matchRegex && !this.matchRegex.test(url ?? "") && !this.matchRegex.test(payload)) {
+          return;
+        }
+        void this.emit({
+          channel: "ws",
+          event: "ws.frame.received",
+          summary: `WebSocket frame received ${requestId}`,
+          connectionId: requestId,
+          requestId,
+          url,
+          data: {
+            opcode: response?.opcode ?? 1,
+            payload,
+            length: response?.payloadData?.length ?? 0
+          }
+        });
+      });
+      this.subscribe("Network.webSocketClosed", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const url = this.wsUrls.get(requestId);
+        this.wsUrls.delete(requestId);
+        void this.emit({
+          channel: "ws",
+          event: "ws.connection.closed",
+          summary: `WebSocket closed ${requestId}`,
+          severity: "warn",
+          connectionId: requestId,
+          requestId,
+          url,
+          data: { url }
+        });
+      });
+    }
+    if ((this.options.mode ?? "all") !== "ws") {
+      this.subscribe("Network.requestWillBeSent", (params) => {
+        const request = params["request"];
+        const requestId = readStringOr(params["requestId"]);
+        const url = request?.url ?? "";
+        if (!this.matchesUrl(url)) {
+          return;
+        }
+        this.httpUrls.set(requestId, url);
+        void this.emit({
+          channel: "http",
+          event: "http.request.sent",
+          summary: `${request?.method ?? "GET"} ${url}`,
+          requestId,
+          url,
+          data: {
+            method: request?.method ?? "GET",
+            headers: request?.headers ?? {},
+            body: request?.postData ?? null
+          }
+        });
+      });
+      this.subscribe("Network.responseReceived", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        if (!this.httpUrls.has(requestId)) {
+          return;
+        }
+        const response = params["response"];
+        void this.emit({
+          channel: "http",
+          event: "http.response.received",
+          summary: `${response?.status ?? 0} ${response?.url ?? this.httpUrls.get(requestId) ?? ""}`,
+          requestId,
+          url: response?.url ?? this.httpUrls.get(requestId),
+          data: {
+            status: response?.status ?? 0,
+            headers: response?.headers ?? {},
+            mimeType: response?.mimeType ?? null
+          }
+        });
+      });
+      this.subscribe("Network.loadingFailed", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const url = readString(params["blockedReason"]) ?? this.httpUrls.get(requestId) ?? "";
+        void this.emit({
+          channel: "http",
+          event: "http.response.failed",
+          summary: `HTTP request failed ${requestId}`,
+          severity: "error",
+          requestId,
+          url,
+          data: {
+            errorText: params["errorText"] ?? null,
+            blockedReason: params["blockedReason"] ?? null,
+            canceled: params["canceled"] ?? false
+          }
+        });
+      });
+    }
+    this.subscribe("Runtime.consoleAPICalled", (params) => {
+      const type = readStringOr(params["type"], "log");
+      if (type !== "log" && type !== "warn" && type !== "error") {
+        return;
+      }
+      const args = Array.isArray(params["args"]) ? params["args"] : [];
+      const text = args.map(formatConsoleArg).filter(Boolean).join(" ");
+      void this.emit({
+        channel: "console",
+        event: `console.${type}`,
+        severity: type === "error" ? "error" : type === "warn" ? "warn" : "info",
+        summary: text || `console.${type}`,
+        data: { args }
+      });
+    });
+    this.subscribe("Runtime.exceptionThrown", (params) => {
+      const details = params["exceptionDetails"] ?? {};
+      const text = readString(details["text"]) ?? "Runtime exception";
+      void this.emit({
+        channel: "runtime",
+        event: "runtime.exception",
+        severity: "error",
+        summary: text,
+        data: details
+      });
+    });
+    this.subscribe("Runtime.bindingCalled", (params) => {
+      if (params["name"] !== TRACE_BINDING_NAME) {
+        return;
+      }
+      const raw = readStringOr(params["payload"]);
+      try {
+        const payload = JSON.parse(raw);
+        const channel = this.channelForTraceEvent(payload.event);
+        void this.emit({
+          channel,
+          event: payload.event,
+          severity: payload.severity,
+          summary: payload.summary ?? payload.event,
+          ts: payload.ts ? new Date(payload.ts).toISOString() : void 0,
+          data: payload.data ?? {},
+          url: readString(payload.data?.["url"])
+        });
+      } catch {
+      }
+    });
+  }
+  async stop() {
+    for (const { event, handler } of this.handlers) {
+      this.cdp.off(event, handler);
+    }
+    this.handlers.length = 0;
+    return [...this.events];
+  }
+  getEvents() {
+    return [...this.events];
+  }
+  subscribe(event, handler) {
+    this.cdp.on(event, handler);
+    this.handlers.push({ event, handler });
+  }
+  matchesUrl(url) {
+    if (!this.matchRegex) {
+      return true;
+    }
+    return this.matchRegex.test(url);
+  }
+  formatPayload(payloadData, opcode) {
+    const data = payloadData ?? "";
+    const maxPayload = this.options.maxPayload ?? 256;
+    if (opcode === 2) {
+      const byteLength = Math.floor(data.length * 3 / 4);
+      return `[binary: ${byteLength} bytes]`;
+    }
+    if (data.length > maxPayload) {
+      return `${data.slice(0, maxPayload)}... [truncated, ${data.length} total]`;
+    }
+    return data;
+  }
+  channelForTraceEvent(eventName) {
+    if (eventName.startsWith("ws.")) return "ws";
+    if (eventName.startsWith("http.")) return "http";
+    if (eventName.startsWith("console.")) return "console";
+    if (eventName.startsWith("permission.")) return "permission";
+    if (eventName.startsWith("media.")) return "media";
+    if (eventName.startsWith("voice.")) return "voice";
+    if (eventName.startsWith("dom.")) return "dom";
+    if (eventName.startsWith("runtime.")) return "runtime";
+    return "session";
+  }
+  async emit(event) {
+    const normalized = normalizeTraceEvent({
+      traceId: event.traceId ?? createTraceId(event.channel),
+      sessionId: this.options.sessionId,
+      targetId: this.options.targetId,
+      elapsedMs: event.elapsedMs ?? Date.now() - this.startTime,
+      ...event
+    });
+    this.events.push(normalized);
+    await this.options.onEvent?.(normalized);
+  }
+};
+
 // src/trace/store.ts
 import * as fs from "fs";
 import { homedir } from "os";
@@ -1220,7 +1549,7 @@ async function audioCommand(args, globalOptions) {
           event: checkJson.ready ? "voice.pipeline.ready" : "voice.pipeline.notReady",
           severity: checkJson.ready ? "info" : "error",
           summary: checkJson.ready ? "Audio pipeline ready" : "Audio pipeline not ready",
-          data: checkJson
+          data: { ...checkJson }
         });
         if (checkJson.agentDetected) {
           logger.logTrace({
@@ -1521,13 +1850,15 @@ bp clean - Remove stale browser sessions
 Usage:
   bp clean [options]
 
-Options:
+Local options:
   --max-age <hours>    Remove sessions older than N hours (default: 24)
   --max-size <size>    Remove oldest sessions until total size < limit (e.g. "100MB", "1GB")
   --dry-run            Show what would be removed without deleting
   --all                Remove all sessions regardless of age
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
+
+Global options:
+  --json               Output JSON
+  --pretty             Output readable text (default)
   -h, --help           Show this help
 
 Examples:
@@ -1731,11 +2062,11 @@ bp close - Close a browser session
 Usage:
   bp close [session-id]
 
-Options:
+Global options:
   -s, --session <id>   Session to close (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
@@ -1840,18 +2171,30 @@ async function waitForDaemonReady(sessionFilePath, expectedPid, timeoutMs = DAEM
 var CONNECT_HELP = `
 bp connect - Create or resume a browser session
 
+When to use:
+  Create a session before running inspect, exec, record, trace, audio, or env commands.
+
+When not to use:
+  You already have a session and only need to open a page. Use \`bp exec '{"action":"goto","url":"..."}'\`.
+
+Browser and page URL guidance:
+  Use \`--browser-url\` for a DevTools WebSocket endpoint.
+  Use \`--page-url\` to open a page in the attached tab or a new tab.
+  \`--url\` remains for compatibility and is ambiguous when paired with \`--new-tab\`.
+
 Usage:
   bp connect [options]
 
-Options:
+Local options:
   -p, --provider <type>   Provider: generic | browserbase | browserless (default: generic)
-  --url <value>           Browser WebSocket URL, or page URL when used with --new-tab
-  --browser-url <ws-url>  Explicit browser WebSocket URL
+  --browser-url <ws-url>  Explicit browser WebSocket URL (preferred)
+  --page-url <url>        Page URL to open in the attached tab/new tab (preferred)
+  --url <value>           Compatibility shorthand; browser URL, or page URL with --new-tab
   --channel <name>        Local Chrome channel: stable | beta | dev | canary
   --user-data-dir <path>  Explicit local Chrome user data dir for auto-discovery
-  --page-url <url>        URL to open in the attached page/new tab
   -n, --name <id>         Custom session name (default: auto-generated)
   -r, --resume <id>       Resume an existing session by ID
+  -s, --session <id>      Alias for --resume
   --new-tab               Create and attach to a fresh tab instead of reusing an existing one
   --target-url <str>      Filter targets to those whose URL contains this string
   --api-key <key>         API key for cloud providers
@@ -1863,28 +2206,57 @@ Options:
   --no-highlights         Disable visual highlights on screenshots
   --no-daemon             Skip daemon creation (direct WebSocket only)
   --daemon-idle <mins>    Daemon idle timeout in minutes (default: 60)
-  -s, --session <id>      Alias for --resume
-  --trace                 Enable debug tracing
+
+Global options:
+  --json                  Output JSON
+  --pretty                Output readable text (default)
+  --debug                 Enable CDP transport debugging
   -h, --help              Show this help
 
 Examples:
-  bp connect                                    # Auto-connect to local Chrome
-  bp connect --channel beta                     # Narrow auto-discovery to Chrome Beta
-  bp connect --user-data-dir ~/tmp/chrome-dev   # Use a specific Chrome profile
-  bp connect --record                           # Connect with session-level recording
-  bp connect --name dev                         # Auto-connect with a custom session name
-  bp connect --url ws://localhost:9222/devtools/browser/abc123  # Explicit WebSocket URL
-  bp connect --resume dev                       # Resume a previous session
+  bp connect                                     # Auto-connect to local Chrome
+  bp connect --name dev                          # Auto-connect with a custom session name
+  bp connect --resume dev                        # Resume a previous session
+  bp connect --browser-url ws://localhost:9222/devtools/browser/abc123
+  bp connect --channel beta                      # Narrow auto-discovery to Chrome Beta
+  bp connect --user-data-dir ~/tmp/chrome-dev    # Use a specific Chrome profile
   bp connect --target-url localhost:3000         # Attach to tab matching URL
-  bp connect --new-tab --url https://example.com # Create and attach to a fresh tab
-  bp connect --no-daemon                        # Connect without daemon (file-based only)
+  bp connect --record                            # Connect with session-level recording
+  bp connect --new-tab --page-url https://example.com
+  bp connect --no-daemon                         # Connect without daemon (file-based only)
+
+Likely next commands:
+  bp exec -s dev '{"action":"goto","url":"https://example.com"}'
+  bp snapshot -i -s dev
+  bp text -s dev
 `.trimEnd();
+async function resolveInitialPageUrl(page, requestedUrl) {
+  const initialUrl = await page.url();
+  if (!requestedUrl || requestedUrl === "about:blank" || initialUrl !== "about:blank") {
+    return initialUrl;
+  }
+  const deadline = Date.now() + 5e3;
+  while (Date.now() < deadline) {
+    await Bun.sleep(100);
+    const currentUrl = await page.url();
+    if (currentUrl !== "about:blank") {
+      return currentUrl;
+    }
+  }
+  return initialUrl;
+}
 function parseConnectArgs(args) {
   const options = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--provider" || arg === "-p") {
-      options.provider = args[++i];
+      const p = args[++i];
+      if (p !== "browserbase" && p !== "browserless" && p !== "generic") {
+        throw new Error(
+          `Invalid provider: ${p}. Must be one of: browserbase, browserless, generic`
+        );
+      }
+      options.provider = p;
     } else if (arg === "--url") {
       options.url = args[++i];
     } else if (arg === "--browser-url") {
@@ -2016,7 +2388,7 @@ async function connectCommand(args, globalOptions) {
     void 0,
     options.targetUrl ? { targetUrl: options.targetUrl } : void 0
   );
-  const currentUrl = await page.url();
+  const currentUrl = await resolveInitialPageUrl(page, pageUrl);
   const sessionId = options.name ?? generateSessionId();
   let recordSettings;
   if (options.record) {
@@ -2098,10 +2470,12 @@ Subcommands:
   logs      Show daemon log output
 
 Options:
-  -s, --session <id>   Target session (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
   -n, --lines <n>      Number of log lines to show (default: 50)
+
+Global options:
+  -s, --session <id>   Target session (default: most recent)
+  --json               Output JSON
+  --pretty             Output readable text (default)
   -h, --help           Show this help
 
 Examples:
@@ -2731,11 +3105,15 @@ Examples:
   bp diagnose "submit"             Find elements matching "submit"
   bp diagnose "ref:e4"             Diagnose by element ref
 
-Options:
-  --json               Output as JSON
+Local options:
   --max <n>            Max candidates for fuzzy match (default: 5)
-  -s, --session <id>   Use specific session
-  --help               Show this help
+
+Global options:
+  -s, --session <id>   Session to use (default: most recent)
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
+  -h, --help           Show this help
 
 Likely next commands:
   bp exec '[{"action":"click","selector":"<suggested-selector>"}]'
@@ -3770,8 +4148,8 @@ async function attachSession(session, options = {}) {
         const cdp = createCDPClientFromTransport(transport, {
           debug: options.trace
         });
-        const { Browser: BrowserClass } = await import("./browser-ZCR6AA4D.mjs");
-        const { Page: PageClass } = await import("./page-IUUTJ3SW.mjs");
+        const { Browser: BrowserClass } = await import("./browser-4ZHNAQR5.mjs");
+        const { Page: PageClass } = await import("./page-SD64DY3F.mjs");
         const browser2 = BrowserClass.fromCDP(cdp, session);
         const page2 = session.daemon.cdpSessionId && session.targetId ? addBatchToPage(
           await (async () => {
@@ -3824,25 +4202,29 @@ bp eval - Evaluate JavaScript in the browser
 
 Convenience wrapper around exec's evaluate action.
 No JSON escaping needed -- just pass a JS expression directly.
+Use this as an escape hatch after higher-level commands like snapshot, text, review, and exec.
 
 Usage:
   bp eval '<expression>'        Evaluate inline JavaScript
   bp eval -f <file>             Evaluate JavaScript from a file
   echo '<expr>' | bp eval       Evaluate from stdin
 
-Options:
-  -f, --file <path>    Read JavaScript from a file
-  --wrap               Wrap the expression in an async IIFE
-  -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
-  -h, --help           Show this help
+Local options:
+  -f, --file <path>     Read JavaScript from a file
+  --wrap                Wrap the expression in an async IIFE
+
+Global options:
+  -s, --session <id>    Session to use (default: most recent)
+  --json                Output JSON
+  --pretty              Output readable text (default)
+  --debug               Enable CDP transport debugging
+  -h, --help            Show this help
 
 Examples:
   bp eval 'document.title'
   bp eval 'document.querySelectorAll("a").length'
   bp eval -f scrape.js
+  bp eval --wrap 'await fetch("/health").then((r) => r.status)'
 `.trimEnd();
 function parseEvalArgs(args) {
   const options = {};
@@ -3938,14 +4320,10 @@ Usage:
   bp exec -f <file>             Execute action(s) from a JSON file
   echo '<json>' | bp exec       Execute action(s) from stdin
 
-Options:
-  -f, --file <path>    Read actions from a JSON file
-  -o, --output <path>  Write command output to a file instead of stdout
-  --dialog <mode>      Handle native dialogs: accept | dismiss
-  -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
-  --debug              Enable CDP transport debugging (global option)
+Local options:
+  -f, --file <path>     Read actions from a JSON file
+  -o, --output <path>   Write command output to a file instead of stdout
+  --dialog <mode>       Handle native dialogs: accept | dismiss
 
 Recording:
   --record                    Enable screenshot recording
@@ -3955,6 +4333,11 @@ Recording:
   --no-highlights             Disable visual highlights on screenshots
                               Sensitive fields (passwords, OTPs, card inputs) are redacted
 
+Global options:
+  -s, --session <id>   Session to use (default: most recent)
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
@@ -4181,6 +4564,22 @@ Run 'bp actions' for complete action reference.${evalTip}`
           data: stepResult.result
         });
       }
+      if (stepResult.outcomeStatus) {
+        logger.logTrace({
+          channel: "action",
+          event: `action.outcome.${stepResult.outcomeStatus}`,
+          summary: `Outcome: ${stepResult.outcomeStatus}${stepResult.retrySafe === false ? " (unsafe to retry)" : ""}`,
+          data: {
+            outcomeStatus: stepResult.outcomeStatus,
+            retrySafe: stepResult.retrySafe,
+            matchedConditions: stepResult.matchedConditions?.map((mc) => ({
+              kind: mc.condition.kind,
+              matched: mc.matched,
+              detail: mc.detail
+            }))
+          }
+        });
+      }
     }
     if (result.recordingManifest && session.exportLog) {
       mirrorRecordingToExport(result.recordingManifest, session.exportLog);
@@ -4222,7 +4621,10 @@ Run 'bp actions' for complete action reference.${evalTip}`
       selectorUsed: s.selectorUsed,
       error: s.error,
       text: s.text,
-      result: s.result
+      result: s.result,
+      ...s.outcomeStatus !== void 0 ? { outcomeStatus: s.outcomeStatus } : {},
+      ...s.matchedConditions !== void 0 ? { matchedConditions: s.matchedConditions } : {},
+      ...s.retrySafe !== void 0 ? { retrySafe: s.retrySafe } : {}
     }));
     const payload = {
       success: result.success,
@@ -4332,19 +4734,29 @@ function formatInteractiveElementsPretty(elements, limit = elements.length) {
 var FORMS_HELP = `
 bp forms - List form controls on the current page
 
+When to use:
+  You need field names, types, values, or disabled state without the rest of the page.
+
+When not to use:
+  You need clickable refs or a broader page summary. Use \`bp snapshot -i\` or \`bp page\`.
+
 Usage:
   bp forms [options]
 
-Options:
+Global options:
   -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
   bp forms
   bp forms --json
+
+Likely next commands:
+  bp exec '[{"action":"fill","selector":"ref:e4","value":"..."}]'
+  bp review --json
 `.trimEnd();
 async function formsCommand(_args, globalOptions) {
   if (globalOptions.help) {
@@ -4381,11 +4793,14 @@ Usage:
   bp list -s <id> --log-path       Print path to session log file (for analysis)
 
 Options:
-  -s, --session <id>    Target session (or uses default session)
   --info                Show session details and log statistics
   --log-tail [n]        Show last n action log entries (default: 20)
   --log-path            Print absolute path to log.jsonl file
-  -f json, --json       Machine-readable JSON output
+
+Global options:
+  -s, --session <id>    Target session (or uses default session)
+  --json                Machine-readable JSON output
+  --pretty              Output readable text (default)
   -h, --help            Show this help
 
 Examples:
@@ -4567,7 +4982,11 @@ When to use:
   You want a quick summary of URL, title, headings, forms, and interactive controls.
 
 When not to use:
-  You need the full accessibility tree or reusable refs for precise automation. Use \`bp snapshot\`.
+  You need the full accessibility tree or the full ref inventory for precise automation. Use \`bp snapshot\`.
+
+Common mistake:
+  Treating \`bp page\` as exhaustive. It is a compact overview; the Actions section caches reusable refs,
+  but use \`bp snapshot -i\` when you need the full actionable surface.
 
 Likely next commands:
   bp snapshot -i
@@ -4577,11 +4996,11 @@ Likely next commands:
 Usage:
   bp page [options]
 
-Options:
+Global options:
   -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
@@ -4649,7 +5068,16 @@ async function pageCommand(_args, globalOptions) {
       globalOptions.format === "json" ? summary : formatPageSummary(summary),
       globalOptions.format
     );
-    await updateSession(session.id, { currentUrl: url });
+    await updateSession(session.id, {
+      currentUrl: url,
+      metadata: {
+        refCache: {
+          url,
+          savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          refMap: page.exportRefMap()
+        }
+      }
+    });
   } finally {
     await browser.disconnect();
   }
@@ -4660,14 +5088,14 @@ var QUICKSTART = `
 browser-pilot CLI - Quick Start Guide
 
 STEP 1: CONNECT TO A BROWSER
-  bp connect --provider generic --name mysite
+  bp connect --name mysite
 
   This creates a session. The CLI remembers it for subsequent commands.
 
 STEP 2: NAVIGATE
-  bp exec '{"action":"goto","url":"https://example.com"}'
+  bp exec -s mysite '{"action":"goto","url":"https://example.com"}'
 
-STEP 3: GET PAGE SNAPSHOT
+STEP 3: CHOOSE THE RIGHT INSPECTION COMMAND
   bp snapshot -i
 
   Shows only interactive elements (buttons, inputs, links) with refs:
@@ -4675,39 +5103,48 @@ STEP 3: GET PAGE SNAPSHOT
     textbox "Email" ref:e3
     link "Forgot password?" ref:e6
 
-  Other formats:
-    bp snapshot --format text    # Full accessibility tree (all elements)
-    bp snapshot --json           # Full snapshot as JSON
+  Other inspection commands:
+    bp page                # Compact overview: URL, title, headings, forms, actions
+    bp text                # Readable page copy or policy text
+    bp review --json       # Structured business state after actions
+    bp diagnose 'submit'   # Debug selector or targeting failures
 
 STEP 4: INTERACT USING REFS
-  bp exec '{"action":"fill","selector":"ref:e3","value":"test@example.com"}'
-  bp exec '{"action":"click","selector":"ref:e2"}'
+  bp exec -s mysite '{"action":"fill","selector":"ref:e3","value":"test@example.com"}'
+  bp exec -s mysite '{"action":"click","selector":"ref:e2"}'
 
 STEP 5: BATCH MULTIPLE ACTIONS
-  bp exec '[
+  bp exec -s mysite '[
     {"action":"fill","selector":"ref:e3","value":"user@test.com"},
     {"action":"click","selector":"ref:e2"},
     {"action":"snapshot"}
   ]'
 
 FOR AI AGENTS
-  Use bp snapshot -i for most workflows - shows only actionable elements.
+  Start with:
+    bp --help
+    bp --version
+
+  Use bp snapshot -i for most workflows - it shows actionable elements.
   Add --json for machine-readable output:
-    bp snapshot -i --json
-    bp exec '{"action":"click","selector":"ref:e3"}' --json
+    bp snapshot -i -s mysite --json
+    bp exec -s mysite '{"action":"click","selector":"ref:e3"}' --json
 
 PAGE DISCOVERY SHORTCUTS
-  bp page              # URL, title, headings, forms, and interactive controls
-  bp forms             # Structured list of form fields only
-  bp targets           # All available browser tabs
-  bp connect --new-tab --url https://example.com
-                      # Start from a fresh tab instead of reusing one
+  bp page                           # URL, title, headings, forms, and interactive controls
+  bp forms                          # Structured list of form fields only
+  bp text --selector '#main'        # Focused readable text extraction
+  bp review --json                  # Structured business state
+  bp targets                        # All available browser tabs
+  bp connect --new-tab --page-url https://example.com
+                                   # Convenience: start from a fresh tab
 
 TIPS
-  \u2022 Refs (e1, e2...) are stable within a page - prefer them over CSS selectors
-  \u2022 After navigation, take a new snapshot to get updated refs
-  \u2022 Use multi-selectors for resilience: ["ref:e3", "#email", "input[type=email]"]
-  \u2022 Add "optional":true to skip elements that may not exist
+  - Refs (e1, e2...) are stable within the current page state
+  - After navigation or major DOM changes, take a new snapshot to refresh refs
+  - Use multi-selectors for resilience: ["ref:e3", "#email", "input[type=email]"]
+  - Add "optional":true to skip elements that may not exist
+  - Use bp eval only as an escape hatch when higher-level commands are insufficient
 
 SELECTOR PRIORITY
   1. ref:e5         From snapshot - most reliable
@@ -5524,15 +5961,6 @@ var RECORDER_SCRIPT = `(function() {
 })();`;
 
 // src/recording/recorder.ts
-function readString(value) {
-  return typeof value === "string" ? value : void 0;
-}
-function readStringOr(value, fallback = "") {
-  return readString(value) ?? fallback;
-}
-function formatConsoleArg(entry) {
-  return readString(entry["value"]) ?? readString(entry["description"]) ?? "";
-}
 var Recorder = class {
   cdp;
   options;
@@ -6073,11 +6501,6 @@ var Recorder = class {
     return entries;
   }
 };
-function globToRegex(pattern) {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-  const withWildcards = escaped.replace(/\*/g, ".*");
-  return new RegExp(`^${withWildcards}$`);
-}
 
 // src/cli/commands/record.ts
 var RECORD_HELP = `
@@ -6598,6 +7021,114 @@ async function recordCommand(args, globalOptions) {
   }
 }
 
+// src/cli/commands/review.ts
+var REVIEW_HELP = `
+bp review - Extract structured business state from the current page
+
+When to use:
+  You want a structured summary of the page: headings, forms, alerts, tables,
+  key-value pairs, and status labels. Useful for verifying business state after
+  an action sequence, especially on detail, checkout, and confirmation pages.
+
+When not to use:
+  You need the full accessibility tree with refs. Use \`bp snapshot\`.
+  You want a compact overview. Use \`bp page\`.
+  You are on a dense catalog or marketing page with lots of nav chrome. Use \`bp text\` or \`bp page\`.
+
+Likely next commands:
+  bp snapshot -i
+  bp exec '[{"action":"click","selector":"ref:e4"}]'
+
+Usage:
+  bp review [options]
+
+Global options:
+  -s, --session <id>   Session to use (default: most recent)
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
+  -h, --help           Show this help
+
+Examples:
+  bp review
+  bp review --json
+  bp review -s my-session
+`.trimEnd();
+function formatReviewPretty(review) {
+  const lines = [];
+  lines.push(`URL: ${review.url}`);
+  lines.push(`Title: ${review.title}`);
+  lines.push("", "Headings:");
+  if (review.headings.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const h of review.headings) {
+      lines.push(`  ${h}`);
+    }
+  }
+  if (review.alerts.length > 0) {
+    lines.push("", "Alerts:");
+    for (const a of review.alerts) {
+      lines.push(`  ${a}`);
+    }
+  }
+  if (review.statusLabels.length > 0) {
+    lines.push("", "Status:");
+    for (const s of review.statusLabels) {
+      lines.push(`  ${s}`);
+    }
+  }
+  if (review.keyValues.length > 0) {
+    lines.push("", "Key-Value Pairs:");
+    for (const kv of review.keyValues) {
+      lines.push(`  ${kv.key}: ${kv.value}`);
+    }
+  }
+  if (review.tables.length > 0) {
+    lines.push("", "Tables:");
+    for (const table of review.tables) {
+      if (table.headers.length > 0) {
+        lines.push(`  | ${table.headers.join(" | ")} |`);
+        lines.push(`  | ${table.headers.map(() => "---").join(" | ")} |`);
+      }
+      for (const row of table.rows) {
+        lines.push(`  | ${row.join(" | ")} |`);
+      }
+      lines.push("");
+    }
+  }
+  lines.push("", "Forms:");
+  if (review.forms.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const f of review.forms) {
+      const disabled = f.disabled ? " (disabled)" : "";
+      const label = f.label ?? "(unlabeled)";
+      lines.push(`  ${label} [${f.type}]: ${f.value ?? ""}${disabled}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function reviewCommand(_args, globalOptions) {
+  if (globalOptions.help) {
+    process.stdout.write(`${REVIEW_HELP}
+`);
+    return;
+  }
+  const session = await resolveSession(globalOptions.session);
+  const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
+  try {
+    const review = await page.review();
+    output(
+      globalOptions.format === "json" ? review : formatReviewPretty(review),
+      globalOptions.format
+    );
+    await updateSession(session.id, { currentUrl: review.url });
+  } finally {
+    await browser.disconnect();
+  }
+}
+
 // src/cli/commands/run.ts
 import { readFile } from "fs/promises";
 import { resolve as resolve6 } from "path";
@@ -6740,17 +7271,26 @@ ${result.success ? "Workflow passed" : "Workflow failed"} in ${result.totalDurat
 var SCREENSHOT_HELP = `
 bp screenshot - Take a screenshot of the current page
 
+When to use:
+  You need a visual artifact, regression evidence, or a screenshot to attach elsewhere.
+
+When not to use:
+  You need readable copy or structured business data. Use \`bp text\`, \`bp page\`, or \`bp review\`.
+
 Usage:
   bp screenshot [options]
 
-Options:
+Local options:
   -o, --output <path>    Save screenshot to file (default: print base64 to stdout)
   -f, --format <type>    Image format: png | jpeg | webp (default: png)
   -q, --quality <n>      Image quality 0-100 (jpeg/webp only)
   --full-page            Capture the full scrollable page
+
+Global options:
   -s, --session <id>     Session to use (default: most recent)
-  --json                 Output as JSON (base64 data + metadata)
-  --trace                Enable debug tracing
+  --json                 Output JSON (base64 data + metadata)
+  --pretty               Output readable text for file writes (default)
+  --debug                Enable CDP transport debugging
   -h, --help             Show this help
 
 Examples:
@@ -7096,23 +7636,27 @@ Common mistake:
 Usage:
   bp snapshot [options]
 
-Options:
-  -i, --interactive      Show only interactive elements (buttons, inputs, links)
-  -f, --format <type>    Output format: full | interactive | text (default: text)
-  --role <roles>         Filter snapshot to accessibility roles (for example: radio,checkbox)
-  -o, --output <path>    Write command output to a file instead of stdout
-  -d, --diff <file>      Compare current page against a saved snapshot JSON
-  --inspect              Inject visual ref labels onto the page (auto-removes after 10s)
-  --keep                 Keep visual ref labels visible (use with --inspect)
-  -s, --session <id>     Session to use (default: most recent)
-  -f, --format <fmt>     Output format: json | pretty (default: pretty)
-  --json                 Alias for -f json
-  --debug                Enable CDP transport debugging (global option)
-  -h, --help             Show this help
+Local options:
+  -i, --interactive       Shortcut for --view interactive
+  --view <type>           Snapshot view: full | interactive | text (default: text)
+  -f, --format <type>     Backward-compatible alias for --view
+  --role <roles>          Filter snapshot to accessibility roles (for example: radio,checkbox)
+  -o, --output <path>     Write command output to a file instead of stdout
+  -d, --diff <file>       Compare current page against a saved snapshot JSON
+  --inspect               Inject visual ref labels onto the page (auto-removes after 10s)
+  --keep                  Keep visual ref labels visible (use with --inspect)
+
+Global options:
+  -s, --session <id>      Session to use (default: most recent)
+  --json                  Output JSON; without --view this returns the full snapshot payload
+  --pretty                Output readable text (default)
+  --debug                 Enable CDP transport debugging
+  -h, --help              Show this help
 
 Examples:
   bp snapshot                       # Full accessibility tree as readable text
   bp snapshot -i                    # Interactive elements only; best default for automation
+  bp snapshot --view full           # Full structured snapshot
   bp snapshot --role radio,checkbox # Focus on specific control roles
   bp snapshot --json > page.json    # Save full snapshot to file
   bp snapshot --diff before.json    # Show what changed since before.json
@@ -7129,7 +7673,7 @@ function parseSnapshotArgs(args) {
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === "--format" || arg === "-f") {
+    if (arg === "--view" || arg === "--format" || arg === "-f") {
       options.format = args[++i];
       options.formatExplicit = true;
     } else if (arg === "--diff" || arg === "-d") {
@@ -7262,11 +7806,11 @@ bp targets - List page tabs available in the connected browser
 Usage:
   bp targets [options]
 
-Options:
+Global options:
   -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
@@ -7331,28 +7875,31 @@ Common mistake:
 Usage:
   bp text [options]
 
-Options:
-  --selector <sel>     Extract text from a specific element (default: entire page)
-  -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
-  --debug              Enable CDP transport debugging (global option)
-  -h, --help           Show this help
+Local options:
+  --selector <selector>  Extract text from a specific element (default: entire page)
+
+Global options:
+  -s, --session <id>     Session to use (default: most recent)
+  --json                 Output JSON with text, URL, and selector
+  --pretty               Output readable text only (default)
+  --debug                Enable CDP transport debugging
+  -h, --help             Show this help
 
 Examples:
   bp text                          # Extract all text from the page
   bp text --selector '#main'       # Extract text from #main element only
-  bp text --json                   # Output as JSON with URL and selector info
+  bp text -s dev --json            # Output JSON with URL and selector info
 
 Likely next commands:
   bp snapshot -i
+  bp review --json
   bp exec '[{"action":"assertText","expect":"..."}]'
 `.trimEnd();
 function parseTextArgs(args) {
   const options = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === "--selector" || arg === "-s") {
+    if (arg === "--selector") {
       options.selector = args[++i];
     } else if (arg === "-h" || arg === "--help") {
       options.help = true;
@@ -7360,6 +7907,9 @@ function parseTextArgs(args) {
   }
   return options;
 }
+function looksLikeSelector(value) {
+  return value.startsWith("#") || value.startsWith(".") || value.startsWith("[") || value.startsWith("/") || value.startsWith("ref:") || value.includes(">");
+}
 async function textCommand(args, globalOptions) {
   const options = parseTextArgs(args);
   if (options.help || globalOptions.help) {
@@ -7368,7 +7918,18 @@ async function textCommand(args, globalOptions) {
   }
   let session;
   if (globalOptions.session) {
-    session = await loadSession(globalOptions.session);
+    try {
+      session = await loadSession(globalOptions.session);
+    } catch (error) {
+      if (!options.selector && looksLikeSelector(globalOptions.session)) {
+        throw new Error(
+          `bp text uses --selector for element targeting. "-s" is reserved for sessions.
+
+Try: bp text --selector ${JSON.stringify(globalOptions.session)}`
+        );
+      }
+      throw error;
+    }
   } else {
     session = await getDefaultSession();
     if (!session) {
@@ -7726,74 +8287,77 @@ async function traceCommand(args, globalOptions) {
   }
 }
 
+// src/cli/version.ts
+import { readFileSync as readFileSync9 } from "fs";
+var cachedCliVersion;
+function getCliVersion() {
+  if (cachedCliVersion) {
+    return cachedCliVersion;
+  }
+  cachedCliVersion = "0.0.17";
+  return cachedCliVersion;
+}
+
 // src/cli/index.ts
-var HELP2 = `
+function buildRootHelp() {
+  const routeLabelWidth = Math.max(...CLI_ROUTE_GROUPS.map((group) => group.label.length)) + 2;
+  const routeLines = CLI_ROUTE_GROUPS.map((group) => {
+    const note = group.note ? `  ${group.note}` : "";
+    return `  ${group.label.padEnd(routeLabelWidth)}${group.commands.join(", ")}${note}`;
+  });
+  const commandLabelWidth = Math.max(...ROOT_HELP_COMMANDS.map((command) => command.name.length)) + 2;
+  const commandLines = ROOT_HELP_COMMANDS.map((command) => {
+    return `  ${command.name.padEnd(commandLabelWidth)}${command.description}`;
+  });
+  return `
 bp - automation-first browser CLI for agents
 
 Route the job first:
-  Inspect page state              snapshot, page, forms, text, targets, diagnose
-  Act in the browser              exec, run
-  Capture a human demo            record
-  Analyze behavior over time      trace   (listen is a compatibility alias)
-  Exercise voice/media            audio
-  Change browser conditions       env
+${routeLines.join("\n")}
 
 Usage:
   bp <command> [options]
 
 Commands:
-  quickstart  Getting started guide
-  connect     Create a browser session
-  exec        Execute high-level actions
-  snapshot    Inspect current page with refs
-  record      Record a human workflow and derive replayable output
-  trace       Inspect and analyze behavior over time (listen alias for live stream)
-  audio       Set up/validate/inject/capture voice pipelines
-  env         Session and browser-environment controls
-  run         Run a workflow file
-  page        Compact page overview
-  forms       List form controls
-  targets     List available browser tabs
-  daemon      Manage session daemon
-  list        List sessions
-  close       Close session
-  clean       Clean old sessions and artifacts
-  actions     Complete action reference
+${commandLines.join("\n")}
 
 Golden paths:
-  1. Automate a page
-     bp connect --provider generic --name dev
+  1. Connect, open a page, inspect it, then act
+     bp connect --name dev
+     bp exec -s dev '{"action":"goto","url":"https://example.com"}'
      bp snapshot -i -s dev
      bp exec -s dev '[{"action":"click","selector":"ref:e4"}]'
 
-  2. Capture a manual workflow and derive automation
+  2. Read content or verify business state
+     bp text -s dev --selector main
+     bp review -s dev --json
+
+  3. Capture a manual workflow and derive automation
      bp record -s demo --profile automation
      bp record summary demo/recording.json
      bp record derive demo/recording.json -o workflow.json
      bp run workflow.json
 
-  3. Debug a realtime or voice session
+  4. Debug a realtime or voice session
      bp trace start -s dev
      bp trace summary -s dev --view ws
      bp audio check -s dev
      bp trace summary -s dev --view voice
 
-  4. Exercise failure modes
-     bp env network offline -s dev --duration 10000
-     bp trace watch -s dev --view ws --assert profile:reconnect --timeout 15000
-
 Options:
   -s, --session <id>    Session ID
   -f, --format <fmt>    json | pretty (default: pretty)
   --json                Alias for -f json
+  --pretty              Alias for -f pretty
   --debug               Enable debug logs for CDP transport
   --trace               Legacy alias for --debug
-  --dialog <mode>       Handle dialogs: accept | dismiss
   -h, --help            Show help
+  --version             Print CLI version
 
 Notes:
   Start with "record summary" or "trace summary" before opening raw artifacts.
-`;
+`.trim();
+}
 function parseGlobalOptions(args) {
   const options = {
     format: "pretty"
@@ -7869,14 +8433,28 @@ function prettyPrint(obj, lines, indent = 0) {
 }
 async function main() {
   const args = process.argv.slice(2);
-  if (args.length === 0) {
-    console.log(HELP2);
+  if (args.length === 0 || args.length === 1 && (args[0] === "--help" || args[0] === "-h" || args[0] === "help")) {
+    console.log(buildRootHelp());
     process.exit(0);
   }
-  const command = args[0];
-  const { options, remaining } = parseGlobalOptions(args.slice(1));
+  if (args.length === 1 && (args[0] === "--version" || args[0] === "version")) {
+    process.stdout.write(`${getCliVersion()}
+`);
+    process.exit(0);
+  }
+  let command = args[0];
+  let commandArgs = args.slice(1);
+  if (command === "help") {
+    if (commandArgs.length === 0) {
+      console.log(buildRootHelp());
+      process.exit(0);
+    }
+    command = commandArgs[0];
+    commandArgs = [...commandArgs.slice(1), "--help"];
+  }
+  const { options, remaining } = parseGlobalOptions(commandArgs);
   if (options.help && !command) {
-    console.log(HELP2);
+    console.log(buildRootHelp());
     process.exit(0);
   }
   try {
@@ -7932,6 +8510,9 @@ async function main() {
       case "record":
         await recordCommand(remaining, options);
         break;
+      case "review":
+        await reviewCommand(remaining, options);
+        break;
       case "trace":
         await traceCommand(remaining, options);
         break;
@@ -7950,11 +8531,12 @@ async function main() {
       case "help":
       case "--help":
       case "-h":
-        console.log(HELP2);
+        console.log(buildRootHelp());
         break;
       default:
         console.error(`Unknown command: ${command}`);
-        console.log(HELP2);
+        console.error('Run "bp --help" to see the available command tree.');
+        console.log(buildRootHelp());
         process.exit(1);
     }
   } catch (error) {