@reticlehq/server 2.4.0 → 2.6.0

package/dist/{cli-parse.d.ts → cli/cli-parse.d.ts}

@@ -4,14 +4,9 @@
  * file-size cap and keep the parser pure + unit-testable. Re-exported from cli.ts so existing
  * imports are unchanged.
  */
-export declare const CLI_USAGE = "usage:\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]\n  reticle status [--port N]\n  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port \u2014 one command)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode \u2014 for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy \u2014 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 \u2014 status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't \u2014 prints exactly what it sends)\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 Cloud \u2014 runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\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                                          (send local run artifacts to the dashboard)\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 \u2014 batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
-export declare const COMPANY_FLAG = "--company";
-export declare const EMAIL_FLAG = "--email";
-export declare const CONTEXT_FLAG = "--context";
-export declare const FORGET_FLAG = "--forget";
-/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
-export declare const RATING_FLAG = "--rating";
-export declare const BUG_FLAG = "--bug";
+import { type ParsedFeedback } from './cli-parse-feedback.js';
+export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
+export declare const CLI_USAGE = "usage:\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\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]\n  reticle status [--port N]\n  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port \u2014 one command)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode \u2014 for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy \u2014 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 \u2014 status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't \u2014 prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> \"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 Cloud \u2014 runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\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                                          (send local run artifacts to the dashboard)\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 \u2014 batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -33,12 +28,6 @@ export declare const UNKNOWN_COMMAND = "unknown";
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export declare function knownCommand(arg: string | undefined): string;
 export declare const HEADED_FLAG = "--headed";
-/**
- * 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 PORT_FLAG = "--port";
 export declare const DRIVE_FLAG = "--drive";
 export declare const HTTP_FLAG = "--http";
@@ -50,6 +39,7 @@ export type CliResult = {
     mcp: boolean;
     dryRun: boolean;
     install: boolean;
+    app: string | undefined;
 } | {
     kind: 'serve';
     port: number;
@@ -70,12 +60,9 @@ export type CliResult = {
 } | {
     kind: 'telemetry';
     action: TelemetryAction;
-} | {
+} | Extract<ParsedFeedback, {
     kind: 'feedback';
-    text: string;
-    rating?: number;
-    bug: boolean;
-} | {
+}> | {
     kind: 'identify';
     context?: string;
     company?: string;

package/dist/{cli-parse.js → cli/cli-parse.js}

@@ -4,8 +4,15 @@
  * file-size cap and keep the parser pure + unit-testable. Re-exported from cli.ts so existing
  * imports are unchanged.
  */
+import { parseFeedbackArgs } from './cli-parse-feedback.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';
 export const CLI_USAGE = `usage:
-  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)
+  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
+                --app picks WHICH app in a monorepo, when several are found
+                --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]
   reticle status [--port N]
@@ -22,6 +29,8 @@ export const CLI_USAGE = `usage:
   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> "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)
 
@@ -56,13 +65,10 @@ const VERSION_COMMAND = 'version';
 const TELEMETRY_COMMAND = 'telemetry';
 const FEEDBACK_COMMAND = 'feedback';
 const IDENTIFY_COMMAND = 'identify';
