cbrowser 19.5.0 → 20.0.0

package/dist/cli.js

@@ -11,6 +11,10 @@
  */
 import { CBrowser } from "./browser.js";
 import { parseArgs } from "./cli-args.js";
+import { browserFlagsOrExit, refuseBrowserFlags } from "./cli-browser-flags.js";
+import { browserLaunchConfig } from "./browser-options.js";
+import { SENT_WEBHOOK_EVENTS, WEBHOOK_FORMATS, WEBHOOK_TIMEOUT_MS, loadWebhooks, sendWebhookEvent, webhookUrlProblem, webhooksPath } from "./webhooks.js";
+import { loadSuiteForExport, resultsName, saveSuiteResult } from "./testing/suite-results.js";
 // Analysis module imports
 import { executeNaturalLanguage, executeNaturalLanguageScript, huntBugs, runChaosTest, comparePersonas, formatComparisonReport, findElementByIntent, runAgentReadyAudit, formatAgentReadyReport, generateAgentReadyHtmlReport, runCompetitiveBenchmark, formatCompetitiveBenchmarkReport, generateCompetitiveBenchmarkHtmlReport, runEmpathyAudit, formatEmpathyAuditReport, generateEmpathyAuditHtmlReport, runWebMCPReadyAudit, generateWebMCPReadyHtmlReport, runAIReadinessBenchmark } from "./analysis/index.js";
 // Testing module imports
