pursr 0.10.0 → 0.10.2

package/README.md

@@ -36,23 +36,40 @@ Most teams need **five separate tools** to do visual QA: a screenshot CLI, a reg
 - **An agent-grade MCP stdio server** (`pursr-mcp`) built on the official Model Context Protocol SDK, with persistent tabs, direct image responses, rendered-state inspection, actions, diagnostics, screenshots, sweeps, and resources.
 - **Visual Operator** sessions with a rendered cursor, target labels, click markers, visible Chrome windows, and authenticated Chrome attachment over CDP.
 - **A library API** with 25 subpath modules, so you can embed the browser and QA primitives in your own tooling.
-- **A plugin system** for custom viewports, sweep ops, and capture hooks.
-- **PDF reports + AI diff summaries** built in - render a sweep to a styled PDF or ask a vision LLM to describe the regression in plain language.
-- **Zero browser bundled** - drives your system Chrome via Playwright. No 200 MB Chromium download.
+- **A plugin system** for custom viewports, sweep ops, and capture hooks.
+- **PDF reports + AI diff summaries** built in - render a sweep to a styled PDF or ask a vision LLM to describe the regression in plain language.
+- **Zero browser bundled** - drives your system Chrome, Edge, Brave, or Chromium via Playwright. No surprise browser download during install.
+- **First-run doctor + update notices** - diagnose missing browser/runtime pieces and get lightweight release notifications without breaking CI or JSON output.
 
 ## Install
 
 ```bash
-npm install pursr
-npm install --save-dev playwright-core   # peer dep - bring your own Chrome
-```
-
-Then verify:
-
-```bash
-pursr viewports         # list 10+ registered viewport presets
-pursr probe https://example.com   # health check
-```
+npm install pursr
+npm install --save-dev playwright-core   # peer dep - bring your own Chrome
+```
+
+Then verify:
+
+```bash
+pursr doctor                    # check Node, playwright-core, browser, and SKILL.md
+pursr setup                     # print next steps if anything is missing
+pursr viewports                 # list 10+ registered viewport presets
+pursr probe https://example.com # health check
+```
+
+Pursr intentionally does **not** download browsers during `npm install`. Install Chrome, Edge, Brave, or Chromium yourself, or point Pursr at a Chrome-compatible executable:
+
+```bash
+# Windows
+setx PURSR_BROWSER_PATH "C:\Program Files\Google\Chrome\Application\chrome.exe"
+
+# macOS/Linux
+export PURSR_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+```
+
+Browser discovery checks standard global installs, user installs, Dev/Beta/Canary/Nightly channels, and executable names found in `PATH` across Windows, macOS, and Linux. Current target is Chromium-family browsers; Firefox/WebKit are planned, but not claimed as stable targets yet.
+
+CLI update notifications are cached for 24 hours, written to stderr, and disabled automatically in CI/non-interactive runs. Disable them manually with `PURSR_NO_UPDATE_NOTIFIER=1`.
 
 ## 30 seconds
 
@@ -154,12 +171,23 @@ pursr baseline approve myapp ./new.png home --url https://example.com
 pursr validate ./plan.json
 ```
 
-### Subcommands
+### Subcommands
+
+Flags are order-independent. Both commands below are valid, and explicit output paths override Pursr's default output directory:
+
+```bash
+pursr shot --preset desktop-1280 https://example.com --out ./captures/home.png
+pursr full https://example.com --preset desktop-1280 --out-dir ./captures
+```
+
+`--out` is a complete file path. `--out-dir` is a directory where Pursr writes the command's standard filename.
 
-| Subcommand | Purpose |
-| --- | --- |
-| `probe` | Health check (HTTP status, page title) |
-| `shot` / `full` | Viewport / full-page screenshot |
+| Subcommand | Purpose |
+| --- | --- |
+| `doctor` | Diagnose Node, `playwright-core`, browser discovery, and packaged skill availability |
+| `setup` | Print first-run setup guidance without auto-installing browsers |
+| `probe` | Health check (HTTP status, page title) |
+| `shot` / `full` | Viewport / full-page screenshot |
 | `eval` | Execute JS in the page, return result |
 | `click` / `type` / `wait` / `seq` | Interaction primitives |
 | `operator` | Run a visible action plan with cursor feedback, screenshot, trace, diagnostics, and optional WebM video |
@@ -175,7 +203,11 @@ pursr validate ./plan.json
 | `every-viewport` | Capture once per preset in parallel (3-wide pool) |
 | `baseline` | save / list / approve / show visual baselines |
 | `auth` | save / load / list / delete Playwright storageState |
