@reticlehq/server 3.6.0 → 3.7.0

package/dist/command/cli/cli-parse-verify.js

@@ -34,6 +34,10 @@ const EXPLORE_FLAG = '--explore';
 const PERSONA_FLAG = '--persona';
 /** Narrow the suite to flows carrying this label. Repeatable — a set is the union of what you name. */
 const SELECT_FLAG = '--select';
+/** Write the per-journey verdicts to this file as JSON, for a CI step that posts them. */
+const RESULTS_JSON_FLAG = '--results-json';
+/** Acknowledge, for this run only, the steps the replay guard holds as destructive ("Place order"). */
+const CONFIRM_DANGEROUS_FLAG = '--confirm-dangerous';
 /**
  * Parse `verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]
  * [--session-id <id>]`. The first non-flag token is the preview URL. `defaultPort` is already
@@ -90,6 +94,8 @@ export function parseVerifySuffix(args, defaultPort) {
     let explore = false;
     let persona;
     const select = [];
+    let resultsJson;
+    let confirmDangerous = false;
     let port = defaultPort;
     let i = 0;
     while (i < args.length) {
@@ -142,9 +148,19 @@ export function parseVerifySuffix(args, defaultPort) {
             // silently become two selections that match nothing.
             select.push(v);
         }
+        else if (arg === RESULTS_JSON_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(RESULTS_JSON_FLAG);
+            resultsJson = v;
+        }
         else if (arg === EXPLORE_FLAG) {
             explore = true;
         }
+        else if (arg === CONFIRM_DANGEROUS_FLAG) {
+            confirmDangerous = true;
+        }
         else if (arg === PERSONA_FLAG) {
             i++;
             const v = args[i];
@@ -212,5 +228,7 @@ export function parseVerifySuffix(args, defaultPort) {
         ...(explore ? { explore } : {}),
         ...(persona !== undefined ? { persona } : {}),
         ...(select.length > 0 ? { select } : {}),
+        ...(resultsJson !== undefined ? { resultsJson } : {}),
+        ...(confirmDangerous ? { confirmDangerous } : {}),
     };
 }

package/dist/command/cli/cli-parse.d.ts

@@ -3,19 +3,12 @@
  * The parser stays pure and unit-testable; `cli.ts` owns the side-effecting handlers and dispatch,
  * and re-exports this surface.
  */
-import { TutorialAudience } from './tutorial.js';
 import { type ParsedFeedback } from './cli-parse-feedback.js';
 import { HEADED_FLAG, PORT_FLAG } from './cli-parse-grammar.js';
 export { HEADED_FLAG, PORT_FLAG };
 export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