@@ -18,9 +22,11 @@ import { parseNLInstruction, parseNLTestSuite, runNLTestSuite, formatNLTestRepor
 // Performance module imports
 import { capturePerformanceBaseline, listPerformanceBaselines, loadPerformanceBaseline, deletePerformanceBaseline, detectPerformanceRegression, formatPerformanceRegressionReport } from "./performance/index.js";
 // Visual module imports
-import { captureVisualBaseline, listVisualBaselines, getVisualBaseline, deleteVisualBaseline, runVisualRegression, runVisualRegressionSuite, formatVisualRegressionReport, generateVisualRegressionHtmlReport, runCrossBrowserTest, runCrossBrowserSuite, formatCrossBrowserReport, generateCrossBrowserHtmlReport, runResponsiveTest, runResponsiveSuite, formatResponsiveReport, generateResponsiveHtmlReport, listViewportPresets, runABComparison, runABSuite, formatABReport, generateABHtmlReport, crossBrowserDiff } from "./visual/index.js";
-import { BUILTIN_PERSONAS, loadCustomPersonas, saveCustomPersona, deleteCustomPersona, isBuiltinPersona, generatePersonaFromDescription, listAccessibilityPersonas, } from "./personas.js";
-import { DEVICE_PRESETS, LOCATION_PRESETS } from "./types.js";
+import { captureVisualBaseline, listVisualBaselines, getVisualBaseline, deleteVisualBaseline, runVisualRegression, runVisualRegressionSuite, formatVisualRegressionReport, generateVisualRegressionHtmlReport, runCrossBrowserTest, runCrossBrowserSuite, formatCrossBrowserReport, generateCrossBrowserHtmlReport, runResponsiveTest, runResponsiveSuite, formatResponsiveReport, generateResponsiveHtmlReport, listViewportPresets, formatViewportPresetList, runABComparison, runABSuite, formatABReport, generateABHtmlReport, crossBrowserDiff } from "./visual/index.js";
+import { VIEWPORT_PRESETS } from "./types.js";
+import { BUILTIN_PERSONAS, loadCustomPersonas, saveCustomPersona, deleteCustomPersona, isBuiltinPersona, generatePersonaFromDescription, listAccessibilityPersonas, PERSONA_ALIASES, } from "./personas.js";
+import { LOCATION_PRESETS } from "./types.js";
+import { CBROWSER_DEVICE_KEYS, DEVICE_PRESETS, resolveDevice } from "./devices.js";
 import { startMcpServer } from "./mcp-server.js";
 import { startRemoteMcpServer } from "./mcp-server-remote.js";
 import { startDaemon, stopDaemon, getDaemonStatus, isDaemonRunning, sendToDaemon, runDaemonServer } from "./daemon.js";
@@ -30,6 +36,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync,
 import { resolveCookieDomain, hostFromUrl } from "./utils.js";
 import { dirname, join, resolve } from "node:path";
 import { guardConsole, guardTerminalOutput } from "./terminal-safe.js";
+import { evaluateScript } from "./eval-script.js";
 import { VideoCaptureSession } from "./recording/engine.js";
 import { changeSignal, parseManifest } from "./recording/types.js";
 import { printEnterpriseStatus } from "./stealth/index.js";
@@ -81,7 +88,7 @@ function helpText() {
 
 NAVIGATION
   navigate <url>              Navigate and take screenshot
-  screenshot [path]           Take screenshot of current page
+  screenshot [url] [path]     Take a screenshot (of <url> when given, else the current page)
     --no-restore                Don't reload saved URL (capture current state after interactions)
 
 INTERACTION
@@ -116,6 +123,7 @@ SCRIPTING
     --raw                     Print the raw value, unquoted
     --wait-for <selector>     Wait for the selector before evaluating
     --expect-truthy           Exit 1 when the result is falsy (CI assertion)
+    --timeout <ms>            How long --wait-for waits: ms, or 5s / 2m (default: 30000)
     Examples:
       cbrowser evaluate "document.title" --force
       cbrowser evaluate --file check.js --arg '"#main"' --expect-truthy --force
@@ -128,6 +136,7 @@ KEYBOARD
     --hold <mod>              Hold a modifier across the whole sequence
     --repeat <n>              Repeat the whole sequence n times
     --text                    Treat every token as literal text (for "+" in text)
+    --url <url>               Navigate to URL first
     A token with modifiers is a chord (Control+A); a known key name is that key
     (Enter, Tab, ArrowLeft); anything else is typed as literal text. Unknown
     key names are rejected, not typed. For a single key use 'press', for a
@@ -137,12 +146,12 @@ KEYBOARD
       cbrowser keyboard "ArrowRight" --repeat 5 --hold Shift
       cbrowser keyboard "Tab" "Tab" "Enter" --selector "#email" --delay 120
 
-SITE EXPLORATION (Free, heuristic-based)
-  explore <persona>           Quick autonomous exploration using built-in heuristics
+SITE EXPLORATION (API-powered)
+  explore <persona>           Short cognitive journey (needs an Anthropic API key; costs tokens)
     --start <url>             Starting URL (required)
     --goal <goal>             What to accomplish
     --record-video            Record exploration as video
-    Note: No API key needed. Uses rule-based navigation - fast but not "smart".
+    Note: the keyless heuristic explorer was removed in 20.0.0; its success verdicts were not accurate.
 
 COGNITIVE JOURNEY (API-powered, realistic user simulation)
   cognitive-journey           Simulate a real user with emotions, patience, and abandonment
@@ -158,10 +167,13 @@ COGNITIVE JOURNEY (API-powered, realistic user simulation)
     --verbose                 Show step-by-step narration and internal monologue
     --no-vision               Disable vision mode (text-only, less accurate but faster)
     --output <file>           Save JSON report to file
-    --html                    Generate HTML report
+    --trace                   Record the journey to ~/.cbrowser/traces/<id>.jsonl
+    --replay-trace <file>     Replay a recorded journey: no model calls, no API key
+    --persistent              Run in the shared browser profile (default: a fresh one,
+                              so the persona starts as a new visitor)
     --timezone <tz>           Override persona timezone (e.g., "America/New_York", "Europe/London")
     --locale <loc>            Override persona locale (e.g., "en-US", "de-DE")
-    --geolocation <lat,lng>   Override persona geolocation (e.g., "40.7128,-74.0060")
+    --geo <preset|lat,lon>    Override persona location (also --geolocation <lat,lng>)
 
     Why use this over 'explore'?
       • Tracks cognitive state: patience, frustration, confusion
@@ -177,12 +189,14 @@ COGNITIVE JOURNEY (API-powered, realistic user simulation)
 
     Note: Requires Anthropic API key. Set with: cbrowser config set-api-key <key>
 
-MULTI-PERSONA COMPARISON (v6.0.0)
+MULTI-PERSONA COMPARISON
   compare-personas            Compare multiple personas on the same journey
     --start <url>             Starting URL (required)
     --goal <goal>             What to accomplish (required)
     --personas <list>         Comma-separated persona names
     --concurrency <n>         Max parallel browsers (default: 3)
+    --device <name>           Device every journey emulates
+    --viewport <WxH>          Page size for every journey
     --output <file>           Save JSON report to file
     --html                    Generate HTML report
     Examples:
@@ -190,8 +204,10 @@ MULTI-PERSONA COMPARISON (v6.0.0)
         --goal "Complete checkout" \\
         --personas power-user,first-timer,elderly-user,mobile-user
 
-NATURAL LANGUAGE TEST SUITES (v6.1.0)
+NATURAL LANGUAGE TEST SUITES
   test-suite <file.txt>        Run tests written in plain English
+                               Saves each run for 'export'; sends test.pass or
+                               test.fail to webhooks ('webhook add')
     --continue-on-failure      Keep running after a test fails
     --screenshot-on-failure    Take screenshots on failure (default: true)
     --output <file>            Save JSON report to file
@@ -226,29 +242,31 @@ NATURAL LANGUAGE TEST SUITES (v6.1.0)
       click search button
       verify page contains "results"
 
-AI TEST REPAIR (v6.2.0)
+AI TEST REPAIR
   repair-tests <file.txt>      Analyze failing tests and suggest/apply repairs
     --auto-apply               Automatically apply the best repair
     --verify                   Re-run tests after repair to verify they pass
     --output <file>            Save repaired tests to new file
-    --json <file>              Save repair report as JSON
+    --json-out <file>          Save repair report as JSON (--json prints it)
+    --device, --viewport, --browser, --no-headless   The browser the tests run in
     Examples:
       cbrowser repair-tests broken-test.txt
       cbrowser repair-tests tests.txt --auto-apply --verify
       cbrowser repair-tests tests.txt --auto-apply --output fixed-tests.txt
 
-FLAKY TEST DETECTION (v6.3.0)
+FLAKY TEST DETECTION
   flaky-check <file.txt>       Run tests multiple times to detect flaky tests
     --runs <n>                 Number of runs per test (default: 5)
     --threshold <n>            Flakiness % threshold to flag (default: 20)
     --delay <ms>               Delay between runs (default: 500)
     --output <file>            Save JSON report to file
+    --device, --viewport, --browser, --no-headless   The browser every run uses
     Examples:
       cbrowser flaky-check tests.txt
       cbrowser flaky-check tests.txt --runs 10
       cbrowser flaky-check tests.txt --runs 5 --threshold 30 --output flaky-report.json
 
-TEST COVERAGE MAP (v6.5.0)
+TEST COVERAGE MAP
   coverage <url>               Generate test coverage map for a site
     --tests <glob>             Test files to analyze (default: tests/*.txt)
     --sitemap <url>            Use sitemap.xml instead of crawling
@@ -257,7 +275,8 @@ TEST COVERAGE MAP (v6.5.0)
     --exclude <pattern>        Exclude paths matching pattern
     --min-coverage <n>         Min coverage % to not flag (default: 50)
     --html                     Generate HTML report
-    --output <file>            Save JSON report to file
+    --output <file>            Save the report (JSON if the name ends in .json, else text)
+    --device, --viewport, --browser, --no-headless   The crawl's browser (not with --sitemap)
     Examples:
       cbrowser coverage "https://example.com" --tests "tests/*.txt"
       cbrowser coverage "https://example.com" --sitemap "https://example.com/sitemap.xml"
@@ -280,6 +299,8 @@ PERSONAS
   persona delete <name>       Delete a custom persona
   persona export <name>       Export persona to JSON file
   persona import <file>       Import persona from JSON file
+  persona cleanup             Remove custom personas that fail validation
+    --dry-run                 List them without removing anything
 
 SESSION MANAGEMENT
   session save <name>         Save browser session (cookies, storage, URL)
@@ -287,6 +308,12 @@ SESSION MANAGEMENT
   session load <name>         Load a saved session
   session list                List all saved sessions
   session delete <name>       Delete a saved session
+  session show <name>         Show a saved session's cookies, storage and URL
+  session cleanup             Delete saved sessions older than N days
+    --older-than <days>       Age in days (default: 30)
+  session export <name>       Export a session to a JSON file
+    --output <file>           File to write (default: <name>.json)
+  session import <file>       Import a session from a JSON file
 
 COOKIE MANAGEMENT
   cookie list                 List all cookies for current page
@@ -299,7 +326,7 @@ COOKIE MANAGEMENT
   cookie clear                Clear all cookies
 
 DEVICE EMULATION
-  device list                 List available device presets
+  device list [filter]        List device presets, one per line (filter by name)
   device set <name>           Set device emulation for session
     Example: cbrowser device set iphone-15
 
@@ -317,10 +344,12 @@ PERFORMANCE
     --budget-fcp <ms>         FCP budget (default: 1800)
     --budget-cls <score>      CLS budget (default: 0.1)
 
-PERFORMANCE REGRESSION (v6.4.0)
+PERFORMANCE REGRESSION
   perf-baseline save <url>    Capture and save performance baseline
     --name <name>             Human-readable name for baseline
     --runs <n>                Number of runs to average (default: 3)
+    --device <name>           Device to measure as; perf-regression renders the same
+    --viewport <WxH>          Page size; perf-regression renders the same
     Examples:
       cbrowser perf-baseline save "https://example.com" --name "homepage"
       cbrowser perf-baseline save "https://example.com/checkout" --runs 5
@@ -334,6 +363,9 @@ PERFORMANCE REGRESSION (v6.4.0)
     --threshold-lcp <n>       Max LCP increase % (default: 20)
     --threshold-cls <n>       Max CLS increase (default: 0.1)
     --threshold-fcp <n>       Max FCP increase % (default: 20)
+    --threshold-ttfb <n>      Max TTFB increase % (default: 30)
+    --threshold-tti <n>       Max TTI increase %
+    --threshold-tbt <n>       Max TBT increase %
     --output <file>           Save JSON report to file
     Examples:
       cbrowser perf-regression "https://example.com" homepage
@@ -344,14 +376,17 @@ NETWORK / HAR (need the daemon: each command is its own process)
   daemon start                Start the daemon first; it holds the browser between commands
   har start                   Start recording HAR in the daemon's browser
   har stop [output]           Stop and save HAR file
-  network list                List network requests the daemon's browser captured
+  network list                List network requests the daemon's browser captured, newest first
+    --filter <text>           Only requests whose URL contains <text>, or of that type or method
+    --all                     List every request (default: the newest 20)
+    --json                    Print the list as JSON
   network clear               Clear that list
   console                     List the daemon tab's console messages (errors, warnings, logs)
     --filter <type>           all | error | warning | log | info (default all)
     --clear                   Empty the console buffer after reading
     --json                    Print the raw messages as JSON
 
-VISUAL REGRESSION (v2.5.0)
+VISUAL REGRESSION
   visual save <name>          Save baseline screenshot
     --url <url>               Navigate to URL first
   visual compare <name>       Compare current page against baseline
@@ -359,19 +394,22 @@ VISUAL REGRESSION (v2.5.0)
   visual list                 List all saved baselines
   visual delete <name>        Delete a baseline
 
-AI VISUAL REGRESSION (v7.0.0)
+AI VISUAL REGRESSION
   ai-visual capture <url>     Capture AI-analyzed visual baseline
     --name <name>             Baseline name (required)
     --selector <sel>          Capture specific element instead of viewport
     --device <device>         Device emulation (iphone-15, pixel-7, etc.)
+    --viewport <WxH>          Page size (default: 1920x1080)
     --width <n>               Viewport width (default: 1920)
     --height <n>              Viewport height (default: 1080)
+    --browser <engine>        chromium, firefox or webkit; the baseline keeps it
     --wait <ms|selector>      Wait before capture (ms or CSS selector)
     Examples:
       cbrowser ai-visual capture "https://example.com" --name homepage
       cbrowser ai-visual capture "https://example.com/dashboard" --name dashboard --device iphone-15
 
   ai-visual test <url> <baseline>  Test current page against baseline using AI
+    Renders with the baseline's engine, device and size
     --threshold <n>           Similarity threshold 0-1 (default: 0.9)
     --sensitivity <level>     Detection sensitivity: low, medium, high (default: medium)
     --html                    Generate HTML report
@@ -389,41 +427,13 @@ AI VISUAL REGRESSION (v7.0.0)
   ai-visual show <name>       Show baseline details
   ai-visual delete <name>     Delete a baseline
 
-SMART BASELINES & TRANSPORT MAP (v18.0.0)
-  smart-baseline capture <url>  Capture consensus baseline from multiple screenshots
-    --name <name>             Baseline name (required)
-    --captures <n>            Number of screenshots to take (default: 5)
-    --delay <ms>              Delay between captures (default: 1500)
-    --selector <sel>          Capture specific element
-    --device <device>         Device emulation
-    --outlier-threshold <n>   Outlier rejection threshold in stddev (default: 2.0)
-    Examples:
-      cbrowser smart-baseline capture "https://example.com" --name homepage
-      cbrowser smart-baseline capture "https://example.com" --name hero --captures 10
-
-  smart-baseline test <url> <name>  Test against smart baseline
-    --threshold <n>           Override adaptive threshold (0-1)
-    --transport-map           Also generate visual transport map
-    Examples:
-      cbrowser smart-baseline test "https://staging.example.com" homepage
-      cbrowser smart-baseline test "https://staging.example.com" homepage --transport-map
-
-  smart-baseline list         List all smart baselines
-  smart-baseline delete <name>  Delete a smart baseline
-
-  transport-map <baseline> <current>  Generate visual transport map between two screenshots
-    --cell-size <n>           Grid cell size in pixels (default: 32)
-    --output <file.svg>       Save SVG to file
-    --hotspots <n>            Number of hotspots to identify (default: 5)
-    Examples:
-      cbrowser transport-map baseline.png current.png
-      cbrowser transport-map baseline.png current.png --cell-size 16 --output changes.svg
-
-CROSS-BROWSER VISUAL TESTING (v7.3.0)
+CROSS-BROWSER VISUAL TESTING
   cross-browser <url>         Compare visual rendering across browsers
     --browsers <list>         Browsers to test: chromium,firefox,webkit (default: all)
+    --viewport <WxH>          Page size (default: 1920x1080)
     --width <n>               Viewport width (default: 1920)
     --height <n>              Viewport height (default: 1080)
+    --device <name>           Device preset (firefox cannot emulate a mobile one)
     --wait <ms>               Wait before screenshot (ms)
     --wait-for <selector>     Wait for selector before screenshot
     --sensitivity <level>     Comparison sensitivity: low, medium, high
@@ -445,9 +455,11 @@ CROSS-BROWSER VISUAL TESTING (v7.3.0)
       "options": { "browsers": ["chromium", "firefox"] }
     }
 
-RESPONSIVE VISUAL TESTING (v7.3.0)
+RESPONSIVE VISUAL TESTING
   responsive <url>            Test visual rendering across viewport sizes
     --viewports <list>        Viewports to test (default: mobile,tablet,desktop)
+    --browser <engine>        chromium, firefox or webkit (firefox cannot emulate
+                              the mobile and tablet presets)
     --wait <ms>               Wait before screenshot (ms)
     --wait-for <selector>     Wait for selector before screenshot
     --sensitivity <level>     Comparison sensitivity: low, medium, high
@@ -471,18 +483,19 @@ RESPONSIVE VISUAL TESTING (v7.3.0)
       "options": { "viewports": ["mobile", "tablet", "desktop"] }
     }
 
-    Available viewport presets:
-      mobile-sm (320x568)     mobile (375x667)      mobile-lg (414x896)
-      mobile-xl (428x926)     tablet (768x1024)     tablet-lg (1024x1366)
-      desktop-sm (1280x800)   desktop (1440x900)    desktop-lg (1920x1080)
-      desktop-xl (2560x1440)
+    Available viewport presets (mobile and tablet emulate their device: touch,
+    user agent, pixel ratio):
+${formatViewportPresetList("      ")}
 
-A/B VISUAL COMPARISON (v7.3.0)
+A/B VISUAL COMPARISON
   ab <urlA> <urlB>            Compare two URLs visually
     --label-a <name>          Label for URL A (default: "Version A")
     --label-b <name>          Label for URL B (default: "Version B")
+    --viewport <WxH>          Page size (default: 1920x1080)
     --width <n>               Viewport width (default: 1920)
     --height <n>              Viewport height (default: 1080)
+    --device <name>           Device preset
+    --browser <engine>        chromium, firefox or webkit
     --wait <ms>               Wait before screenshot (ms)
     --wait-for <selector>     Wait for selector before screenshot
     --sensitivity <level>     Comparison sensitivity: low, medium, high
@@ -512,6 +525,9 @@ AI FRIENDLINESS - Audit sites for AI agent compatibility
 
   agent-ready-audit <url>     Audit site for AI-agent friendliness (A-F grade)
     --headless                Run in headless mode (default: true)
+    --device <name>           Device to audit on, e.g. iphone-16
+    --geo-region <region>     Run through a configured regional proxy (exits 1 if not configured)
+    --lightpanda              Use Lightpanda instead of Chromium (see LIGHTPANDA)
     --output <file>           Save JSON report to file
     --html                    Generate HTML report
     Grades sites on: Findability (35%), Stability (30%),
@@ -522,6 +538,7 @@ AI FRIENDLINESS - Audit sites for AI agent compatibility
 
   ai-benchmark                Compare AI-friendliness across multiple sites
     --urls <list>             Comma-separated URLs to benchmark (required)
+    --concurrency <n>         Sites audited at once (default: 3)
     --output <file>           Save JSON report to file
     --html                    Generate HTML report
     Runs agent-ready-audit on each URL and produces ranked comparison.
@@ -530,14 +547,17 @@ AI FRIENDLINESS - Audit sites for AI agent compatibility
       cbrowser ai-benchmark --urls "https://amazon.com,https://ebay.com" --html
 
   empathy-audit <url>         Simulate disability experience on site
-    --goal <goal>             Task goal (required)
-    --personas <list>         Disability personas (comma-separated)
+    --goal <goal>             Task goal (optional; without one the page is checked)
+    --personas <list>         Disability personas (comma-separated; also --disabilities)
+    --device <name>           Device to audit on, e.g. iphone-16
+    --scope <scope>           viewport (default) or full_page
     --wcag-level <level>      WCAG level: A, AA, AAA (default: AA)
+    --max-steps <n>           Steps per persona when a goal is given
+    --max-time <s>            Seconds per persona when a goal is given
     --output <file>           Save JSON report to file
     --html                    Generate HTML report
     Available personas:
-      motor-impairment-tremor, low-vision-magnified, cognitive-adhd,
-      dyslexic-user, deaf-user, elderly-low-vision, color-blind-deuteranopia
+      ${listAccessibilityPersonas().join(", ")}
     Examples:
       cbrowser empathy-audit "https://example.com" \\
         --goal "complete checkout" \\
@@ -555,13 +575,13 @@ AI FRIENDLINESS - Audit sites for AI agent compatibility
       cbrowser webmcp-ready "https://demo.cbrowser.ai/mcp"
       cbrowser webmcp-ready "https://your-server.com/mcp" --api-key KEY --html
 
-  hunt-bugs <url>             Automatically find UX bugs on a page
+  hunt-bugs <url>             Automatically find UX bugs on a page (alias: hunt)
     --max-pages <n>           Max pages to crawl (default: 10)
     --timeout <ms>            Timeout in ms (default: 60000)
     Examples:
       cbrowser hunt-bugs "https://example.com"
 
-  competitive-benchmark       Compare UX across competitor sites
+  competitive-benchmark       Compare UX across competitor sites (needs an Anthropic API key)
     --sites <list>            Comma-separated site URLs (required)
     --goal <goal>             Task goal (required)
     --persona <name>          Persona to use (default: first-timer)
@@ -574,12 +594,12 @@ AI FRIENDLINESS - Audit sites for AI agent compatibility
         --sites "https://yoursite.com,https://competitor.com" \\
         --goal "sign up for free trial" --html
 
-ACCESSIBILITY (v2.5.0)
+ACCESSIBILITY
   a11y audit                  Run WCAG accessibility audit
     --url <url>               Navigate to URL first
   a11y audit [url]            Audit a specific URL
 
-TEST RECORDING (v2.5.0)
+TEST RECORDING
   record start                Start recording interactions
     --url <url>               Navigate to URL to begin recording
   record stop                 Stop recording and show actions
@@ -591,7 +611,7 @@ SCREEN CAPTURE (video/GIF — distinct from 'record', which captures actions)
   capture start <url>         Capture the screen to GIF/WebP/video
     --fps <n>                 Target frames per second (default: 10)
     --duration <5s>           Auto-stop after this long (5s, 2m, 1500ms)
-    --viewport <WxH>          Viewport size, e.g. 1280x720
+    --viewport <WxH>          Viewport size, e.g. 1280x720, or a size name (mobile, tablet, desktop...)
     --region <x,y,w,h>        Capture a fixed region instead of the viewport
     --element <selector>      Track an element; crop follows it as it moves
     --element-padding <n>     Expand the element box by n CSS px per side
@@ -625,13 +645,16 @@ SCREEN CAPTURE (video/GIF — distinct from 'record', which captures actions)
     and the still stretches are reported as frame_gaps rather than padded out.
     mp4 needs a full ffmpeg (CBROWSER_FFMPEG_PATH); the bundled one does webm.
 
-TEST EXPORT (v2.5.0)
+TEST EXPORT
   export junit <name> [output]   Export test results as JUnit XML
   export tap <name> [output]     Export test results as TAP format
+    <name> is a suite test-suite has run (its file name); each run is saved
 
-WEBHOOKS (v2.5.0)
-  webhook add <name> <url>    Add webhook notification
-    --events <events>         Comma-separated: test.pass,test.fail,journey.complete
+WEBHOOKS
+  webhook add <name> <url>    Add webhook notification (http or https)
+    --events <events>         test.pass,test.fail,journey.complete (default: test.fail);
+                              test-suite sends one per run, cognitive-journey one per
+                              journey; JSON, 10s timeout, no retries
     --format <format>         slack, discord, or generic
   webhook list                List configured webhooks
   webhook delete <name>       Delete a webhook
@@ -639,30 +662,37 @@ WEBHOOKS (v2.5.0)
 
 PERSONA QUESTIONNAIRE
   persona-questionnaire start        Build a persona from a behavioural questionnaire
-    --comprehensive                  All 26 traits (default: 8 core traits)
+    --comprehensive                  All 30 traits (default: 13 core traits)
     --name <name>                    Persona name (prompted if omitted)
     --output <file>                  Save answers to JSON
   persona-questionnaire list-traits  List available traits with descriptions
   persona-questionnaire lookup       Look up behaviours for a trait value
 
-PARALLEL EXECUTION (v2.5.0)
+PARALLEL EXECUTION
   parallel devices <url>      Run same URL across multiple devices
     --devices <list>          Comma-separated device names (default: all)
     --concurrency <n>         Max parallel browsers (default: 3)
+    --browser, --no-headless  The browser for every device
   parallel urls <urls>        Run same task across multiple URLs
     --concurrency <n>         Max parallel browsers (default: 3)
+    --device, --viewport, --browser, --no-headless   The browser for every URL
   parallel perf <urls>        Performance audit multiple URLs in parallel
     --concurrency <n>         Max parallel browsers (default: 3)
+    --device, --viewport, --browser, --no-headless   The browser for every URL
 
-NATURAL LANGUAGE (v3.0.0)
+NATURAL LANGUAGE
   run "<command>"             Execute natural language command
     Examples:
       cbrowser run "go to https://example.com"
       cbrowser run "click the login button"
       cbrowser run "type 'hello' in the search box"
   script <file>               Execute script file with natural language commands
+  scroll <top|bottom|up|down> [px]  Scroll the page (up/down default 300px)
+    --url <url>               Navigate to URL first
+    Note: without the daemon the next command reloads the page, so the
+          scroll position does not carry over; start the daemon first.
 
-VISUAL AI (v4.0.0)
+VISUAL AI
   ai find "<intent>"          Find element by semantic intent
     Examples:
       cbrowser ai find "the cheapest product"
@@ -670,23 +700,20 @@ VISUAL AI (v4.0.0)
       cbrowser ai find "search box"
   ai click "<intent>"         Find and click element by intent
 
-BUG HUNTER (v4.0.0)
-  hunt <url>                  Automatically find bugs on a page
-    --max-pages <n>           Max pages to crawl (default: 10)
-    --timeout <ms>            Timeout in ms (default: 60000)
-
-CROSS-BROWSER (v4.0.0)
+BROWSER DIFF
   diff <url>                  Compare page across browsers
     --browsers <list>         chromium,firefox,webkit (default: all)
+    --viewport <WxH>          Page size (default: 1920x1080)
+    --device <name>           Device preset (firefox cannot emulate a mobile one)
 
-CHAOS ENGINEERING (v4.0.0)
+CHAOS ENGINEERING
   chaos <url>                 Test app resilience
     --latency <ms>            Add network latency
     --offline                 Simulate offline mode
     --block <patterns>        Block URL patterns (comma-separated)
     --fail-api <pattern:status>  Fail specific API calls
 
-SMART RETRY & ASSERTIONS (v5.0.0)
+SMART RETRY & ASSERTIONS
   smart-click <selector>      Click with auto-retry and alternative selectors
     --url <url>               Navigate to URL first
     --max-retries <n>         Maximum retry attempts (default: 3)
@@ -705,7 +732,7 @@ SMART RETRY & ASSERTIONS (v5.0.0)
       cbrowser assert "'Login' button exists"
       cbrowser assert "page has 3 items"
 
-SELF-HEALING SELECTORS (v5.0.0)
+SELF-HEALING SELECTORS
   heal stats                  Show selector cache statistics
   heal list                   List all cached selector mappings
     --domain <domain>         Filter by domain
@@ -714,18 +741,22 @@ SELF-HEALING SELECTORS (v5.0.0)
   heal test <selector>        Test if a selector would be healed
     --url <url>               Navigate to URL first
 
-AI TEST GENERATION (v5.0.0)
+AI TEST GENERATION
   generate <url>              Analyze page and generate test scenarios
     --format <format>         Output: summary, cbrowser, playwright, all (default: summary)
     --output <file>           Save to file instead of stdout
   analyze <url>               Show page analysis without generating tests
+    --output <file>           Save the analysis as JSON
 
-MCP SERVER (v5.0.0)
+MCP SERVER
   mcp-server                  Start CBrowser as MCP server for Claude integration
                               Use with Claude Desktop or other MCP-compatible clients
   mcp-remote                  Start remote HTTP MCP server for claude.ai connectors
     --port <port>             Port to listen on (default: 3000)
     --host <host>             Host to bind to (default: 0.0.0.0)
+    --stateful                Use stateful session mode
+    Smart visual baselines and transport maps have no CLI command; they are the
+    MCP tools visual_baseline / visual_regression (smart mode) and transport_map.
 
 UNINSTALL
   uninstall                   Remove CBrowser data: credentials, sessions, captures
@@ -740,47 +771,58 @@ CLAUDE SKILL INSTALLATION & SYNC
                               Downloads latest skill files from GitHub
                               Run after 'npm update -g cbrowser' to stay in sync
                               Add to skill-index.json after first installation
-    --stateful                Use stateful session mode
 
-DAEMON MODE (v6.4.0)
+DAEMON MODE
   daemon start                Start background daemon (keeps browser running)
     --port <port>             Daemon port (default: 9222)
-    --timeout <min>           Idle timeout in minutes (default: 30)
+    --device <name>           Device the daemon's browser emulates
+    --viewport <WxH>          Page size of the daemon's browser
+    --timeout <min>           Idle timeout: minutes, or 90s / 45m / 2h (default: 30)
   daemon stop                 Stop the running daemon
-  daemon status               Check if daemon is running
+  daemon status               Check if daemon is running (exits 1 when it is not)
   daemon run                  Run daemon in foreground (internal use)
-    Note: When daemon is running, all commands automatically connect to it
-          instead of launching a new browser - much faster for iteration!
+    Note: while the daemon runs, navigate, click, fill, hover, type, press,
+          keyboard, screenshot, extract, run, scroll, evaluate, capture, har,
+          network and console use its browser. Commands that would open a second
+          browser on its profile (script, ai, explore, a11y, perf, visual,
+          drag, upload, reset and others) refuse until you stop it.
 
-API CONFIGURATION (v8.0.0)
+API CONFIGURATION
   config set-api-key <key>    Set Anthropic API key for cognitive journeys
   config show-api-key         Show configured API key (masked)
   config remove-api-key       Remove stored API key
   config set-model <model>    Set Claude model (default: claude-sonnet-5)
 
-LIGHTPANDA (v18.20.0) - High-Performance Headless Browser (OPT-IN ONLY)
+LIGHTPANDA - High-Performance Headless Browser (OPT-IN ONLY)
   lightpanda-status           Check Lightpanda availability and configuration
   lightpanda-setup            Show setup instructions with security warnings
     ⚠️ SECURITY NOTICE:
       • Lightpanda is BETA software with no security audit
       • Cloud mode exposes traffic to lightpanda.io servers
       • NEVER use for auth, credentials, or payments
-      • Requires explicit --lightpanda flag (not automatic)
+      • Used only by agent-ready-audit, and only with --lightpanda
     Environment Variables:
       LIGHTPANDA_ENDPOINT     WebSocket endpoint (e.g., ws://127.0.0.1:9222)
       LIGHTPANDA_TOKEN        Cloud API token (⚠️ data visible to lightpanda.io)
     Examples:
       cbrowser lightpanda-status
-      cbrowser screenshot https://example.com --lightpanda
       cbrowser agent-ready-audit https://example.com --lightpanda
 
+PRODUCT HELP
+  ask "<question>"            Ask the CBrowser docs a question; prints an AI answer and its sources
+    --context <text>          What you are looking at (a URL, a tool, a score)
+    --json                    Print the answer as JSON
+    Sends your question to cbrowser.ai. No account or API key; rate-limited.
+    Example:
+      cbrowser ask "Which persona should I use for a screen reader user?"
+
 DIAGNOSTICS
   version, -v, --version      Show version number
   status                      Show environment status and diagnostics
                               Displays data directories, browsers, config, heal cache
   doctor                      Check environment health (Node, Playwright, API key)
 
-ACCESSIBILITY
+OUTPUT MODES (accessibility)
   --no-color                  Disable all color output (also respects NO_COLOR env var)
   --plain                     Disable emoji, box-drawing, and unicode decorations
   --json-output               Output structured JSON (for scripts and screen readers)
@@ -792,11 +834,16 @@ STORAGE & CLEANUP
     --older-than <days>       Delete files older than N days (default: 7)
     --keep-screenshots <n>    Keep at least N screenshots (default: 10)
     --keep-journeys <n>       Keep at least N journeys (default: 5)
+    --keep-sessions <n>       Keep at least N sessions (default: 3)
   reset                       Clear persistent browser state (cookies, storage)
 
 OPTIONS
   --browser <type>            Browser: chromium, firefox, webkit (default: chromium)
-  --device <name>             Device preset: iphone-15, pixel-8, ipad-pro-12, etc.
+  --device <name>             Device preset: iphone-16, pixel-9, ipad-pro-13, ... ('device list')
+  --viewport <WxH>            Page size, e.g. 390x844; with --device it sets the size and
+                              the device keeps its pixel ratio, touch and user agent
+                              Size names work too (mobile, tablet, desktop-md...): size
+                              only; use --device for touch and a mobile user agent
   --geo <location>            Location preset or lat,lon coordinates
   --locale <locale>           Browser locale (e.g., en-US, fr-FR)
   --timezone <tz>             Timezone (e.g., America/New_York)
@@ -864,8 +911,27 @@ const COMMAND_ALIASES = {
     "chaos-test": "chaos",
     "generate-tests": "generate",
     journey: "explore",
+    // Dispatch aliases that `help` used to resolve by text search, so
+    // `help stats` showed "heal stats" (audit 2026-10-21).
+    hunt: "hunt-bugs",
+    flaky: "flaky-check",
+    repair: "repair-tests",
+    stats: "storage",
 };
 /** Escape a string for safe use inside a RegExp. */
+/**
+ * Print a command result that is data. Under --json-output it becomes the
+ * envelope's `data`, untouched; otherwise pretty JSON on stdout. Before 20.0
+ * extract went through the text capture, which stored its JSON as text lines
+ * (audit 2026-10-21).
+ */
+function printData(command, data) {
+    if (getOutputOptions().json) {
+        emitJson({ success: true, command, data, meta: { version: VERSION } });
+        return;
+    }
+    console.log(JSON.stringify(data, null, 2));
+}
 function escapeForRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -970,15 +1036,35 @@ function showCommandHelp(command) {
  * against a second browser while the daemon holds the first. Anything listed
  * here must either be daemon-routed or refuse to run.
  */
+/** What `extract` can return (browser.extract). */
+const EXTRACT_KINDS = ["text", "links", "headings", "images", "forms"];
 const DRIVES_THE_PAGE = [
     "navigate", "click", "fill", "hover", "screenshot", "extract", "run",
     "keyboard", "press", "type", "evaluate", "eval", "drag", "upload",
     "smart-click", "dismiss-overlay", "assert",
+    // These also launch the shared profile the daemon holds, so they acted on
+    // a page the user was not watching or failed on its lock (audit
+    // 2026-10-21). reset deleted the profile under the daemon, which wrote its
+    // cookies back on exit.
+    "script", "ai", "explore", "analyze", "generate", "hunt", "hunt-bugs",
+    "chaos", "a11y", "perf", "visual", "reset",
 ];
-const GLOBAL_FLAGS = [
-    "url", "browser", "device", "headless", "persistent", "restore",
-    "locale", "timezone", "geo", "verbose", "help", "no-color", "quiet", "json",
+/**
+ * Flags the shared CBrowser construction consumes, for every command that uses
+ * it. One list, spread into each command's set below: when this list was copied
+ * into each set, --viewport (2026-10-21) reached some commands and was refused
+ * by evaluate and keyboard.
+ */
+const SHARED_BROWSER_FLAGS = [
+    "url", "browser", "device", "viewport", "headless", "persistent", "restore",
+    "locale", "timezone", "geo", "verbose",
 ];
+/**
+ * Globals every command accepts. --plain and --json-output are the documented
+ * output modes (src/output.ts); before 2026-10-21 the validated commands
+ * rejected them.
+ */
+const GLOBAL_FLAGS = [...SHARED_BROWSER_FLAGS, "help", "no-color", "json", "plain", "json-output"];
 /**
  * Declared options per command.
  *
@@ -1009,25 +1095,19 @@ const COMMAND_FLAGS = {
     evaluate: ["file", "arg", "json", "raw", "wait-for", "timeout", "expect-truthy", "force"],
     eval: ["file", "arg", "json", "raw", "wait-for", "timeout", "expect-truthy", "force"],
     keyboard: ["delay", "selector", "hold", "repeat", "text", "force"],
+    // test-suite and cognitive-journey list only the flags their code reads
+    // (measured 2026-10-21). They used to declare every report command's flags,
+    // so `test-suite --persona x` passed validation and did nothing.
+    ask: ["context", "json"],
     "test-suite": [
         "capture", "capture-fps", "capture-format", "capture-out",
-        "api-key", "auto-apply", "comprehensive", "concurrency", "continue-on-failure",
-        "delay", "disabilities", "dry-run", "exclude", "fuzzy-match", "goal",
-        "html", "include", "inline", "length", "lightpanda", "max-pages", "max-steps",
-        "max-time", "min-coverage", "name", "no-vision", "oauth-token", "output",
-        "persona", "retries", "runs", "screenshot-on-failure", "sensitivity",
-        "sitemap", "sites", "start", "step-through", "tests", "threshold",
-        "threshold-cls", "threshold-fcp", "threshold-lcp", "threshold-tbt",
-        "threshold-ttfb", "threshold-tti", "timeout", "trait", "urls", "value",
-        "verify", "wcag-level", "geolocation", "geo-region",
+        "continue-on-failure", "dry-run", "fuzzy-match", "html", "inline", "output",
+        "screenshot-on-failure", "step-through", "timeout",
     ],
     "cognitive-journey": [
         "capture", "capture-fps", "capture-format", "capture-out",
-        "api-key", "comprehensive", "concurrency", "disabilities", "goal", "html",
-        "length", "lightpanda", "max-steps", "max-time", "name", "no-vision",
-        "oauth-token", "output", "persona", "sites", "start", "timeout", "trait",
-        "urls", "value", "wcag-level", "geolocation", "geo-region", "vision",
-        "trace", "replay-trace",
+        "goal", "persona", "start", "max-steps", "max-time", "no-vision", "output",
+        "geolocation", "trace", "replay-trace",
     ],
 };
 /**
@@ -1044,11 +1124,29 @@ const UNVALIDATED_REASON = "not yet declared - see COMMAND_FLAGS in src/cli.ts";
  * Fails on the FIRST invalid flag with the command's full accepted set, so a
  * typo is a one-command fix rather than a guessing game.
  */
+/**
+ * Every flag a validated command accepts: its declared flags, the globals, and
+ * both halves of each on/off pair. The parser turns --no-x into "no-x" and
+ * "x"=false, so declaring either half must accept both; before 2026-10-21
+ * --no-color failed with "does not support --color", a flag the user never
+ * typed. The capture, evaluate and keyboard gates read this same set, so one
+ * command line can no longer pass one gate and fail the other.
+ */
+function allowedFlags(command) {
+    const allowed = new Set([...(COMMAND_FLAGS[command] ?? []), ...GLOBAL_FLAGS]);
+    for (const flag of [...allowed]) {
+        if (flag.startsWith("no-"))
+            allowed.add(flag.slice(3));
+        else
+            allowed.add(`no-${flag}`);
+    }
+    return allowed;
+}
 function validateCommandFlags(command, options) {
     const declared = COMMAND_FLAGS[command];
     if (!declared)
         return; // UNVALIDATED_REASON
-    const allowed = new Set([...declared, ...GLOBAL_FLAGS]);
+    const allowed = allowedFlags(command);
     const unknown = Object.keys(options).filter((flag) => !allowed.has(flag));
     if (unknown.length === 0)
         return;
@@ -1073,14 +1171,66 @@ function captureStatePath() {
     return join(getPaths().videosDir, "active.json");
 }
 /** Parse "5s", "2m", "1500ms" or a bare millisecond count. */
+/**
+ * A numeric option, checked. parseInt/parseFloat let "abc" through as NaN and
+ * read "0.2" as 0 (flaky-check --threshold flagged every test), so a value
+ * outside the range or not a number exits 1 naming the flag (audit F21).
+ */
+function numberOption(flag, value, fallback, range) {
+    if (value === undefined)
+        return fallback;
+    const n = typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+    if (!Number.isFinite(n) || n < range.min || n > range.max) {
+        console.error(`Error: --${flag} must be a number from ${range.min} to ${range.max}, got "${String(value)}"`);
+        process.exit(1);
+    }
+    return n;
+}
+/** An option from a fixed set of words; anything else exits 1 (audit F21). */
+function enumOption(flag, value, allowed) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        console.error(`Error: --${flag} must be ${allowed.join(", ")}, got "${String(value)}"`);
+        process.exit(1);
+    }
+    return value;
+}
+/**
+ * Where --html writes when --output names the JSON report. The HTML used to
+ * take `output.replace(".json", ".html")`, so `--output report` or
+ * `--output report.html` wrote the HTML over the JSON (audit 2026-10-21).
+ */
+function htmlReportPath(output, fallback) {
+    if (typeof output !== "string" || output === "")
+        return fallback;
+    const base = output.replace(/\.(json|html?)$/i, "");
+    const html = `${base}.html`;
+    return html === output ? `${base}.report.html` : html;
+}
+/**
+ * A --timeout value in milliseconds: a bare number is ms, and 5s / 2m / 1h work.
+ * Exits 1 on anything else rather than guessing.
+ */
+function timeoutOption(value, fallbackMs) {
+    if (value === undefined)
+        return fallbackMs;
+    try {
+        return parseDurationMs(String(value));
+    }
+    catch {
+        console.error(`Error: --timeout must be a positive number of milliseconds or a duration (5s, 2m, 1h), got "${String(value)}"`);
+        process.exit(1);
+    }
+}
 function parseDurationMs(input) {
-    const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m)?$/i.exec(input.trim());
+    const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/i.exec(input.trim());
     if (!match) {
-        throw new Error(`Invalid duration "${input}" - use 5s, 2m, 1500ms or a millisecond count`);
+        throw new Error(`Invalid duration "${input}" - use 5s, 2m, 1h, 1500ms or a millisecond count`);
     }
     const value = parseFloat(match[1]);
     const unit = (match[2] || "ms").toLowerCase();
-    const ms = unit === "s" ? value * 1000 : unit === "m" ? value * 60_000 : value;
+    const ms = unit === "s" ? value * 1000 : unit === "m" ? value * 60_000 : unit === "h" ? value * 3_600_000 : value;
     if (ms <= 0)
         throw new Error(`Invalid duration "${input}" - must be greater than zero`);
     return Math.round(ms);
@@ -1099,9 +1249,13 @@ function parseFormats(input) {
 }
 /** Parse "1280x720". */
 function parseViewportSize(input) {
+    const preset = VIEWPORT_PRESETS.find((p) => p.name === input.trim().toLowerCase());
+    if (preset)
+        return { width: preset.width, height: preset.height };
     const match = /^(\d+)x(\d+)$/i.exec(input.trim());
-    if (!match)
-        throw new Error(`Invalid viewport "${input}" - use WIDTHxHEIGHT, e.g. 1280x720`);
+    if (!match) {
+        throw new Error(`Invalid viewport "${input}" - use WIDTHxHEIGHT, e.g. 1280x720, or a size name: ${VIEWPORT_PRESETS.map((p) => p.name).join(", ")}`);
+    }
     const width = parseInt(match[1], 10);
     const height = parseInt(match[2], 10);
     if (width <= 0 || height <= 0) {
@@ -1139,36 +1293,23 @@ function parseRegion(input) {
  * confident "✓" for a capture the user did not ask for, which is worse than
  * an error. The globals are the ones the CLI itself consumes before dispatch.
  */
-const CAPTURE_FLAGS = new Set([
-    // capture-specific
-    "fps", "duration", "format", "out", "name", "quality", "max-frames",
-    "viewport", "region", "element", "element-padding",
-    "contact-sheet", "attention-overlay", "overlay-persona", "overlay-goal",
-    "after", "after-element", "after-delay",
-    "until-element", "until-element-gone", "until-idle", "timeout",
-    // globals honoured by the shared CBrowser construction
-    "url", "browser", "device", "headless", "persistent", "restore",
-    "locale", "timezone", "geo", "verbose",
-]);
+const CAPTURE_FLAGS = allowedFlags("capture");
 /**
  * Resolve `--device` to a real preset key, or exit naming the bad value.
  *
- * CBrowser silently ignores an unknown device name (browser.ts: the preset
- * lookup is inside the `if`), which would hand back a 1280x800 desktop capture
- * for `--device "iPhone 14"` and call it success. Spaces and case are
- * normalised so "iPhone 15" finds "iphone-15".
+ * `capture start` checks here, before it builds anything. Every other command
+ * gets the same check from CBrowser.launch() (src/devices.ts resolveDevice);
+ * before 2026-10-21 the browser skipped names it did not know and rendered
+ * 1280x800 desktop. Case and spaces do not matter: "iPhone 15" is "iphone-15".
  */
 function resolveDevicePreset(value) {
-    const normalised = value.trim().toLowerCase().replace(/\s+/g, "-");
-    if (DEVICE_PRESETS[normalised])
-        return normalised;
-    const known = Object.keys(DEVICE_PRESETS);
-    const stem = normalised.replace(/-?\d+.*$/, "");
-    const close = known.filter((k) => k.startsWith(stem) && stem.length > 0);
+    const resolved = resolveDevice(value);
+    if ("key" in resolved)
+        return resolved.key;
     console.error(`Error: unknown --device "${value}"`);
-    if (close.length > 0)
-        console.error(`  Did you mean: ${close.join(", ")}?`);
-    console.error(`  Available presets: ${known.join(", ")}`);
+    if (resolved.suggestions.length > 0)
+        console.error(`  Did you mean: ${resolved.suggestions.join(", ")}?`);
+    console.error(`  'cbrowser device list' shows all ${Object.keys(DEVICE_PRESETS).length} presets; --viewport WIDTHxHEIGHT sets any size.`);
     process.exit(1);
 }
 /** Reject any flag `capture start` cannot honour, naming it. */
@@ -1505,12 +1646,19 @@ function failCaptureCommand(message) {
  * later `cbrowser click` or `cbrowser fill` appear in the recording.
  */
 async function runCaptureStartViaDaemon(url, options) {
+    // The daemon's page size and device are fixed when it starts. These were
+    // accepted here and dropped, so a capture "at 390x844" recorded at the
+    // daemon's size and reported success (audit 2026-10-21).
+    for (const flag of ["viewport", "device", "browser"]) {
+        if (options[flag] !== undefined) {
+            failCaptureCommand(`--${flag} cannot change a running daemon's browser. Restart it with: cbrowser daemon stop && cbrowser daemon start --${flag} <value>`);
+        }
+    }
     const target = buildCaptureTarget(options);
     const triggers = buildCaptureTriggers(options);
     const slug = slugFor(options);
     const response = await sendToDaemon("captureStart", {
         url,
-        engine: options.browser === "firefox" ? "firefox" : options.browser === "webkit" ? "webkit" : "chromium",
         options: {
             fps: options.fps !== undefined ? Number(options.fps) : undefined,
             quality: options.quality !== undefined ? Number(options.quality) : undefined,
@@ -1520,6 +1668,16 @@ async function runCaptureStartViaDaemon(url, options) {
             contactSheet: options["contact-sheet"] === true,
             slug,
             target,
+            // Plain strings, so the overlay crosses the HTTP boundary intact; the
+            // daemon path used to drop it.
+            ...(options["attention-overlay"]
+                ? {
+                    saliencyOverlay: {
+                        ...(typeof options["overlay-persona"] === "string" ? { persona: options["overlay-persona"] } : {}),
+                        ...(typeof options["overlay-goal"] === "string" ? { goal: options["overlay-goal"] } : {}),
+                    },
+                }
+                : {}),
             ...triggers,
         },
     });
@@ -1750,11 +1908,7 @@ function reportAutoCapture(capture) {
 // evaluate — run JavaScript in the page
 // =========================================================================
 /** Flags `evaluate` understands; anything else is rejected rather than ignored. */
-const EVALUATE_FLAGS = new Set([
-    "file", "arg", "json", "raw", "wait-for", "timeout", "expect-truthy", "force",
-    "url", "browser", "device", "headless", "persistent", "restore",
-    "locale", "timezone", "geo", "verbose",
-]);
+const EVALUATE_FLAGS = allowedFlags("evaluate");
 /**
  * `--force` is a bare flag, but the parser gives any flag the next non-flag
  * word as its value, so `evaluate --force "document.title"` reads the SCRIPT as
@@ -1787,61 +1941,14 @@ function repeatedFlag(name) {
     return values;
 }
 /**
- * Evaluate a script in the page, accepting all three shapes people write.
- *
- * `--file` exists because multi-line scripts die in shell quoting, so it has to
- * accept real scripts - `const`, `let`, an explicit `return` - not only a
- * single expression. The source is compiled inside the page as a function
- * body: a bare expression gets an implicit return, a statement body keeps its
- * own, and a function/arrow literal is called with the arguments.
- */
-async function evaluateScript(page, script, args) {
-    const source = script.trim();
-    // A function or arrow literal is called with the arguments directly.
-    const isCallable = /^(async\s+)?function\b/.test(source) || /=>/.test(source);
-    return page.evaluate((payload) => {
-        if (payload.callable) {
-            const fn = (0, eval)(`(${payload.src})`);
-            return fn(...payload.a);
-        }
-        const compile = (src) => {
-            // 1. A bare expression: implicit return.
-            try {
-                return new Function("args", `return (${src});`);
-            }
-            catch { /* not an expression */ }
-            // 2. Statements with no explicit return: return the final expression,
-            //    which is what a REPL and the old one-arg form both did.
-            if (!/\breturn\b/.test(src)) {
-                const trimmed = src.replace(/;\s*$/, "");
-                const split = Math.max(trimmed.lastIndexOf(";"), trimmed.lastIndexOf("\n"));
-                if (split > -1) {
-                    const head = trimmed.slice(0, split + 1);
-                    const tail = trimmed.slice(split + 1).trim();
-                    if (tail) {
-                        try {
-                            return new Function("args", `${head}\nreturn (${tail});`);
-                        }
-                        catch { /* the tail is not an expression either */ }
-                    }
-                }
-            }
-            // 3. Statements as written. Any syntax error surfaces from here, which
-            //    is the error the user should actually see.
-            return new Function("args", src);
-        };
-        return compile(payload.src)(payload.a);
-    }, { src: source, a: args, callable: isCallable });
-}
-/**
- * Run JavaScript in the page.
- *
- * The bare `evaluate "<js>"` form is unchanged. Everything else is additive:
- * a script from a file (shell quoting mangles multi-line scripts), JSON
- * arguments (so a script is reusable instead of string-interpolated), an
- * explicit output mode, and an assertion mode for CI.
+ * Validate evaluate's flags and build the script, its arguments and the wait.
+ * Exits with a message on any error. Shared by the local path and the daemon
+ * route so they cannot drift: before 2026-10-21 the daemon route sent only the
+ * script, so --arg, --url, --wait-for, --timeout, --raw, --json and
+ * --expect-truthy did nothing when a daemon was running, and an
+ * --expect-truthy CI check passed on a falsy result.
  */
-async function runEvaluate(browser, args, options) {
+async function prepareEvaluate(args, options) {
     const unknown = Object.keys(options).filter((f) => !EVALUATE_FLAGS.has(f));
     if (unknown.length > 0) {
         console.error(`Error: 'evaluate' does not support ${unknown.map((f) => `--${f}`).join(", ")}`);
@@ -1910,45 +2017,53 @@ async function runEvaluate(browser, args, options) {
     }
     // Said on stderr so stdout stays exactly the result (--raw / --json pipes).
     console.error("⚠ Red zone: running caller-supplied page script (--force)");
-    if (options.url)
-        await browser.navigate(options.url);
-    const page = await browser.getPage();
-    if (typeof options["wait-for"] === "string") {
-        // Bounded by the caller, not by a constant.
-        //
-        // This was a hardcoded 30s, which is two defects wearing one number. For a
-        // user it meant no way to fail fast on a page that renders in 200ms and no
-        // way to wait longer on one that does not. For the suite it meant the test
-        // asserting that a never-matching selector fails loudly spent 30 of its 60
-        // second budget deliberately waiting, so browser launch plus teardown had
-        // to fit in the rest -- which held when the test ran alone and did not when
-        // the full suite ran browsers in parallel. The test read as flaky and was
-        // not: it was structurally tight against a constant it could not reach.
-        // (2026-08-02)
-        // Falls back to the configured default rather than a fresh literal.
-        // `CBROWSER_TIMEOUT` is documented in --help as "Default timeout in ms" and
-        // config.ts already resolves it; a second hardcoded 30_000 here would mean
-        // the documented env var silently did not apply to this one wait.
+    const waitFor = typeof options["wait-for"] === "string" ? options["wait-for"] : undefined;
+    let waitMs = 30_000;
+    if (waitFor) {
         const { getDefaultConfig } = await import("./config.js");
         const configuredMs = getDefaultConfig().timeout ?? 30_000;
-        const waitMs = typeof options.timeout === "string" ? Number(options.timeout)
-            : typeof options.timeout === "number" ? options.timeout
-                : configuredMs;
+        waitMs = typeof options.timeout === "number" ? options.timeout : timeoutOption(options.timeout, configuredMs);
         if (!Number.isFinite(waitMs) || waitMs <= 0) {
             console.error(`Error: --timeout must be a positive number of milliseconds, got: ${options.timeout}`);
             process.exit(1);
         }
+    }
+    return { script, evalArgs, waitFor, waitMs };
+}
+/** Print an evaluate result the same way for the local path and the daemon. */
+function printEvaluateResult(result, options) {
+    if (options.raw === true) {
+        console.log(String(result));
+    }
+    else if (options.json === true) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        // Legacy default, kept so the existing one-arg form behaves identically.
+        console.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+    }
+    if (options["expect-truthy"] === true && !result) {
+        console.error(`✗ Expected a truthy result, got ${JSON.stringify(result)}`);
+        process.exit(1);
+    }
+}
+async function runEvaluate(browser, args, options) {
+    const prep = await prepareEvaluate(args, options);
+    if (options.url)
+        await browser.navigate(options.url);
+    const page = await browser.getPage();
+    if (prep.waitFor) {
         try {
-            await page.waitForSelector(options["wait-for"], { timeout: waitMs });
+            await page.waitForSelector(prep.waitFor, { timeout: prep.waitMs });
         }
         catch {
-            console.error(`✗ Timed out waiting for selector: ${options["wait-for"]} (after ${waitMs}ms)`);
+            console.error(`✗ Timed out waiting for selector: ${prep.waitFor} (after ${prep.waitMs}ms)`);
             process.exit(1);
         }
     }
     let result;
     try {
-        result = await evaluateScript(page, script, evalArgs);
+        result = await evaluateScript(page, prep.script, prep.evalArgs);
     }
     catch (e) {
         const error = e;
@@ -1958,20 +2073,7 @@ async function runEvaluate(browser, args, options) {
             console.error(error.stack.split("\n").slice(1).join("\n"));
         process.exit(1);
     }
-    if (options.raw === true) {
-        console.log(String(result));
-    }
-    else if (options.json === true) {
-        console.log(JSON.stringify(result, null, 2));
-    }
-    else {
-        // Legacy default, kept so the existing one-arg form behaves identically.
-        console.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
-    }
-    if (options["expect-truthy"] === true && !result) {
-        console.error(`✗ Expected a truthy result, got ${JSON.stringify(result)}`);
-        process.exit(1);
-    }
+    printEvaluateResult(result, options);
 }
 // =========================================================================
 // keyboard — sequences, chords and held modifiers
@@ -2069,12 +2171,26 @@ function parseKeyboardToken(token, literal = false) {
     }
     return { kind: "text", text: token };
 }
+/**
+ * --delay and --repeat for keyboard, checked the same way whether the keys go
+ * to the local browser or the daemon. The daemon route used to skip this, so
+ * --repeat 0 typed nothing and reported success, and --repeat 2.5 ran 3 passes.
+ */
+function parseKeyboardNumbers(options) {
+    const delay = options.delay !== undefined ? Number(options.delay) : 50;
+    if (!Number.isFinite(delay) || delay < 0) {
+        console.error(`Error: --delay must be a non-negative number (got "${String(options.delay)}")`);
+        process.exit(1);
+    }
+    const repeat = options.repeat !== undefined ? Number(options.repeat) : 1;
+    if (!Number.isInteger(repeat) || repeat < 1) {
+        console.error(`Error: --repeat must be a positive integer (got "${String(options.repeat)}")`);
+        process.exit(1);
+    }
+    return { delay, repeat };
+}
 /** Flags `keyboard` understands. */
-const KEYBOARD_FLAGS = new Set([
-    "delay", "selector", "hold", "repeat", "text", "force",
-    "url", "browser", "device", "headless", "persistent", "restore",
-    "locale", "timezone", "geo", "verbose",
-]);
+const KEYBOARD_FLAGS = allowedFlags("keyboard");
 /**
  * Drive a keyboard sequence.
  *
@@ -2094,16 +2210,7 @@ async function runKeyboard(browser, args, options) {
         console.error("  Run 'cbrowser help keyboard' for options");
         process.exit(1);
     }
-    const delay = options.delay !== undefined ? Number(options.delay) : 50;
-    if (!Number.isFinite(delay) || delay < 0) {
-        console.error(`Error: --delay must be a non-negative number (got "${String(options.delay)}")`);
-        process.exit(1);
-    }
-    const repeat = options.repeat !== undefined ? Number(options.repeat) : 1;
-    if (!Number.isInteger(repeat) || repeat < 1) {
-        console.error(`Error: --repeat must be a positive integer (got "${String(options.repeat)}")`);
-        process.exit(1);
-    }
+    const { delay, repeat } = parseKeyboardNumbers(options);
     const hold = typeof options.hold === "string"
         ? options.hold.split("+").map((m) => m.trim()).filter(Boolean)
         : [];
@@ -2613,8 +2720,29 @@ function parseGeoLocation(location) {
     }
     return null;
 }
+/**
+ * `scroll <top|bottom|up|down> [px]` is `run "scroll ..."`: the same executor,
+ * the same daemon route. The CLI had no way to scroll at all (audit 2026-10-21,
+ * daemon lane: the likely cause of a screenshot stuck at the top of the page).
+ */
+function rewriteScroll(parsed) {
+    if (parsed.command !== "scroll")
+        return parsed;
+    const [where, px] = parsed.args;
+    const dir = (where ?? "").toLowerCase();
+    let nl;
+    if ((dir === "top" || dir === "bottom") && px === undefined)
+        nl = `scroll to ${dir}`;
+    else if ((dir === "up" || dir === "down") && (px === undefined || /^\d+$/.test(px)))
+        nl = `scroll ${dir}${px ? ` ${px}` : ""}`;
+    if (!nl) {
+        console.error("Usage: cbrowser scroll <top|bottom|up|down> [pixels]   (default 300 for up/down)");
+        process.exit(1);
+    }
+    return { command: "run", args: [nl], options: parsed.options };
+}
 async function main() {
-    const { command, args, options } = parseArgs(process.argv.slice(2));
+    const { command, args, options } = rewriteScroll(parseArgs(process.argv.slice(2)));
     // Initialize accessible output system (v18.54.0)
     const outputOpts = detectOutputOptions(options);
     setOutputOptions(outputOpts);
@@ -2656,6 +2784,35 @@ async function main() {
         // path unreachable from a shell no matter what the checks found.
         process.exit(process.exitCode ?? 0);
     }
+    // ask: product help from the CBrowser docs (src/help-client.ts). No browser.
+    if (command === "ask") {
+        const question = args.join(" ").trim();
+        if (!question) {
+            console.error('Usage: cbrowser ask "<question>" [--context <text>] [--json]');
+            console.error('  e.g. cbrowser ask "How do I test my site on an iPhone?"');
+            process.exit(1);
+        }
+        const { askCbrowser } = await import("./help-client.js");
+        try {
+            const r = await askCbrowser(question, { context: typeof options.context === "string" ? options.context : undefined });
+            if (options.json === true || getOutputOptions().json) {
+                printData("ask", { question: r.question, answer: r.answer, sources: r.sources });
+            }
+            else {
+                console.log(r.answer);
+                if (r.sources.length > 0) {
+                    console.log("\nSources:");
+                    for (const s of r.sources)
+                        console.log(`  - ${s.split("\n")[0].slice(0, 120)}`);
+                }
+            }
+            process.exit(0);
+        }
+        catch (e) {
+            console.error(`Error: ${e.message}`);
+            process.exit(1);
+        }
+    }
     // MCP Server mode - runs before browser instantiation
     if (command === "mcp-server") {
         console.error("🔌 Starting CBrowser MCP Server...");
@@ -2799,17 +2956,10 @@ async function main() {
             console.log("Creating ~/.claude/skills directory...");
             fs.mkdirSync(skillsDir, { recursive: true });
         }
-        // Check if skill exists
-        if (fs.existsSync(skillDir)) {
-            console.log("CBrowser skill already exists. Updating...");
-            fs.rmSync(skillDir, { recursive: true });
-        }
-        // Create directories
-        console.log("Creating skill directory structure...");
-        fs.mkdirSync(path.join(skillDir, "Workflows"), { recursive: true });
-        fs.mkdirSync(path.join(skillDir, "Tools"), { recursive: true });
-        fs.mkdirSync(path.join(skillDir, ".memory", "sessions"), { recursive: true });
-        // Download files using native fetch (cross-platform, better error handling)
+        // Download everything first and change nothing unless every file arrived.
+        // This used to delete the installed skill (its .memory/sessions included)
+        // before downloading, then print "Installed Successfully" even when every
+        // download failed (audit 2026-10-21).
         console.log("Downloading skill files...");
         const files = [
             "SKILL.md",
@@ -2826,22 +2976,35 @@ async function main() {
             "Workflows/Journey.md",
             "Tools/CBrowser.ts",
         ];
+        const downloaded = new Map();
+        const failed = [];
         for (const file of files) {
             try {
                 const url = `${repoUrl}/skill/${file}`;
-                const dest = path.join(skillDir, file);
                 console.log(`  - ${file}`);
-                const response = await fetch(url);
+                const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
                 if (!response.ok) {
                     throw new Error(`HTTP ${response.status}`);
                 }
-                const content = await response.text();
-                fs.writeFileSync(dest, content, "utf-8");
+                downloaded.set(file, await response.text());
             }
             catch (e) {
-                console.log(`  Warning: Could not download ${file} (${e.message})`);
+                failed.push(`${file} (${e.message})`);
             }
         }
+        if (failed.length > 0) {
+            console.error(`✗ ${failed.length} of ${files.length} files could not be downloaded; the installed skill was left unchanged:`);
+            for (const f of failed)
+                console.error(`  ${f}`);
+            process.exit(1);
+        }
+        console.log(fs.existsSync(skillDir) ? "Updating the installed skill..." : "Creating skill directory structure...");
+        fs.mkdirSync(path.join(skillDir, "Workflows"), { recursive: true });
+        fs.mkdirSync(path.join(skillDir, "Tools"), { recursive: true });
+        fs.mkdirSync(path.join(skillDir, ".memory", "sessions"), { recursive: true });
+        for (const [file, content] of downloaded) {
+            fs.writeFileSync(path.join(skillDir, file), content, "utf-8");
+        }
         console.log(`
 ╔═══════════════════════════════════════════════════════════════╗
 ║              CBrowser Skill Installed Successfully!           ║
@@ -2868,9 +3031,69 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
         const port = parseInt(options.port) || 9222;
         switch (subCommand) {
             case "start": {
+                // The daemon's browser takes its device and size from here. Both are
+                // checked now: a bad value inside the detached daemon would only show
+                // up as a daemon that failed to start.
+                const launchArgs = [];
+                if (typeof options.device === "string")
+                    launchArgs.push("--device", resolveDevicePreset(options.device));
+                if (typeof options.viewport === "string") {
+                    try {
+                        parseViewportList(options.viewport);
+                    }
+                    catch (e) {
+                        console.error(`Error: ${e.message}`);
+                        process.exit(1);
+                    }
+                    launchArgs.push("--viewport", options.viewport);
+                }
+                // The rest of the shared browser settings. daemon start used to forward
+                // only --device and --viewport, so --browser firefox or --no-headless
+                // silently gave a headless chromium daemon.
+                if (typeof options.browser === "string") {
+                    if (!["chromium", "firefox", "webkit"].includes(options.browser)) {
+                        console.error(`Error: --browser must be chromium, firefox or webkit, got: ${options.browser}`);
+                        process.exit(1);
+                    }
+                    launchArgs.push("--browser", options.browser);
+                }
+                if (options.headless === false)
+                    launchArgs.push("--no-headless");
+                for (const flag of ["locale", "timezone"]) {
+                    if (typeof options[flag] === "string")
+                        launchArgs.push(`--${flag}`, options[flag]);
+                }
+                if (typeof options.geo === "string") {
+                    if (!parseGeoLocation(options.geo)) {
+                        console.error(`Error: invalid --geo: ${options.geo} (a preset name or lat,lon)`);
+                        process.exit(1);
+                    }
+                    launchArgs.push("--geo", options.geo);
+                }
+                // --timeout: a bare number is minutes, as the help has always said;
+                // 90s / 45m / 2h also work. It used to be accepted and ignored.
+                if (options.timeout !== undefined) {
+                    const raw = String(options.timeout).trim();
+                    let ms;
+                    try {
+                        ms = /^\d+(\.\d+)?$/.test(raw) ? Math.round(parseFloat(raw) * 60_000) : parseDurationMs(raw);
+                    }
+                    catch {
+                        console.error(`Error: --timeout must be a positive number of minutes or a duration (90s, 45m, 2h), got "${raw}"`);
+                        process.exit(1);
+                    }
+                    if (!(ms > 0)) {
+                        console.error(`Error: --timeout must be greater than zero, got: ${raw}`);
+                        process.exit(1);
+                    }
+                    launchArgs.push("--idle-timeout-ms", String(ms));
+                }
                 console.log("🚀 Starting CBrowser daemon...");
-                const result = await startDaemon(port);
+                const result = await startDaemon(port, launchArgs);
                 console.log(result.success ? `✓ ${result.message}` : `✗ ${result.message}`);
+                if (result.alreadyRunning && launchArgs.length > 0) {
+                    console.error("⚠ The browser flags were not applied: the daemon was already running. Run cbrowser daemon stop first.");
+                }
                 process.exit(result.success ? 0 : 1);
                 break;
             }
@@ -2878,13 +3101,14 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 console.log("🛑 Stopping CBrowser daemon...");
                 const result = await stopDaemon();
                 console.log(result.success ? `✓ ${result.message}` : `✗ ${result.message}`);
-                process.exit(0);
+                process.exit(result.success ? 0 : 1);
                 break;
             }
             case "status": {
                 const status = await getDaemonStatus();
                 console.log(status);
-                process.exit(0);
+                // Non-zero when nothing is running, so `cbrowser daemon status && ...` works.
+                process.exit((await isDaemonRunning()) ? 0 : 1);
                 break;
             }
             case "run": {
@@ -2894,10 +3118,16 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     : options.browser === "webkit" ? "webkit"
                         : "chromium";
                 // runDaemonServer will merge with defaults internally
+                const runViewport = typeof options.viewport === "string" ? parseViewportList(options.viewport)[0] : undefined;
                 await runDaemonServer({
                     browser: browserType,
                     headless: options.headless !== false && options.headless !== "false",
-                }, port);
+                    ...(typeof options.device === "string" ? { device: options.device } : {}),
+                    ...(runViewport ? { viewportWidth: runViewport.width, viewportHeight: runViewport.height, viewportOverride: runViewport } : {}),
+                    ...(typeof options.locale === "string" ? { locale: options.locale } : {}),
+                    ...(typeof options.timezone === "string" ? { timezone: options.timezone } : {}),
+                    ...(typeof options.geo === "string" && parseGeoLocation(options.geo) ? { geolocation: parseGeoLocation(options.geo) } : {}),
+                }, port, typeof options["idle-timeout-ms"] === "string" ? Number(options["idle-timeout-ms"]) : undefined);
                 return;
             }
             default:
@@ -2918,21 +3148,35 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
         "keyboard", "press", "type", "evaluate", "eval",
     ];
     if (daemonRunning && INTERACTION_COMMANDS.includes(command)) {
-        console.log("🔌 Connected to running daemon");
-        const daemonCommand = command;
+        // Status on stderr: stdout carries only the command's result, so piping
+        // it (--raw, --json) works the same with and without a daemon.
+        console.error("🔌 Connected to running daemon");
+        // The daemon's browser keeps the settings it started with; a flag on a
+        // command it runs cannot change them, so say so instead of ignoring it.
+        const browserFlags = ["device", "viewport", "browser", "headless", "locale", "timezone", "geo"]
+            .filter((f) => options[f] !== undefined);
+        if (browserFlags.length > 0) {
+            console.error(`⚠ ${browserFlags.map((f) => `--${f}`).join(", ")} do not apply to commands the daemon runs: its browser keeps the settings it started with.`);
+            console.error("  To change them: cbrowser daemon stop, then cbrowser daemon start with those flags");
+        }
+        // The daemon knows "evaluate"; "eval" reached it unchanged and failed.
+        const daemonCommand = command === "eval" ? "evaluate" : command;
         let daemonArgs = {};
+        // --url means "act on this page" for every routed command; the daemon
+        // navigates first, as the local path does.
+        const urlArg = typeof options.url === "string" ? { url: options.url } : {};
         switch (command) {
             case "navigate":
                 daemonArgs = { url: args[0] || options.url };
                 break;
             case "click":
-                daemonArgs = { selector: args[0], force: options.force === true };
+                daemonArgs = { selector: args[0], force: options.force === true, ...urlArg };
                 break;
             case "hover":
-                daemonArgs = { selector: args[0] };
+                daemonArgs = { selector: args[0], ...urlArg };
                 break;
             case "fill":
-                daemonArgs = { selector: args[0], value: args[1] };
+                daemonArgs = { selector: args[0], value: args[1], ...urlArg };
                 break;
             case "keyboard": {
                 validateCommandFlags("keyboard", options);
@@ -2954,42 +3198,45 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         process.exit(1);
                     }
                 }
+                const { delay, repeat } = parseKeyboardNumbers(options);
                 daemonArgs = {
                     steps,
                     hold,
-                    delay: options.delay !== undefined ? Number(options.delay) : 50,
-                    repeat: options.repeat !== undefined ? Number(options.repeat) : 1,
+                    delay,
+                    repeat,
                     selector: typeof options.selector === "string" ? options.selector : undefined,
                     force: options.force === true,
+                    ...urlArg,
                 };
                 break;
             }
             case "press":
-                daemonArgs = { key: args[0], force: options.force === true };
+                daemonArgs = { key: args[0], force: options.force === true, ...urlArg };
                 break;
-            case "type":
-                daemonArgs = { text: args[0], delay: options.delay !== undefined ? Number(options.delay) : 50, force: options.force === true };
+            case "type": {
+                const delay = options.delay !== undefined ? Number(options.delay) : 50;
+                if (!Number.isFinite(delay) || delay < 0) {
+                    console.error(`Error: --delay must be a number of milliseconds, got: ${options.delay}`);
+                    process.exit(1);
+                }
+                daemonArgs = { text: args[0], delay, force: options.force === true, ...urlArg };
                 break;
+            }
             case "eval":
             case "evaluate": {
                 validateCommandFlags(command, options);
-                rejectForceValue(options);
-                const script = typeof options.file === "string"
-                    ? readFileSync(resolve(options.file), "utf-8")
-                    : args[0];
-                if (!script) {
-                    console.error('Usage: cbrowser evaluate "<javascript>" | --file <path>');
-                    process.exit(1);
-                }
-                // Refused here, before the request leaves, and again daemon-side
-                // (anything on this machine can POST to the daemon).
-                const refusal = evaluateScriptRefusal(options.force === true);
-                if (refusal) {
-                    console.error(`✗ ${refusal}`);
-                    console.error("  Re-run with --force to run it anyway.");
-                    process.exit(1);
-                }
-                daemonArgs = { body: `return (function(){ ${/\breturn\b/.test(script) ? script : `return (${script});`} })();`, args: [], force: true };
+                // Same validation as the local path (prepareEvaluate), then the whole
+                // request: refused here and again daemon-side, since anything on this
+                // machine can POST to the daemon. The daemon compiles the raw script
+                // with the same evaluateScript as the local path.
+                const prep = await prepareEvaluate(args, options);
+                daemonArgs = {
+                    script: prep.script,
+                    args: prep.evalArgs,
+                    force: true,
+                    ...(typeof options.url === "string" ? { url: options.url } : {}),
+                    ...(prep.waitFor ? { waitFor: prep.waitFor, timeout: prep.waitMs } : {}),
+                };
                 break;
             }
             case "screenshot": {
@@ -3005,7 +3252,9 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         ssPath = args[0];
                     }
                 }
-                daemonArgs = { path: ssPath, url: ssUrl || options.url };
+                // Resolved here: the daemon's cwd is wherever `daemon start` ran, so a
+                // relative path used to land there instead of where the user is.
+                daemonArgs = { path: ssPath ? resolve(ssPath) : undefined, url: ssUrl || options.url };
                 break;
             }
             case "extract": {
@@ -3020,17 +3269,30 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         extractWhat = args[0];
                     }
                 }
+                if (!EXTRACT_KINDS.includes(extractWhat.toLowerCase())) {
+                    console.error(`Error: extract takes one of: ${EXTRACT_KINDS.join(", ")} (got "${extractWhat}")`);
+                    process.exit(1);
+                }
                 daemonArgs = { what: extractWhat, url: extractUrl || options.url };
                 break;
             }
             case "run":
-                daemonArgs = { command: args.join(" ") };
+                daemonArgs = { command: args.join(" "), ...urlArg };
                 break;
         }
         const result = await sendToDaemon(daemonCommand, daemonArgs);
         if (result.success) {
-            console.log("✓ Command executed via daemon");
-            if (result.result) {
+            console.error("✓ Command executed via daemon");
+            if (daemonCommand === "evaluate") {
+                // The same output and --expect-truthy rule as the local path; the
+                // daemon used to print strings JSON-quoted.
+                printEvaluateResult(result.result, options);
+            }
+            else if (daemonCommand === "extract" && result.result && typeof result.result === "object" && "data" in result.result) {
+                // As the local path prints it: the extracted data, not the wrapper.
+                printData("extract", result.result.data);
+            }
+            else if (result.result) {
                 console.log(JSON.stringify(result.result, null, 2));
             }
         }
@@ -3092,15 +3354,17 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             process.exit(1);
         }
     }
+    // Only what the user passed: an unset flag leaves the env var or config file
+    // value in place (mergeConfig drops undefined keys too).
     const browser = new CBrowser({
-        browser: browserType,
-        headless,
+        ...(options.browser !== undefined ? { browser: browserType } : {}),
+        ...(options.headless !== undefined ? { headless } : {}),
         device: options.device,
-        ...(viewportOverride ? { viewportWidth: viewportOverride.width, viewportHeight: viewportOverride.height } : {}),
+        ...(viewportOverride ? { viewportWidth: viewportOverride.width, viewportHeight: viewportOverride.height, viewportOverride } : {}),
         geolocation,
         locale: options.locale,
         timezone: options.timezone,
-        recordVideo: options["record-video"] === true,
+        ...(options["record-video"] !== undefined ? { recordVideo: options["record-video"] === true } : {}),
         persistent: persistentMode,
         skipSessionRestore: skipRestore,
         verbose: true,
@@ -3114,7 +3378,14 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     process.exit(1);
                 }
                 const result = await browser.navigate(url);
-                console.log(`✓ Navigated to: ${result.url}`);
+                // A navigation that landed somewhere else (an interstitial, a
+                // cross-host redirect) reports success: false; it used to print
+                // "Navigated to" and exit 0.
+                if (result.success === false) {
+                    console.error(`✗ Navigation to ${url} did not land on that page (now at ${result.url})`);
+                    process.exitCode = 1;
+                }
+                console.log(`${result.success === false ? "✗" : "✓"} Navigated to: ${result.url}`);
                 console.log(`  Title: ${result.title}`);
                 console.log(`  Load time: ${result.loadTime}ms`);
                 console.log(`  Screenshot: ${result.screenshot}`);
@@ -3185,7 +3456,13 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 if (options.url)
                     await browser.navigate(options.url);
                 const page = await browser.getPage();
-                const delay = typeof options.delay === "number" ? options.delay : 50;
+                // parseArgs yields strings, so the old `typeof === "number"` test was
+                // never true and --delay was always 50 ms (audit 2026-10-21).
+                const delay = typeof options.delay === "string" ? Number(options.delay) : 50;
+                if (!Number.isFinite(delay) || delay < 0) {
+                    console.error(`Error: --delay must be a number of milliseconds, got: ${options.delay}`);
+                    process.exit(1);
+                }
                 const refusal = await browser.keystrokeRedZone({ text }, options.force === true);
                 if (refusal) {
                     console.error(`✗ ${refusal}`);
@@ -3305,8 +3582,15 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 if (url) {
                     await browser.navigate(url);
                 }
+                // Five kinds exist. Anything else used to return the whole page text, so
+                // a typo ("link") or a description ("all product names") looked like a
+                // result (audit 2026-10-21).
+                if (!EXTRACT_KINDS.includes(what.toLowerCase())) {
+                    console.error(`Error: extract takes one of: ${EXTRACT_KINDS.join(", ")} (got "${what}")`);
+                    process.exit(1);
+                }
                 const result = await browser.extract(what);
-                console.log(JSON.stringify(result.data, null, 2));
+                printData("extract", result.data);
                 break;
             }
             // =========================================================================
@@ -3344,7 +3628,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 else {
                     console.error(`\n✗ ${result.message}`);
                     if (result.aiSuggestion) {
-                        console.log(`\n💡 Suggestion:\n${result.aiSuggestion}`);
+                        console.error(`\n💡 Suggestion:\n${result.aiSuggestion}`);
                     }
                     process.exit(1);
                 }
@@ -3511,6 +3795,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 console.log(`\n🧪 Analyzing page and generating tests...\n`);
                 const result = await browser.generateTests(url);
                 const format = options.format || "summary";
+                // An unknown format printed nothing and exited 0.
+                if (!["summary", "cbrowser", "playwright", "all"].includes(format)) {
+                    console.error(`Error: --format must be summary, cbrowser, playwright or all, got: ${format}`);
+                    process.exit(1);
+                }
                 const outputFile = options.output;
                 let output = "";
                 if (format === "summary" || format === "all") {
@@ -3562,6 +3851,17 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 }
                 await browser.navigate(url);
                 const analysis = await browser.analyzePage();
+                // --output was accepted and ignored, so the GitHub Action's url mode
+                // (`analyze "$URL" --output .../analysis.json`) never wrote its file.
+                if (typeof options.output === "string") {
+                    const { writeFileSync } = await import("node:fs");
+                    writeFileSync(options.output, JSON.stringify(analysis, null, 2));
+                    console.error(`📄 Analysis saved: ${options.output}`);
+                }
+                if (getOutputOptions().json) {
+                    printData("analyze", analysis);
+                    break;
+                }
                 console.log(`\n📊 Page Analysis: ${analysis.url}\n`);
                 console.log(`Title: ${analysis.title}`);
                 console.log(`\n📝 Forms (${analysis.forms.length}):`);
@@ -3613,20 +3913,28 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.warn("⚠️  'journey' is deprecated. Use 'explore' instead.\n");
                 }
                 const persona = args[0] || "first-timer";
-                const startUrl = options.start;
+                // --url works too (audit F25: four spellings of "start URL").
+                const startUrl = (options.start ?? options.url);
                 const goal = options.goal || "Explore the site";
                 if (!startUrl) {
                     console.error("Error: --start URL required");
                     process.exit(1);
                 }
+                // 20.0.0: no keyless mode. The heuristic explorer reported success
+                // whenever any goal word ("the" included) was on the page (2026-10-21).
+                if (!isApiKeyConfigured()) {
+                    console.error("Error: explore needs an Anthropic API key (cbrowser config set-api-key <key>). The keyless heuristic mode was removed in 20.0.0 because its results were not accurate.");
+                    process.exit(1);
+                }
                 console.log(`🔍 Starting exploration as "${persona}"...`);
                 console.log(`   Goal: ${goal}`);
-                console.log(`   Mode: Heuristic (free, no API)`);
                 console.log("");
                 const result = await browser.journey({ persona, startUrl, goal });
                 console.log("");
                 console.log(`📊 Journey Results`);
                 console.log(`   Success: ${result.success ? "✓" : "✗"}`);
+                if (!result.success)
+                    process.exitCode = 1;
                 console.log(`   Steps: ${result.steps.length}`);
                 console.log(`   Time: ${result.totalTime}ms`);
                 console.log(`   Friction points: ${result.frictionPoints.length}`);
@@ -3661,12 +3969,18 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const concurrency = options.concurrency
                     ? parseInt(options.concurrency)
                     : 3;
+                const personaFlags = browserFlagsOrExit("compare-personas", options);
+                refuseBrowserFlags("compare-personas", personaFlags, {
+                    browser: "it runs cognitive journeys, which take no engine option",
+                });
                 const comparison = await comparePersonas({
                     startUrl,
                     goal,
                     personas: personaNames,
                     maxConcurrency: concurrency,
                     headless,
+                    device: personaFlags.device,
+                    viewport: personaFlags.viewport,
                 });
                 // Print formatted report
                 const report = formatComparisonReport(comparison);
@@ -3681,7 +3995,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 if (options.html) {
                     const fs = await import("fs");
                     const htmlReport = generateHtmlReport(comparison);
-                    const htmlPath = options.output?.replace(".json", ".html") || "comparison-report.html";
+                    const htmlPath = htmlReportPath(options.output, "comparison-report.html");
                     fs.writeFileSync(htmlPath, htmlReport);
                     console.log(`\n🌐 HTML report saved: ${htmlPath}`);
                 }
@@ -3780,7 +4094,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         // Save the persona
                         const filepath = saveCustomPersona(persona);
                         console.log(`\n✓ Persona saved: ${filepath}`);
-                        console.log(`\nUse with: cbrowser journey ${personaName} --start <url> --goal "<goal>"`);
+                        console.log(`\nUse with: cbrowser cognitive-journey --persona ${personaName} --start <url> --goal "<goal>"`);
                         break;
                     }
                     case "show": {
@@ -3923,6 +4237,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.error("  cbrowser persona delete my-custom-persona");
                         console.error("  cbrowser persona cleanup --dry-run    # Preview invalid personas");
                         console.error("  cbrowser persona cleanup              # Remove invalid personas");
+                        process.exit(1);
                 }
                 break;
             }
@@ -4103,6 +4418,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         }
                         else {
                             console.error(`✗ Session not found: ${name}`);
+                            process.exit(1);
                         }
                         break;
                     }
@@ -4116,6 +4432,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.error("  cleanup --older-than <days>    Delete old sessions");
                         console.error("  export <name> --output <file>  Export session to file");
                         console.error("  import <file> --name <name>    Import session from file");
+                        process.exit(1);
                 }
                 break;
             }
@@ -4231,6 +4548,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     }
                     default:
                         console.error("Usage: cbrowser cookie [list|set|delete|clear]");
+                        process.exit(1);
                 }
                 break;
             }
@@ -4241,14 +4559,18 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const subcommand = args[0];
                 switch (subcommand) {
                     case "list": {
-                        console.log("\n📱 Available Device Presets:\n");
-                        for (const [name, device] of Object.entries(DEVICE_PRESETS)) {
-                            console.log(`  ${name}`);
-                            console.log(`    ${device.name}`);
-                            console.log(`    ${device.viewport.width}x${device.viewport.height} @${device.deviceScaleFactor}x`);
-                            console.log(`    Mobile: ${device.isMobile} | Touch: ${device.hasTouch}`);
-                            console.log("");
-                        }
+                        // One line per preset: there are a few hundred now. An optional
+                        // filter matches the key or the display name.
+                        const filter = (args[1] ?? "").toLowerCase();
+                        const rows = Object.entries(DEVICE_PRESETS).filter(([key, d]) => !filter || key.includes(filter) || d.name.toLowerCase().includes(filter));
+                        const width = Math.max(...rows.map(([key]) => key.length), 4);
+                        console.log(`\n📱 Device presets${filter ? ` matching "${filter}"` : ""}: ${rows.length}\n`);
+                        for (const [key, d] of rows) {
+                            const kind = d.isMobile ? "mobile" : "desktop";
+                            const touch = d.hasTouch ? ", touch" : "";
+                            console.log(`  ${key.padEnd(width)}  ${d.viewport.width}x${d.viewport.height} @${d.deviceScaleFactor}x  ${kind}${touch}  (${d.name})`);
+                        }
+                        console.log("\n  Case and spaces do not matter: --device \"iPhone 16\" is iphone-16.");
                         break;
                     }
                     case "set": {
@@ -4257,20 +4579,17 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error("Usage: cbrowser device set <name>");
                             process.exit(1);
                         }
-                        if (!DEVICE_PRESETS[deviceName]) {
-                            console.error(`Unknown device: ${deviceName}`);
-                            console.error("Run 'cbrowser device list' to see available devices");
-                            process.exit(1);
-                        }
+                        const presetKey = resolveDevicePreset(deviceName);
                         // Save device setting to persistent session state
                         const deviceBrowser = new CBrowser({ persistent: true, headless: true, verbose: false });
-                        deviceBrowser.saveDeviceSetting(deviceName);
-                        console.log(`✓ Device set: ${deviceName}`);
+                        deviceBrowser.saveDeviceSetting(presetKey);
+                        console.log(`✓ Device set: ${presetKey}`);
                         console.log("  Device emulation will apply to all subsequent commands");
                         break;
                     }
                     default:
                         console.error("Usage: cbrowser device [list|set]");
+                        process.exit(1);
                 }
                 break;
             }
@@ -4301,12 +4620,18 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error(`Invalid location: ${location}`);
                             process.exit(1);
                         }
-                        await browser.setGeolocationRuntime(geo);
+                        // Saved to session state like `device set`: each command is its own
+                        // process, so a runtime change here died with this one.
+                        const geoBrowser = new CBrowser({ persistent: true, headless: true, verbose: false });
+                        if (!geoBrowser.saveGeolocationSetting(geo))
+                            process.exit(1);
                         console.log(`✓ Geolocation set: ${geo.latitude}, ${geo.longitude}`);
+                        console.log("  Applies to later commands in the persistent session (for an hour, like device set)");
                         break;
                     }
                     default:
                         console.error("Usage: cbrowser geo [list|set]");
+                        process.exit(1);
                 }
                 break;
             }
@@ -4335,6 +4660,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.log("\n📊 Performance Audit:\n");
                     console.log(`  URL: ${result.url}`);
                     console.log(`  Result: ${result.passed ? "✓ PASSED" : "✗ FAILED"}`);
+                    if (!result.passed)
+                        process.exitCode = 1;
                     console.log("");
                     console.log("  Metrics:");
                     if (result.metrics.lcp)
@@ -4396,7 +4723,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const subcommand = args[0];
                 if (subcommand !== "start" && subcommand !== "stop") {
                     console.error("Usage: cbrowser har [start|stop]");
-                    break;
+                    process.exit(1);
                 }
                 // A recording has to span several commands, and each cbrowser command is
                 // its own process: only the daemon's browser outlives them. Recorded here,
@@ -4481,7 +4808,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const subcommand = args[0];
                 if (subcommand !== "list" && subcommand !== "clear") {
                     console.error("Usage: cbrowser network [list|clear]");
-                    break;
+                    process.exit(1);
                 }
                 // Same reason as har: the request log lives in a browser, and only the
                 // daemon's browser outlives a command. A fresh process always listed
@@ -4509,19 +4836,32 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 }
                 switch (subcommand) {
                     case "list": {
-                        const requests = listed.result.requests;
-                        if (requests.length === 0) {
-                            console.log("No network requests captured");
-                            console.log("Navigate to a page first to capture requests");
+                        const all = listed.result.requests;
+                        // Newest first, as the MCP tool lists them; it used to print the
+                        // oldest of the last 20 first and offered no way past 20.
+                        const filter = typeof options.filter === "string" ? options.filter.toLowerCase() : undefined;
+                        const matching = all.filter((r) => !filter || r.url.toLowerCase().includes(filter)
+                            || r.resourceType.toLowerCase() === filter || r.method.toLowerCase() === filter);
+                        const newestFirst = [...matching].reverse();
+                        const shown = options.all === true ? newestFirst : newestFirst.slice(0, 20);
+                        if (options.json === true || getOutputOptions().json) {
+                            printData("network", { total: all.length, matching: matching.length, requests: shown });
+                            break;
+                        }
+                        if (matching.length === 0) {
+                            console.log(filter ? `No captured request matches "${filter}"` : "No network requests captured");
+                            if (!filter)
+                                console.log("Navigate to a page first to capture requests");
                         }
                         else {
-                            console.log(`\n🌐 Network Requests (${requests.length}):\n`);
-                            for (const req of requests.slice(-20)) {
-                                console.log(`  ${req.method} ${req.url.substring(0, 80)}${req.url.length > 80 ? "..." : ""}`);
+                            console.log(`\n🌐 Network Requests (${matching.length}${filter ? ` of ${all.length}` : ""}, newest first):\n`);
+                            for (const req of shown) {
+                                const status = req.status !== undefined ? ` ${req.status}` : "";
+                                console.log(`  ${req.method}${status} ${req.url.substring(0, 80)}${req.url.length > 80 ? "..." : ""}`);
                                 console.log(`    Type: ${req.resourceType} | Time: ${req.timestamp}`);
                             }
-                            if (requests.length > 20) {
-                                console.log(`\n  ... and ${requests.length - 20} more requests`);
+                            if (matching.length > shown.length) {
+                                console.log(`\n  ... and ${matching.length - shown.length} older requests (--all lists them)`);
                             }
                         }
                         break;
@@ -4558,13 +4898,15 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         if (options.url) {
                             await browser.navigate(options.url);
                         }
-                        const threshold = options.threshold ? parseFloat(options.threshold) : 0.1;
+                        const threshold = numberOption("threshold", options.threshold, 0.1, { min: 0, max: 1 });
                         const result = await browser.compareBaseline(name, threshold);
                         console.log("\n🔍 Visual Comparison:\n");
                         console.log(`  Baseline: ${name}`);
                         console.log(`  Difference: ${(result.diffPercentage * 100).toFixed(2)}%`);
                         console.log(`  Threshold: ${(threshold * 100).toFixed(0)}%`);
                         console.log(`  Result: ${result.passed ? "✓ PASSED" : "✗ FAILED"}`);
+                        if (!result.passed)
+                            process.exitCode = 1;
                         if (result.diffPath) {
                             console.log(`  Diff image: ${result.diffPath}`);
                         }
@@ -4608,6 +4950,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     }
                     default:
                         console.error("Usage: cbrowser visual [save|compare|list|delete]");
+                        process.exit(1);
                 }
                 break;
             }
@@ -4616,6 +4959,12 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             // =========================================================================
             case "ai-visual": {
                 const subcommand = args[0];
+                // A test renders the way its baseline was captured.
+                const BASELINE_SHAPE_FLAGS = {
+                    browser: "a test renders with its baseline's engine; capture a new baseline to change it",
+                    device: "a test renders with its baseline's device; capture a new baseline to change it",
+                    viewport: "a test renders at its baseline's size; capture a new baseline to change it",
+                };
                 switch (subcommand) {
                     case "capture": {
                         const url = args[1];
@@ -4623,20 +4972,18 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error("Usage: cbrowser ai-visual capture <url> --name <name> [options]");
                             console.error("  --selector <sel>    Capture specific element");
                             console.error("  --device <device>   Device emulation");
-                            console.error("  --width <n>         Viewport width");
-                            console.error("  --height <n>        Viewport height");
+                            console.error("  --viewport <WxH>    Page size (default: 1920x1080)");
+                            console.error("  --width/--height    One side of the page size");
+                            console.error("  --browser <engine>  chromium, firefox or webkit");
                             console.error("  --wait <ms|sel>     Wait before capture");
                             process.exit(1);
                         }
+                        const flags = browserFlagsOrExit("ai-visual capture", options);
                         console.log(`📸 Capturing visual baseline: ${options.name}`);
                         console.log(`   URL: ${url}`);
                         const baseline = await captureVisualBaseline(url, options.name, {
                             selector: options.selector,
-                            device: options.device,
-                            viewport: options.width || options.height ? {
-                                width: parseInt(options.width) || 1920,
-                                height: parseInt(options.height) || 1080,
-                            } : undefined,
+                            ...flags,
                             waitFor: options.wait ? (/^\d+$/.test(options.wait)
                                 ? parseInt(options.wait)
                                 : options.wait) : undefined,
@@ -4644,6 +4991,10 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.log(`\n✅ Baseline captured successfully!`);
                         console.log(`   ID: ${baseline.id}`);
                         console.log(`   Viewport: ${baseline.viewport.width}x${baseline.viewport.height}`);
+                        if (baseline.device)
+                            console.log(`   Device: ${baseline.device}`);
+                        if (baseline.browser)
+                            console.log(`   Browser: ${baseline.browser}`);
                         console.log(`   Screenshot: ${baseline.screenshotPath}`);
                         break;
                     }
@@ -4658,13 +5009,16 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error("  --output <file>     Save JSON report");
                             process.exit(1);
                         }
+                        const flags = browserFlagsOrExit("ai-visual test", options);
+                        refuseBrowserFlags("ai-visual test", flags, BASELINE_SHAPE_FLAGS);
                         console.log(`\n🔍 Running AI visual regression test...`);
                         console.log(`   URL: ${url}`);
                         console.log(`   Baseline: ${baselineName}\n`);
                         const result = await runVisualRegression(url, baselineName, {
-                            threshold: options.threshold ? parseFloat(options.threshold) : 0.9,
-                            sensitivity: options.sensitivity || "medium",
+                            threshold: numberOption("threshold", options.threshold, 0.9, { min: 0, max: 1 }),
+                            sensitivity: enumOption("sensitivity", options.sensitivity, ["low", "medium", "high"]) ?? "medium",
                             generateDiff: true,
+                            headless: flags.headless,
                         });
                         // Print report
                         console.log(formatVisualRegressionReport(result));
@@ -4716,10 +5070,13 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error(`Suite file not found: ${suiteFile}`);
                             process.exit(1);
                         }
+                        const flags = browserFlagsOrExit("ai-visual suite", options);
+                        refuseBrowserFlags("ai-visual suite", flags, BASELINE_SHAPE_FLAGS);
                         const suite = JSON.parse(fs.readFileSync(suiteFile, "utf-8"));
                         console.log(`\n🔍 Running visual regression suite: ${suite.name}`);
                         const result = await runVisualRegressionSuite(suite, {
-                            threshold: options.threshold ? parseFloat(options.threshold) : 0.9,
+                            threshold: numberOption("threshold", options.threshold, 0.9, { min: 0, max: 1 }),
+                            headless: flags.headless,
                         });
                         // Save outputs
                         if (options.output && !options.html) {
@@ -4810,6 +5167,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.error("       cbrowser ai-visual list");
                         console.error("       cbrowser ai-visual show <name>");
                         console.error("       cbrowser ai-visual delete <name>");
+                        process.exit(1);
                 }
                 break;
             }
@@ -4818,6 +5176,10 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             // =========================================================================
             case "cross-browser": {
                 const subcommand = args[0];
+                const flags = browserFlagsOrExit("cross-browser", options);
+                refuseBrowserFlags("cross-browser", flags, {
+                    browser: "it runs each engine in turn; choose them with --browsers chromium,firefox,webkit",
+                });
                 if (subcommand === "suite") {
                     // Cross-browser suite
                     const suiteFile = args[1];
@@ -4833,7 +5195,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         process.exit(1);
                     }
                     const suite = JSON.parse(fs.readFileSync(suiteFile, "utf-8"));
-                    const result = await runCrossBrowserSuite(suite);
+                    // Flags given on the command line win over the suite file's options.
+                    const result = await runCrossBrowserSuite({ ...suite, options: { ...suite.options, ...flags } });
                     // Save outputs
                     if (options.output && !options.html) {
                         fs.writeFileSync(options.output, JSON.stringify(result, null, 2));
@@ -4861,8 +5224,9 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.error("       cbrowser cross-browser suite <file.json>");
                         console.error("\nOptions:");
                         console.error("  --browsers <list>   chromium,firefox,webkit (default: all)");
-                        console.error("  --width <n>         Viewport width (default: 1920)");
-                        console.error("  --height <n>        Viewport height (default: 1080)");
+                        console.error("  --viewport <WxH>    Page size (default: 1920x1080)");
+                        console.error("  --width/--height    One side of the page size");
+                        console.error("  --device <name>     Device preset (firefox cannot emulate a mobile one)");
                         console.error("  --wait <ms>         Wait before screenshot");
                         console.error("  --wait-for <sel>    Wait for selector");
                         console.error("  --sensitivity <l>   low, medium, high");
@@ -4875,13 +5239,10 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         : undefined;
                     const result = await runCrossBrowserTest(url, {
                         browsers,
-                        viewport: options.width || options.height ? {
-                            width: parseInt(options.width) || 1920,
-                            height: parseInt(options.height) || 1080,
-                        } : undefined,
+                        ...flags,
                         waitBeforeCapture: options.wait ? parseInt(options.wait) : undefined,
                         waitForSelector: options["wait-for"],
-                        sensitivity: options.sensitivity,
+                        sensitivity: enumOption("sensitivity", options.sensitivity, ["low", "medium", "high"]),
                     });
                     // Print report
                     console.log("\n" + formatCrossBrowserReport(result));
@@ -4920,6 +5281,19 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             // =========================================================================
             case "responsive": {
                 const subcommand = args[0];
+                // Headless and the engine apply; the page shapes are the presets'.
+                const responsiveFlags = () => {
+                    const flags = browserFlagsOrExit("responsive", options);
+                    refuseBrowserFlags("responsive", flags, {
+                        device: "the sizes come from --viewports, whose mobile and tablet presets emulate their own devices",
+                        viewport: "the sizes come from --viewports ('cbrowser responsive viewports' lists them)",
+                    });
+                    // Only the flags given, so a suite file's own options stand otherwise.
+                    return {
+                        ...(flags.headless !== undefined ? { headless: flags.headless } : {}),
+                        ...(flags.browser ? { browser: flags.browser } : {}),
+                    };
+                };
                 if (subcommand === "viewports") {
                     // List viewport presets
                     const presets = listViewportPresets();
@@ -4945,6 +5319,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 }
                 else if (subcommand === "suite") {
                     // Responsive suite
+                    const flags = responsiveFlags();
                     const suiteFile = args[1];
                     if (!suiteFile) {
                         console.error("Usage: cbrowser responsive suite <file.json> [options]");
@@ -4958,7 +5333,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         process.exit(1);
                     }
                     const suite = JSON.parse(fs.readFileSync(suiteFile, "utf-8"));
-                    const result = await runResponsiveSuite(suite);
+                    // Flags given on the command line win over the suite file's options.
+                    const result = await runResponsiveSuite({ ...suite, options: { ...suite.options, ...flags } });
                     // Save outputs
                     if (options.output && !options.html) {
                         fs.writeFileSync(options.output, JSON.stringify(result, null, 2));
@@ -4993,19 +5369,20 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.error("  --sensitivity <l>   low, medium, high");
                         console.error("  --html              Generate HTML report");
                         console.error("  --output <file>     Save report");
-                        console.error("\nViewport presets: mobile-sm, mobile, mobile-lg, mobile-xl,");
-                        console.error("                  tablet, tablet-lg, desktop-sm, desktop,");
-                        console.error("                  desktop-lg, desktop-xl");
+                        console.error("\nViewport presets:");
+                        console.error(formatViewportPresetList("  "));
                         process.exit(1);
                     }
+                    const flags = responsiveFlags();
                     const viewports = options.viewports
                         ? options.viewports.split(",")
                         : undefined;
                     const result = await runResponsiveTest(url, {
                         viewports,
+                        ...flags,
                         waitBeforeCapture: options.wait ? parseInt(options.wait) : undefined,
                         waitForSelector: options["wait-for"],
-                        sensitivity: options.sensitivity,
+                        sensitivity: enumOption("sensitivity", options.sensitivity, ["low", "medium", "high"]),
                     });
                     // Print report
                     console.log("\n" + formatResponsiveReport(result));
@@ -5046,6 +5423,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             // =========================================================================
             case "ab": {
                 const subcommand = args[0];
+                const flags = browserFlagsOrExit("ab", options);
                 if (subcommand === "suite") {
                     // A/B suite
                     const suiteFile = args[1];
@@ -5061,7 +5439,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         process.exit(1);
                     }
                     const suite = JSON.parse(fs.readFileSync(suiteFile, "utf-8"));
-                    const result = await runABSuite(suite);
+                    // Flags given on the command line win over the suite file's options.
+                    const result = await runABSuite({ ...suite, options: { ...suite.options, ...flags } });
                     // Save outputs
                     if (options.output && !options.html) {
                         fs.writeFileSync(options.output, JSON.stringify(result, null, 2));
@@ -5091,8 +5470,9 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.error("\nOptions:");
                         console.error("  --label-a <name>    Label for URL A (default: 'Version A')");
                         console.error("  --label-b <name>    Label for URL B (default: 'Version B')");
-                        console.error("  --width <n>         Viewport width (default: 1920)");
-                        console.error("  --height <n>        Viewport height (default: 1080)");
+                        console.error("  --viewport <WxH>    Page size (default: 1920x1080)");
+                        console.error("  --width/--height    One side of the page size");
+                        console.error("  --device <name>     Device preset");
                         console.error("  --wait <ms>         Wait before screenshot");
                         console.error("  --wait-for <sel>    Wait for selector");
                         console.error("  --sensitivity <l>   low, medium, high");
@@ -5105,13 +5485,10 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             a: options["label-a"] || "Version A",
                             b: options["label-b"] || "Version B",
                         } : undefined,
-                        viewport: options.width || options.height ? {
-                            width: parseInt(options.width) || 1920,
-                            height: parseInt(options.height) || 1080,
-                        } : undefined,
+                        ...flags,
                         waitBeforeCapture: options.wait ? parseInt(options.wait) : undefined,
                         waitForSelector: options["wait-for"],
-                        sensitivity: options.sensitivity,
+                        sensitivity: enumOption("sensitivity", options.sensitivity, ["low", "medium", "high"]),
                     });
                     // Print report
                     console.log("\n" + formatABReport(result));
@@ -5177,6 +5554,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 }
                 else {
                     console.error("Usage: cbrowser a11y audit [url]");
+                    process.exit(1);
                 }
                 break;
             }
@@ -5185,6 +5563,17 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             // =========================================================================
             case "record": {
                 const subcommand = args[0];
+                // A recording has to span several commands, and each command is its own
+                // process, so start / stop / save each saw a fresh, empty recorder: stop
+                // always reported 0 actions and save wrote an empty test (audit
+                // 2026-10-21, the class HAR had until 19.4.3). Only list and generate
+                // work on their own; the rest are refused instead of pretending.
+                if (subcommand === "start" || subcommand === "stop" || subcommand === "save") {
+                    console.error(`Error: 'record ${subcommand}' cannot capture anything: each cbrowser command is its own process, so a recording does not survive between them.`);
+                    console.error("  To record a flow, write it as a test and run it in one process:");
+                    console.error('    cbrowser test-suite --inline "go to https://example.com ; click Sign in ; verify page contains Welcome" --capture');
+                    process.exit(1);
+                }
                 switch (subcommand) {
                     case "start": {
                         const url = options.url;
@@ -5261,6 +5650,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     }
                     default:
                         console.error("Usage: cbrowser record [start|stop|save|list|generate]");
+                        process.exit(1);
                 }
                 break;
             }
@@ -5298,31 +5688,25 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.error("Usage: cbrowser export [junit|tap] <name> [output]");
                     process.exit(1);
                 }
-                // Load test results (for now, create a mock suite)
-                const fs = await import("fs");
-                const path = await import("path");
-                const resultsPath = path.join(browser.getDataDir(), "results", `${name}.json`);
-                let suite;
-                if (fs.existsSync(resultsPath)) {
-                    suite = JSON.parse(fs.readFileSync(resultsPath, "utf-8"));
+                if (format !== "junit" && format !== "tap") {
+                    console.error("Unknown export format. Use 'junit' or 'tap'");
+                    process.exit(1);
                 }
-                else {
+                // The last `test-suite` run of that suite (it saves every run).
+                const suite = loadSuiteForExport(browser.getDataDir(), name);
+                if (!suite) {
                     console.error(`Test results not found: ${name}`);
-                    console.error("Run tests first to generate results");
+                    console.error(`  Run 'cbrowser test-suite <file>' first; it saves results as ${resultsName(name)}.json under ${join(browser.getDataDir(), "results")}`);
                     process.exit(1);
                 }
                 if (format === "junit") {
                     const exportPath = browser.exportJUnit(suite, output);
                     console.log(`✓ JUnit XML exported: ${exportPath}`);
                 }
-                else if (format === "tap") {
+                else {
                     const exportPath = browser.exportTAP(suite, output);
                     console.log(`✓ TAP exported: ${exportPath}`);
                 }
-                else {
-                    console.error("Unknown export format. Use 'junit' or 'tap'");
-                    process.exit(1);
-                }
                 break;
             }
             // =========================================================================
@@ -5331,13 +5715,9 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             case "webhook": {
                 const subcommand = args[0];
                 const fs = await import("fs");
-                const path = await import("path");
-                const webhooksPath = path.join(browser.getDataDir(), "webhooks.json");
+                const hooksFile = webhooksPath(browser.getDataDir());
                 // Load existing webhooks
-                let webhooks = [];
-                if (fs.existsSync(webhooksPath)) {
-                    webhooks = JSON.parse(fs.readFileSync(webhooksPath, "utf-8"));
-                }
+                let webhooks = loadWebhooks(browser.getDataDir());
                 switch (subcommand) {
                     case "add": {
                         const name = args[1];
@@ -5346,14 +5726,30 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error("Usage: cbrowser webhook add <name> <url> [--events <events>] [--format <format>]");
                             process.exit(1);
                         }
-                        const events = options.events
-                            ? options.events.split(",")
-                            : ["test.fail", "journey.complete"];
-                        const format = options.format || "generic";
+                        const urlProblem = webhookUrlProblem(url);
+                        if (urlProblem) {
+                            console.error(`Error: ${urlProblem}`);
+                            process.exit(1);
+                        }
+                        // Only events something sends. journey.complete was the default
+                        // and nothing ever sent it, nor test.fail (audit O17).
+                        const events = options.events === undefined
+                            ? ["test.fail"]
+                            : String(options.events).split(",").map((e) => e.trim()).filter(Boolean);
+                        const unsent = events.filter((e) => !SENT_WEBHOOK_EVENTS.includes(e));
+                        if (events.length === 0 || unsent.length > 0) {
+                            console.error(`Error: no command sends ${unsent.join(", ") || "an empty event list"}. Events sent: ${SENT_WEBHOOK_EVENTS.join(", ")} (test.pass/test.fail by test-suite once per run, journey.complete by cognitive-journey)`);
+                            process.exit(1);
+                        }
+                        const format = options.format === undefined ? "generic" : String(options.format);
+                        if (!WEBHOOK_FORMATS.includes(format)) {
+                            console.error(`Error: --format must be ${WEBHOOK_FORMATS.join(", ")}, got "${format}"`);
+                            process.exit(1);
+                        }
                         // Remove existing webhook with same name
                         webhooks = webhooks.filter(w => w.name !== name);
                         webhooks.push({ name, url, events, format });
-                        fs.writeFileSync(webhooksPath, JSON.stringify(webhooks, null, 2));
+                        fs.writeFileSync(hooksFile, JSON.stringify(webhooks, null, 2));
                         console.log(`✓ Webhook added: ${name}`);
                         console.log(`  URL: ${url}`);
                         console.log(`  Events: ${events.join(", ")}`);
@@ -5367,9 +5763,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         else {
                             console.log("\n🔔 Configured Webhooks:\n");
                             for (const w of webhooks) {
+                                // An event no command sends (a typo, or one stored before 20.0 checked) is named as such.
+                                const unsent = w.events.filter((e) => !SENT_WEBHOOK_EVENTS.includes(e));
                                 console.log(`  ${w.name}`);
                                 console.log(`    URL: ${w.url}`);
-                                console.log(`    Events: ${w.events.join(", ")}`);
+                                console.log(`    Events: ${w.events.join(", ")}${unsent.length > 0 ? ` (never sent: ${unsent.join(", ")})` : ""}`);
                                 console.log(`    Format: ${w.format}`);
                                 console.log("");
                             }
@@ -5385,7 +5783,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         const originalLength = webhooks.length;
                         webhooks = webhooks.filter(w => w.name !== name);
                         if (webhooks.length < originalLength) {
-                            fs.writeFileSync(webhooksPath, JSON.stringify(webhooks, null, 2));
+                            fs.writeFileSync(hooksFile, JSON.stringify(webhooks, null, 2));
                             console.log(`✓ Webhook deleted: ${name}`);
                         }
                         else {
@@ -5405,6 +5803,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error(`✗ Webhook not found: ${name}`);
                             process.exit(1);
                         }
+                        const urlProblem = webhookUrlProblem(webhook.url);
+                        if (urlProblem) {
+                            console.error(`✗ ${urlProblem}`);
+                            process.exit(1);
+                        }
                         // Send test notification
                         const testPayload = webhook.format === "slack"
                             ? { text: "🔔 CBrowser test notification" }
@@ -5416,6 +5819,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                                 method: "POST",
                                 headers: { "Content-Type": "application/json" },
                                 body: JSON.stringify(testPayload),
+                                redirect: "error",
+                                signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
                             });
                             if (response.ok) {
                                 console.log(`✓ Test notification sent to: ${name}`);
@@ -5433,6 +5838,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     }
                     default:
                         console.error("Usage: cbrowser webhook [add|list|delete|test]");
+                        process.exit(1);
                 }
                 break;
             }
@@ -5441,6 +5847,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             // =========================================================================
             case "parallel": {
                 const subcommand = args[0];
+                const flags = browserFlagsOrExit("parallel", options);
                 switch (subcommand) {
                     case "devices": {
                         const url = args[1];
@@ -5448,9 +5855,14 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error("Usage: cbrowser parallel devices <url> [--devices <list>] [--concurrency <n>]");
                             process.exit(1);
                         }
+                        refuseBrowserFlags("parallel devices", flags, {
+                            device: "it runs every device in --devices; list them there",
+                            viewport: "each device renders at its own size",
+                        });
+                        // Without --devices, cbrowser's own presets, not all few hundred.
                         const deviceList = options.devices
-                            ? options.devices.split(",")
-                            : Object.keys(DEVICE_PRESETS);
+                            ? options.devices.split(",").map((d) => resolveDevicePreset(d))
+                            : [...CBROWSER_DEVICE_KEYS];
                         const concurrency = options.concurrency ? parseInt(options.concurrency) : 3;
                         console.log(`\n🚀 Running parallel device tests...`);
                         console.log(`   URL: ${url}`);
@@ -5460,11 +5872,12 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             const nav = await b.navigate(url);
                             const screenshot = await b.screenshot();
                             return { title: nav.title, loadTime: nav.loadTime, screenshot };
-                        }, { maxConcurrency: concurrency });
+                        }, { maxConcurrency: concurrency, config: browserLaunchConfig(flags) });
                         console.log("📊 Results:\n");
                         for (const r of results) {
                             if (r.error) {
                                 console.log(`  ✗ ${r.device}: ${r.error} (${r.duration}ms)`);
+                                process.exitCode = 1;
                             }
                             else {
                                 console.log(`  ✓ ${r.device}: ${r.result?.title} - ${r.result?.loadTime}ms (${r.duration}ms total)`);
@@ -5487,11 +5900,12 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         const results = await CBrowser.parallelUrls(urls, async (b, url) => {
                             const nav = await b.navigate(url);
                             return { title: nav.title, loadTime: nav.loadTime };
-                        }, { maxConcurrency: concurrency });
+                        }, { maxConcurrency: concurrency, config: browserLaunchConfig(flags) });
                         console.log("📊 Results:\n");
                         for (const r of results) {
                             if (r.error) {
                                 console.log(`  ✗ ${r.url}: ${r.error}`);
+                                process.exitCode = 1;
                             }
                             else {
                                 console.log(`  ✓ ${r.url}: ${r.result?.title} (${r.result?.loadTime}ms)`);
@@ -5512,11 +5926,12 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         const results = await CBrowser.parallelUrls(urls, async (b, url) => {
                             await b.navigate(url);
                             return await b.getPerformanceMetrics();
-                        }, { maxConcurrency: concurrency });
+                        }, { maxConcurrency: concurrency, config: browserLaunchConfig(flags) });
                         console.log("📊 Performance Results:\n");
                         for (const r of results) {
                             if (r.error) {
                                 console.log(`  ✗ ${r.url}: ${r.error}`);
+                                process.exitCode = 1;
                             }
                             else {
                                 const m = r.result;
@@ -5533,6 +5948,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     }
                     default:
                         console.error("Usage: cbrowser parallel [devices|urls|perf]");
+                        process.exit(1);
                 }
                 break;
             }
@@ -5550,6 +5966,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     process.exit(1);
                 }
                 console.log(`\n🗣️  Executing: "${nlCommand}"\n`);
+                if (typeof options.url === "string")
+                    await browser.navigate(options.url);
                 const result = await executeNaturalLanguage(browser, nlCommand);
                 if (result.success) {
                     console.log(`✓ Action: ${result.action}`);
@@ -5563,6 +5981,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.log(`  ${r.message}`);
                         if (r.screenshot)
                             console.log(`  Screenshot: ${r.screenshot}`);
+                        if (typeof r.scrollY === "number")
+                            console.log(`  scrollY: ${r.scrollY}`);
                     }
                 }
                 else {
@@ -5593,7 +6013,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     }
                     else {
                         console.log(`✗ ${r.command}`);
-                        console.log(`  Error: ${r.error}`);
+                        process.exitCode = 1;
+                        console.error(`  Error: ${r.error}`);
                     }
                 }
                 const passed = results.filter(r => r.success).length;
@@ -5630,7 +6051,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.log(`  Description: ${result.description}`);
                         }
                         else {
-                            console.log(`✗ Could not find element matching: "${intent}"`);
+                            console.error(`✗ Could not find element matching: "${intent}"`);
                             process.exit(1);
                         }
                         break;
@@ -5640,17 +6061,24 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         const result = await findElementByIntent(browser, intent);
                         if (result) {
                             console.log(`✓ Found: ${result.description}`);
-                            await browser.click(result.selector);
+                            // The click's own result decides: a red-zone refusal or a miss used
+                            // to print "Clicked element" and exit 0 (audit 2026-10-21).
+                            const clicked = await browser.click(result.selector, { force: options.force === true });
+                            if (!clicked.success) {
+                                console.error(`✗ ${clicked.message}`);
+                                process.exit(1);
+                            }
                             console.log(`✓ Clicked element`);
                         }
                         else {
-                            console.log(`✗ Could not find element matching: "${intent}"`);
+                            console.error(`✗ Could not find element matching: "${intent}"`);
                             process.exit(1);
                         }
                         break;
                     }
                     default:
                         console.error("Usage: cbrowser ai [find|click] \"<intent>\"");
+                        process.exit(1);
                 }
                 break;
             }
@@ -5665,7 +6093,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     process.exit(1);
                 }
                 const maxPages = options["max-pages"] ? parseInt(options["max-pages"]) : 10;
-                const timeout = options.timeout ? parseInt(options.timeout) : 60000;
+                const timeout = timeoutOption(options.timeout, 60000);
                 console.log(`\n🔍 Bug Hunter starting...`);
                 console.log(`   URL: ${url}`);
                 console.log(`   Max pages: ${maxPages}`);
@@ -5700,16 +6128,24 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             case "diff": {
                 const url = args[0];
                 if (!url) {
-                    console.error("Usage: cbrowser diff <url> [--browsers <list>]");
+                    console.error("Usage: cbrowser diff <url> [--browsers <list>] [--viewport <WxH>] [--device <name>]");
                     process.exit(1);
                 }
+                const flags = browserFlagsOrExit("diff", options);
+                refuseBrowserFlags("diff", flags, {
+                    browser: "it runs each engine in turn; choose them with --browsers chromium,firefox,webkit",
+                });
                 const browserList = options.browsers
                     ? options.browsers.split(",")
                     : ["chromium", "firefox", "webkit"];
                 console.log(`\n🔀 Cross-Browser Diff`);
                 console.log(`   URL: ${url}`);
                 console.log(`   Browsers: ${browserList.join(", ")}\n`);
-                const result = await crossBrowserDiff(url, [...browserList]);
+                const result = await crossBrowserDiff(url, [...browserList], {
+                    headless: flags.headless,
+                    device: flags.device,
+                    viewport: flags.viewport,
+                });
                 console.log(`📊 Results:\n`);
                 console.log(`   Metrics:`);
                 for (const [browser, metrics] of Object.entries(result.metrics)) {
@@ -5761,6 +6197,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const result = await runChaosTest(browser, url, chaosConfig);
                 console.log(`📊 Results:\n`);
                 console.log(`   Passed: ${result.passed ? "✅ Yes" : "❌ No"}`);
+                if (!result.passed)
+                    process.exitCode = 1;
                 console.log(`   Duration: ${result.duration}ms`);
                 if (result.errors.length > 0) {
                     console.log(`\n   Errors:`);
@@ -5807,10 +6245,9 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.log("");
                     }
                     console.log("Usage (OPT-IN REQUIRED):");
-                    console.log("  cbrowser screenshot https://example.com --lightpanda");
                     console.log("  cbrowser agent-ready-audit https://example.com --lightpanda");
                     console.log("");
-                    console.log("Note: Lightpanda is NOT used automatically. The --lightpanda flag is required.");
+                    console.log("Note: Lightpanda is NOT used automatically. Only agent-ready-audit uses it, with --lightpanda.");
                 }
                 else {
                     console.log("⚠️  Configured but unavailable");
@@ -5912,7 +6349,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     });
                     console.log(`\n🔍 Step-through mode enabled. Press Enter to execute each step.\n`);
                     const { CBrowser } = await import("./browser.js");
-                    const stepBrowser = new CBrowser({ headless });
+                    const stepBrowser = new CBrowser({
+                        headless,
+                        ...(typeof options.device === "string" ? { device: options.device } : {}),
+                        ...(viewportOverride ? { viewportWidth: viewportOverride.width, viewportHeight: viewportOverride.height, viewportOverride } : {}),
+                    });
                     await stepBrowser.launch();
                     try {
                         const totalSteps = suite.tests.reduce((sum, t) => sum + t.steps.length, 0);
@@ -5977,6 +6418,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                                 }
                                 catch (e) {
                                     console.log(`  ✗ Failed: ${e.message} (${Date.now() - start}ms)`);
+                                    process.exitCode = 1;
                                 }
                             }
                         }
@@ -5989,10 +6431,16 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 }
                 assertCaptureNamespaceFlags("test-suite", options);
                 const suiteOptions = {
-                    stepTimeout: options.timeout ? parseInt(options.timeout) : 30000,
+                    stepTimeout: timeoutOption(options.timeout, 30000),
                     continueOnFailure: options["continue-on-failure"] === true,
                     screenshotOnFailure: options["screenshot-on-failure"] !== false,
                     headless,
+                    device: typeof options.device === "string" ? options.device : undefined,
+                    viewport: viewportOverride,
+                    ...(options.browser !== undefined ? { browser: browserType } : {}),
+                    ...(geolocation ? { geolocation } : {}),
+                    ...(typeof options.locale === "string" ? { locale: options.locale } : {}),
+                    ...(typeof options.timezone === "string" ? { timezone: options.timezone } : {}),
                     fuzzyMatch: options["fuzzy-match"] === true,
                     capture: buildAutoCaptureSetting(options, `test-suite-${suite.name.replace(/[^a-zA-Z0-9-_]+/g, "-").toLowerCase()}-${Date.now()}`),
                 };
@@ -6001,6 +6449,22 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const report = formatNLTestReport(result);
                 console.log(report);
                 reportAutoCapture(result.capture);
+                // Saved for `cbrowser export junit|tap`, which read this directory
+                // while nothing wrote it (audit O17).
+                const savedPath = saveSuiteResult(browser.getDataDir(), result);
+                console.log(`\n💾 Results saved: ${savedPath} (export: cbrowser export junit ${resultsName(result.name)})`);
+                // Webhooks: one event per run. A failed send is a warning, never the
+                // run's result.
+                await sendWebhookEvent(browser.getDataDir(), result.summary.failed > 0 ? "test.fail" : "test.pass", {
+                    suite: result.name,
+                    summary: {
+                        total: result.summary.total,
+                        passed: result.summary.passed,
+                        failed: result.summary.failed,
+                        skipped: result.summary.skipped,
+                    },
+                    failedTests: result.testResults.filter((t) => !t.passed).map((t) => ({ name: t.name, ...(t.error ? { error: t.error } : {}) })),
+                });
                 // Save JSON output if requested
                 if (options.output) {
                     const fs = await import("fs");
@@ -6011,7 +6475,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 if (options.html) {
                     const fs = await import("fs");
                     const htmlReport = generateTestSuiteHtmlReport(result);
-                    const htmlPath = options.output?.replace(".json", ".html") || "test-report.html";
+                    const htmlPath = htmlReportPath(options.output, "test-report.html");
                     fs.writeFileSync(htmlPath, htmlReport);
                     console.log(`\n🌐 HTML report saved: ${htmlPath}`);
                 }
@@ -6034,7 +6498,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.error("  --auto-apply    Automatically apply the best repair suggestion");
                     console.error("  --verify        Re-run repaired tests to verify they pass");
                     console.error("  --output <file> Save repaired tests to a new file");
-                    console.error("  --json <file>   Save repair report as JSON");
+                    console.error("  --json-out <file>  Save repair report as JSON (--json prints it)");
                     console.error("");
                     console.error("Examples:");
                     console.error("  cbrowser repair-tests broken-test.txt");
@@ -6054,8 +6518,18 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 for (const test of suite.tests) {
                     console.log(`   - ${test.name}: ${test.steps.length} steps`);
                 }
+                // --output writes the repaired file, which only exists with --auto-apply;
+                // without it the flag used to do nothing and say nothing.
+                if (options.output && options["auto-apply"] !== true) {
+                    console.error("Error: --output saves the repaired tests, which needs --auto-apply");
+                    process.exit(1);
+                }
+                const repairFlags = browserFlagsOrExit("repair-tests", options);
                 const repairOptions = {
                     headless,
+                    browser: repairFlags.browser,
+                    device: repairFlags.device,
+                    viewport: repairFlags.viewport,
                     autoApply: options["auto-apply"] === true,
                     verifyRepairs: options.verify === true,
                     maxRetries: options.retries ? parseInt(options.retries) : 3,
@@ -6064,10 +6538,18 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 // Print formatted report
                 const report = formatRepairReport(result);
                 console.log(report);
-                // Save JSON report if requested
-                if (options.json) {
-                    fs.writeFileSync(options.json, JSON.stringify(result, null, 2));
-                    console.log(`\n📄 JSON report saved: ${options.json}`);
+                // Save the JSON report: --json-out <file>, or the older --json=<file>.
+                // --json alone is the on/off flag every other command uses, so here it
+                // prints the report to stdout instead of passing `true` as a path.
+                // (Audit 2026-10-21: --json was a path here and a switch elsewhere.)
+                const jsonOut = typeof options["json-out"] === "string" ? options["json-out"]
+                    : typeof options.json === "string" ? options.json : undefined;
+                if (jsonOut) {
+                    fs.writeFileSync(jsonOut, JSON.stringify(result, null, 2));
+                    console.log(`\n📄 JSON report saved: ${jsonOut}`);
+                }
+                else if (options.json === true) {
+                    console.log(JSON.stringify(result, null, 2));
                 }
                 // Save repaired tests if requested
                 if (options.output && repairOptions.autoApply) {
@@ -6084,6 +6566,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.log("\n💡 Run with --auto-apply to automatically fix issues");
                     process.exit(1);
                 }
+                // With --auto-apply, a test that failed and was not repaired still fails.
+                if (result.summary.testsRepaired < result.summary.testsWithFailures) {
+                    console.error(`✗ ${result.summary.testsWithFailures - result.summary.testsRepaired} failing test(s) could not be repaired`);
+                    process.exit(1);
+                }
                 break;
             }
             // =========================================================================
@@ -6119,10 +6606,15 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 for (const test of suite.tests) {
                     console.log(`   - ${test.name}: ${test.steps.length} steps`);
                 }
+                const flakyFlags = browserFlagsOrExit("flaky-check", options);
                 const flakyOptions = {
                     headless,
+                    browser: flakyFlags.browser,
+                    device: flakyFlags.device,
+                    viewport: flakyFlags.viewport,
                     runs: options.runs ? parseInt(options.runs) : 5,
-                    flakinessThreshold: options.threshold ? parseInt(options.threshold) : 20,
+                    // A percentage: parseInt read "0.2" as 0, which flagged every test.
+                    flakinessThreshold: numberOption("threshold", options.threshold, 20, { min: 0, max: 100 }),
                     delayBetweenRuns: options.delay ? parseInt(options.delay) : 500,
                 };
                 const result = await detectFlakyTests(suite, flakyOptions);
@@ -6153,9 +6645,15 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error("Usage: cbrowser perf-baseline save <url> [--name <name>] [--runs <n>]");
                             process.exit(1);
                         }
+                        const perfFlags = browserFlagsOrExit("perf-baseline save", options);
+                        refuseBrowserFlags("perf-baseline save", perfFlags, {
+                            browser: "each run disables the HTTP cache through Chromium's DevTools protocol; on another engine the runs would mix cold and warm loads",
+                        });
                         console.log(`\n📊 Capturing performance baseline for: ${url}`);
                         const baselineOptions = {
                             headless,
+                            device: perfFlags.device,
+                            viewport: perfFlags.viewport,
                             name: options.name,
                             runs: options.runs ? parseInt(options.runs) : 3,
                         };
@@ -6164,6 +6662,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         console.log(`\n✅ Baseline saved: ${baseline.name}`);
                         console.log(`   ID: ${baseline.id}`);
                         console.log(`   URL: ${baseline.url}`);
+                        const env = baseline.environment;
+                        console.log(`   Page: ${env.viewport.width}x${env.viewport.height}${env.device ? ` (${env.device})` : ""}`);
                         console.log(`   Timestamp: ${new Date(baseline.timestamp).toLocaleString()}`);
                         console.log(`\n📈 Metrics (averaged over ${baseline.runsAveraged} runs):`);
                         if (baseline.metrics.lcp !== undefined) {
@@ -6283,7 +6783,19 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.error("  cbrowser perf-regression https://example.com homepage --threshold-lcp 30");
                     process.exit(1);
                 }
+                // A regression renders as its baseline was captured; a different
+                // device or size here would compare unlike pages (audit F20: these
+                // flags were accepted and dropped).
+                refuseBrowserFlags("perf-regression", browserFlagsOrExit("perf-regression", options), {
+                    device: "it renders with the baseline's recorded device; capture a new baseline with perf-baseline save --device",
+                    viewport: "it renders with the baseline's recorded size; capture a new baseline with perf-baseline save --viewport",
+                    browser: "performance baselines are measured in Chromium",
+                });
                 const sensitivity = options.sensitivity || "normal";
+                if (!["strict", "normal", "ci", "lenient"].includes(sensitivity)) {
+                    console.error(`Error: --sensitivity must be strict, normal, ci or lenient, got: ${sensitivity}`);
+                    process.exit(1);
+                }
                 console.log(`\n🔍 Checking for performance regressions...`);
                 console.log(`   URL: ${url}`);
                 console.log(`   Baseline: ${baselineName}`);
@@ -6355,6 +6867,12 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     }
                     return files;
                 }
+                // The browser flags reach the crawl. A sitemap is read without one.
+                const coverageFlags = browserFlagsOrExit("coverage", options);
+                if (options.sitemap) {
+                    const noBrowser = "--sitemap reads the sitemap without a browser, so there is no page to apply it to";
+                    refuseBrowserFlags("coverage", coverageFlags, { headless: noBrowser, browser: noBrowser, device: noBrowser, viewport: noBrowser });
+                }
                 // Handle "coverage gaps" subcommand
                 if (subcommand === "gaps") {
                     const url = args[1];
@@ -6374,6 +6892,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         sitemapUrl: options.sitemap,
                         maxPages: 50, // Quick mode
                         minCoverage: 50,
+                        ...coverageFlags,
                     };
                     const result = await generateCoverageMap(url, testFiles, coverageOptions);
                     // Show only gaps
@@ -6414,6 +6933,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     includePattern: options.include,
                     excludePattern: options.exclude,
                     minCoverage: options["min-coverage"] ? parseInt(options["min-coverage"]) : 50,
+                    ...coverageFlags,
                 };
                 if (coverageOptions.sitemapUrl) {
                     console.log(`   Using sitemap: ${coverageOptions.sitemapUrl}`);
@@ -6453,8 +6973,16 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             // Cognitive Journey (v8.0.0) - API-powered autonomous user simulation
             // =========================================================================
             case "cognitive-journey": {
+                // A replay makes no model calls, so it needs no key (audit 2026-10-21:
+                // the key gate blocked replays, and --replay-trace never reached the
+                // engine, so a "replay" was a live, paid run).
+                const replayTrace = typeof options["replay-trace"] === "string" ? resolve(options["replay-trace"]) : undefined;
+                if (replayTrace && !existsSync(replayTrace)) {
+                    console.error(`Error: trace file not found: ${replayTrace}`);
+                    process.exit(1);
+                }
                 // Check API key first
-                if (!isApiKeyConfigured()) {
+                if (!replayTrace && !isApiKeyConfigured()) {
                     // Output structured prompt for Claude Code integration
                     // Format matches Claude Agent SDK's AskUserQuestion tool
                     const apiKeyPrompt = {
@@ -6489,10 +7017,10 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.log(JSON.stringify(apiKeyPrompt, null, 2));
                     process.exit(1);
                 }
-                const startUrl = options.start;
+                const startUrl = (options.start ?? options.url); // --url works too (audit F25)
                 const goal = options.goal;
                 if (!startUrl) {
-                    console.error("Error: --start <url> is required");
+                    console.error("Error: --start <url> is required (--url works too)");
                     process.exit(1);
                 }
                 if (!goal) {
@@ -6503,12 +7031,18 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const maxSteps = options["max-steps"] ? parseInt(options["max-steps"]) : 50;
                 const maxTime = options["max-time"] ? parseInt(options["max-time"]) : 120;
                 const verbose = options.verbose === true;
-                const headless = options.headless === true;
+                // Undefined unless asked, so the engine decides from $DISPLAY. This was
+                // `=== true`, which made a plain journey launch headed on a server
+                // with no display, unlike every other command.
+                const headless = options.headless === true ? true : options.headless === false ? false : undefined;
                 const vision = options["no-vision"] !== true; // Vision ON by default (v17.1.0)
                 // Parse location options
                 let locationOverride;
-                if (options.timezone || options.locale || options.geolocation) {
+                if (options.timezone || options.locale || options.geolocation || geolocation) {
                     locationOverride = {};
+                    // The global --geo (a preset or lat,lon) was accepted here and ignored.
+                    if (geolocation)
+                        locationOverride.geolocation = { latitude: geolocation.latitude, longitude: geolocation.longitude };
                     if (options.timezone)
                         locationOverride.timezone = options.timezone;
                     if (options.locale)
@@ -6567,6 +7101,14 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         maxTime,
                         verbose,
                         headless,
+                        device: typeof options.device === "string" ? options.device : undefined,
+                        viewport: viewportOverride,
+                        trace: options.trace === true,
+                        replayTrace,
+                        // A persona is a new visitor: a fresh profile unless --persistent.
+                        // The engine's default used the shared logged-in profile, so a
+                        // "first-timer" carried the user's cookies (audit 2026-10-21).
+                        persistent: options.persistent === true,
                         vision,
                         customTraits, // Pass custom traits from env var
                         location: locationOverride, // Pass location override
@@ -6577,6 +7119,10 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     });
                     console.log("\n");
                     reportAutoCapture(result.capture);
+                    if (result.tracePath) {
+                        console.log(`🧾 Trace: ${result.tracePath}`);
+                        console.log(`   Replay it with no API calls: cbrowser cognitive-journey --start <url> --goal <goal> --replay-trace ${result.tracePath}`);
+                    }
                     if (result.goalAchieved) {
                         console.log(`✅ GOAL ACHIEVED in ${result.stepCount} steps (${result.totalTime.toFixed(1)}s)`);
                     }
@@ -6618,7 +7164,20 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     // goalAchieved genuinely means the persona reached the goal — unlike
                     // the empathy audit's field of the same old name, which measured
                     // barriers and was renamed to noBlockingBarriers.
-                    process.exit(result.goalAchieved ? 0 : 1);
+                    // journey.complete, once per journey (audit O17: it was the default
+                    // event and nothing ever sent it). Never fails the journey.
+                    await sendWebhookEvent(browser.getDataDir(), "journey.complete", {
+                        persona: personaName,
+                        goal,
+                        startUrl,
+                        goalAchieved: result.goalAchieved,
+                        ...(result.abandonmentReason ? { abandonmentReason: result.abandonmentReason } : {}),
+                        stepCount: result.stepCount,
+                        totalTimeSeconds: Math.round(result.totalTime * 10) / 10,
+                    });
+                    // Keep a failure reportAutoCapture already set: a lost capture used
+                    // to be overwritten by the goal's 0.
+                    process.exit(result.goalAchieved ? (process.exitCode ?? 0) : 1);
                 }
                 catch (error) {
                     console.error(`\n❌ Error: ${error.message}`);
@@ -6652,7 +7211,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         auditProxy = { server: geoProxy.server, username: geoProxy.username, password: geoProxy.password };
                     }
                     else {
-                        console.error(`Warning: geo-region "${geoRegion}" not configured. Run without proxy.`);
+                        // The README promises this fails loudly; it warned, ran from the
+                        // local IP, and still printed "(via <region>)" (audit 2026-10-21).
+                        console.error(`Error: geo-region "${geoRegion}" is not configured, so the audit would run from this machine's own IP.`);
+                        console.error("  Configure it in ~/.cbrowser/geo-proxy.json, or run without --geo-region.");
+                        process.exit(1);
                     }
                 }
                 console.log(`\n🤖 Running Agent-Ready Audit on ${url}...${useLightpanda ? " (with Lightpanda)" : ""}${geoRegion ? ` (via ${geoRegion})` : ""}\n`);
@@ -6660,6 +7223,10 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     headless,
                     useLightpanda,
                     ...(auditProxy ? { proxy: auditProxy } : {}),
+                    // Accepted by the engine and dropped here until 20.0, so a mobile
+                    // audit from the CLI was silently a desktop audit.
+                    ...(typeof options.device === "string" ? { device: resolveDevicePreset(options.device) } : {}),
+                    ...(typeof options.locale === "string" ? { locale: options.locale } : {}),
                 });
                 // Print formatted report
                 const report = formatAgentReadyReport(result);
@@ -6674,7 +7241,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 if (options.html) {
                     const fs = await import("fs");
                     const htmlReport = generateAgentReadyHtmlReport(result);
-                    const htmlPath = options.output?.replace(".json", ".html") || "agent-ready-report.html";
+                    const htmlPath = htmlReportPath(options.output, "agent-ready-report.html");
                     fs.writeFileSync(htmlPath, htmlReport);
                     console.log(`🌐 HTML report saved: ${htmlPath}`);
                 }
@@ -6697,8 +7264,16 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     process.exit(1);
                 }
                 console.log(`\n🏁 Running AI Readiness Benchmark on ${urls.length} sites...\n`);
+                // --device was accepted and dropped (audit F20). The audit can emulate a
+                // device but not set a bare size or another engine.
+                const benchFlags = browserFlagsOrExit("ai-benchmark", options);
+                refuseBrowserFlags("ai-benchmark", benchFlags, {
+                    viewport: "the agent-ready audit takes a device, not a bare size; use --device",
+                    browser: "the agent-ready audit runs in Chromium",
+                });
                 const result = await runAIReadinessBenchmark({
                     urls,
+                    ...(benchFlags.device ? { device: benchFlags.device } : {}),
                     headless: options.headless !== false,
                     maxConcurrency: options.concurrency ? parseInt(options.concurrency) : 3,
                 });
@@ -6711,6 +7286,9 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 for (const site of result.sites) {
                     const rank = result.ranking.find(r => r.site === site.siteName)?.rank || "-";
                     const score = site.score !== null ? site.score.toString().padStart(3) : "ERR";
+                    // A site that could not be scored is a failed run, not a blank row.
+                    if (site.score === null)
+                        process.exitCode = 1;
                     const grade = site.grade || "-";
                     const find = site.scoreBreakdown?.findability?.toString().padStart(3) || "-";
                     const stab = site.scoreBreakdown?.stability?.toString().padStart(3) || "-";
@@ -6753,7 +7331,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 // Generate HTML report if requested
                 if (options.html) {
                     const fs = await import("fs");
-                    const htmlPath = options.output?.replace(".json", ".html") || "ai-benchmark-report.html";
+                    const htmlPath = htmlReportPath(options.output, "ai-benchmark-report.html");
                     // Simple HTML table report
                     const html = `<!DOCTYPE html>
 <html lang="en">
@@ -6839,7 +7417,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const result = await runWebMCPReadyAudit(url, {
                     apiKey: options["api-key"],
                     oauthToken: options["oauth-token"],
-                    timeout: options.timeout ? parseInt(options.timeout) : 30000,
+                    timeout: timeoutOption(options.timeout, 30000),
                 });
                 // Print formatted summary
                 console.log(`╔══════════════════════════════════════════════════════════════╗`);
@@ -6879,7 +7457,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 // Generate HTML report if requested
                 if (options.html) {
                     const fs = await import("fs");
-                    const htmlPath = options.output?.replace(".json", ".html") || "webmcp-ready-report.html";
+                    const htmlPath = htmlReportPath(options.output, "webmcp-ready-report.html");
                     const htmlReport = generateWebMCPReadyHtmlReport(result);
                     fs.writeFileSync(htmlPath, htmlReport);
                     console.log(`🌐 HTML report saved: ${htmlPath}`);
@@ -6903,6 +7481,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.error("Usage: cbrowser competitive-benchmark --sites <urls> --goal <goal> [--persona <name>] [--html]");
                     process.exit(1);
                 }
+                // 20.0.0: no keyless mode (its goal verdicts were not accurate).
+                if (!isApiKeyConfigured()) {
+                    console.error("Error: competitive-benchmark needs an Anthropic API key (cbrowser config set-api-key <key>). The keyless heuristic mode was removed in 20.0.0 because its goal verdicts were not accurate.");
+                    process.exit(1);
+                }
                 const sites = sitesArg.split(",").map((s) => ({ url: s.trim() }));
                 const personaName = options.persona || "first-timer";
                 const maxSteps = options["max-steps"] ? parseInt(options["max-steps"]) : 30;
@@ -6911,6 +7494,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 console.log(`   Sites: ${sites.map((s) => s.url).join(", ")}`);
                 console.log(`   Goal: ${goal}`);
                 console.log(`   Persona: ${personaName}\n`);
+                // --device and --viewport were accepted and dropped (audit F20).
+                const journeyFlags = browserFlagsOrExit("competitive-benchmark", options);
+                refuseBrowserFlags("competitive-benchmark", journeyFlags, {
+                    browser: "cognitive journeys run in Chromium",
+                });
                 const result = await runCompetitiveBenchmark({
                     sites,
                     goal,
@@ -6918,6 +7506,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     maxSteps,
                     maxTime,
                     headless,
+                    ...(journeyFlags.device ? { device: journeyFlags.device } : {}),
+                    ...(journeyFlags.viewport ? { viewport: journeyFlags.viewport } : {}),
                 });
                 // Print formatted report
                 const report = formatCompetitiveBenchmarkReport(result);
@@ -6932,7 +7522,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 if (options.html) {
                     const fs = await import("fs");
                     const htmlReport = generateCompetitiveBenchmarkHtmlReport(result);
-                    const htmlPath = options.output?.replace(".json", ".html") || "competitive-benchmark-report.html";
+                    const htmlPath = htmlReportPath(options.output, "competitive-benchmark-report.html");
                     fs.writeFileSync(htmlPath, htmlReport);
                     console.log(`🌐 HTML report saved: ${htmlPath}`);
                 }
@@ -6941,41 +7531,22 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             case "empathy-audit": {
                 const url = args[0];
                 const goal = options.goal;
-                const disabilitiesArg = options.disabilities;
+                // --personas is what the help and its examples say; --disabilities is the
+                // older name. Before 2026-10-21 only --disabilities was read, so the
+                // documented form silently ran every accessibility persona.
+                const disabilitiesArg = (typeof options.personas === "string" ? options.personas : options.disabilities);
                 if (!url) {
                     console.error("Error: URL required");
-                    console.error("Usage: cbrowser empathy-audit <url> --goal <goal> [--disabilities <list>] [--html]");
-                    process.exit(1);
-                }
-                if (!goal) {
-                    console.error("Error: --goal required");
-                    console.error("Usage: cbrowser empathy-audit <url> --goal <goal> [--disabilities <list>] [--html]");
+                    console.error("Usage: cbrowser empathy-audit <url> [--goal <goal>] [--personas <list>] [--device <name>] [--html]");
                     process.exit(1);
                 }
+                // --goal is optional, as it is over MCP: without one the audit checks
+                // the page rather than a task (it was required here only).
                 // Parse disabilities or use all
                 const allAccessibilityNames = listAccessibilityPersonas();
-                // Short alias mapping for convenience
-                const aliasMap = {
-                    "motor-tremor": "motor-impairment-tremor",
-                    "motor": "motor-impairment-tremor",
-                    "tremor": "motor-impairment-tremor",
-                    "low-vision": "low-vision-magnified",
-                    "vision": "low-vision-magnified",
-                    "magnified": "low-vision-magnified",
-                    "adhd": "cognitive-adhd",
-                    "cognitive": "cognitive-adhd",
-                    "attention": "cognitive-adhd",
-                    "dyslexia": "dyslexic-user",
-                    "dyslexic": "dyslexic-user",
-                    "reading": "dyslexic-user",
-                    "deaf": "deaf-user",
-                    "hearing": "deaf-user",
-                    "elderly": "elderly-low-vision",
-                    "senior": "elderly-low-vision",
-                    "color-blind": "color-blind-deuteranopia",
-                    "colorblind": "color-blind-deuteranopia",
-                    "deuteranopia": "color-blind-deuteranopia",
-                };
+                // The shared alias table (personas.ts), as MCP uses. This command had its
+                // own stale copy, so --disabilities autism failed here and worked there.
+                const aliasMap = PERSONA_ALIASES;
                 const disabilityNames = disabilitiesArg
                     ? disabilitiesArg.split(",").map((d) => {
                         const trimmed = d.trim().toLowerCase();
@@ -6987,7 +7558,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 if (invalidNames.length > 0) {
                     console.error(`Error: Unknown disability persona(s): ${invalidNames.join(", ")}`);
                     console.error(`Available: ${allAccessibilityNames.join(", ")}`);
-                    console.error(`Aliases: motor-tremor, low-vision, adhd, dyslexia, deaf, elderly, color-blind`);
+                    console.error(`Aliases: ${Object.keys(aliasMap).filter((a) => allAccessibilityNames.includes(aliasMap[a]) && a !== aliasMap[a]).join(", ")}`);
                     process.exit(1);
                 }
                 const wcagLevel = options["wcag-level"] || "AA";
@@ -6998,13 +7569,22 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 console.log(`   Goal: ${goal}`);
                 console.log(`   Disabilities: ${disabilityNames.join(", ")}`);
                 console.log(`   WCAG Level: ${wcagLevel}\n`);
+                const scope = options.scope === undefined ? undefined : String(options.scope);
+                if (scope !== undefined && scope !== "viewport" && scope !== "full_page") {
+                    console.error(`Error: --scope must be viewport or full_page, got: ${scope}`);
+                    process.exit(1);
+                }
                 const result = await runEmpathyAudit(url, {
-                    goal,
+                    ...(goal ? { goal } : {}),
                     disabilities: disabilityNames,
                     wcagLevel: wcagLevel,
                     maxSteps,
                     maxTime,
                     headless,
+                    // Accepted by the engine and dropped here until 20.0 (the MCP tool
+                    // passed it), so a mobile empathy audit from the CLI was a desktop one.
+                    ...(typeof options.device === "string" ? { device: resolveDevicePreset(options.device) } : {}),
+                    ...(scope ? { scope: scope } : {}),
                 });
                 // Print formatted report
                 const report = formatEmpathyAuditReport(result);
@@ -7019,7 +7599,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 if (options.html) {
                     const fs = await import("fs");
                     const htmlReport = generateEmpathyAuditHtmlReport(result);
-                    const htmlPath = options.output?.replace(".json", ".html") || "empathy-audit-report.html";
+                    const htmlPath = htmlReportPath(options.output, "empathy-audit-report.html");
                     fs.writeFileSync(htmlPath, htmlReport);
                     console.log(`🌐 HTML report saved: ${htmlPath}`);
                 }
@@ -7048,7 +7628,7 @@ Commands:
   persona-questionnaire lookup       Look up behaviors for a specific trait value
 
 Options for 'start':
-  --comprehensive     Include all 26 traits (default: 8 core traits)
+  --comprehensive     Include all 30 traits (default: 13 core traits)
   --name <name>       Name for the persona (prompted if not provided)
   --output <file>     Save questionnaire answers to JSON file