-export const COMPANY_FLAG = '--company';
-export const EMAIL_FLAG = '--email';
-export const CONTEXT_FLAG = '--context';
-export const FORGET_FLAG = '--forget';
-/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
-export const RATING_FLAG = '--rating';
-export const BUG_FLAG = '--bug';
+const COMPANY_FLAG = '--company';
+const EMAIL_FLAG = '--email';
+const CONTEXT_FLAG = '--context';
+const FORGET_FLAG = '--forget';
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export const TelemetryAction = {
     STATUS: 'status',
@@ -118,7 +124,7 @@ const KNOWN_COMMANDS = new Set([
 ]);
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export function knownCommand(arg) {
-    if (arg === undefined || arg === '')
+    if (arg === undefined || '' === arg)
         return 'help';
     return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
 }
@@ -128,25 +134,40 @@ export const HEADED_FLAG = '--headed';
  * 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 const HEADLESS_FLAG = '--headless';
+const HEADLESS_FLAG = '--headless';
 export const PORT_FLAG = '--port';
 export const DRIVE_FLAG = '--drive';
 const QUIET_FLAG = '--quiet';
 const DRY_RUN_FLAG = '--dry-run';
 const YES_FLAG = '--yes';
 const NO_MCP_FLAG = '--no-mcp';
+const APP_FLAG = '--app';
 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';
 const TIMEOUT_FLAG = '--timeout';
 const STORAGE_STATE_FLAG = '--storage-state';
-/**
- * `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.
- */
+const unknownArgument = (arg) => ({
+    kind: 'error',
+    message: `unknown argument '${arg}'`,
+});
+const missingValue = (flag) => ({
+    kind: 'error',
+    message: `${flag} needs a value`,
+});
+const notANumber = (flag, value) => ({
+    kind: 'error',
+    message: `${flag} expects a number, got '${value}'`,
+});
+const missingOperand = (command, what) => ({
+    kind: 'error',
+    message: `${command} needs ${what}`,
+});
+const unknownCommand = (command) => ({
+    kind: 'error',
+    message: `unknown command '${command}'`,
+});
 function parseServeFlags(args, defaultPort, _defaultHeadless) {
     let port = defaultPort;
     let driveUrl;
@@ -157,21 +178,25 @@ function parseServeFlags(args, defaultPort, _defaultHeadless) {
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
+        // `i < args.length` already guarantees this, but the index signature does not say so and the
+        // unknown-argument error needs a real string to name.
+        if (arg === undefined)
+            break;
         if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(PORT_FLAG, n);
             port = parsed;
         }
         else if (arg === DRIVE_FLAG) {
             i++;
             driveUrl = args[i];
             if (driveUrl === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(DRIVE_FLAG);
         }
         else if (arg === HEADED_FLAG) {
             headless = false;
@@ -186,20 +211,20 @@ function parseServeFlags(args, defaultPort, _defaultHeadless) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(HTTP_PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(HTTP_PORT_FLAG, n);
             httpPort = parsed;
         }
         else if (arg === HTTP_TOKEN_FLAG) {
             i++;
             httpToken = args[i];
             if (httpToken === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(HTTP_TOKEN_FLAG);
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
@@ -215,7 +240,7 @@ function parseServeFlags(args, defaultPort, _defaultHeadless) {
 }
 function parsePortFlag(args, defaultPort) {
     const idx = args.indexOf(PORT_FLAG);
-    if (idx === -1)
+    if (-1 === idx)
         return defaultPort;
     const n = args[idx + 1];
     if (n === undefined)
@@ -234,17 +259,17 @@ function parseDriveSuffix(args, port, defaultHeadless) {
             headless = true;
         }
         else if (arg.startsWith('--')) {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         else if (driveUrl === undefined) {
             driveUrl = arg;
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
     }
     if (driveUrl === undefined)
-        return { kind: 'error', message: CLI_USAGE };
+        return missingOperand(DRIVE_COMMAND, 'a url');
     return { kind: 'ok', port, driveUrl, headless };
 }
 /**
@@ -268,32 +293,32 @@ function parseVerifySuffix(args) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(TIMEOUT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(TIMEOUT_FLAG, n);
             timeoutMs = parsed;
         }
         else if (arg === STORAGE_STATE_FLAG) {
             i++;
             const v = args[i];
             if (v === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(STORAGE_STATE_FLAG);
             storageState = v;
         }
         else if (arg.startsWith('--')) {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         else if (url === undefined) {
             url = arg;
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
     if (url === undefined)
-        return { kind: 'error', message: CLI_USAGE };
+        return missingOperand(VERIFY_COMMAND, 'a url');
     return {
         kind: 'ok',
         url,
@@ -307,19 +332,31 @@ function parseInitFlags(args) {
     let mcp = true;
     let dryRun = false;
     let install = true;
+    let app;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
+        // `i < args.length` already guarantees this, but the index signature does not say so and the
+        // unknown-argument error needs a real string to name.
+        if (arg === undefined)
+            break;
         if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
             if (n === undefined)
-                return { kind: 'error', message: CLI_USAGE };
+                return missingValue(PORT_FLAG);
             const parsed = parseInt(n, 10);
             if (isNaN(parsed))
-                return { kind: 'error', message: CLI_USAGE };
+                return notANumber(PORT_FLAG, n);
             port = parsed;
         }
+        else if (arg === APP_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(APP_FLAG);
+            app = value;
+        }
         else if (arg === NO_MCP_FLAG) {
             mcp = false;
         }
@@ -333,15 +370,29 @@ function parseInitFlags(args) {
             // Accepted for scripting/CI; init has no interactive prompts today.
         }
         else {
-            return { kind: 'error', message: CLI_USAGE };
+            return unknownArgument(arg);
         }
         i++;
     }
-    return { kind: 'ok', port, mcp, dryRun, install };
+    return { kind: 'ok', port, mcp, dryRun, install, app };
 }
 /** Pure CLI arg parser — exported for unit tests. argv = process.argv.slice(2). */
 const SINCE_FLAG = '--since';
 /** Parse `[--since <ref>] [file...]` shared by `affected` and `gate`. */
+/**
+ * What `reticle gate` / `reticle affected` mean with NOTHING after them: the working tree.
+ *
+ * They used to mean a usage error — while the rule `reticle init` writes into the agent's own
+ * instruction file says, in as many words, "run `reticle gate`". An instruction the tool rejects is
+ * worse than no instruction: the agent spends a turn on it and concludes Reticle is broken.
+ *
+ * HEAD is the ref that answers the question being asked. Explicit files or an explicit --since still
+ * win; this only fills the empty case.
+ */
+const WORKING_TREE_REF = 'HEAD';
+function implicitSince(files) {
+    return 0 === files.length ? WORKING_TREE_REF : undefined;
+}
 function parseTargetArgs(rest) {
     const files = [];
     let since;
@@ -365,27 +416,37 @@ function parseTargetArgs(rest) {
  */
 export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
     // Bare `reticle` is `serve` — a pool-owning command, so headless like the rest of that family.
-    if (argv.length === 0)
+    if (0 === argv.length)
         return { kind: 'serve', port: defaultPort, headless: true, 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)
+        return { kind: 'error', message: CLI_USAGE };
     // `version` (or the conventional -v/--version flags) prints the running version — the diagnostic the
     // troubleshooting docs lean on to confirm which npx-resolved build is actually executing.
-    if (cmd === VERSION_COMMAND || cmd === '--version' || cmd === '-v')
+    if (cmd === VERSION_COMMAND || '--version' === cmd || '-v' === cmd)
         return { kind: 'version' };
     // `help` (and the conventional -h/--help) print usage to stdout and exit 0 — the universal first move
     // for a new user, which otherwise fell through to a JSON error with exit 1.
-    if (cmd === 'help' || cmd === '--help' || cmd === '-h')
+    if ('help' === cmd || '--help' === cmd || '-h' === cmd)
         return { kind: 'help' };
     switch (cmd) {
         case INIT_COMMAND: {
             const r = parseInitFlags(rest);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
-            return { kind: 'init', port: r.port, mcp: r.mcp, dryRun: r.dryRun, install: r.install };
+            return {
+                kind: 'init',
+                port: r.port,
+                mcp: r.mcp,
+                dryRun: r.dryRun,
+                install: r.install,
+                app: r.app,
+            };
         }
         case SERVE_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'serve',
@@ -424,7 +485,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         case IDENTIFY_COMMAND: {
             const flag = (name) => {
                 const at = rest.indexOf(name);
-                return at === -1 ? undefined : rest[at + 1];
+                return -1 === at ? undefined : rest[at + 1];
             };
             const context = flag(CONTEXT_FLAG);
             const company = flag(COMPANY_FLAG);
@@ -437,26 +498,8 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 forget: rest.includes(FORGET_FLAG),
             };
         }
-        case FEEDBACK_COMMAND: {
-            const ratingAt = rest.indexOf(RATING_FLAG);
-            const rating = ratingAt === -1 ? undefined : Number(rest[ratingAt + 1]);
-            if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
-                return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
-            }
-            // Everything that is not a flag or the rating's value is the message. Quoting is the user's
-            // job for shell reasons, but joining the remainder means an unquoted sentence still works.
-            const consumed = new Set(ratingAt === -1 ? [] : [ratingAt, ratingAt + 1]);
-            const text = rest
-                .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
-                .join(' ')
-                .trim();
-            return {
-                kind: 'feedback',
-                text,
-                ...(rating !== undefined ? { rating } : {}),
-                bug: rest.includes(BUG_FLAG),
-            };
-        }
+        case FEEDBACK_COMMAND:
+            return parseFeedbackArgs(rest);
         case OPEN_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             // The first non-flag arg is the url (optional — omitting reuses a connected tab).
@@ -465,13 +508,13 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case DRIVE_COMMAND: {
             const r = parseDriveSuffix(rest, defaultPort, defaultHeadless);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return { kind: 'drive', port: r.port, driveUrl: r.driveUrl, headless: r.headless };
         }
         case DAEMON_INNER_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: '_daemon',
@@ -485,7 +528,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case VERIFY_COMMAND: {
             const r = parseVerifySuffix(rest);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'verify',
@@ -505,21 +548,13 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
-            if (t.files.length === 0 && t.since === undefined) {
-                return { kind: 'error', message: 'usage: reticle affected [--since <ref>] [file...]' };
-            }
-            return {
-                kind: 'affected',
-                files: t.files,
-                ...(t.since === undefined ? {} : { since: t.since }),
-            };
+            const since = t.since ?? implicitSince(t.files);
+            return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case GATE_COMMAND: {
             const t = parseTargetArgs(rest);
-            if (t.files.length === 0 && t.since === undefined) {
-                return { kind: 'error', message: 'usage: reticle gate [--since <ref>] [file...]' };
-            }
-            return { kind: 'gate', files: t.files, ...(t.since === undefined ? {} : { since: t.since }) };
+            const since = t.since ?? implicitSince(t.files);
+            return { kind: 'gate', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case WATCH_COMMAND: {
             // `reticle watch [url]` — on file save, report which saved flows must re-verify.
@@ -532,7 +567,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'rollback' };
         case MCP_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if (r.kind === 'error')
+            if ('error' === r.kind)
                 return r;
             return {
                 kind: 'mcp',
@@ -545,6 +580,8 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             };
         }
         default:
-            return { kind: 'error', message: CLI_USAGE };
+            // A bare `reticle` never lands here — it defaults to `serve` above — so `cmd` is always a real
+            // word somebody typed, and naming it is strictly more useful than reprinting the whole help.
+            return unknownCommand(cmd);
     }
 }

package/dist/{cli-port.d.ts → cli/cli-port.d.ts}

@@ -7,6 +7,18 @@
  * 3..reticle.json "port" field in the cwd ← per-project isolation
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
+/**
+ * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
+ * Astro to 4321, and so on.
+ *
+ * `.reticle.json`'s `port` is the bridge — the daemon ↔ SDK channel, default 4400 — and it has
+ * nothing to do with the port the app is served on. Setting it to the dev-server port makes the
+ * daemon try to bind the port the app already holds; what the user sees is either a bind failure or
+ * a daemon that never connects, neither of which mentions the actual mistake. The old setup skill
+ * asked "what port does your dev server run on?" a few lines before showing this field, which is how
+ * the confusion got manufactured in the first place.
+ */
+export declare const DEV_SERVER_PORTS: ReadonlySet<number>;
 export declare function isLikelyDevServerPort(port: number): boolean;
 /** The warning printed when a project pins the bridge to something that looks like its dev server. */
 export declare function devServerPortWarning(port: number): string;

package/dist/{cli-port.js → cli/cli-port.js}

@@ -19,7 +19,7 @@ import { readFileSync } from 'node:fs';
  * asked "what port does your dev server run on?" a few lines before showing this field, which is how
  * the confusion got manufactured in the first place.
  */
-const DEV_SERVER_PORTS = new Set([
+export const DEV_SERVER_PORTS = new Set([
     3000, 3001, 4200, 4321, 5000, 5173, 5174, 8000, 8080, 8100, 9000,
 ]);
 export function isLikelyDevServerPort(port) {
@@ -37,9 +37,9 @@ export function readProjectPort(cwd) {
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
+        if ('object' === typeof config && config !== null) {
             const p = config['port'];
-            if (typeof p === 'number' && Number.isInteger(p) && p > 0 && p < 65536)
+            if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
                 return p;
         }
     }
@@ -57,9 +57,9 @@ export function readProjectId(cwd) {
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
+        if ('object' === typeof config && config !== null) {
             const id = config['projectId'];
-            if (typeof id === 'string' && id.length > 0)
+            if ('string' === typeof id && id.length > 0)
                 return id;
         }
     }
@@ -76,16 +76,16 @@ export function readProjectId(cwd) {
 export function readJournalEnabled(cwd, env) {
     if (env !== undefined) {
         const v = env.trim().toLowerCase();
-        if (v === '0' || v === 'false' || v === 'off')
+        if ('0' === v || 'false' === v || 'off' === v)
             return false;
-        if (v === '1' || v === 'true' || v === 'on')
+        if ('1' === v || 'true' === v || 'on' === v)
             return true;
     }
     try {
         const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
         const config = JSON.parse(raw);
-        if (typeof config === 'object' && config !== null) {
-            if (config['journal'] === false)
+        if ('object' === typeof config && config !== null) {
+            if (false === config['journal'])
                 return false;
         }
     }

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

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