@reticlehq/server 2.11.0 → 2.13.0

package/dist/init/plan-framework.js

@@ -3,15 +3,17 @@
  * 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';
-import { CRA_DEV_MODULE_IMPORT, CRA_DEV_MODULE_PATH, CRA_ENV_PATH, CRA_TOKEN_PER_MACHINE_NOTICE, TOKEN_VAR, craDevModuleFile, craEnvPatch, craImportPatch, } from './cra.js';
+import { ASTRO_ENV_DTS_PATH, patchAstroConfig, patchAstroEnvDts, patchAstroLayout, } from './astro-patch.js';
+import { CRA_DEV_MODULE_IMPORT, CRA_ENV_PATH, CRA_TOKEN_PER_MACHINE_NOTICE, TOKEN_VAR, craDevModuleFile, craDevModulePath, craEnvPatch, craImportPatch, } from './cra.js';
 import { PatchKind } from './patch-kind.js';
 import { viteManual, NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, viteDevModuleFile, VITE_DEV_MODULE_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, astroManual, nuxtManual, NUXT_PLUGIN_PATH, } from './snippets.js';
-import { RETICLE_CONFIG_FILE, StepStatus } from './plan.js';
+import { StepStatus } from './plan.js';
 import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { CSP_STEP_TITLE, cspPlanProblem } from './csp-check.js';
+import { CSP_STEP_TITLE } from './csp-check.js';
+import { diagnoseWebCsp } from './csp-doctor.js';
 /** What adding `reticle()` to a Vite config buys, which differs by framework. */
 export const VITE_PLUGIN_DETAIL = {
     /** A plain Vite app gets both halves from the plugin. */
@@ -40,20 +42,13 @@ const CAPABILITIES_TITLE = 'Capabilities + store';
  */
 const CAPABILITIES_TODO_TITLE = 'AGENT: finish the capabilities file';
 function capabilitiesTodo(path, stores) {
-    const store = stores.length > 0
-        ? `This app depends on a state library init cannot wire on its own (it needs an argument only ` +
-            `reading the code can supply). Uncomment the suggested line in that file and complete it: ` +
-            `${stores.join('; ')}.`
-        : `No state library was detected. If the app holds state somewhere init cannot see, register ` +
-            `it — see node_modules/@reticlehq/server/docs/usage.md.`;
-    return (`${path} was written but registers nothing, so \`hasCapabilities\` stays false and reticle_state ` +
-        `has nothing to read.\n` +
+    return (`This app's state lives in a library nothing in the running app points at, so it is the one ` +
+        `thing Reticle cannot find for itself — reticle_state will not see it until you say where it ` +
+        `is.\n` +
         `Do this now, before driving anything:\n` +
-        `  1. ${store}\n` +
-        `  2. Open the app's main flow and add \`testids\` for the elements it touches (or add ` +
-        `data-testid attributes where there are none).\n` +
-        `  3. Prove it: drive one flow and check reticle_state returns your keys. An empty state read ` +
-        `means this file is still not doing anything, whatever else went green.`);
+        `  1. In ${path}, uncomment the suggested line and complete it: ${stores.join('; ')}.\n` +
+        `  2. Prove it: drive one flow and check reticle_state returns your key. An empty state read ` +
+        `means the line is still not doing anything, whatever else went green.`);
 }
 /**
  * The dev module carrying `registerCapabilities` / `registerStore`.
@@ -62,6 +57,28 @@ 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.
  */
+/**
+ * Is there state left that ONLY the app can hand over?
+ *
+ * This used to ask a much bigger question — "does the generated file register anything at all?" —
+ * and fired on almost every install, because almost every install generated a file whose testids
+ * and stores were both empty. The answer was homework: go read the source, uncomment a line, add
+ * data-testid attributes, then drive to prove it. Several turns, on every onboarding.
+ *
+ * Two of those three are no longer anyone's homework. Testids are read from the live DOM, and a
+ * store passed through a React context provider (Redux, TanStack Query) is discovered and
+ * registered on the first commit. What is left is the genuinely unreachable case: a module-scope
+ * store, or one needing an argument only the source supplies — Zustand, Jotai atoms, an XState
+ * actor. Nothing in the running app points at those, so the notice still has to fire, and it now
+ * fires ONLY there.
+ *
+ * `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 needsManualStore(hints, wired) {
+    return hints.length > 0 && 0 === wired.length;
+}
 function capabilitiesStep(input) {
     if (true === input.viteDevModuleExists) {
         return [
@@ -76,11 +93,26 @@ function capabilitiesStep(input) {
     const testids = input.testids ?? [];
     const stores = input.storeHints ?? [];
     const wired = input.foundStores ?? [];
-    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;
+    // Testids no longer need counting here. They are read from the live DOM at announce time, so a
+    // number printed at install time would be a stale claim about a codebase that is about to change —
+    // which is exactly what "no data-testid values yet" used to be on an app whose testids arrive with
+    // a lazy route.
+    const found = 'testids read from the live DOM';
+    // A store we found and WIRED is a registration, so the 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.
+    //
+    // jotai is still exactly that case. A Redux or TanStack app is not, any more: its store rides a
+    // context provider and the React adapter registers it on the first commit, so `storeHints` no
+    // longer names either one and this notice no longer fires for them.
+    const nothingToRegister = needsManualStore(stores, wired);
     return [
         {
             title: CAPABILITIES_TITLE,
@@ -135,7 +167,7 @@ function viteConfigSteps(input, detail) {
             },
         ];
     }
-    const patch = patchViteConfig(cfg.source, port);
+    const patch = patchViteConfig(cfg.source, port, true === input.captureBodies);
     if (patch.kind === VitePatchKind.ALREADY) {
         return [
             {
@@ -197,16 +229,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 +293,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 &&
+        needsManualStore(input.storeHints ?? [], 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),
     ];
@@ -255,21 +329,27 @@ export function nextSteps(input) {
  */
 export function craSteps(input) {
     const entry = input.craEntry ?? null;
+    // Match the project language the same way Next does (#675): a JS CRA app cannot resolve `.ts`.
+    const modulePath = craDevModulePath(input.detection.typescript);
     const steps = [
         {
             title: 'Reticle connect module',
-            target: CRA_DEV_MODULE_PATH,
+            target: modulePath,
             status: StepStatus.APPLY,
             detail: 'create the dev-only connect (CRA cannot inject through public/index.html)',
             write: {
-                path: CRA_DEV_MODULE_PATH,
-                content: craDevModuleFile(input.options.port, input.options.projectId),
+                path: modulePath,
+                content: craDevModuleFile(input.options.port, input.options.projectId, {
+                    typescript: input.detection.typescript,
+                }),
             },
             dependsOnInstall: true,
         },
     ];
     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',
@@ -426,9 +506,14 @@ export function astroSteps(input) {
             },
         ];
     }
