@reticlehq/server 3.8.2 → 3.10.0

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

@@ -38,6 +38,18 @@ const SELECT_FLAG = '--select';
 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';
+/** A missing step 1 control on a freshly loaded start page fails the flow (#2061). */
+export const REQUIRE_START_CONTROL_FLAG = '--require-start-control';
+/** Keep judging after a step whose consequence failed, so every step gets a verdict (the score). */
+export const SWEEP_FLAG = '--sweep';
+/** Compare the url with this reference build, and report each difference in what users see. */
+export const AGAINST_FLAG = '--against';
+/**
+ * `--against` compares two builds with the same actions. A predicate asks another question, and a
+ * model drive does not repeat its actions, so neither can join it.
+ */
+const MSG_AGAINST_ALONE = `${AGAINST_FLAG} compares two builds with the same actions. It cannot be combined with ` +
+    `${EXPECT_FLAG}, ${EXPECT_FILE_FLAG}, ${EXPLORE_FLAG} or ${PERSONA_FLAG}. Run them as two commands.`;
 /**
  * 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
@@ -96,54 +108,65 @@ export function parseVerifySuffix(args, defaultPort) {
     const select = [];
     let resultsJson;
     let confirmDangerous = false;
+    let requireStartControl = false;
+    let sweep = false;
+    let against;
     let port = defaultPort;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
-        if (arg === undefined)
+        if (arg === undefined) {
             break;
+        }
         if (arg === HEADED_FLAG) {
             headless = false;
         }
         else if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
-            if (n === undefined)
+            if (n === undefined) {
                 return missingValue(PORT_FLAG);
+            }
             const parsed = parseInt(n, 10);
-            if (isNaN(parsed))
+            if (isNaN(parsed)) {
                 return notANumber(PORT_FLAG, n);
+            }
             port = parsed;
         }
         else if (arg === TIMEOUT_FLAG) {
             i++;
             const n = args[i];
-            if (n === undefined)
+            if (n === undefined) {
                 return missingValue(TIMEOUT_FLAG);
+            }
             const parsed = parseInt(n, 10);
-            if (isNaN(parsed))
+            if (isNaN(parsed)) {
                 return notANumber(TIMEOUT_FLAG, n);
+            }
             timeoutMs = parsed;
         }
         else if (arg === STORAGE_STATE_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(STORAGE_STATE_FLAG);
+            }
             storageState = v;
         }
         else if (arg === SESSION_ID_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(SESSION_ID_FLAG);
+            }
             sessionId = v;
         }
         else if (arg === SELECT_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(SELECT_FLAG);
+            }
             // Repeatable rather than comma-split: a label is free-form, and a comma inside one would
             // silently become two selections that match nothing.
             select.push(v);
@@ -151,21 +174,37 @@ export function parseVerifySuffix(args, defaultPort) {
         else if (arg === RESULTS_JSON_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(RESULTS_JSON_FLAG);
+            }
             resultsJson = v;
         }
+        else if (arg === AGAINST_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined) {
+                return missingValue(AGAINST_FLAG);
+            }
+            against = v;
+        }
         else if (arg === EXPLORE_FLAG) {
             explore = true;
         }
         else if (arg === CONFIRM_DANGEROUS_FLAG) {
             confirmDangerous = true;
         }
+        else if (arg === REQUIRE_START_CONTROL_FLAG) {
+            requireStartControl = true;
+        }
+        else if (arg === SWEEP_FLAG) {
+            sweep = true;
+        }
         else if (arg === PERSONA_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(PERSONA_FLAG);
+            }
             // A persona is what to explore AS, so naming one is asking for the drive. Requiring both
             // flags would only give a user a way to say something they cannot mean.
             persona = v;
@@ -174,18 +213,21 @@ export function parseVerifySuffix(args, defaultPort) {
         else if (arg === EXPECT_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(EXPECT_FLAG);
+            }
             const read = parseExpect(v);
-            if ('error' === read.kind)
+            if ('error' === read.kind) {
                 return read;
+            }
             expect = read.value;
         }
         else if (arg === EXPECT_FILE_FLAG) {
             i++;
             const v = args[i];
-            if (v === undefined)
+            if (v === undefined) {
                 return missingValue(EXPECT_FILE_FLAG);
+            }
             expectFile = v;
         }
         else if (arg.startsWith('--')) {
@@ -199,8 +241,9 @@ export function parseVerifySuffix(args, defaultPort) {
         }
         i++;
     }
-    if (url === undefined)
+    if (url === undefined) {
         return missingOperand(VERIFY_COMMAND, 'a url');
+    }
     // Two ways to say the same thing, and no way to say two different things. Preferring one
     // silently is how a run asserts something the person did not write.
     if (expect !== undefined && expectFile !== undefined) {
@@ -209,6 +252,9 @@ export function parseVerifySuffix(args, defaultPort) {
             message: `${EXPECT_FLAG} and ${EXPECT_FILE_FLAG} both name the predicate; pass one`,
         };
     }
+    if (against !== undefined && (expect !== undefined || expectFile !== undefined || explore)) {
+        return { kind: 'error', message: MSG_AGAINST_ALONE };
+    }
     // Refused here, where nothing has been bound and no browser exists yet, because the damage this
     // pair does is a verdict taken against the wrong user. A predicate from a file is the same
     // predicate, so it is refused the same way.
@@ -230,5 +276,8 @@ export function parseVerifySuffix(args, defaultPort) {
         ...(select.length > 0 ? { select } : {}),
         ...(resultsJson !== undefined ? { resultsJson } : {}),
         ...(confirmDangerous ? { confirmDangerous } : {}),
+        ...(requireStartControl ? { requireStartControl } : {}),
+        ...(sweep ? { sweep } : {}),
+        ...(against !== undefined ? { against } : {}),
     };
 }

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

@@ -4,8 +4,12 @@
  * and re-exports this surface.
  */
 import { type ParsedFeedback } from './cli-parse-feedback.js';