-/**
- * The lines below say `reticle <command>`, which is the bin this package installs and is correct
- * once it is on PATH. Copied into `npx`, it is not: `npx reticle` resolves the PACKAGE named
- * `reticle`, which belongs to somebody else, and npx will happily fetch and run it. The docs were
- * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
- * the usage block rather than being a footnote somewhere else.
- */
-export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle tutorial [--run] [--headless] [--port N]   (watch Reticle verify a demo app, in seconds)\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]\n                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)\n                init is ONBOARDING: it wires the project, boots the app and proves a session\n                connected. It does not drive. The FIRST RUN is the stage that proves a flow:\n                an agent drives one journey with reticle_act_and_wait and an `until` on its last\n                step; with a linked project, reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                (or reticle verify <url> --explore --persona \"\u2026\") drives it instead\n                --app picks WHICH app in a monorepo, when several are found\n                --env is what the app needs to reach a usable state: the key from\n                .env.example, the mock backend, the variable that skips an auth wall.\n                Repeatable, and a value may contain spaces and equals signs\n                --files-only writes the files and stops, which is what init did before it\n                learned to boot the app and prove the install works\n                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\n                --license writes the key to .env and keeps .env out of git\n                --json puts the result on stdout, so an agent reads one object\n                --no-open / --no-agents / --url / --timeout are the runtime dials: CI, a\n                headless box, or an app you already run\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N] [--json]                   (a readable block; --json for the event)\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)\n                       [--select <label>]              (repeatable: verify only flows carrying these labels \u2014 no model, exit 0=pass)\n                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved\n                flows needed. --expect-file avoids cmd.exe and PowerShell quote mangling. It\n                asks an existing daemon, never binds or stops one; with none, it refuses.\n                Cannot combine with --storage-state. Use when the client lacks reticle_*\n                tools. exit 0 ONLY on verified:\"yes\" \u2014 \"unknown\" is not a pass. For an\n                action --expect cannot do, drive the daemon's HTTP MCP transport instead \u2014 see\n                https://docs.reticle.sh/http-transport.md)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [--accept-coverage] [file...]  (exit non-zero unless passing artifacts cover the affected flows)\n  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)\n  reticle setup mcp                                    (register the MCP server with your agents; the installer's registration half)\n  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)\n  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle; runs/flows recorded on the dashboard):\n  reticle connect [--project <name|id>] [--url <cloud origin>]\n                                                       (wire this app if needed, sign in, link, send local history)\n  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]\n                                                       (browser device flow by default; --email mails a code)\n  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+import { CLI_USAGE } from './cli-usage.js';
+export { CLI_USAGE };
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -34,8 +27,16 @@ export declare const DAEMON_INNER_COMMAND = "_daemon";
  * defined; a second list somewhere else would drift the first time a command is added.
  */
 export declare const UNKNOWN_COMMAND = "unknown";
+/** Every command the typed parser below routes. The parser refuses any word not in this list. */
+export declare const LOCAL_COMMANDS: readonly string[];
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export declare function knownCommand(arg: string | undefined): string;
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export declare const HEADLESS_FLAG = "--headless";
 export declare const DRIVE_FLAG = "--drive";
 export declare const HTTP_FLAG = "--http";
 export declare const HTTP_PORT_FLAG = "--http-port";
@@ -62,6 +63,7 @@ export type CliResult = {
     json: boolean;
     relaunch: boolean;
     open: boolean;
+    firstRun: boolean;
     agents: boolean;
     url: string | undefined;
     timeoutSeconds: number | undefined;
@@ -98,15 +100,13 @@ export type CliResult = {
 } | Extract<ParsedFeedback, {
     kind: 'feedback';
 }> | {
-    kind: 'identify';
-    context?: string;
-    company?: string;
-    email?: string;
-    forget: boolean;
-} | {
     kind: 'version';
 } | {
     kind: 'help';
+    topic?: string;
+} | {
+    kind: 'removed';
+    message: string;
 } | {
     kind: 'doctor';
     port: number;
@@ -117,12 +117,6 @@ export type CliResult = {
     runtimeSecs: number;
     installSecs: number;
     mcp: boolean;
-} | {
-    kind: 'tutorial';
-    audience: TutorialAudience;
-    run: boolean;
-    port: number;
-    headless: boolean;
 } | {
     kind: 'open';
     port: number;
@@ -153,15 +147,12 @@ export type CliResult = {
     explore?: boolean;
     persona?: string;
     select?: string[];
+    resultsJson?: string;
+    confirmDangerous?: boolean;
 } | {
     kind: 'affected';
     files: string[];
     since?: string;
-} | {
-    kind: 'hunt';
-    dir: string;
-} | {
-    kind: 'capsules';
 } | {
     kind: 'gate';
     files: string[];
@@ -173,8 +164,8 @@ export type CliResult = {
     session?: string;
     hook: boolean;
 } | {
-    kind: 'watch';
-    url?: string;
+    kind: 'context';
+    session?: string;
 } | {
     kind: 'update';
 } | {

package/dist/command/cli/cli-parse.js

@@ -3,102 +3,18 @@
  * The parser stays pure and unit-testable; `cli.ts` owns the side-effecting handlers and dispatch,
  * and re-exports this surface.
  */
-import { TutorialAudience } from './tutorial.js';
 import { parseFeedbackArgs } from './cli-parse-feedback.js';
 import { parseVerifySuffix } from './cli-parse-verify.js';
-import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, retiredFlag, unknownArgument, } from './cli-parse-grammar.js';
+import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, retiredFlag, unknownArgument, CLOUD_COMMANDS, REMOVED_COMMANDS, removedNote, } from './cli-parse-grammar.js';
 // Re-exported because the daemon's own argv builder reaches for these through this module, which is
 // where the grammar has always lived as far as every caller is concerned.
 export { HEADED_FLAG, PORT_FLAG };
 import { FORCE_FLAG } from './cli-kill.js';
 // Re-exported so every existing importer of these flags is unaffected by the file split.
 export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
-/**
- * The lines below say `reticle <command>`, which is the bin this package installs and is correct
- * once it is on PATH. Copied into `npx`, it is not: `npx reticle` resolves the PACKAGE named
- * `reticle`, which belongs to somebody else, and npx will happily fetch and run it. The docs were
- * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
- * the usage block rather than being a footnote somewhere else.
- */
-export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticle <command>\` once the bin is on your PATH)
-
-  reticle tutorial [--run] [--headless] [--port N]   (watch Reticle verify a demo app, in seconds)
-  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
-                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)
-                init is ONBOARDING: it wires the project, boots the app and proves a session
-                connected. It does not drive. The FIRST RUN is the stage that proves a flow:
-                an agent drives one journey with reticle_act_and_wait and an \`until\` on its last
-                step; with a linked project, reticle_verify { action: "explore", persona: "…" }
-                (or reticle verify <url> --explore --persona "…") drives it instead
-                --app picks WHICH app in a monorepo, when several are found
-                --env is what the app needs to reach a usable state: the key from
-                .env.example, the mock backend, the variable that skips an auth wall.
-                Repeatable, and a value may contain spaces and equals signs
-                --files-only writes the files and stops, which is what init did before it
-                learned to boot the app and prove the install works
-                --relaunch prints the exact command that restarts THIS conversation with
-                the tools loaded, so the restart is not a chore handed to a human. It
-                refuses when the session id has no transcript behind it, because
-                --resume on an empty id opens a blank conversation that looks like
-                success. Works with --files-only
-                --license writes the key to .env and keeps .env out of git
-                --json puts the result on stdout, so an agent reads one object
-                --no-open / --no-agents / --url / --timeout are the runtime dials: CI, a
-                headless box, or an app you already run
-                --no-mcp skips MORE than the server registration: also the agent rule files
-                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
-                only make sense once the tools are reachable.
-  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
-  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)
-  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)
-  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)
-  reticle status [--port N] [--json]                   (a readable block; --json for the event)
-  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
-  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
-  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
-                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)
-                       [--select <label>]              (repeatable: verify only flows carrying these labels — no model, exit 0=pass)
-                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved
-                flows needed. --expect-file avoids cmd.exe and PowerShell quote mangling. It
-                asks an existing daemon, never binds or stops one; with none, it refuses.
-                Cannot combine with --storage-state. Use when the client lacks reticle_*
-                tools. exit 0 ONLY on verified:"yes" — "unknown" is not a pass. For an
-                action --expect cannot do, drive the daemon's HTTP MCP transport instead — see
-                https://docs.reticle.sh/http-transport.md)
-  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
-  reticle gate [--since <ref>] [--accept-coverage] [file...]  (exit non-zero unless passing artifacts cover the affected flows)
-  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)
-  reticle setup mcp                                    (register the MCP server with your agents; the installer's registration half)
-  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)
-  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)
-  reticle watch [url]                                  (on save, report which saved flows must re-verify)
-  reticle drive <url> [--headless]                     (foreground mode, for debugging)
-  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)
-  reticle update                                       (install the latest server version and restart)
-  reticle rollback                                     (restore the previous server version and restart)
-  reticle license                                      (show enterprise license status: active | eval | missing)
-  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)
-  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't; prints exactly what it sends)
-  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "message"
-                                                       (agents: file from anywhere, including a setup that never finished)
-  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
-                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
-
-Cloud (link this project to Reticle; runs/flows recorded on the dashboard):
-  reticle connect [--project <name|id>] [--url <cloud origin>]
-                                                       (wire this app if needed, sign in, link, send local history)
-  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]
-                                                       (browser device flow by default; --email mails a code)
-  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)
-  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
-  reticle whoami                                        (who am I signed in as, and is this repo attached?)
-  reticle project <ls|create <name>>                   (list or create cloud projects)
-  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
-  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)
-  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
-
-'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
-and the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.`;
+// The help text lives on its own page; re-exported so every importer of it is unaffected.
+import { CLI_USAGE } from './cli-usage.js';
+export { CLI_USAGE };
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
@@ -108,16 +24,15 @@ const STATUS_COMMAND = 'status';
 const OPEN_COMMAND = 'open';
 const DRIVE_COMMAND = 'drive';
 const AFFECTED_COMMAND = 'affected';
-const HUNT_COMMAND = 'hunt';
-const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
 /** Hook mode: prose a human can read, and silence when there was simply nothing to check. */
 const HOOK_FLAG = '--hook';
 const ACCEPT_COVERAGE_FLAG = '--accept-coverage';
 /** `reticle report [--session <id>] [--hook]` — what the latest session claimed, and what held. */
 const REPORT_COMMAND = 'report';
+/** `reticle context --compact`: the resume block, from disk. A SessionStart hook prints it. */
+const CONTEXT_COMMAND = 'context';
 const SESSION_FLAG = '--session';
-const WATCH_COMMAND = 'watch';
 const UPDATE_COMMAND = 'update';
 const ROLLBACK_COMMAND = 'rollback';
 const MCP_COMMAND = 'mcp';
@@ -125,11 +40,8 @@ const LICENSE_COMMAND = 'license';
 const VERSION_COMMAND = 'version';
 const TELEMETRY_COMMAND = 'telemetry';
 const FEEDBACK_COMMAND = 'feedback';
-const IDENTIFY_COMMAND = 'identify';
-const COMPANY_FLAG = '--company';
-const EMAIL_FLAG = '--email';
-const CONTEXT_FLAG = '--context';
-const FORGET_FLAG = '--forget';
+const DOCTOR_COMMAND = 'doctor';
+const SETUP_COMMAND = 'setup';
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export const TelemetryAction = {
     STATUS: 'status',
@@ -147,7 +59,10 @@ export const DAEMON_INNER_COMMAND = '_daemon';
  * defined; a second list somewhere else would drift the first time a command is added.
  */
 export const UNKNOWN_COMMAND = 'unknown';
-const KNOWN_COMMANDS = new Set([
+const HELP_COMMAND = 'help';
+const HELP_FLAGS = new Set(['--help', '-h']);
+/** Every command the typed parser below routes. The parser refuses any word not in this list. */
+export const LOCAL_COMMANDS = [
     INIT_COMMAND,
     SERVE_COMMAND,
     STOP_COMMAND,
@@ -158,11 +73,9 @@ const KNOWN_COMMANDS = new Set([
     DRIVE_COMMAND,
     VERIFY_COMMAND,
     AFFECTED_COMMAND,
-    HUNT_COMMAND,
-    CAPSULES_COMMAND,
     GATE_COMMAND,
     REPORT_COMMAND,
-    WATCH_COMMAND,
+    CONTEXT_COMMAND,
     UPDATE_COMMAND,
     ROLLBACK_COMMAND,
     MCP_COMMAND,
@@ -170,25 +83,23 @@ const KNOWN_COMMANDS = new Set([
     VERSION_COMMAND,
     TELEMETRY_COMMAND,
     FEEDBACK_COMMAND,
-    IDENTIFY_COMMAND,
     DAEMON_INNER_COMMAND,
-    'connect',
-    'login',
-    'logout',
-    'whoami',
-    'link',
-    'project',
-    'config',
-    'push',
-    'runs',
-    'issues',
-    'memory',
-    'regression',
-    'share',
-    'doctor',
-    'setup',
-    'tutorial',
-    'help',
+    DOCTOR_COMMAND,
+    SETUP_COMMAND,
+];
+const LOCAL_COMMAND_SET = new Set(LOCAL_COMMANDS);
+const KNOWN_COMMANDS = new Set([
+    ...LOCAL_COMMANDS,
+    ...CLOUD_COMMANDS,
+    ...REMOVED_COMMANDS.keys(),
+    HELP_COMMAND,
+]);
+/** The conventional flag spellings of two commands, reported as the command they ask for. */
+const COMMAND_FLAG_ALIASES = new Map([
+    ['--version', VERSION_COMMAND],
+    ['-v', VERSION_COMMAND],
+    ['--help', HELP_COMMAND],
+    ['-h', HELP_COMMAND],
 ]);
 /**
  * A non-negative integer flag, or 0.
@@ -207,15 +118,15 @@ function numberFlag(args, name) {
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export function knownCommand(arg) {
     if (arg === undefined || '' === arg)
-        return 'help';
-    return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
+        return HELP_COMMAND;
+    return KNOWN_COMMANDS.has(arg) ? arg : (COMMAND_FLAG_ALIASES.get(arg) ?? UNKNOWN_COMMAND);
 }
 /**
  * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
  * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
  * CI, which flips the default) because there is no display there to be headed on.
  */
-const HEADLESS_FLAG = '--headless';
+export const HEADLESS_FLAG = '--headless';
 export const DRIVE_FLAG = '--drive';
 const QUIET_FLAG = '--quiet';
 const DRY_RUN_FLAG = '--dry-run';
@@ -236,6 +147,8 @@ const FLOW_FLAG = '--flow';
 const FIRST_RUN_MOVED = 'onboarding wires the project, the FIRST RUN proves a flow. Drive one with reticle_verify { action: "explore", persona: "<who does what>" }, or npx @reticlehq/server verify <url> --explore --persona "<who does what>"';
 const ENV_FLAG = '--env';
 const FILES_ONLY_FLAG = '--files-only';
+/** With `--app`, also start the app: naming one app of a workspace otherwise writes its files only. */
+const START_FLAG = '--start';
 /**
  * Write `captureNetworkBodies: true` into the app's config. OFF unless asked (#705).
  *
@@ -256,6 +169,8 @@ const HOOKS_FLAG = '--hooks';
 const JSON_FLAG = '--json';
 const NO_DRIVE_FLAG = '--no-drive';
 const NO_OPEN_FLAG = '--no-open';
+/** Connect and stop: no coverage summary and no prompt at the end. */
+const NO_FIRST_RUN_FLAG = '--no-first-run';
 const NO_AGENTS_FLAG = '--no-agents';
 /**
  * Restart the calling client so IT gets the tools.
@@ -281,12 +196,6 @@ const NO_INSTALL_FLAG = '--no-install';
 export const HTTP_FLAG = '--http';
 export const HTTP_PORT_FLAG = '--http-port';
 export const HTTP_TOKEN_FLAG = '--http-token';
-/**
- * `serve` / `mcp` / `_daemon` own the browser POOL, which backs automated work — leased contexts for
- * parallel agents, flow replay, the spec runner. Those are batch: nobody is watching, and launching
- * them headed changed timing enough to break four e2e specs. The headed default belongs to the
- * INTERACTIVE command (`drive`), where a human asked to see the run. `--headed` still opts in here.
- */
 /**
  * A usage error names the thing that was wrong.
  *
@@ -307,10 +216,10 @@ const unknownCommand = (command) => ({
     kind: 'error',
     message: `unknown command '${command}'`,
 });
-function parseServeFlags(args, defaultPort, _defaultHeadless) {
+function parseServeFlags(args, defaultPort, defaultHeadless) {
     let port = defaultPort;
     let driveUrl;
-    let headless = true;
+    let headless = defaultHeadless;
     let http = false;
     let httpPort;
     let httpToken;
@@ -427,10 +336,12 @@ function parseInitFlags(args) {
     // Repeatable: one variable per flag, so a value containing spaces or `=` needs no quoting rules.
     const env = [];
     let filesOnly = false;
+    let start = false;
     let captureBodies = false;
     let hooks = false;
     let json = false;
     let open = true;
+    let firstRun = true;
     let relaunch = false;
     let agents = true;
     let url;
@@ -473,6 +384,9 @@ function parseInitFlags(args) {
         else if (arg === FILES_ONLY_FLAG) {
             filesOnly = true;
         }
+        else if (arg === START_FLAG) {
+            start = true;
+        }
         else if (arg === CAPTURE_BODIES_FLAG) {
             captureBodies = true;
         }
@@ -485,6 +399,9 @@ function parseInitFlags(args) {
         else if (arg === NO_OPEN_FLAG) {
             open = false;
         }
+        else if (arg === NO_FIRST_RUN_FLAG) {
+            firstRun = false;
+        }
         else if (arg === RELAUNCH_FLAG) {
             relaunch = true;
         }
@@ -540,11 +457,14 @@ function parseInitFlags(args) {
         install,
         app,
         env,
-        filesOnly,
+        // One app of a workspace, named: its files, and nothing started unless asked (`--start`). Its
+        // dev server is often run from the root, and a monorepo init started the daemon and failed it.
+        filesOnly: filesOnly || (app !== undefined && !start),
         captureBodies,
         hooks,
         json,
         open,
+        firstRun,
         relaunch,
         agents,
         url,
@@ -592,8 +512,6 @@ function parseTargetArgs(rest) {
 export function dialsTheDaemon(parsed) {
     if ('init' === parsed.kind)
         return false;
-    if ('tutorial' === parsed.kind)
-        return parsed.run;
     return 'port' in parsed;
 }
 /**
@@ -603,9 +521,9 @@ export function dialsTheDaemon(parsed) {
  *   trustworthy, and asking people to opt into seeing their own app was backwards.
  */
 export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
-    // Bare `reticle` is `serve` — a pool-owning command, so headless like the rest of that family.
+    // Bare `reticle` is `serve`.
     if (0 === argv.length)
-        return { kind: 'serve', port: defaultPort, headless: true, http: false };
+        return { kind: 'serve', port: defaultPort, headless: defaultHeadless, http: false };
     const [cmd, ...rest] = argv;
     // Guaranteed by the bare-argv check above; restated so the unknown-command error can name it.
     if (cmd === undefined)
@@ -623,9 +541,22 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
     // `reticle_usage_error: unknown argument '--help'` on stderr with exit 1. The usage text was
     // printed underneath it, so the request was in fact answered; it was simply answered as a failure,
     // which is the wrong first impression to give somebody who has just asked a tool what it does.
-    if ('help' === cmd || argv.some((arg) => '--help' === arg || '-h' === arg)) {
-        return { kind: 'help' };
+    //
+    // Removed commands answer before help does: `reticle hunt --help` should say it is gone, not
+    // describe something that no longer runs.
+    const removed = REMOVED_COMMANDS.get(cmd);
+    if (removed !== undefined)
+        return { kind: 'removed', message: removedNote(cmd, removed) };
+    if (HELP_COMMAND === cmd || HELP_FLAGS.has(cmd)) {
+        // `reticle help all`, `reticle --help all`, `reticle help init`.
+        const topic = rest.find((arg) => !HELP_FLAGS.has(arg));
+        return topic === undefined ? { kind: 'help' } : { kind: 'help', topic };
     }
+    if (argv.some((arg) => HELP_FLAGS.has(arg)))
+        return { kind: 'help', topic: cmd };
+    // The list is the gate, so a command cannot be routed without also being named in telemetry.
+    if (!LOCAL_COMMAND_SET.has(cmd))
+        return unknownCommand(cmd);
     switch (cmd) {
         case INIT_COMMAND: {
             const r = parseInitFlags(rest);
@@ -644,6 +575,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 hooks: r.hooks,
                 json: r.json,
                 open: r.open,
+                firstRun: r.firstRun,
                 relaunch: r.relaunch,
                 agents: r.agents,
                 url: r.url,
@@ -667,6 +599,10 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case STOP_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
+            // `stop --force` is what `kill` was: free the port by its listener, which must still be a
+            // Reticle daemon. Overriding that refusal stays on `restart --force` and the old `kill --force`.
+            if (rest.includes(FORCE_FLAG))
+                return { kind: 'kill', port, force: false };
             const quiet = rest.includes(QUIET_FLAG);
             return { kind: 'stop', port, quiet };
         }
@@ -685,22 +621,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             // parsing it knows to ask for the object.
             return { kind: 'status', port, json: rest.includes(JSON_FLAG) };
         }
-        case 'tutorial': {
-            // `--agent` is the opt-in, because a person typing this is the common case and should not have
-            // to ask for prose. An agent knows to pass the flag; a human would not know to avoid it.
-            const audience = argv.includes('--agent') ? TutorialAudience.AGENT : TutorialAudience.HUMAN;
-            // `--run` drives the demo instead of describing it. Opt-in rather than the default: the tour
-            // starts a daemon and opens a browser, and a command that did that to somebody who typed it
-            // expecting a page of text would be a surprise in the one place surprises are least welcome.
-            return {
-                kind: 'tutorial',
-                audience,
-                run: argv.includes('--run'),
-                port: parsePortFlag(rest, defaultPort),
-                headless: !argv.includes('--headed'),
-            };
-        }
-        case 'doctor': {
+        case DOCTOR_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             return { kind: 'doctor', port };
         }
@@ -716,7 +637,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
          * no flag: it tells a reader a confirmation exists. What this writes is stated before it runs
          * and printed after, which is the honest version of the same reassurance.
          */
-        case 'setup': {
+        case SETUP_COMMAND: {
             const what = rest[0];
             /*
              * `setup install` — the Node half of the one-line installer.
@@ -737,7 +658,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             // Only `mcp` today. A bare `reticle setup` falls to help rather than guessing, because the
             // next subcommand here will not be a synonym for this one.
             if (what !== 'mcp')
-                return { kind: 'help' };
+                return { kind: 'help', topic: SETUP_COMMAND };
             return { kind: 'setup-mcp' };
         }
         case LICENSE_COMMAND:
@@ -751,22 +672,6 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             }
             return { kind: 'telemetry', action };
         }
-        case IDENTIFY_COMMAND: {
-            const flag = (name) => {
-                const at = rest.indexOf(name);
-                return -1 === at ? undefined : rest[at + 1];
-            };
-            const context = flag(CONTEXT_FLAG);
-            const company = flag(COMPANY_FLAG);
-            const email = flag(EMAIL_FLAG);
-            return {
-                kind: 'identify',
-                ...(context !== undefined ? { context } : {}),
-                ...(company !== undefined ? { company } : {}),
-                ...(email !== undefined ? { email } : {}),
-                forget: rest.includes(FORGET_FLAG),
-            };
-        }
         case FEEDBACK_COMMAND:
             return parseFeedbackArgs(rest);
         case OPEN_COMMAND: {
@@ -812,16 +717,10 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(true === r.explore ? { explore: true } : {}),
                 ...(r.persona !== undefined ? { persona: r.persona } : {}),
                 ...(r.select !== undefined ? { select: r.select } : {}),
+                ...(r.resultsJson !== undefined ? { resultsJson: r.resultsJson } : {}),
+                ...(true === r.confirmDangerous ? { confirmDangerous: true } : {}),
             };
         }
-        case CAPSULES_COMMAND:
-            return { kind: 'capsules' };
-        case HUNT_COMMAND: {
-            const dir = rest.find((a) => !a.startsWith('-'));
-            return dir === undefined
-                ? { kind: 'error', message: 'usage: reticle hunt <dir-of-crawl-reports>' }
-                : { kind: 'hunt', dir };
-        }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
             const since = t.since ?? implicitSince(t.files);
@@ -850,10 +749,11 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(session === undefined ? {} : { session }),
             };
         }
-        case WATCH_COMMAND: {
-            // `reticle watch [url]` — on file save, report which saved flows must re-verify.
-            const url = rest.find((arg) => !arg.startsWith('-'));
-            return url === undefined ? { kind: 'watch' } : { kind: 'watch', url };
+        case CONTEXT_COMMAND: {
+            // `--compact` is the only form; accepted so the hook line reads as what it does.
+            const at = rest.indexOf(SESSION_FLAG);
+            const session = -1 === at ? undefined : rest[at + 1];
+            return { kind: 'context', ...(session === undefined ? {} : { session }) };
         }
         case UPDATE_COMMAND:
             return { kind: 'update' };

package/dist/command/cli/cli-update-commands.d.ts

@@ -1,4 +1,4 @@
 /** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
-export declare function handleUpdate(): Promise<void>;
+export declare function handleUpdate(cwd?: string): Promise<void>;
 /** `reticle rollback` — restore the previous server version and restart. */
 export declare function handleRollback(): Promise<void>;