+    const envPatch = patchAstroEnvDts(input.astroEnvDts ?? null);
     return [
         patchStep('Astro config (token + build target)', config.path, configPatch, 'inline the pairing token and raise build.target to es2022', manualWithLayout),
         patchStep('Connect snippet (Astro)', layout.path, layoutPatch, 'add the dev-only connect <script> before </body>', manualWithLayout),
+        // Declares the Vite define names so `astro check` (create-astro's default build) can see them
+        // (#677). Independent of the two halves above: even an ALREADY config/layout still needs this
+        // when the env file was never written.
+        patchStep('Astro env types (Vite defines)', ASTRO_ENV_DTS_PATH, envPatch, 'declare __RETICLE_TOKEN__ / __RETICLE_ROOT__ for astro check', manualWithLayout),
     ];
 }
 /**
@@ -441,15 +526,40 @@ export function astroSteps(input) {
  * warning and a fix.
  */
 export function cspStep(input) {
-    const problem = cspPlanProblem([input.nextConfigSource, input.nextLayout?.source], input.options.port ?? RETICLE_DEFAULT_PORT);
-    if (problem === undefined)
+    // Reads the SAME list `reticle doctor` reads. It used to read a hand-written pair —
+    // `[nextConfigSource, nextLayout?.source]` — while csp-doctor.ts already carried the full set
+    // including `index.html`, which is where every Vite and Electron app declares its policy. So the
+    // command you run BEFORE anything works checked less than the one you run after it has failed.
+    //
+    // Measured on MarkText, a production Electron editor: its renderer sets `default-src 'self'` with
+    // no `connect-src`, the browser blocked the bridge WebSocket, and `init` printed a clean plan. The
+    // daemon cannot see a dial that never left the page, so nothing anywhere said why — and the check
+    // that would have said it was sitting one import away.
+    // The pre-read Next sources are folded in ON TOP of the shared list, not replaced by it: init
+    // resolves `nextConfigFile` across more spellings than CSP_FILES names (`.mts`, for one), and a
+    // layout is found by search rather than by a fixed path. Two sources of the same truth is the
+    // problem being fixed here — one of them being a SUPERSET is not.
+    const extra = {
+        ...(input.nextConfigFile !== null && input.nextConfigFile !== undefined
+            ? { [input.nextConfigFile]: input.nextConfigSource ?? undefined }
+            : {}),
+        ...(input.nextLayout ? { [input.nextLayout.path]: input.nextLayout.source } : {}),
+    };
+    const read = (file) => extra[file] ?? input.cspSources?.[file];
+    const findings = diagnoseWebCsp(read, input.options.port ?? RETICLE_DEFAULT_PORT, [
+        ...Object.keys(extra),
+    ]);
+    const first = findings[0];
+    if (first === undefined)
         return [];
     return [
         {
             title: CSP_STEP_TITLE,
-            target: input.nextConfigFile ?? RETICLE_CONFIG_FILE,
+            target: first.file,
             status: StepStatus.NOTICE,
-            detail: problem,
+            // `problem` already ends with the text to paste; `fix` is the same sentence for callers that
+            // want it on its own (doctor renders them separately). Printing both said it twice.
+            detail: first.problem,
         },
     ];
 }