+import { type VerifySuffix } from './cli-parse-verify.js';
+import { type CompareArgs } from './cli-parse-compare.js';
+import { type GradeArgs } from './cli-parse-grade.js';
+import { DAEMON_INNER_COMMAND } from '../daemon/daemon-argv.js';
 import { HEADED_FLAG, PORT_FLAG } from './cli-parse-grammar.js';
-export { HEADED_FLAG, PORT_FLAG };
+export { DAEMON_INNER_COMMAND, HEADED_FLAG, PORT_FLAG };
 export { DRIVE_FLAG, HEADLESS_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, } from './cli-parse-serve.js';
 export { AGENT_FLAG, BUG_FLAG, CONTACT_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
 import { CLI_USAGE } from './cli-usage.js';
@@ -19,7 +23,6 @@ export declare const TelemetryAction: {
     readonly DISABLE: "disable";
 };
 export type TelemetryAction = (typeof TelemetryAction)[keyof typeof TelemetryAction];
-export declare const DAEMON_INNER_COMMAND = "_daemon";
 /**
  * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
  * this is what keeps that property low-cardinality and non-identifying: an argument we do not
@@ -110,8 +113,11 @@ export type CliResult = {
 } | {
     kind: 'doctor';
     port: number;
+    fix: boolean;
 } | {
     kind: 'setup-mcp';
+} | {
+    kind: 'setup-wait-agents';
 } | {
     kind: 'setup-install';
     runtimeSecs: number;
@@ -135,22 +141,21 @@ export type CliResult = {
     port: number;
     driveUrl: string;
     headless: boolean;
-} | {
+} | ({
     kind: 'verify';
-    url: string;
-    headless: boolean;
-    port: number;
-    timeoutMs?: number;
-    storageState?: string;
-    sessionId?: string;
-    expect?: unknown;
-    expectFile?: string;
-    explore?: boolean;
-    persona?: string;
-    select?: string[];
-    resultsJson?: string;
-    confirmDangerous?: boolean;
-} | {
+} & Omit<Extract<VerifySuffix, {
+    kind: 'ok';
+}>, 'kind'>) | ({
+    kind: 'compare';
+} & Omit<Extract<CompareArgs, {
+    kind: 'ok';
+}>, 'kind'>) | ({
+    kind: 'grade';
+} & {
+    args: Extract<GradeArgs, {
+        kind: 'ok';
+    }>;
+}) | {
     kind: 'affected';
     files: string[];
     since?: string;

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

@@ -6,10 +6,13 @@
 import { parseFeedbackArgs } from './cli-parse-feedback.js';
 import { HEADLESS_FLAG, parseServeFlags } from './cli-parse-serve.js';
 import { parseVerifySuffix } from './cli-parse-verify.js';
-import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, retiredFlag, unknownArgument, CLOUD_COMMANDS, REMOVED_COMMANDS, removedNote, } from './cli-parse-grammar.js';
+import { COMPARE_COMMAND, parseCompareArgs } from './cli-parse-compare.js';
+import { GRADE_COMMAND, parseGradeArgs } from './cli-parse-grade.js';
+import { DAEMON_INNER_COMMAND } from '../daemon/daemon-argv.js';
+import { HEADED_FLAG, JSON_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 };
+export { DAEMON_INNER_COMMAND, HEADED_FLAG, PORT_FLAG };
 export { DRIVE_FLAG, HEADLESS_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, } from './cli-parse-serve.js';
 import { FORCE_FLAG } from './cli-kill.js';
 // Re-exported so every existing importer of these flags is unaffected by the file split.
@@ -20,13 +23,18 @@ export { CLI_USAGE };
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
-const KILL_COMMAND = 'kill';
+/** Kept for one release as `serve --restart`. */
 const RESTART_COMMAND = 'restart';
+/** `serve --restart`: stop the daemon, then start it and wait until it listens. */
+const RESTART_FLAG = '--restart';
 const STATUS_COMMAND = 'status';
 const OPEN_COMMAND = 'open';
 const DRIVE_COMMAND = 'drive';
+/** Kept for one release as `gate --list`. */
 const AFFECTED_COMMAND = 'affected';
 const GATE_COMMAND = 'gate';
+/** `gate --list`: name the saved flows the changes touch, and check nothing. */
+const LIST_FLAG = '--list';
 /** 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';
@@ -36,7 +44,9 @@ const REPORT_COMMAND = 'report';
 const CONTEXT_COMMAND = 'context';
 const SESSION_FLAG = '--session';
 const UPDATE_COMMAND = 'update';
+/** Kept for one release as `update --rollback`. */
 const ROLLBACK_COMMAND = 'rollback';
+const ROLLBACK_FLAG = '--rollback';
 const MCP_COMMAND = 'mcp';
 const LICENSE_COMMAND = 'license';
 const VERSION_COMMAND = 'version';
@@ -44,6 +54,7 @@ const TELEMETRY_COMMAND = 'telemetry';
 const FEEDBACK_COMMAND = 'feedback';
 const DOCTOR_COMMAND = 'doctor';
 const SETUP_COMMAND = 'setup';
+const SETUP_WAIT_AGENTS = 'wait-agents';
 /** `reticle hook`: the agent prompt hook. `cli.ts` runs it before this parser, and before telemetry. */
 export const HOOK_COMMAND = 'hook';
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
@@ -52,7 +63,6 @@ export const TelemetryAction = {
     ENABLE: 'enable',
     DISABLE: 'disable',
 };
-export const DAEMON_INNER_COMMAND = '_daemon';
 /**
  * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
  * this is what keeps that property low-cardinality and non-identifying: an argument we do not
@@ -79,12 +89,13 @@ export const LOCAL_COMMANDS = [
     INIT_COMMAND,
     SERVE_COMMAND,
     STOP_COMMAND,
-    KILL_COMMAND,
     RESTART_COMMAND,
     STATUS_COMMAND,
     OPEN_COMMAND,
     DRIVE_COMMAND,
     VERIFY_COMMAND,
+    COMPARE_COMMAND,
+    GRADE_COMMAND,
     AFFECTED_COMMAND,
     GATE_COMMAND,
     REPORT_COMMAND,
@@ -138,6 +149,7 @@ export function knownCommand(arg) {
     return KNOWN_COMMANDS.has(arg) ? arg : (COMMAND_FLAG_ALIASES.get(arg) ?? UNKNOWN_COMMAND);
 }
 const QUIET_FLAG = '--quiet';
+const FIX_FLAG = '--fix';
 const DRY_RUN_FLAG = '--dry-run';
 const YES_FLAG = '--yes';
 const NO_MCP_FLAG = '--no-mcp';
@@ -177,7 +189,6 @@ const NO_PROMPT_CAPTURE_FLAG = '--no-prompt-capture';
  * and reading one object is one turn where interpreting a report is several. The three opt-outs are
  * what a machine without a browser, or a caller already running their app, actually needs.
  */
-const JSON_FLAG = '--json';
 const NO_DRIVE_FLAG = '--no-drive';
 const NO_OPEN_FLAG = '--no-open';
 /** `reticle open <url> --navigate`: move a tab already on the origin to the url (#1140). */
@@ -548,6 +559,16 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             };
         }
         case SERVE_COMMAND: {
+            if (rest.includes(RESTART_FLAG)) {
+                return {
+                    kind: 'restart',
+                    port: parsePortFlag(rest, defaultPort),
+                    force: rest.includes(FORCE_FLAG),
+                };
+            }
+            if (rest.includes(FORCE_FLAG)) {
+                return { kind: 'error', message: `${FORCE_FLAG} works only with ${RESTART_FLAG}` };
+            }
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
             if ('error' === r.kind) {
                 return r;
@@ -565,17 +586,13 @@ 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`.
+            // Reticle daemon. Overriding that refusal stays on `serve --restart --force`.
             if (rest.includes(FORCE_FLAG)) {
                 return { kind: 'kill', port, force: false };
             }
             const quiet = rest.includes(QUIET_FLAG);
             return { kind: 'stop', port, quiet };
         }
-        case KILL_COMMAND: {
-            const port = parsePortFlag(rest, defaultPort);
-            return { kind: 'kill', port, force: rest.includes(FORCE_FLAG) };
-        }
         case RESTART_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             return { kind: 'restart', port, force: rest.includes(FORCE_FLAG) };
@@ -589,7 +606,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case DOCTOR_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
-            return { kind: 'doctor', port };
+            return { kind: 'doctor', port, fix: rest.includes(FIX_FLAG) };
         }
         /*
          * `setup mcp` — register the MCP server with the coding agents on this machine.
@@ -621,8 +638,11 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                     mcp: !rest.includes('--no-mcp'),
                 };
             }
-            // 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.
+            // `setup wait-agents` — the installer's last step: wait for the agents to connect.
+            if (SETUP_WAIT_AGENTS === what) {
+                return { kind: 'setup-wait-agents' };
+            }
+            // A bare `reticle setup` falls to help rather than guessing.
             if (what !== 'mcp') {
                 return { kind: 'help', topic: SETUP_COMMAND };
             }
@@ -677,22 +697,21 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             if ('error' === r.kind) {
                 return r;
             }
-            return {
-                kind: 'verify',
-                url: r.url,
-                headless: r.headless,
-                port: r.port,
-                ...(r.timeoutMs !== undefined ? { timeoutMs: r.timeoutMs } : {}),
-                ...(r.storageState !== undefined ? { storageState: r.storageState } : {}),
-                ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
-                ...(r.expect !== undefined ? { expect: r.expect } : {}),
-                ...(r.expectFile !== undefined ? { expectFile: r.expectFile } : {}),
-                ...(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 } : {}),
-            };
+            // Every parsed field, so a flag the suffix parser reads cannot be lost here.
+            const { kind: _ok, ...fields } = r;
+            return { kind: 'verify', ...fields };
+        }
+        case COMPARE_COMMAND: {
+            const r = parseCompareArgs(rest, defaultPort);
+            if ('error' === r.kind) {
+                return r;
+            }
+            const { kind: _ok, ...fields } = r;
+            return { kind: 'compare', ...fields };
+        }
+        case GRADE_COMMAND: {
+            const r = parseGradeArgs(rest);
+            return 'error' === r.kind ? r : { kind: 'grade', args: r };
         }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
@@ -703,8 +722,11 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             // Flags are stripped before target parsing, which would reject them as unknown.
             const hook = rest.includes(HOOK_FLAG);
             const acceptCoverage = rest.includes(ACCEPT_COVERAGE_FLAG);
-            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG && a !== ACCEPT_COVERAGE_FLAG));
+            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG && a !== ACCEPT_COVERAGE_FLAG && a !== LIST_FLAG));
             const since = t.since ?? implicitSince(t.files);
+            if (rest.includes(LIST_FLAG)) {
+                return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
+            }
             return {
                 kind: 'gate',
                 files: t.files,
@@ -732,7 +754,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'context', ...(session === undefined ? {} : { session }) };
         }
         case UPDATE_COMMAND:
-            return { kind: 'update' };
+            return rest.includes(ROLLBACK_FLAG) ? { kind: 'rollback' } : { kind: 'update' };
         case ROLLBACK_COMMAND:
             return { kind: 'rollback' };
         case MCP_COMMAND: {

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(cwd?: string): Promise<void>;
-/** `reticle rollback` — restore the previous server version and restart. */
+/** `reticle update --rollback` — restore the previous server version and restart. */
 export declare function handleRollback(): Promise<void>;

package/dist/command/cli/cli-update-commands.js

@@ -1,5 +1,5 @@
 /**
- * The self-update command pair — `reticle update` and `reticle rollback`.
+ * The self-update command pair — `reticle update` and `reticle update --rollback`.
  *
  * Split out of cli.ts, which sits at the 600-line cap: these two are one cohesive unit (swap the
  * installed version, restart) and the file they came from is the CLI's dispatch table, which grows
@@ -91,6 +91,29 @@ function syncProjectSdk(target, cwd) {
     }
     say(MSG_SDK_SYNCED(target));
 }
+/**
+ * Bring this project's agent rules up with the version.
+ *
+ * The managed block has always been updatable — marker-delimited, idempotent by comparing content —
+ * and nothing called it after the first install. `mergeMarkedInstruction` is reachable from
+ * `buildPlan` alone, so a project set up on an older release kept that release's instructions
+ * forever and every improvement to them reached new projects only.
+ *
+ * That is backwards: the people who most need better instructions are the ones already installed
+ * and not getting value, and this is the moment they are touching the install anyway. Only files
+ * that ALREADY carry the block are touched, and only inside the markers.
+ */
+function refreshProjectRules(cwd, version) {
+    const refreshed = refreshAgentRules(cwd, {
+        read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+        write: (path, content) => {
+            writeFileSync(path, content, 'utf8');
+        },
+    });
+    if (0 !== refreshed.updated.length) {
+        log('reticle_rules_refreshed', { files: refreshed.updated, to: version });
+    }
+}
 /** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
 export async function handleUpdate(cwd = process.cwd()) {
     try {
@@ -103,6 +126,9 @@ export async function handleUpdate(cwd = process.cwd()) {
             // is on the latest release while the app keeps the SDK `init` pinned months ago, and this
             // branch used to return before the sync — so the one command that should fix that pair
             // answered "already on the latest version" and left the old overlay in the page.
+            // The same holds for the agent rules: a project on the latest CLI kept the block that its
+            // first `init` wrote, because this branch returned before the refresh (#1948).
+            refreshProjectRules(cwd, SERVER_VERSION);
             const installed = installedSdkVersion(cwd, readTextFile);
             if (installed === undefined)
                 say(MSG_NO_SDK_HERE);
@@ -118,24 +144,7 @@ export async function handleUpdate(cwd = process.cwd()) {
             return;
         }
         log('reticle_update', { ok: true, from: SERVER_VERSION, to: target });
-        // Bring this project's agent rules up with the version.
-        //
-        // The managed block has always been updatable — marker-delimited, idempotent by comparing
-        // content — and nothing called it after the first install. `mergeMarkedInstruction` is reachable
-        // from `buildPlan` alone, so a project set up on an older release kept that release's
-        // instructions forever and every improvement to them reached new projects only.
-        //
-        // That is backwards: the people who most need better instructions are the ones already
-        // installed and not getting value, and this is the moment they are touching the install anyway.
-        // Only files that ALREADY carry the block are touched, and only inside the markers.
-        const refreshed = refreshAgentRules(cwd, {
-            read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
-            write: (path, content) => {
-                writeFileSync(path, content, 'utf8');
-            },
-        });
-        if (0 !== refreshed.updated.length)
-            log('reticle_rules_refreshed', { files: refreshed.updated, to: target });
+        refreshProjectRules(cwd, target);
         // The app's SDK FIRST, then the CLI. `reticle update` used to swap only the CLI, so the command
         // whose job is keeping an install current was itself a way to produce a version-skewed pair —
         // and the skew message told people to run it to fix an outdated SDK, which it could not do.
@@ -157,7 +166,7 @@ export async function handleUpdate(cwd = process.cwd()) {
         process.exitCode = 1;
     }
 }
-/** `reticle rollback` — restore the previous server version and restart. */
+/** `reticle update --rollback` — restore the previous server version and restart. */
 export async function handleRollback() {
     try {
         await rollback(); // calls process.exit