-| `validate` | Validate a sweep plan JSON without running it |
+| `validate` | Validate a sweep plan JSON without running it |
+
+### Agent Skill
+
+The npm package includes [`SKILL.md`](./SKILL.md), a compact operating guide for coding agents. Point an agent at `node_modules/pursr/SKILL.md`, or copy it into the skill directory used by your agent host. It explains when to use CLI versus MCP, correct argument order, action plans, visual verification, and safety boundaries.
 
 ## MCP Server
 

package/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: pursr
+description: Use Pursr for browser screenshots, scripted visual operation, visual regression, accessibility audits, DOM inspection, and MCP-driven browser sessions. Use when a user asks an agent to inspect a site, operate an existing browser session, fill or draft UI content, record a tutorial, compare visuals, debug layout, or behave like a careful browser operator that observes, acts, verifies, and pauses before external side effects.
+---
+
+# Pursr
+
+Use this skill when a user asks an agent to inspect, operate, record, test, or compare a browser interface.
+
+## Operator Mindset
+
+Act like a careful visual browser operator, not a command runner.
+
+- Infer the user's practical goal from the page and request, then state the first step briefly.
+- Prefer the smallest useful action: observe, act once, verify, then continue.
+- Use the current authenticated browser session when the task depends on login state, open tabs, cookies, or a dashboard the user already opened.
+- Use a fresh session for repeatable tests, visual regression, tutorial recordings, or unauthenticated pages.
+- Draft or prepare external communication, but pause before publishing, sending, buying, deleting, or changing permissions.
+- Report what changed, what was verified, and what still needs user approval.
+
+Examples:
+
+- If the user says "help me make a first post on the Twitter tab I opened", find the open tab, inspect the composer, write a polished draft, then ask before clicking `Post`.
+- If the user says "check why this dashboard looks wrong", open a session, capture a screenshot, inspect geometry/styles for the suspect element, make a small diagnosis, and propose or apply the fix if the repo is available.
+- If the user says "make a tutorial video", use `pursr operator` or MCP actions with visible cursor, labels, slow motion, screenshots, and WebM recording.
+
+## Choose The Right Surface
+
+- Use the CLI for repeatable commands and prewritten action plans.
+- Use MCP when the agent must inspect the current page, choose the next action, verify it, or pause for human approval.
+- Use `pursr doctor` before first-run debugging or when browser/runtime setup is uncertain.
+- Use `pursr setup` to give the user safe install guidance without downloading browsers automatically.
+- Use `pursr operator` for a visible scripted walkthrough or silent WebM recording.
+- Use `pursr shoot` for a rich screenshot with viewport, layer, camera, grid, or animation controls.
+- Use `pursr check` for CI regression against an approved baseline.
+- Use `pursr sweep` only with a local JSON plan path. A URL is not a sweep plan.
+
+## Capability Check
+
+Before operating a browser, pick the strongest available path:
+
+1. Existing browser-control plugin or app: use it for logged-in tabs and user-opened pages.
+2. Pursr MCP session: use it for inspect-act-verify loops, visual debugging, and agent-driven browser work.
+3. Pursr CLI: use it for screenshots, scripted operator plans, regression checks, and recordings.
+4. No browser tools: provide the draft, action plan JSON, or exact command for the user to run.
+
+Do not pretend to control the user's live browser if only the CLI is available. Use CDP attach only when the user intentionally starts Chrome with a local debugging port.
+
+## First Run And Setup
+
+Do not auto-install browsers during package installation. Pursr is intentionally lightweight at install time.
+
+Run:
+
+```bash
+pursr doctor
+pursr setup
+```
+
+Expected support target:
+
+- Chrome-compatible browsers first: Google Chrome, Microsoft Edge, Brave, and Chromium.
+- Discovery should cover global installs, user installs, Dev/Beta/Canary/Nightly channels, and executables found in `PATH` across Windows, macOS, and Linux.
+- Use `PURSR_BROWSER_PATH` when discovery misses the executable.
+- Firefox and WebKit are not the primary supported target yet; do not claim full all-browser support unless the implementation has been added and verified.
+- Update notifications are informational only, cached, written to stderr, and disabled by `PURSR_NO_UPDATE_NOTIFIER=1`.
+
+## Autonomous Browser Workflow
+
+For open-ended browser tasks:
+
+1. Discover context: list or open the relevant tab, read URL/title, and snapshot the visible page.
+2. Build intent: identify the user's real goal, the current page state, and the next safe action.
+3. Act narrowly: click, type, scroll, or run an action plan only after the target is visible or identified from a snapshot.
+4. Verify immediately: take a new snapshot, screenshot, URL check, or diagnostics read after meaningful actions.
+5. Stop at side effects: ask for confirmation immediately before final publish/send/delete/purchase/permission actions.
+6. Leave a handoff: keep important tabs or artifacts available and summarize the exact state.
+
+Use this loop for social posts, dashboard setup, design QA, local app testing, checkout-like flows, account settings, and tutorial recording.
+
+Default short progress pattern:
+
+- "I will inspect the current page first."
+- "I found the relevant tab/page and I am preparing the smallest safe action."
+- "Draft/action is ready; I am stopping before the final external side effect."
+- "Verified: [state]. Remaining approval/action: [item]."
+
+## CLI Argument Contract
+
+Flags may appear before or after positional arguments.
+
+```bash
+pursr shot --preset desktop-1280 https://example.com --out ./out/page.png
+pursr full https://example.com --out-dir ./out
+pursr eval --preset desktop-1280 https://example.com "document.title" --out ./out/eval.png
+pursr click https://example.com "role=button|Continue" --out ./out/click.png
+pursr type https://example.com "#email" "hello@example.com" --out ./out/type.png
+pursr hover https://example.com "text=Pricing" --out ./out/hover.png
+pursr seq https://example.com ./actions.json --out ./out/final.png
+pursr sweep ./sweep-plan.json --out-dir ./out/sweep
+```
+
+`--out` is a complete file path. `--out-dir` is a directory; Pursr chooses the command's standard filename inside it.
+
+For `seq` and `operator`, actions may be inline JSON, a plain `.json` path, or an `@file.json` reference.
+
+## Visual Operator
+
+```bash
+pursr operator https://example.com ./actions.json \
+  --visible --start-delay 1500 --slow-mo 80 \
+  --video ./recordings --out ./recordings/final.png
+```
+
+The result includes the action trace, final screenshot, diagnostics, and WebM path. Browser video is silent.
+
+Common actions:
+
+```json
+[
+  { "type": "annotate", "selector": "role=button|Continue", "label": "Continue" },
+  { "type": "click", "selector": "role=button|Continue" },
+  { "type": "fill", "selector": "#email", "text": "hello@example.com" },
+  { "type": "drag", "fromX": 200, "fromY": 300, "toX": 600, "toY": 300 },
+  { "type": "press", "key": "Escape" }
+]
+```
+
+## MCP Agent Loop
+
+1. Open one stable session with `pursr_session_open`.
+2. Read rendered state with `pursr_snapshot`.
+3. Perform a small action sequence with `pursr_act`.
+4. Use `pursr_screenshot` when visual judgment is needed.
+5. Use `pursr_inspect` for geometry, clipping, style, or stacking issues.
+6. Read `pursr_diagnostics` after failures.
+7. Close with `pursr_session_close`; this finalizes any video recording.
+
+Recommended MCP behavior:
+
+- Keep one persistent session per task.
+- Prefer snapshots for target discovery and screenshots for visual judgment.
+- Use `pursr_inspect` when the issue is position, z-index, clipping, opacity, transform, or layout.
+- Use `pursr_act` for small verified action batches, not long blind scripts.
+- When recording, add visible cursor movement, target labels, and short pauses so the output is understandable.
+
+## Communication Drafting
+
+When operating social media, email, forms, comments, or public dashboards:
+
+1. Draft text in the UI or provide it to the user.
+2. Verify the account/page context before filling anything.
+3. Keep tone natural and specific to the product; avoid generic AI-marketing language.
+4. Ask for final approval before clicking the button that transmits the content.
+5. After approval and posting, verify the success state or resulting URL.
+
+## Safety
+
+- Inspect before acting on unfamiliar pages.
+- Ask for human confirmation immediately before publishing, sending, purchasing, deleting, or changing permissions.
+- Keep CDP endpoints on localhost. CDP preserves the browser profile but cannot record video.
+- Do not claim a visual result passed until the produced screenshot or video has been checked.
+
+## Avoid
+
+- Do not pass a URL to `sweep`; pass a JSON plan file.
+- Do not treat `viewports` as a capture command; it only lists presets.
+- Do not use `probe` as visual evidence; it only returns HTTP and page metadata.
+- Do not invent selectors. Snapshot or inspect the page first when using MCP.