package/dist/init/plan.d.ts

@@ -5,17 +5,7 @@
  */
 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[];
+import { McpClient } from './mcp-clients.js';
 /**
  * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
  *
@@ -95,18 +85,28 @@ export interface Plan {
 }
 export interface PlanInput {
     detection: Detection;
+    /**
+     * Write `captureNetworkBodies: true` into the app's config. Off unless the caller asked (#705).
+     *
+     * Optional so every existing caller and test keeps the safe default without naming it — the one
+     * direction a default about somebody else's data should be wrong in.
+     */
+    captureBodies?: boolean | undefined;
+    /**
+     * The CSP-bearing files this project actually has, keyed by path — read once in `gatherPlanInput`.
+     *
+     * Pre-read rather than given a reader, because `PlanInput` is the pure input to a pure planner and
+     * handing it an io would let any later step reach the disk from inside `buildPlan`.
+     */
+    cspSources?: Readonly<Record<string, string | undefined>> | undefined;
     /** Whether the `claude` CLI is installed (so we can register the MCP server globally). */
     claudeCli: boolean;
     /** Whether an `reticle` MCP server is already registered with Claude (any scope) — idempotency. */
     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. */
-    cursorConfig: string | null;
-    /** Absolute path of ~/.cursor/mcp.json (the write target). */
-    cursorConfigPath: string;
     /**
      * Every OTHER MCP client detected on this machine, with its config path and current content.
      *
@@ -139,6 +139,11 @@ export interface PlanInput {
         path: string;
         source: string;
     } | null | undefined;
+    /**
+     * Existing `src/env.d.ts` content, when present — where the Vite-define ambient declarations go
+     * so `astro check` can see `__RETICLE_TOKEN__` / `__RETICLE_ROOT__` (#677).
+     */
+    astroEnvDts?: string | null | undefined;
     /** Discovered Next config filename (e.g. 'next.config.mjs'), or null. */
     nextConfigFile: string | null;
     /** Source of that Next config, so the export can be wrapped in withReticle. */
@@ -154,6 +159,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 +239,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,15 +4,16 @@
  * 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 { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.js';
-import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, } from './mcp-clients.js';
+import { installFailureHint } from './install-hint.js';
+import { claudeAddCommand, mcpManual, mcpWindowsNote } from './mcp.js';
+import { NodePlatform } from '../platform.js';
+import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, McpClient, } from './mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from './slash-command.js';
 import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, RETICLE_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
 import { viteSteps, nextSteps, craSteps, svelteKitSteps, nuxtSteps, astroSteps, cspStep, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
 import { join } from 'node:path';
 import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote } from './snippets.js';
-import { declaredInstallSource } from '../telemetry/install-source.js';
+import { configWithInstallSource, declaredInstallSource } from '../telemetry/install-source.js';
 import { devServerPortWarning, isLikelyDevServerPort } from '../cli/cli-port.js';
 // An app dev installs exactly the audience-scoped browser-side dependencies — never the retired
 // `@reticlehq/core` umbrella (which dragged the Node MCP server + ws into every app). The kit is the
