@reticlehq/server 2.11.0 → 2.12.0

package/dist/init/cra.js

@@ -12,12 +12,26 @@
  * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
  * mechanism and is gitignored by CRA's own template.
  */
+import { bridgeWsUrl } from '@reticlehq/core';
 import { CLI } from './agent-rules.js';
 /** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
 export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
 export const CRA_DEV_MODULE_PATH = 'src/reticle-dev.ts';
 export const CRA_ENV_PATH = '.env.development.local';
 export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
+/**
+ * The bridge URL, carried through the same channel as the token.
+ *
+ * CRA is the one supported stack with no build-time hook of ours: no plugin, no config wrapper, no
+ * `define`. Vite and Astro re-resolve the daemon every dev-server start and Next does it through
+ * `withReticle`; CRA has nowhere to run that code. So the URL goes where the token already goes, and
+ * is refreshed by the same `init` step that refreshes the token.
+ *
+ * That makes `reticle init` the heal rather than the dev server, which is weaker and is stated
+ * plainly in the step's own detail. It is still strictly better than a URL frozen into a source file
+ * the owner has to hand-edit, and `.env.development.local` is already the per-machine file.
+ */
+export const URL_VAR = 'REACT_APP_RETICLE_URL';
 /**
  * What the app itself says when the token is not there.
  *
@@ -64,25 +78,38 @@ export function craImportPatch(source) {
     return lines.join('\n');
 }
 /** Set the token variable, or null when nothing needs to change. */