package/bin/pursr.mjs

@@ -13,12 +13,14 @@ import { runFrames } from "../src/frames.js";
 import { runDiff, runDiffWithAi } from "../src/diff.js";
 import { runSweep } from "../src/sweep.js";
 import { runEveryViewport } from "../src/every-viewport.js";
-import { runAudit } from "../src/plugin-audit.js";
-import { captureDomSnapshot } from "../src/dom-snapshot.js";
-import { listViewports } from "../src/viewport.js";
-import { parseFlags, asNum, readArg, makeOut, pickOutPath, __PURSR_GET } from "../src/util.js";
-import { writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import { runAudit } from "../src/plugin-audit.js";
+import { captureDomSnapshot } from "../src/dom-snapshot.js";
+import { listViewports } from "../src/viewport.js";
+import { asNum, readArg, makeOut, __PURSR_GET } from "../src/util.js";
+import { filePathArg, parseCommandArgs } from "../src/cli-args.js";
+import { notifyUpdate } from "../src/update-notifier.js";
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { readFileSync as _readFileSync } from "node:fs";
 const readFile = _readFileSync;
 import { loadPlugins, listPlugins, getFlagHelp } from "../src/plugin.js";
@@ -27,15 +29,16 @@ const USAGE = `usage:
   v1: pursr {probe|shot|full|eval|click|type|wait|diff|seq} <url> [...]
   v2: pursr {viewports|shoot|layer|frames|hover|sweep} <...>
   operator: pursr operator <url> <actions.json|@file> [--visible] [--start-delay 3000] [--video <dir>] [--out <final.png>]
-  flags: --preset <name> --width N --height N --dpr N
+  flags: --preset <name> --width N --height N --dpr N
          --zoom 1.5 --panX 200 --panY -100
          --cursor pointer|grab|grabbing|crosshair|none
          --layer entity|terrain|hud|ui
          --grid --grid-tile 64 --grid-color rgba(255,0,255,0.35)
          --no-animation --wait-frame 600 --full
   @file prefix reads argv contents from file (UTF-8, newline trimmed).
-  report: pursr report --sweep <sweep.json> [--out <report.pdf>] [--title "..."] [--no-embed]
-         diff extras: --ai [--ai-model M] [--ai-base-url U] [--ai-api-key K]
+  report: pursr report --sweep <sweep.json> [--out <report.pdf>] [--title "..."] [--no-embed]
+  setup: pursr doctor [--json] | pursr setup [--json]
+         diff extras: --ai [--ai-model M] [--ai-base-url U] [--ai-api-key K]
   plugins: pursr automatically loads built-in plugins from plugins/.
   You can also pass --plugin <path> to load custom plugins (repeatable).`;
 
@@ -44,60 +47,67 @@ function die(msg, code = 2) {
   process.exit(code);
 }
 
-const argv = process.argv;
-const [, , cmd, a, b, c, d] = argv;
-const url = __PURSR_GET("PURSR_URL") || a;
-// Top-level --plan / --out parsing for subcommands that need it before dispatch
-function _topOpts() {
-  const o = {};
-  for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === "--plan" && i + 1 < argv.length) o.plan = argv[++i];
-    if (argv[i] === "--out" && i + 1 < argv.length) o.out = argv[++i];
-  }
-  return o;
-}
-const opts = _topOpts();
+const argv = process.argv;
+const [, , cmd] = argv;
+const { flags: cliFlags, positionals } = parseCommandArgs(argv.slice(3));
+const [a, b, c, d] = positionals;
+const url = __PURSR_GET("PURSR_URL") || a;
+const opts = { plan: cliFlags.plan, out: cliFlags.out };
+
+function outputPath(positional, filename) {
+  if (cliFlags.out) return String(cliFlags.out);
+  if (positional) return positional;
+  if (cliFlags["out-dir"]) return join(String(cliFlags["out-dir"]), filename);
+  return makeOut(filename);
+}
+
+function dataArg(value) {
+  if (value && !value.startsWith("@") && existsSync(value)) return readFile(value, "utf8").replace(/\r?\n$/, "");
+  return readArg(value);
+}
 
 // Plugin loading: scan for --plugin <path> and built-in plugins/
 const pluginPaths = [];
 for (let i = 0; i < argv.length; i++) if (argv[i] === "--plugin" && i + 1 < argv.length) pluginPaths.push(argv[++i]);
