@reticlehq/server 2.10.0 → 2.12.0

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/node-io.js

@@ -52,6 +52,9 @@ export function buildNodeIo(cwd) {
         homeDir() {
             return homedir();
         },
+        cwd() {
+            return cwd;
+        },
         rootFiles() {
             return readdirSync(cwd).filter((name) => {
                 try {

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;

package/dist/init/refresh-rules.js

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+import { join } from 'node:path';
+import { mergeMarkedInstruction, AgentRuleStatus, hasManagedBlock } from './agent-rules.js';
+/** The instruction files the managed block lives in. Cursor's rule file is regenerated whole. */
+export const RULE_FILES = ['CLAUDE.md', 'AGENTS.md'];
+/**
+ * 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 function refreshAgentRules(cwd, io) {
+    const updated = [];
+    const unchanged = [];
+    for (const name of RULE_FILES) {
+        const path = join(cwd, name);
+        const existing = io.read(path);
+        if (null === existing || !hasManagedBlock(existing)) {
+            unchanged.push(name);
+            continue;
+        }
+        const result = mergeMarkedInstruction(existing);
+        if (AgentRuleStatus.APPLY === result.status && result.content !== existing) {
+            io.write(path, result.content);
+            updated.push(name);
+        }
+        else {
+            unchanged.push(name);
+        }
+    }
+    return { updated, unchanged };
+}

package/dist/init/run.d.ts

@@ -56,6 +56,8 @@ export interface InitIo {
     exists(relPath: string): boolean;
     /** The user's home directory (for global agent config like ~/.cursor/mcp.json). */
     homeDir(): string;
+    /** Absolute path of the directory `init` is running in — the project's own root. */
+    cwd(): string;
     /** Basenames present in the project root. */
     rootFiles(): readonly string[];
     /** Subdirectory names inside a project-relative directory; empty when it isn't one. */
@@ -89,14 +91,4 @@ export interface InitResult {
  * it knows it is in a workspace; this is the matching walk DOWN.
  */
 export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
-/**
- * The standing ask, printed at the end of every `init`.
- *
- * Addressed to the agent as much as the human: whichever of them just ran this command is the one
- * holding the experience, and neither has a Reticle tool surface to file through at this point.
- *
- * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
- * the workspace redirect is kept from asking twice.
- */
-export declare const FEEDBACK_HINT: string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;

package/dist/init/run.js

@@ -5,16 +5,19 @@
  */
 import { dirname, join } from 'node:path';
 import { noPackageJsonMessage } from './non-js-project.js';
+import { devCommandFrom } from './dev-script.js';
+import { restartHint, FEEDBACK_HINT } from './closing-hint.js';
 import { spanSync } from '../trace.js';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { projectIdOf, rememberProjectOnDisk } from '../project/remember-project.js';
 import { detect, Framework, namesAPackageManager, UiLibrary } from './detect.js';
 import { wasMcpRegistered } from './mcp-registered.js';
 import { pickAstroHost } from './astro-host.js';
 import { workspaceParents } from './workspace-apps.js';
 import { chooseWorkspaceApp } from './app-choice.js';
 import { isConnectStep } from './connect-steps.js';
-import { CLI, CURSOR_RULE_PATH, RETICLE_MD_PATH } from './agent-rules.js';
+import { CURSOR_RULE_PATH, RETICLE_MD_PATH } from './agent-rules.js';
 import { CRA_ENV_PATH } from './cra.js';
 /** CRA's bundled entry, in the order create-react-app itself generates them. */
 const CRA_ENTRY_CANDIDATES = ['src/index.tsx', 'src/index.jsx', 'src/index.ts', 'src/index.js'];
@@ -351,6 +354,7 @@ function gatherPlanInput(options, io, pkgRaw) {
         claudeCli,
         mcpExists,
         cursorPresent,
+        platform: process.platform,
         detectedClients,
         cursorProjectPresent: io.exists(CURSOR_DIR_RELPATH),
         cursorConfig,
@@ -374,6 +378,7 @@ function gatherPlanInput(options, io, pkgRaw) {
         nextReticleDevPath: devLocation.path,
         nextReticleDevImport: devLocation.importSpecifier,
         nextReticleDevExists: io.exists(devLocation.path),
+        nextReticleDevSource: io.readFile(devLocation.path),
         svelteKitHooksExists: io.exists(SVELTEKIT_HOOKS),
         craEntry: craEntryOf(io),
         craEnv: io.readFile(CRA_ENV_PATH),
@@ -467,72 +472,11 @@ export function findWorkspaceApps(io) {
     }
     return [...new Set(found)];
 }
-/**
- * The standing ask, printed at the end of every `init`.
- *
- * Addressed to the agent as much as the human: whichever of them just ran this command is the one
- * holding the experience, and neither has a Reticle tool surface to file through at this point.
- *
- * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
- * the workspace redirect is kept from asking twice.
- */
-export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
-    'one thing that decides what gets fixed:\n' +
-    `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
-    `  ${CLI} feedback "what worked, what didn't"   (humans)`;
-function devServerRestart(framework) {
-    if (framework === Framework.NEXT)
-        return 'Restart `next dev`';
-    if (framework === Framework.VITE)
-        return 'Restart `vite`';
-    if (framework === Framework.ASTRO)
-        return 'Restart `astro dev`';
-    if (framework === Framework.SVELTEKIT)
-        return 'Restart your dev server (`npm run dev`)';
-    return 'Reload your app on localhost';
-}
-/**
- * The last two lines a user reads, and the order matters.
- *
- * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
- * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
- * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
- * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
- * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
- * failed.
- *
- * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
- * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
- */
-function restartHint(framework, mcpRegistered) {
-    const dev = `${devServerRestart(framework)}.`;
-    // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
-    //
-    // `init` writes files and stops; the install is not finished until an app carrying the SDK has
-    // actually dialled the daemon, and nothing here confirmed that. The field shape is unambiguous:
-    // people complete the agent half, never complete the app half, and keep a daemon running for
-    // weeks with nothing to drive — so this is the last instruction most of them read.
-    //
-    // "Ask your agent: List Reticle sessions" asks a question whose failure is a dead end. `reticle
-    // status` ANSWERS it: as of 2.7.0 it reports the session, or says why there is none — no app
-    // running, an app running that never dialled us, a tab that closed — with the fix for each.
-    const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
-        'it has not.';
-    if (!mcpRegistered)
-        return `${dev} ${prove}`;
-    return (`${dev}\n` +
-        'Then restart your agent so it picks up the new MCP server — restart Claude Code, reload the ' +
-        'window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code.\n' +
-        'The tools only appear after that: your agent read its server list before Reticle existed, ' +
-        'and no slash command re-reads it (`/mcp` manages servers already loaded, so it cannot pick ' +
-        'up a new one). This is once per machine — Reticle is registered globally, so every later ' +
-        'project starts with the tools already there.\n' +
-        `${prove}\n` +
-        'Once it shows a session, ask your agent to drive a flow — that is the install finished.');
-}
 const SKIPPED_DETAIL = 'skipped — the dependency install above failed, and wiring the app to a package that is not ' +
     'installed stops it booting. Run that install, then re-run `reticle init`.';
-function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRoot) {
+function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRoot, 
+/** The project's own dev command, so the closing line names what a human would type. */
+devCommand) {
     io.print(dryRun ? 'reticle init (dry run, no files written)' : 'reticle init');
     // Every path below is printed RELATIVE, and until now nothing said what to. Reported from the
     // field as "[✓] Reticle config → .reticle.json" followed by the file not being there: the app was
@@ -592,7 +536,7 @@ function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRo
             '"no browser session connected" until then. Everything else is already in place.');
         io.print('');
     }
-    io.print(restartHint(plan.framework, wasMcpRegistered(resolvedStatus(plan, MCP_TARGET, failed, skipped))));
+    io.print(restartHint(plan.framework, resolvedStatus(plan, MCP_TARGET, failed, skipped), devCommand));
     return { ok: !connectPending, applied, manual };
 }
 /**
@@ -684,6 +628,17 @@ function applyEffects(plan, io) {
                 installFailed = true;
         }
     }
+    // Where this project lives, remembered for a daemon that will be started somewhere else.
+    //
+    // Deliberately AFTER the loop and unconditional on which steps ran: most init runs report "already
+    // wired", and a re-run in a re-cloned or moved checkout is exactly when the remembered path has
+    // gone stale — so the run that would otherwise be a no-op is the one that repairs the entry. The
+    // return value is ignored on purpose; this is a cache, and a read-only home directory must not
+    // turn a wired project into a failed init.
+    const projectId = projectIdOf(io.readFile(RETICLE_CONFIG_FILE));
+    if (projectId !== undefined) {
+        rememberProjectOnDisk(io, projectId, io.cwd(), Date.now());
+    }
     return { failed, skipped, degraded };
 }
 /**
@@ -803,12 +758,15 @@ function runInitSteps(options, io) {
     // Init is the flow a user experiences the wait of personally, and the fixture gate measures it at
     // 1–6s per app with no explanation of the spread. These three spans split that number into detect
     // (filesystem probing), plan (pure), and apply (writes + package-manager and CLI subprocesses).
-    const plan = spanSync('init.plan', {}, () => buildPlan(gatherPlanInput(options, io, pkgRaw)));
+    const planInput = gatherPlanInput(options, io, pkgRaw);
+    const plan = spanSync('init.plan', {}, () => buildPlan(planInput));
     const effects = options.dryRun
         ? { failed: new Set(), skipped: new Set(), degraded: new Map() }
         : spanSync('init.apply', { steps: plan.steps.length }, () => applyEffects(plan, io));
     const { failed, skipped, degraded } = effects;
-    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd, agentRootOf(options));
+    // The project's own dev command, so the closing line names what a human would actually type.
+    const devCommand = devCommandFrom(pkgRaw, planInput.detection.packageManager);
+    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd, agentRootOf(options), devCommand);
     // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
     if (options.dryRun)
         return result;