@@ -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}`);
@@ -121,7 +122,6 @@ function agentFile(input, relPath) {
     return root === undefined || 0 === root.length ? relPath : join(root, relPath);
 }
 const CLAUDE_MCP_TITLE = 'MCP server (Claude, global)';
-const CURSOR_MCP_TITLE = 'MCP server (Cursor, global)';
 function claudeMcpStep(input) {
     if (!input.claudeCli)
         return null;
@@ -142,34 +142,6 @@ function claudeMcpStep(input) {
         exec: { command: cmd.command, args: cmd.args, fallback: cmd.display },
     };
 }
-function cursorMcpStep(input) {
-    if (!input.cursorPresent)
-        return null;
-    const r = mergeCursorConfig(input.cursorConfig);
-    if (r.status === CursorMergeStatus.ALREADY) {
-        return {
-            title: CURSOR_MCP_TITLE,
-            target: input.cursorConfigPath,
-            status: StepStatus.ALREADY,
-            detail: 'reticle already in Cursor global config',
-        };
-    }
-    if (r.status === CursorMergeStatus.MANUAL) {
-        return {
-            title: CURSOR_MCP_TITLE,
-            target: input.cursorConfigPath,
-            status: StepStatus.MANUAL,
-            detail: `couldn't parse ${input.cursorConfigPath} — add this server by hand:\n  "reticle": ${JSON.stringify(cursorServerEntry())}`,
-        };
-    }
-    return {
-        title: CURSOR_MCP_TITLE,
-        target: input.cursorConfigPath,
-        status: StepStatus.APPLY,
-        detail: 'register reticle in Cursor global config',
-        write: { path: input.cursorConfigPath, content: r.content },
-    };
-}
 /**
  * One step per OTHER detected client.
  *
@@ -232,19 +204,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';
 /**
@@ -289,7 +275,8 @@ function claudeCommandStep(input) {
     return commandStepFor(agentFile(input, CLAUDE_COMMAND_PATH), input.claudeCli, input.claudeCommandContent);
 }
 function cursorCommandStep(input) {
-    const present = true === input.cursorProjectPresent || (input.cursorPresent && !input.claudeCli);
+    const cursorGlobal = (input.detectedClients ?? []).some((c) => c.id === McpClient.CURSOR);
+    const present = true === input.cursorProjectPresent || (cursorGlobal && !input.claudeCli);
     return commandStepFor(agentFile(input, CURSOR_COMMAND_PATH), present, input.cursorCommandContent);
 }
 const AGENT_RULE_TITLE = 'Agent verification rule';
@@ -324,7 +311,8 @@ function claudeRuleStep(input) {
  * committed into their repo. (Global MCP registration is different: it is global, and stays.)
  */
 function cursorRuleStep(input) {
-    if (!input.cursorPresent)
+    const cursorGlobal = (input.detectedClients ?? []).some((c) => c.id === McpClient.CURSOR);
+    if (!cursorGlobal && true !== input.cursorProjectPresent)
         return null;
     if (input.cursorProjectPresent !== true && input.claudeCli)
         return null;
@@ -374,14 +362,13 @@ const AGENT_INTEGRATIONS = [
     },
     {
         id: AgentId.CURSOR,
-        mcpStep: cursorMcpStep,
         ruleStep: cursorRuleStep,
         commandStep: cursorCommandStep,
     },
 ];
 /** The steps one surface contributes across every known agent, in registry order. */
 function stepsForAgents(input, surface) {
-    return AGENT_INTEGRATIONS.map((a) => surface(a)(input)).filter((s) => s !== null);
+    return AGENT_INTEGRATIONS.map((a) => surface(a)?.(input) ?? null).filter((s) => s !== null);
 }
 /** The `/reticle` command file for every agent that has a command surface and is present here. */
 function slashCommandSteps(input) {
@@ -488,15 +475,6 @@ function unpinnedRetryNote(version, pm) {
         `installed instead. That may not match the daemon — if the agent reports protocol errors, check ` +
         `\`versionSkew\` in reticle_sessions.${remedy}`);
 }
-function installFailureHint(pm) {
-    if (pm !== PackageManager.PNPM)
-        return 'If the version was refused, install the SDK yourself.';
-    return ('If pnpm reported ERR_PNPM_NO_MATURE_MATCHING_VERSION, its minimumReleaseAge setting is holding ' +
-        'this release back. Either wait out the window, or allow these packages explicitly:\n' +
-        '  pnpm config set minimumReleaseAgeExclude "@reticlehq/*"\n' +
-        'Do NOT drop the version pin — unpinned, pnpm installs an older SDK against a newer daemon, and ' +
-        'that mismatch surfaces as a -32000 with nothing naming a version.');
-}
 function installStep(input) {
     const pm = input.detection.packageManager;
     const packages = pinnedPackages(frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion);
@@ -614,6 +592,18 @@ function reticleConfigStep(input, content) {
                 detail: problem,
             };
         }