-export function craEnvPatch(existing, token) {
+export function craEnvPatch(existing, token, url) {
     if ('' === token)
         return null;
-    const line = `${TOKEN_VAR}=${token}`;
-    if (null === existing || '' === existing.trim())
-        return `${line}\n`;
-    if (existing.includes(line))
-        return null;
-    // Replace rather than append: two assignments of one variable is a silent coin flip on which wins.
-    if (new RegExp(`^${TOKEN_VAR}=`, 'm').test(existing)) {
-        return existing.replace(new RegExp(`^${TOKEN_VAR}=.*$`, 'm'), line);
+    const pairs = [
+        [TOKEN_VAR, token],
+        ...(url !== undefined && url.length > 0 ? [[URL_VAR, url]] : []),
+    ];
+    let next = null === existing || '' === existing.trim() ? '' : existing;
+    for (const [name, value] of pairs) {
+        const line = `${name}=${value}`;
+        if (next.includes(line))
+            continue;
+        // Replace rather than append: two assignments of one variable is a silent coin flip on which
+        // wins, and for the URL that coin decides which daemon the app talks to.
+        if (new RegExp(`^${name}=`, 'm').test(next)) {
+            next = next.replace(new RegExp(`^${name}=.*$`, 'm'), line);
+        }
+        else {
+            next = `${'' === next || next.endsWith('\n') ? next : `${next}\n`}${line}\n`;
+        }
     }
-    return `${existing.endsWith('\n') ? existing : `${existing}\n`}${line}\n`;
+    return next === (existing ?? '') ? null : next;
 }
 /** The dev-only connect module imported from `src/index.tsx`. */
 export function craDevModuleFile(port, projectId) {
     const fields = [];
+    // `bridgeWsUrl`, not a hand-written string. This was the only client URL in the product spelling
+    // the host as `127.0.0.1` while every other generator said `localhost` — same endpoint, but a
+    // difference with no reason behind it is the kind that becomes a real one after somebody edits half
+    // of it.
     if (port !== undefined)
-        fields.push(`url: 'ws://127.0.0.1:${String(port)}/reticle'`);
+        fields.push(`url: '${bridgeWsUrl(port)}'`);
     if (projectId !== undefined && projectId.length > 0)
         fields.push(`projectId: '${projectId}'`);
     const inline = fields.length > 0 ? `${fields.join(', ')}, ` : '';
@@ -95,10 +122,14 @@ if (process.env.NODE_ENV === 'development') {
   void import('@reticlehq/react').then(({ reticle, install }) => {
     install();
     const token = process.env.${TOKEN_VAR} ?? '';
+    // Written by \`reticle init\` from the daemon that was live when it ran, and refreshed by
+    // re-running it. CRA gives us no hook to resolve this at dev-server start, so if the daemon
+    // moves, re-run \`reticle init\` rather than editing the url below.
+    const url = process.env.${URL_VAR} ?? '';
     // Loud on purpose: without this the only symptom is the bridge's generic auth failure.
     if (token.length === 0) console.error(${JSON.stringify(`[reticle] ${CRA_TOKEN_MISSING_NOTE}`)});
     // Still attempt it — a bridge running without a token pairs fine.
-    reticle.connect({ ${inline}...(token.length > 0 ? { token } : {}) });
+    reticle.connect({ ${inline}...(url.length > 0 ? { url } : {}), ...(token.length > 0 ? { token } : {}) });
   });
 }
 

package/dist/init/dev-script.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Which command starts this project, and should we start it ourselves?
+ *
+ * `init` finishes by telling the human to start or restart their dev server, in a closing
+ * paragraph, in a terminal that is about to be cleared by the client restart it also asks for.
+ * That is the second unmarked hand-off in the install, after the capabilities file, and it lands
+ * on the same surface: prose nobody re-reads.
+ *
+ * Every fact needed to remove it is already in the project. `package.json` names the script; the
+ * framework tells us the conventional port; a probe tells us whether something already answers
+ * there. Nothing here needs a human.
+ *
+ * Kept as a PURE decision, separate from spawning, because the interesting part is the judgement —
+ * which script, and whether to touch anything at all — and that is what wants testing. Spawning a
+ * process is not.
+ */
+export declare const DevScriptChoice: {
+    /** Something already answers on the port. Use it; never replace a server the user is running. */
+    readonly ALREADY_SERVING: "already-serving";
+    /** We know the command and nothing is listening. Start it. */
+    readonly START: "start";
+    /** No script we recognise. Say so rather than guess a command. */
+    readonly NO_SCRIPT: "no-script";
+};
+export type DevScriptChoice = (typeof DevScriptChoice)[keyof typeof DevScriptChoice];
+export interface DevScriptPlan {
+    choice: DevScriptChoice;
+    /** The npm script name, when there is one. */
+    script?: string;
+    /** What a human would type, for the line we print. */
+    command?: string;
+}
+/**
+ * Pick the script and decide whether to run it.
+ *
+ * `serving` is the probe result, passed in rather than measured here so the decision stays pure.
+ * When something is already answering we do not care which script exists: the rule is never to
+ * start a second server, because the one that is running may be the user's, with their state in it.
+ */
+export declare function planDevScript(scripts: Readonly<Record<string, string>>, packageManager: string, serving: boolean): DevScriptPlan;
+/**
+ * The command to print for this project, straight from its `package.json`.
+ *
+ * Lives here rather than in `run.ts` because it is the same judgement as `planDevScript` with the
+ * parsing attached, and `run.ts` is at its cohesion limit. Returns undefined for anything it cannot
+ * read: this phrasing decides nothing, so it must never be able to break an install.
+ */
+export declare function devCommandFrom(pkgRaw: string, packageManager: string): string | undefined;

package/dist/init/dev-script.js

@@ -0,0 +1,63 @@
+/**
+ * Which command starts this project, and should we start it ourselves?
+ *
+ * `init` finishes by telling the human to start or restart their dev server, in a closing
+ * paragraph, in a terminal that is about to be cleared by the client restart it also asks for.
+ * That is the second unmarked hand-off in the install, after the capabilities file, and it lands
+ * on the same surface: prose nobody re-reads.
+ *
+ * Every fact needed to remove it is already in the project. `package.json` names the script; the
+ * framework tells us the conventional port; a probe tells us whether something already answers
+ * there. Nothing here needs a human.
+ *
+ * Kept as a PURE decision, separate from spawning, because the interesting part is the judgement —
+ * which script, and whether to touch anything at all — and that is what wants testing. Spawning a
+ * process is not.
+ */
+/** Script names a JS project uses to run itself, in the order we would pick them. */
+const CANDIDATES = ['dev', 'start', 'serve'];
+export const DevScriptChoice = {
+    /** Something already answers on the port. Use it; never replace a server the user is running. */
+    ALREADY_SERVING: 'already-serving',
+    /** We know the command and nothing is listening. Start it. */
+    START: 'start',
+    /** No script we recognise. Say so rather than guess a command. */
+    NO_SCRIPT: 'no-script',
+};
+/**
+ * Pick the script and decide whether to run it.
+ *
+ * `serving` is the probe result, passed in rather than measured here so the decision stays pure.
+ * When something is already answering we do not care which script exists: the rule is never to
+ * start a second server, because the one that is running may be the user's, with their state in it.
+ */
+export function planDevScript(scripts, packageManager, serving) {
+    if (serving)
+        return { choice: DevScriptChoice.ALREADY_SERVING };
+    const name = CANDIDATES.find((c) => 'string' === typeof scripts[c] && scripts[c] !== '');
+    if (name === undefined)
+        return { choice: DevScriptChoice.NO_SCRIPT };
+    // `npm` needs `run`; the others take the script name directly. Getting this wrong prints a
+    // command that fails, which is worse than printing nothing.
+    const command = 'npm' === packageManager ? `npm run ${name}` : `${packageManager} ${name}`;
+    return { choice: DevScriptChoice.START, script: name, command };
+}
+/**
+ * The command to print for this project, straight from its `package.json`.
+ *
+ * Lives here rather than in `run.ts` because it is the same judgement as `planDevScript` with the
+ * parsing attached, and `run.ts` is at its cohesion limit. Returns undefined for anything it cannot
+ * read: this phrasing decides nothing, so it must never be able to break an install.
+ */
+export function devCommandFrom(pkgRaw, packageManager) {
+    try {
+        const parsed = JSON.parse(pkgRaw);
+        const scripts = 'object' === typeof parsed && null !== parsed
+            ? (parsed.scripts ?? {})
+            : {};
+        return planDevScript(scripts, packageManager, false).command;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/init/mcp.d.ts

@@ -15,11 +15,16 @@ export { MCP_SERVER_NAME } from '@reticlehq/core';
 /**
  * The registered command is STILL bare `npx` on every platform, deliberately.
  *
- * Windows is 66% of Reticle's users (65 of 99 in a day of telemetry) and has NO CI, no fixture, and
- * nothing in this repo has ever run there. Switching the majority platform to a launch command
- * nobody can test — where `.cmd` also has its own spawn caveats in some hosts — risks breaking the
- * users it is meant to help. So the fallback is DOCUMENTED (see mcpManual) rather than defaulted,
- * until somebody can run it on Windows.
+ * Windows is most of Reticle's users and, when this was written, had no CI. There is Windows CI
+ * now, so the `cmd /c` fallback is testable. Defaulting the majority platform to that launch
+ * command is still the riskier change: `.cmd` has spawn caveats in some hosts, and a registration
+ * that works on the machines we can test can still fail in the hosts we cannot. So the fallback
+ * stays documented rather than defaulted.
+ *
+ * What DID change is when it is printed. `mcpManual` used to run only when the `claude` CLI was
+ * absent. The reported Windows install had `claude mcp add` succeed, so the one paragraph that
+ * would have unblocked zero tools never appeared. `mcpWindowsNote` is that paragraph, and init
+ * prints it on every Windows run — including the ones that look like a clean registration.
  */
 export declare const NPX = "npx";
 /**
@@ -74,5 +79,11 @@ export declare function claudeAvailableProbe(): {
     command: string;
     args: string[];
 };
+/**
+ * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
+ * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported
+ * as a clean install with zero tools.
+ */
+export declare function mcpWindowsNote(): string;
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
 export declare function mcpManual(): string;

package/dist/init/mcp.js

@@ -19,11 +19,16 @@ import { MCP_SERVER_NAME } from '@reticlehq/core';
 /**
  * The registered command is STILL bare `npx` on every platform, deliberately.
  *
- * Windows is 66% of Reticle's users (65 of 99 in a day of telemetry) and has NO CI, no fixture, and
- * nothing in this repo has ever run there. Switching the majority platform to a launch command
- * nobody can test — where `.cmd` also has its own spawn caveats in some hosts — risks breaking the
- * users it is meant to help. So the fallback is DOCUMENTED (see mcpManual) rather than defaulted,
- * until somebody can run it on Windows.
+ * Windows is most of Reticle's users and, when this was written, had no CI. There is Windows CI
+ * now, so the `cmd /c` fallback is testable. Defaulting the majority platform to that launch
+ * command is still the riskier change: `.cmd` has spawn caveats in some hosts, and a registration
+ * that works on the machines we can test can still fail in the hosts we cannot. So the fallback
+ * stays documented rather than defaulted.
+ *
+ * What DID change is when it is printed. `mcpManual` used to run only when the `claude` CLI was
+ * absent. The reported Windows install had `claude mcp add` succeed, so the one paragraph that
+ * would have unblocked zero tools never appeared. `mcpWindowsNote` is that paragraph, and init
+ * prints it on every Windows run — including the ones that look like a clean registration.
  */
 export const NPX = 'npx';
 // The `reticle` bin lives in the server package, so `npx <pkg> mcp` runs the bridge without the
@@ -31,6 +36,9 @@ export const NPX = 'npx';
 const RETICLE_PACKAGE = RETICLE_NPM_PACKAGE;
 const MCP_SUBCOMMAND = 'mcp';
 const CLAUDE_CLI = 'claude';
+/** Windows `cmd /c` — the spawn that PowerShell's execution policy does not gate. */
+const WINDOWS_SHELL = 'cmd';
+const WINDOWS_SHELL_C = '/c';
 /**
  * Args after `npx` that launch the bridge: `@reticlehq/server mcp`. Portless — the port comes from
  * the project's `.reticle.json` at runtime, so one global entry works for every project.
@@ -94,6 +102,18 @@ export function claudeExistsProbe() {
 export function claudeAvailableProbe() {
     return { command: CLAUDE_CLI, args: ['--version'] };
 }
+/**
+ * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
+ * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported
+ * as a clean install with zero tools.
+ */
+export function mcpWindowsNote() {
+    return `On Windows, if the agent cannot start Reticle because npx is blocked ("running scripts is disabled
+on this system" — a PowerShell execution policy), register it through cmd instead, which that policy
+does not gate:
+
+  "${MCP_SERVER_NAME}": { "command": "${WINDOWS_SHELL}", "args": ${JSON.stringify([WINDOWS_SHELL_C, NPX, ...serverInvocation().slice(1)])} }`;
+}
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
 export function mcpManual() {
     const tail = serverInvocation().join(' ');
@@ -105,9 +125,5 @@ Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.curso
 
   "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }
 
-On Windows, if the agent cannot start Reticle because npx is blocked ("running scripts is disabled
-on this system" — a PowerShell execution policy), register it through cmd instead, which that policy
-does not gate:
-
-  "${MCP_SERVER_NAME}": { "command": "cmd", "args": ${JSON.stringify(['/c', NPX, ...serverInvocation().slice(1)])} }`;
+${mcpWindowsNote()}`;
 }

package/dist/init/plan-framework.d.ts

@@ -17,11 +17,6 @@ export declare const VITE_PLUGIN_DETAIL: {
     readonly SVELTEKIT: "add reticle() to plugins (stamps data-reticle-source in .svelte components)";
 };
 export declare function viteSteps(input: PlanInput, detail?: string): Step[];
-/**
- * Next used to be the ONLY stack with hand edits left over — and both of them fail silently when
- * skipped, so a Next user's app booted, connected to nothing, and said nothing about why. Both are
- * now patched by the same conservative rules the Vite config gets.
- */
 export declare function nextSteps(input: PlanInput): Step[];
 /**
  * SvelteKit is WIRED but not SUPPORTED, and the plan says so out loud.

package/dist/init/plan-framework.js

@@ -3,6 +3,7 @@
  * Split out of `plan.ts` — that file is the plan's SHAPE (statuses, ordering, the agent/MCP steps),
  * this one is the per-framework detail, and they grow for different reasons.
  */
+import { bridgeWsUrl } from '@reticlehq/core';
 import { patchViteConfig, VitePatchKind } from './vite-config.js';
 import { patchNextConfig, patchRootLayout, patchPagesApp } from './next-patch.js';
 import { patchAstroConfig, patchAstroLayout } from './astro-patch.js';
@@ -62,6 +63,22 @@ function capabilitiesTodo(path, stores) {
  * `__reticle_renders` — the state-truth read was unavailable on every app out of the box. Written
  * only when absent, because it is the one generated file a user is expected to EDIT.
  */
+/**
+ * Does the generated dev module actually REGISTER anything?
+ *
+ * Shared by the Vite and Next paths because it is one question about one generated call, and the
+ * two answered it differently for as long as only Vite asked: `capabilitiesStep` was called from
+ * `viteSteps` and nowhere else, so a Next app whose store can only be SUGGESTED wrote
+ * `registerCapabilities({ testids: [], stores: [] })`, registered nothing, and said nothing.
+ * Measured on a real Next + mobx app: five steps, every one a checkmark, no capabilities line.
+ *
+ * `wired` are stores init resolved and wrote a live `registerStore` call for. Hints are not
+ * registrations: they land in the file as a commented line, and counting one as a registration
+ * silences the notice whose whole purpose is to say "act on the hint".
+ */
+function registersNothing(testids, wired) {
+    return 0 === testids.length && 0 === wired.length;
+}
 function capabilitiesStep(input) {
     if (true === input.viteDevModuleExists) {
         return [
@@ -79,8 +96,21 @@ function capabilitiesStep(input) {
     const found = testids.length > 0
         ? `${String(testids.length)} data-testid values`
         : 'no data-testid values yet';
-    // A store we found and wired IS a registration, so the "registers nothing" notice must not fire.
-    const nothingToRegister = 0 === testids.length && 0 === stores.length && 0 === wired.length;
+    // A store we found and WIRED is a registration, so the "registers nothing" notice must not fire.
+    // A store HINT is not: `stores` holds suggestions, written into the file as a commented line of
+    // the form `// import your store, then: registerStore(...)`. Counting a suggestion as a
+    // registration let the hint silence the notice whose entire job is to say "act on the hint".
+    //
+    // Measured against a real product UI (rowy — 70+ deps, jotai, a whole src/atoms tree): init
+    // detected jotai, offered one commented line, emitted NO notice, and wrote
+    // `registerCapabilities({ testids: [], signals: [], stores: [] })`. So `hasCapabilities` stayed
+    // false, `reticle_state` was empty forever, and the install gate reported "connected: 1,
+    // manual ⚠: none". Every check green, state observability zero.
+    //
+    // This is the common case rather than an edge one: a library whose registration needs an argument
+    // only reading the source supplies — jotai atoms, an XState actor, a TanStack queryClient — is
+    // exactly what init leaves commented.
+    const nothingToRegister = registersNothing(testids, wired);
     return [
         {
             title: CAPABILITIES_TITLE,
@@ -197,16 +227,44 @@ function patchStep(title, path, patch, applyDetail, manualDetail) {
  * skipped, so a Next user's app booted, connected to nothing, and said nothing about why. Both are
  * now patched by the same conservative rules the Vite config gets.
  */
+/** The env var withReticle sets from the discovered daemon, and the component must read. */
+const NEXT_DAEMON_URL_ENV = 'NEXT_PUBLIC_RETICLE_URL';
+/**
+ * The two-line edit that unfreezes an existing install's port.
+ *
+ * Stated as the edit rather than as a problem, because the reader is an agent that can apply it in
+ * one write and is otherwise going to ask what to do.
+ */
+const NEXT_DEV_FILE_STALE_DETAIL = 'predates daemon discovery, so it dials the port init saw when it ran. In this file add ' +
+    '`const url = process.env.NEXT_PUBLIC_RETICLE_URL;` and spread `...(url ? { url } : {})` into ' +
+    'reticle.connect(), after any url already there. Nothing else needs to change.';
 export function nextSteps(input) {
     const configFile = input.nextConfigFile ?? 'next.config.mjs';
     const devPath = input.nextReticleDevPath ?? NEXT_RETICLE_DEV_PATH;
+    // An install that predates daemon discovery has a component that never reads the discovered URL,
+    // so it keeps dialling whatever port `init` saw on the day it ran. Re-running `init` used to call
+    // that "file exists" and move on, which is why the defect survives an upgrade. Named as work.
+    //
+    // Never overwritten: this file is the one an app owner edits — registered stores, capabilities,
+    // their own signals. Rewriting it to fix two lines would take the rest with it. Undefined source
+    // means it was not read, and an unread file stays ALREADY rather than becoming invented work.
+    const devStale = true === input.nextReticleDevExists &&
+        'string' === typeof input.nextReticleDevSource &&
+        !input.nextReticleDevSource.includes(NEXT_DAEMON_URL_ENV);
     const devFile = input.nextReticleDevExists
-        ? {
-            title: 'ReticleDev component',
-            target: devPath,
-            status: StepStatus.ALREADY,
-            detail: 'file exists',
-        }
+        ? devStale
+            ? {
+                title: 'ReticleDev component',
+                target: devPath,
+                status: StepStatus.MANUAL,
+                detail: NEXT_DEV_FILE_STALE_DETAIL,
+            }
+            : {
+                title: 'ReticleDev component',
+                target: devPath,
+                status: StepStatus.ALREADY,
+                detail: 'file exists',
+            }
         : {
             title: 'ReticleDev component',
             target: devPath,
@@ -233,8 +291,22 @@ export function nextSteps(input) {
         : isPagesRouter
             ? patchPagesApp(layout.source, input.nextReticleDevImport)
             : patchRootLayout(layout.source);
+    // The same question the Vite path asks. Skipped when the module already exists: its contents are
+    // the user's, and re-nagging about a file we did not write is noise.
+    const nextTodo = true !== input.nextReticleDevExists &&
+        registersNothing(input.testids ?? [], input.nextFoundStores ?? [])
+        ? [
+            {
+                title: CAPABILITIES_TODO_TITLE,
+                target: devPath,
+                status: StepStatus.NOTICE,
+                detail: capabilitiesTodo(devPath, input.storeHints ?? []),
+            },
+        ]
+        : [];
     return [
         devFile,
+        ...nextTodo,
         patchStep('Next config (withReticle)', configFile, configPatch, 'wrap the export in withReticle (source mapping, dev-only)', nextConfigManual(configFile)),
         patchStep('Mount ReticleDev', layout?.path ?? NEXT_LAYOUT_PATH, layoutPatch, 'mount <ReticleDev /> in the root layout (dev-only)', NEXT_LAYOUT_MANUAL),
     ];
@@ -269,7 +341,9 @@ export function craSteps(input) {
         },
     ];
     const token = input.pairingToken ?? '';
-    const env = craEnvPatch(input.craEnv ?? null, token);
+    // The daemon that is live NOW, not the one baked into the module at first install. CRA has no
+    // build hook, so this is refreshed by re-running `init` rather than by starting the dev server.
+    const env = craEnvPatch(input.craEnv ?? null, token, input.options.port === undefined ? undefined : bridgeWsUrl(input.options.port));
     if (env !== null) {
         steps.push({
             title: 'Pairing token',

package/dist/init/plan.d.ts

@@ -6,16 +6,6 @@
 import { Framework, UiLibrary, type Detection } from './detect.js';
 import type { FoundStore } from './capabilities.js';
 import { type McpClient } from './mcp-clients.js';
-/**
- * Pin the SDK to the CLI's own version.
- *
- * `pnpm add -D @reticlehq/react` installed **2.2.1** in one project while npm and yarn took 2.3.0 in
- * the next — a stale registry metadata cache, invisible to the user and to us. A version-skewed SDK
- * talking to a newer daemon is the `-32000` failure path: the app connects, the protocol disagrees,
- * and nothing on either side names a version. Asking for the CLI's exact version makes the cache
- * irrelevant, and a skewed pair impossible to install by accident.
- */
-export declare function pinnedPackages(packages: readonly string[], version: string | undefined): readonly string[];
 /**
  * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
  *
@@ -101,6 +91,8 @@ export interface PlanInput {
     mcpExists: boolean;
     /** Whether Cursor is installed for this user (its global config dir exists). */
     cursorPresent: boolean;
+    /** `process.platform`. Injected so this module stays pure. Windows is the only branch. */
+    platform?: string;
     /** Whether THIS project has a .cursor/ directory — the signal that Cursor works on this repo. */
     cursorProjectPresent?: boolean | undefined;
     /** Current ~/.cursor/mcp.json content, or null if absent. */
@@ -154,6 +146,14 @@ export interface PlanInput {
     nextReticleDevImport?: string | undefined;
     /** Whether the ReticleDev component file already exists. */
     nextReticleDevExists: boolean;
+    /**
+     * The existing ReticleDev component's source, when there is one.
+     *
+     * Read so an install predating daemon discovery can be told apart from a current one. Undefined
+     * means NOT READ, and an unread file is reported as already-wired rather than as stale: inventing
+     * work from missing information is how a plan grows steps that can never be completed.
+     */
+    nextReticleDevSource?: string | null | undefined;
     /** `data-testid` values scanned from the app's source, for the generated capabilities block. */
     testids?: readonly string[] | undefined;
     /** Ready-to-uncomment `registerStore` lines for the state libraries the app actually depends on. */
@@ -226,24 +226,4 @@ export interface PlanInput {
         sdkVersion?: string;
     };
 }
-/**
- * Every coding agent `reticle init` knows how to wire itself into, and the three surfaces it wires:
- * the global MCP registration, the project rule file that makes the agent USE Reticle, and the
- * `/reticle` command.
- *
- * One list, because those three surfaces used to enumerate Claude and Cursor separately in three
- * places — so supporting a fourth agent meant finding all three and getting each right. Adding one
- * is now an entry here plus its builders; each builder answers null when that agent is not present
- * for this user or this project, which is also how "no agent detected" falls through to the
- * cross-agent AGENTS.md.
- *
- * Deliberately functions rather than data: registering with Claude runs its CLI while Cursor merges
- * a JSON file, and pretending those are the same shape would cost more than it saves.
- */
-declare const AgentId: {
-    readonly CLAUDE: "claude";
-    readonly CURSOR: "cursor";
-};
-export type AgentId = (typeof AgentId)[keyof typeof AgentId];
 export declare function buildPlan(input: PlanInput): Plan;
-export {};

package/dist/init/plan.js

@@ -4,7 +4,8 @@
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
 import { Framework, PackageManager, UiLibrary, installCommand, installCommandParts, } from './detect.js';
-import { claudeAddCommand, mcpManual } from './mcp.js';
+import { claudeAddCommand, mcpManual, mcpWindowsNote } from './mcp.js';
+import { NodePlatform } from '../platform.js';
 import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.js';
 import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, } from './mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from './slash-command.js';
@@ -32,7 +33,7 @@ const RETICLE_NEXT_PLUGIN = '@reticlehq/next';
  * and nothing on either side names a version. Asking for the CLI's exact version makes the cache
  * irrelevant, and a skewed pair impossible to install by accident.
  */
-export function pinnedPackages(packages, version) {
+function pinnedPackages(packages, version) {
     if (version === undefined || 0 === version.length)
         return packages;
     return packages.map((p) => `${p}@${version}`);
@@ -232,19 +233,33 @@ function mcpSteps(input) {
     // client. A machine with Cursor AND Windsurf gets both — registering only the first one found is
     // how a user ends up with Reticle in the editor they were not using.
     const steps = [...stepsForAgents(input, (a) => a.mcpStep), ...otherClientSteps(input)];
-    if (steps.length > 0)
-        return steps;
-    // No supported agent detected — print the one-time global instructions. Reached when the `claude`
-    // CLI is absent AND ~/.cursor does not exist, which includes Cursor installed with a fresh profile
-    // that has not written its config directory yet, so the manual text covers both agents.
-    return [
-        {
-            title: 'MCP server (global)',
-            target: MCP_TARGET,
-            status: StepStatus.MANUAL,
-            detail: mcpManual(),
-        },
-    ];
+    if (0 === steps.length) {
+        // No agent detected. mcpManual already carries the Windows cmd fallback — do not append it again.
+        return [
+            {
+                title: 'MCP server (global)',
+                target: MCP_TARGET,
+                status: StepStatus.MANUAL,
+                detail: mcpManual(),
+            },
+        ];
+    }
+    const windowsNote = windowsMcpNoteStep(input);
+    if (windowsNote !== null)
+        steps.push(windowsNote);
+    return steps;
+}
+const WINDOWS_MCP_TITLE = 'Windows MCP spawn';
+/** Windows only. The reported install never reached mcpManual because `claude mcp add` succeeded. */
+function windowsMcpNoteStep(input) {
+    if (input.platform !== NodePlatform.WINDOWS)
+        return null;
+    return {
+        title: WINDOWS_MCP_TITLE,
+        target: MCP_TARGET,
+        status: StepStatus.NOTICE,
+        detail: mcpWindowsNote(),
+    };
 }
 const SLASH_COMMAND_TITLE = 'The /reticle command';
 /**

package/dist/init/refresh-rules.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Bring an already-installed project's agent rules up to the version that is running.
+ *
+ * `mergeMarkedInstruction` has always been able to do this: the managed block is marker-delimited,
+ * idempotence is decided by comparing CONTENT rather than by seeing a marker, and everything
+ * outside the markers is left exactly as the human wrote it. What was missing is anything that
+ * CALLS it after the first install.
+ *
+ * It is reachable only from `buildPlan`, so the rules refresh when somebody re-runs `init` and
+ * never otherwise. A project set up on an older release keeps that release's instructions forever,
+ * which means every improvement to them — what to do when a capabilities file registers nothing,
+ * that an install is not finished until a verdict exists, that intent is captured while building —
+ * reaches new projects only.
+ *
+ * That is the wrong way round. The people who most need better instructions are the ones already
+ * installed and not getting value, and `reticle update` is the moment they are already touching the
+ * install.
+ */
+/** The instruction files the managed block lives in. Cursor's rule file is regenerated whole. */
+export declare const RULE_FILES: readonly ["CLAUDE.md", "AGENTS.md"];
+export interface RuleFileIo {
+    read: (path: string) => string | null;
+    write: (path: string, content: string) => void;
+}
+export interface RefreshResult {
+    /** Files whose managed block was replaced with the current one. */
+    updated: string[];
+    /** Files that were already current, or that carry no Reticle block to update. */
+    unchanged: string[];
+}
+/**
+ * Refresh every instruction file that already carries a Reticle block.
+ *
+ * Deliberately does NOT create one where none exists. A project with no Reticle block in its
+ * CLAUDE.md either never ran `init` here or had the block removed on purpose, and `update` is not
+ * the place to make that decision for somebody — it is a version command, and quietly writing
+ * instructions into a file a user curates would be a surprise.
+ */
+export declare function refreshAgentRules(cwd: string, io: RuleFileIo): RefreshResult;