-await loadPlugins(pluginPaths);
-
-(async () => {
-  try {
-    switch (cmd) {
+await loadPlugins(pluginPaths);
+
+(async () => {
+  try {
+    await notifyUpdate({ currentVersion: VERSION, stdout: process.stdout, stderr: process.stderr });
+    if (cliFlags.help) { console.log(JSON.stringify({ usage: USAGE }, null, 2)); return; }
+    switch (cmd) {
       case undefined: case "help": case "--help": case "-h": { console.log(JSON.stringify({ usage: USAGE }, null, 2)); break; }
       case "version": case "--version": case "-v": {
         console.log(JSON.stringify({ name: "pursr", version: VERSION, plugins: listPlugins() }, null, 2));
         break;
       }
       case "probe": { if (!url) die("missing url"); const r = await runProbe(url); console.log(JSON.stringify(r, null, 2)); break; }
-      case "shot": { if (!url) die("missing url"); const out = b || makeOut("shot.png"); const r = await runShot(url, out, { fullPage: false }); console.log(JSON.stringify(r, null, 2)); break; }
-      case "full": { if (!url) die("missing url"); const out = b || makeOut("full.png"); const r = await runShot(url, out, { fullPage: true }); console.log(JSON.stringify(r, null, 2)); break; }
-      case "eval": { if (!url) die("missing url"); const js = readArg(b); if (!js) die("eval: missing <js> (or @file)"); const out = c || makeOut("eval.png"); const r = await runEval(url, js, out); console.log(JSON.stringify(r, null, 2)); break; }
-      case "click": { if (!url) die("missing url"); const sel = b; if (!sel) die("click: missing <selector>"); const out = c || makeOut(`click-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runClick(url, sel, out); console.log(JSON.stringify(r, null, 2)); break; }
-      case "type": { if (!url) die("missing url"); const sel = b; const text = readArg(c); if (!sel || text === undefined) die("type: missing <selector> or <text> (text can be @file)"); const out = d || makeOut(`type-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runType(url, sel, text, out); console.log(JSON.stringify(r, null, 2)); break; }
-      case "wait": { if (!url) die("missing url"); const sel = b; if (!sel) die("wait: missing <selector>"); const t = c !== undefined ? asNum(c, 30000) : 30000; const r = await runWait(url, sel, t); console.log(JSON.stringify(r, null, 2)); break; }
+      case "shot": { if (!url) die("missing url"); const out = outputPath(b, "shot.png"); const r = await runShot(url, out, { ...cliFlags, fullPage: false }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "full": { if (!url) die("missing url"); const out = outputPath(b, "full.png"); const r = await runShot(url, out, { ...cliFlags, fullPage: true }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "eval": { if (!url) die("missing url"); const js = dataArg(b); if (!js) die("eval: missing <js> (or @file)"); const out = outputPath(c, "eval.png"); const r = await runEval(url, js, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
+      case "click": { if (!url) die("missing url"); const sel = b; if (!sel) die("click: missing <selector>"); const out = outputPath(c, `click-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runClick(url, sel, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
+      case "type": { if (!url) die("missing url"); const sel = b; const text = dataArg(c); if (!sel || text === undefined) die("type: missing <selector> or <text> (text can be @file)"); const out = outputPath(d, `type-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runType(url, sel, text, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
+      case "wait": { if (!url) die("missing url"); const sel = b; if (!sel) die("wait: missing <selector>"); const t = c !== undefined ? asNum(c, 30000) : 30000; const r = await runWait(url, sel, t, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
       case "diff": {
         if (!url) die("missing url"); const ref = b; if (!ref) die("diff: missing <ref.png>");
-        const out = c || makeOut("diff.png"); const threshold = d !== undefined ? Number(d) : 0.1;
-        const flags = parseFlags(argv.slice(5));
+        const out = outputPath(c, "diff.png"); const threshold = cliFlags.threshold !== undefined ? Number(cliFlags.threshold) : d !== undefined ? Number(d) : 0.1;
+        const flags = { ...cliFlags };
         // --ai / --ai-model / --ai-base-url / --ai-api-key
         const useAi = argv.includes("--ai");
-        const aiModel = (() => { const i = argv.indexOf("--ai-model"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
-        const aiBaseUrl = (() => { const i = argv.indexOf("--ai-base-url"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
-        const aiApiKey = (() => { const i = argv.indexOf("--ai-api-key"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
+        const aiModel = cliFlags["ai-model"];
+        const aiBaseUrl = cliFlags["ai-base-url"];
+        const aiApiKey = cliFlags["ai-api-key"];
         const r = useAi
           ? await runDiffWithAi(url, ref, out, threshold, flags, { model: aiModel, baseUrl: aiBaseUrl, apiKey: aiApiKey })
           : await runDiff(url, ref, out, threshold, flags);
         console.log(JSON.stringify(r, null, 2)); break;
       }
-      case "seq": { if (!url) die("missing url"); const actions = readArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = c || makeOut("seq.png"); const r = await runSeq(url, actions, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "seq": { if (!url) die("missing url"); const actions = dataArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = outputPath(c, "seq.png"); const r = await runSeq(url, actions, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
       case "operator": {
         if (!url) die("operator: missing <url>");
-        const actions = readArg(b); if (!actions) die("operator: missing <actions.json> (or @file)");
-        const flags = parseFlags(argv.slice(5));
-        const out = flags.out || makeOut("operator.png");
+        const actions = dataArg(b); if (!actions) die("operator: missing <actions.json> (or @file)");
+        const flags = { ...cliFlags };
+        const out = outputPath(null, "operator.png");
         const videoValue = flags.video ?? flags["record-video"];
         const recordVideoDir = videoValue
           ? (videoValue === true ? dirname(out) : String(videoValue))
@@ -127,19 +137,35 @@ await loadPlugins(pluginPaths);
         if (!r.ok) process.exitCode = 1;
         break;
       }
-      case "viewports": { console.log(JSON.stringify(listViewports(), null, 2)); break; }
-      case "shoot": {
+      case "viewports": { console.log(JSON.stringify(listViewports(), null, 2)); break; }
+      case "doctor": {
+        const { runDoctor, renderDoctorText } = await import("../src/doctor.js");
+        const r = await runDoctor();
+        if (cliFlags.json) console.log(JSON.stringify(r, null, 2));
+        else console.log(renderDoctorText(r));
+        process.exitCode = r.ok ? 0 : 1;
+        break;
+      }
+      case "setup": {
+        const { runSetup, renderSetupText } = await import("../src/doctor.js");
+        const r = await runSetup();
+        if (cliFlags.json) console.log(JSON.stringify(r, null, 2));
+        else console.log(renderSetupText(r));
+        process.exitCode = r.ok ? 0 : 1;
+        break;
+      }
+      case "shoot": {
         if (!url) die("missing url");
-        const out = (b && !b.startsWith("--")) ? b : pickOutPath(argv.slice(5)) || makeOut("shoot.png");
-        const r = await runShootWithSidecar({ url, out, flags: parseFlags(argv.slice(5)) });
+        const out = outputPath(b, "shoot.png");
+        const r = await runShootWithSidecar({ url, out, flags: { ...cliFlags } });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "layer": {
         if (!url) die("missing url");
         const layerName = b; if (!layerName) die("layer: missing <name>");
-        const out = (c && !c.startsWith("--")) ? c : pickOutPath(argv.slice(6)) || makeOut(`layer-${layerName}.png`);
-        const flags = parseFlags(argv.slice(7)); flags.layer = layerName;
+        const out = outputPath(c, `layer-${layerName}.png`);
+        const flags = { ...cliFlags, layer: layerName };
         const r = await runShootWithSidecar({ url, out, flags });
         console.log(JSON.stringify(r, null, 2));
         break;
@@ -148,71 +174,70 @@ await loadPlugins(pluginPaths);
         if (!url) die("missing url");
         const count = asNum(b, 8);
         const stepMs = asNum(c, 250);
-        const outDir = (d && !d.startsWith("--")) ? d : makeOut(`frames-${count}x${stepMs}ms`);
-        const r = await runFrames({ url, count, intervalMs: stepMs, outDir, flags: parseFlags(argv.slice(7)) });
+        const outDir = cliFlags["out-dir"] || cliFlags.out || d || makeOut(`frames-${count}x${stepMs}ms`);
+        const r = await runFrames({ url, count, intervalMs: stepMs, outDir, flags: { ...cliFlags } });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "hover": {
         if (!url) die("missing url");
         const sel = b; if (!sel) die("hover: missing <selector>");
-        const out = (c && !c.startsWith("--")) ? c : pickOutPath(argv.slice(6)) || makeOut(`hover-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`);
-        const r = await runHover({ url, selector: sel, out, flags: parseFlags(argv.slice(6)) });
+        const out = outputPath(c, `hover-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`);
+        const r = await runHover({ url, selector: sel, out, flags: { ...cliFlags } });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "sweep": {
-        const planPath = readArg(a);
-        if (!planPath) die("sweep: missing <plan.json> (or @file)");
-        const outDirArg = (b && !b.startsWith("--")) ? b : undefined;
+        const planPath = filePathArg(a);
+        if (!planPath) die("sweep: missing <plan.json>");
+        if (/^https?:\/\//i.test(planPath)) die("sweep: expected a local JSON plan path, not a URL");
+        const outDirArg = cliFlags["out-dir"] || cliFlags.out || b;
         const r = await runSweep(planPath, outDirArg);
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "report": {
         // pursr report --sweep <sweep.json> [--out report.pdf] [--title "..."]
-        const sweepIdx = argv.indexOf("--sweep");
-        const sweepPath = sweepIdx >= 0 && sweepIdx + 1 < argv.length ? argv[sweepIdx + 1] : a;
+        const sweepPath = cliFlags.sweep || a;
         if (!sweepPath) die("report: missing --sweep <sweep.json>");
         if (!existsSync(sweepPath)) die("report: sweep not found: " + sweepPath);
-        const outIdx = argv.indexOf("--out");
-        const outPath = outIdx >= 0 && outIdx + 1 < argv.length ? argv[outIdx + 1] : (opts.out || makeOut("report.pdf").replace(/pursr-[^-]+-shot.png$/, "report.pdf"));
+        const outPath = cliFlags.out || makeOut("report.pdf").replace(/pursr-[^-]+-shot.png$/, "report.pdf");
         if (outPath && outPath !== "-") mkdirSync(dirname(outPath), { recursive: true });
-        const titleIdx = argv.indexOf("--title");
-        const title = titleIdx >= 0 && titleIdx + 1 < argv.length ? argv[titleIdx + 1] : undefined;
-        const noEmbed = argv.includes("--no-embed");
+        const title = cliFlags.title;
+        const noEmbed = !!cliFlags["no-embed"];
         const summary = JSON.parse(readFile(sweepPath, "utf8"));
         const { renderSweepPdf } = await import("../src/report.js");
         const buf = await renderSweepPdf(summary, { out: outPath === "-" ? undefined : outPath, title, embedImages: !noEmbed });
         console.log(JSON.stringify({ ok: true, sweep: sweepPath, out: outPath, bytes: buf.length }, null, 2));
         break;
       }
-      case "every-viewport": {
-        if (!url) die("missing url");
-        const outDir = (b && !b.startsWith("--")) ? b : undefined;
-        const viewports = c?.startsWith("--") ? undefined : c?.split(",");
+      case "every-viewport": {
+        if (!url) die("missing url");
+        const outDir = cliFlags["out-dir"] || cliFlags.out || b;
+        const viewports = c?.split(",");
         const r = await runEveryViewport({ url, outDir, viewports });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
-      case "audit": {
-        if (!url) die("missing url");
-        const tags = (b && !b.startsWith("--")) ? b : undefined;
-        const outDir = (c && !c.startsWith("--")) ? c : undefined;
+      case "audit": {
+        if (!url) die("missing url");
+        const tags = cliFlags.tags || b;
+        const outDir = cliFlags["out-dir"] || cliFlags.out || c;
         const r = await runAudit({ url, tags: tags?.split(",").map(t => t.trim()), outDir });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
-      case "dom-snapshot": case "dom": {
-        if (!url) die("missing url");
-        const out = (b && !b.startsWith("--")) ? b : undefined;
+      case "dom-snapshot": case "dom": {
+        if (!url) die("missing url");
+        const out = cliFlags.out || b;
         const r = await captureDomSnapshot({ url, out });
         console.log(JSON.stringify({ url: r.url, title: r.title, elements: r.selectorMap?.length, domSize: r.dom?.length, out: r.url?.replace(/[^/]+$/, "") + "dom.json" }, null, 2));
         break;
       }
-      case "validate": {
-        const planPath = readArg(a);
-        if (!planPath) die("validate: missing <plan.json> (or @file)");
+      case "validate": {
+        const planPath = filePathArg(a);
+        if (!planPath) die("validate: missing <plan.json>");
+        if (/^https?:\/\//i.test(planPath)) die("validate: expected a local JSON plan path, not a URL");
         let plan;
         try { plan = JSON.parse(readFile(planPath, "utf8")); }
         catch (e) { die("validate: " + e.message); }
@@ -237,7 +262,7 @@ await loadPlugins(pluginPaths);
         } else if (sub === "save") {
           if (!b || !c || !d) die("baseline save: <project> <png> <step> [--id <id>] [--url <u>] [--meta-json <file>]");
           const project = b, png = c, step = d;
-          const flags = parseFlags(argv.slice(7));
+          const flags = { ...cliFlags };
           let meta = null;
           if (flags["meta-json"]) meta = JSON.parse(readFile(flags["meta-json"], "utf8"));
           else if (flags.url) meta = { url: flags.url };
@@ -253,14 +278,14 @@ await loadPlugins(pluginPaths);
         } else if (sub === "approve") {
           if (!b || !c || !d) die("baseline approve: <project> <png> <step> [--id <id>] [--url <u>]");
           const project = b, png = c, step = d;
-          const flags = parseFlags(argv.slice(7));
+          const flags = { ...cliFlags };
           const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
           const result = approveBaseline({ project, id, step, fromPng: png });
           console.log(JSON.stringify({ approved: true, ...result }, null, 2));
         } else if (sub === "show") {
           if (!b || !c) die("baseline show: <project> <step> [--id <id>] [--url <u>]");
           const project = b, step = c;
-          const flags = parseFlags(argv.slice(5));
+          const flags = { ...cliFlags };
           const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
           const r = loadBaseline({ project, id, step });
           console.log(JSON.stringify(r, null, 2));
@@ -282,14 +307,14 @@ await loadPlugins(pluginPaths);
                 console.log(JSON.stringify(listAuthStates(project), null, 2));
               } else if (sub === "save") {
                 if (!b || !c) die("auth save: <project> <name> --from <state.json>");
-                const fromFile = argv[argv.indexOf("--from") + 1];
+                const fromFile = cliFlags.from;
                 if (!fromFile) die("auth save: missing --from <state.json>");
                 const state = JSON.parse(readFile(fromFile, "utf8"));
                 const r = saveAuthState({ project: b, name: c, state });
                 console.log(JSON.stringify({ saved: true, ...r }, null, 2));
               } else if (sub === "load") {
                 if (!b || !c) die("auth load: <project> <name> --out <state.json>");
-                const outFile = argv[argv.indexOf("--out") + 1];
+                const outFile = cliFlags.out;
                 if (!outFile) die("auth load: missing --out <state.json>");
                 const state = loadAuthState({ project: b, name: c });
                 if (!state) { console.error("not found"); process.exit(2); }
@@ -312,9 +337,9 @@ await loadPlugins(pluginPaths);
                 die("watch: missing <url> (or use --plan <plan.json>)");
               }
               const { startWatch } = await import("../src/watch.js");
-              const out = (b && !b.startsWith("--")) ? b : (opts.out || makeOut("watch.png"));
+              const out = opts.out || b || makeOut("watch.png");
               if (out && out !== "--plan") mkdirSync(dirname(out), { recursive: true });
-              const flags = parseFlags(argv.slice(3));
+              const flags = { ...cliFlags };
               const onGlobs = [];
               for (let i = 0; i < argv.length; i++) {
                 if (argv[i] === "--on" && i + 1 < argv.length) onGlobs.push(argv[++i]);
@@ -341,9 +366,9 @@ await loadPlugins(pluginPaths);
               // pursr snap <url> <selector> [--out <dir>] [--name <slug>] [--max N] [--baseline <project>]
               if (!url) die("snap: missing <url>");
               const sel = b; if (!sel) die("snap: missing <selector>");
-              const flags = parseFlags(argv.slice(4));
+              const flags = { ...cliFlags };
               const { runSnap, approveSnapsAsBaselines } = await import("../src/snap.js");
-              const outDir = flags.out || makeOut("snaps").replace(/pursr-[^-]+-snap\.png$/, "snaps");
+              const outDir = flags["out-dir"] || flags.out || makeOut("snaps").replace(/pursr-[^-]+-snap\.png$/, "snaps");
               const snap = await runSnap({ url, selector: sel, outDir, name: flags.name, max: flags.max, flags });
               console.log(JSON.stringify({
                 url: snap.url,
@@ -363,7 +388,7 @@ await loadPlugins(pluginPaths);
             case "check": {
               // pursr check <url> [--preset <name>] [--update] [--json] [--threshold 0.1] [--out <diff.png>]
               if (!url) die("check: missing <url>");
-              const flags = parseFlags(argv.slice(4));
+              const flags = { ...cliFlags };
               const update = !!flags.update;
               const threshold = flags.threshold !== undefined ? Number(flags.threshold) : 0.1;
               const { runCheck } = await import("../src/check.js");