+        // The one thing a re-run can still learn: which channel the user actually arrived through.
+        // See configWithInstallSource — it only ever ADDS a field that is absent.
+        const backfilled = configWithInstallSource(input.reticleConfigSource, declaredInstallSource());
+        if (backfilled !== undefined) {
+            return {
+                title: RETICLE_CONFIG_TITLE,
+                target: RETICLE_CONFIG_FILE,
+                status: StepStatus.APPLY,
+                detail: 'record which install route this project came through',
+                write: { path: RETICLE_CONFIG_FILE, content: backfilled },
+            };
+        }
         return {
             title: RETICLE_CONFIG_TITLE,
             target: RETICLE_CONFIG_FILE,

package/dist/init/preflight.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two conditions that make every later phase fail, checked before anything is written.
+ *
+ * Both lived in setup/reticle.mjs and neither survived the port into `init`. What they buy is the
+ * distance between a failure and its cause: without them, an unwritable checkout arrives as EACCES
+ * in a stack trace at phase four, and a missing package manager arrives as `spawn pnpm ENOENT`
+ * inside "the dev server exited" — which sends the reader into their own dev script hunting a bug
+ * that is not there.
+ */
+/** The parts of the environment preflight reads, so the rules are testable without a filesystem. */
+export interface PreflightIo {
+    /** Absolute path of the directory init is running in. */
+    cwd(): string;
+    /** Can this process write into the project root. */
+    canWrite(): boolean;
+    /** Runs a command quietly for a yes/no check; true on exit code 0. */
+    probe(command: string, args: readonly string[]): boolean;
+}
+/**
+ * The refusal to print, or undefined when this machine can run the install.
+ *
+ * `packageManager` is the one init RESOLVED, never a raw lockfile check. An inherited
+ * `pnpm-lock.yaml` at a monorepo root does not mean the app in `frontend/` uses pnpm — that app's own
+ * installed tree outranks an ancestor lockfile, and detect.ts already works this out. Re-deriving it
+ * here from `exists('pnpm-lock.yaml')` refused an npm app sitting under a pnpm monorepo on a machine
+ * with no pnpm, which the install gate proves must succeed.
+ */
+export declare function preflightRefusal(io: PreflightIo, packageManager: string): string | undefined;

package/dist/init/preflight.js

@@ -0,0 +1,38 @@
+/**
+ * The two conditions that make every later phase fail, checked before anything is written.
+ *
+ * Both lived in setup/reticle.mjs and neither survived the port into `init`. What they buy is the
+ * distance between a failure and its cause: without them, an unwritable checkout arrives as EACCES
+ * in a stack trace at phase four, and a missing package manager arrives as `spawn pnpm ENOENT`
+ * inside "the dev server exited" — which sends the reader into their own dev script hunting a bug
+ * that is not there.
+ */
+/**
+ * npm ships with node, so refusing for its absence would refuse on a machine that is fine.
+ */
+const ALWAYS_PRESENT = 'npm';
+/**
+ * The refusal to print, or undefined when this machine can run the install.
+ *
+ * `packageManager` is the one init RESOLVED, never a raw lockfile check. An inherited
+ * `pnpm-lock.yaml` at a monorepo root does not mean the app in `frontend/` uses pnpm — that app's own
+ * installed tree outranks an ancestor lockfile, and detect.ts already works this out. Re-deriving it
+ * here from `exists('pnpm-lock.yaml')` refused an npm app sitting under a pnpm monorepo on a machine
+ * with no pnpm, which the install gate proves must succeed.
+ */
+export function preflightRefusal(io, packageManager) {
+    // First: on a read-only checkout nothing else matters, and one access check is cheaper and
+    // quieter than spawning a subprocess to discover the same thing.
+    if (!io.canWrite()) {
+        return (`${io.cwd()} is not writable, and init has to write into it (.reticle.json, the build config, ` +
+            'a capabilities file). Fix the permissions, or run init from a checkout you own.');
+    }
+    // What the project resolves to says nothing about what the machine HAS, and a project committed to
+    // pnpm on an npm-only box is an ordinary Monday.
+    if (ALWAYS_PRESENT !== packageManager && !io.probe(packageManager, ['--version'])) {
+        return (`this project uses ${packageManager} (its lockfile says so) and ${packageManager} is not ` +
+            `installed on this machine. Install it (npm i -g ${packageManager}, or corepack enable), or ` +
+            'pass --url with the address the app already serves.');
+    }
+    return undefined;
+}