@reticlehq/server 2.3.0 → 2.5.0

package/dist/init/capabilities.js

@@ -0,0 +1,54 @@
+/**
+ * What the app can be driven by: its `data-testid` values, and which state library holds its truth.
+ *
+ * `init` wired none of this, so every app came up with `hasCapabilities: false`, empty capabilities,
+ * and a `reticle_state` holding nothing but `__reticle_renders` — the state-truth read that SKILL.md
+ * calls the highest-value line was unavailable on every app out of the box. Measured across six.
+ *
+ * Testids are scanned rather than asked for. Stores are NAMED but not wired: detecting that an app
+ * depends on zustand is easy, knowing which module exports the store instance is not, and generating
+ * a wrong import would break the dev module that everything else now hangs off.
+ */
+/** `data-testid="foo"` / `data-testid='foo'` / `data-testid={"foo"}` — the forms people actually write. */
+const TESTID_ATTR = /data-testid\s*=\s*[{]?\s*["'`]([^"'`]+)["'`]/g;
+/** Cap the generated list. A capabilities block is a hint for an agent, not an inventory. */
+export const MAX_TESTIDS = 60;
+/** Every distinct `data-testid` literal in the given sources, in first-seen order. */
+export function scanTestids(sources) {
+    const found = new Set();
+    for (const src of sources) {
+        for (const m of src.matchAll(TESTID_ATTR)) {
+            const id = m[1];
+            if (id !== undefined && id.length > 0)
+                found.add(id);
+            if (found.size >= MAX_TESTIDS)
+                return [...found];
+        }
+    }
+    return [...found];
+}
+/**
+ * State libraries the browser SDK has an adapter for, in the order we would recommend registering
+ * them. TanStack Query is first on purpose: a stale cache served as fresh fires NO network request,
+ * so the network log shows silence and the DOM shows a plausible number — the cache is the only
+ * witness, which makes it the highest-value store in the list and the least obvious one to add.
+ */
+const STORE_LIBRARIES = [
+    ['@tanstack/react-query', "registerStore('queries', tanstackQueryStore(queryClient))"],
+    [
+        'zustand',
+        "registerStore('app', useStore) // pass the store itself, not () => store.getState()",
+    ],
+    ['@reduxjs/toolkit', "registerStore('app', store)"],
+    ['redux', "registerStore('app', store)"],
+    ['jotai', "registerStore('app', jotaiStore(getDefaultStore(), { cart, user }))"],
+    ['valtio', "registerStore('app', valtioStore(state))"],
+    ['mobx', "registerStore('app', mobxStore(state))"],
+    ['xstate', "registerStore('machine', xstateStore(actor))"],
+    ['pinia', "registerStore('cart', piniaStore(useCartStore()))"],
+    ['svelte', "registerStore('cart', svelteStore(cartStore))"],
+];
+/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+export function storeHints(deps) {
+    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep)).map(([, hint]) => hint);
+}

package/dist/init/cra.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Wiring Reticle into a Create React App project.
+ *
+ * CRA had no automated path: init reported `⚠ Connect snippet → index.html`, a target that cannot
+ * work. CRA's `public/index.html` is a static template the bundler never processes for modules, so a
+ * bare import in it resolves to nothing. `src/index.tsx` is what gets bundled, and that is where the
+ * connect has to arrive.
+ *
+ * The token is the second half of the problem. Every other stack has somewhere to inline it —
+ * Vite defines `__RETICLE_TOKEN__`, the Astro and HTML snippets read the file in Node. `src/index.tsx`
+ * is browser code inside a bundler that inlines exactly one thing: environment variables prefixed
+ * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
+ * mechanism and is gitignored by CRA's own template.
+ */
+/** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
+export declare const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
+export declare const CRA_DEV_MODULE_PATH = "src/reticle-dev.ts";
+export declare const CRA_ENV_PATH = ".env.development.local";
+export declare const TOKEN_VAR = "REACT_APP_RETICLE_TOKEN";
+/**
+ * What the app itself says when the token is not there.
+ *
+ * The token is a per-machine secret and CRA's own template gitignores the file it lives in, so it
+ * CANNOT travel with the repo — that part is correct and must stay. What was wrong is that it failed
+ * silently: a teammate clones, runs `npm start`, and the app connects with an empty token, so the
+ * only signal is the bridge's generic `authentication failed` in a console nobody had open. Naming
+ * the variable, the gitignored file and the one command that fixes it turns a dead app into a
+ * one-line repair. Every other stack reads the token in Node at dev-server start (the Vite plugin,
+ * withReticle); CRA has no such hook without ejecting, so this message is the fix.
+ */
+export declare const CRA_TOKEN_MISSING_NOTE: string;
+/** Add the import after the last existing one, or null when it is already present. */
+export declare function craImportPatch(source: string): string | null;
+/** Set the token variable, or null when nothing needs to change. */
+export declare function craEnvPatch(existing: string | null, token: string): string | null;
+/** The dev-only connect module imported from `src/index.tsx`. */
+export declare function craDevModuleFile(port: number | undefined, projectId?: string): string;

package/dist/init/cra.js

@@ -0,0 +1,90 @@
+/**
+ * Wiring Reticle into a Create React App project.
+ *
+ * CRA had no automated path: init reported `⚠ Connect snippet → index.html`, a target that cannot
+ * work. CRA's `public/index.html` is a static template the bundler never processes for modules, so a
+ * bare import in it resolves to nothing. `src/index.tsx` is what gets bundled, and that is where the
+ * connect has to arrive.
+ *
+ * The token is the second half of the problem. Every other stack has somewhere to inline it —
+ * Vite defines `__RETICLE_TOKEN__`, the Astro and HTML snippets read the file in Node. `src/index.tsx`
+ * is browser code inside a bundler that inlines exactly one thing: environment variables prefixed
+ * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
+ * mechanism and is gitignored by CRA's own template.
+ */
+/** 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';
+/**
+ * What the app itself says when the token is not there.
+ *
+ * The token is a per-machine secret and CRA's own template gitignores the file it lives in, so it
+ * CANNOT travel with the repo — that part is correct and must stay. What was wrong is that it failed
+ * silently: a teammate clones, runs `npm start`, and the app connects with an empty token, so the
+ * only signal is the bridge's generic `authentication failed` in a console nobody had open. Naming
+ * the variable, the gitignored file and the one command that fixes it turns a dead app into a
+ * one-line repair. Every other stack reads the token in Node at dev-server start (the Vite plugin,
+ * withReticle); CRA has no such hook without ejecting, so this message is the fix.
+ */
+export const CRA_TOKEN_MISSING_NOTE = `${TOKEN_VAR} is not set, so Reticle cannot pair with the daemon. ` +
+    `The pairing token is per-machine and ${CRA_ENV_PATH} is gitignored by CRA's template, ` +
+    'so it does not survive a clone. Run `npx reticle init` in this project to write it for this machine.';
+/** Add the import after the last existing one, or null when it is already present. */
+export function craImportPatch(source) {
+    if (source.includes(CRA_DEV_MODULE_IMPORT))
+        return null;
+    const lines = source.split('\n');
+    // After the LAST import: React's own imports must still run first, and a side-effect import placed
+    // above them would connect before the app exists.
+    let lastImport = -1;
+    for (const [index, line] of lines.entries()) {
+        if (/^\s*import\s/.test(line))
+            lastImport = index;
+    }
+    lines.splice(lastImport + 1, 0, CRA_DEV_MODULE_IMPORT);
+    return lines.join('\n');
+}
+/** Set the token variable, or null when nothing needs to change. */
+export function craEnvPatch(existing, token) {
+    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);
+    }
+    return `${existing.endsWith('\n') ? existing : `${existing}\n`}${line}\n`;
+}
+/** The dev-only connect module imported from `src/index.tsx`. */
+export function craDevModuleFile(port, projectId) {
+    const fields = [];
+    if (port !== undefined)
+        fields.push(`url: 'ws://127.0.0.1:${String(port)}/reticle'`);
+    if (projectId !== undefined && projectId.length > 0)
+        fields.push(`projectId: '${projectId}'`);
+    const inline = fields.length > 0 ? `${fields.join(', ')}, ` : '';
+    return `// Dev-only: connect Reticle. Imported for its side effect from src/index.tsx.
+//
+// CRA's public/index.html is a static template the bundler never processes for modules, so the
+// connect cannot live there. The pairing token arrives through REACT_APP_RETICLE_TOKEN because
+// REACT_APP_* is the only thing CRA inlines into browser code.
+if (process.env.NODE_ENV === 'development') {
+  void import('@reticlehq/react').then(({ reticle, install }) => {
+    install();
+    const token = process.env.${TOKEN_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 } : {}) });
+  });
+}
+
+export {};
+`;
+}

package/dist/init/cursor.js

@@ -5,6 +5,7 @@
  * (jsonc/comment) files bail to manual rather than being rewritten.
  */
 import { NPX, MCP_SERVER_NAME, npxServerArgs } from './mcp.js';
+import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
 /** Path of Cursor's global MCP config, relative to the user's home directory. */
 export const CURSOR_MCP_RELPATH = '.cursor/mcp.json';
 /** The directory whose presence signals Cursor is installed for this user. */
@@ -18,18 +19,47 @@ export function cursorServerEntry() {
     return { command: NPX, args: npxServerArgs() };
 }
 function parseConfig(existing) {
-    if (existing === null || existing.trim().length === 0)
+    if (null === existing || 0 === existing.trim().length)
         return { ok: true, config: {} };
     try {
         const parsed = JSON.parse(existing);
-        if (typeof parsed !== 'object' || parsed === null)
-            return { ok: true, config: {} };
+        // Valid JSON that is not a PLAIN OBJECT — `[]`, `3`, `"x"`, `null` — used to fall through to an
+        // empty config, and the file was then rewritten wholesale. Unparseable JSON was already handled
+        // conservatively; this adjacent case destroyed the file instead. Whatever is in there is the
+        // user's, and we do not understand it, so we do not touch it.
+        if (typeof parsed !== 'object' || null === parsed || Array.isArray(parsed))
+            return { ok: false };
         return { ok: true, config: parsed };
     }
     catch {
         return { ok: false };
     }
 }
+/**
+ * Should this entry be left exactly as it is?
+ *
+ * Two different reasons to leave one alone, and only one of them is "it is correct":
+ *   - it already matches what we would write; or
+ *   - it is not an entry WE wrote. Somebody pointing `reticle` at their own local build is a
+ *     deliberate choice, and silently replacing it with the published npx command would break their
+ *     setup to fix a problem they do not have.
+ *
+ * What IS repaired is a stale entry of our own shape — an old pin, a command that has moved — which
+ * presence-only idempotency reported as "already registered" and never fixed, so an upgrade could
+ * not repair the thing an upgrade exists to repair.
+ */
+function leaveEntryAlone(existing) {
+    if (JSON.stringify(existing) === JSON.stringify(cursorServerEntry()))
+        return true;
+    if (typeof existing !== 'object' || null === existing)
+        return true;
+    const command = existing.command;
+    const args = existing.args;
+    const ours = command === NPX &&
+        Array.isArray(args) &&
+        args.some((arg) => 'string' === typeof arg && arg.includes(RETICLE_NPM_PACKAGE));
+    return !ours;
+}
 export function mergeCursorConfig(existing) {
     const parsed = parseConfig(existing);
     if (!parsed.ok) {
@@ -37,7 +67,12 @@ export function mergeCursorConfig(existing) {
     }
     const config = parsed.config;
     const servers = config.mcpServers ?? {};
-    if (Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME)) {
+    // Presence alone used to mean "already registered", so a `reticle` entry left by an older release —
+    // a command that no longer exists, or a stale pin — was reported done and never repaired. An
+    // upgrade could not fix a bad entry, which is exactly when it needs to. Only OUR key is replaced;
+    // every other server and top-level key is carried through untouched by the spread below.
+    if (Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME) &&
+        leaveEntryAlone(servers[MCP_SERVER_NAME])) {
         return { status: CursorMergeStatus.ALREADY, content: existing ?? '' };
     }
     const merged = {

package/dist/init/desktop-doctor.d.ts

@@ -23,7 +23,7 @@ export declare const DesktopFinding: {
     readonly ELECTRON_CAPTURE_MISSING: "electron-capture-missing";
 };
 export type DesktopFinding = (typeof DesktopFinding)[keyof typeof DesktopFinding];
-export interface DesktopDiagnosis {
+interface DesktopDiagnosis {
     code: DesktopFinding;
     /** Which file to look at. */
     file: string;
@@ -33,8 +33,9 @@ export interface DesktopDiagnosis {
     fix: string;
 }
 /** Reads a project-relative path. Undefined means the file does not exist. */
-export type ReadFile = (path: string) => string | undefined;
+type ReadFile = (path: string) => string | undefined;
 /** Is this project a desktop shell at all? Used to print a positive result instead of silence. */
 export declare function isDesktopProject(read: ReadFile): boolean;
 /** Which desktop shell (if any) this project is, and what is missing from its Reticle wiring. */
 export declare function diagnoseDesktop(read: ReadFile, port: number): DesktopDiagnosis[];
+export {};

package/dist/init/desktop-doctor.js

@@ -31,7 +31,7 @@ function parseJson(text) {
         return undefined;
     try {
         const parsed = JSON.parse(text);
-        return typeof parsed === 'object' && parsed !== null
+        return 'object' === typeof parsed && parsed !== null
             ? parsed
             : undefined;
     }
@@ -40,7 +40,7 @@ function parseJson(text) {
     }
 }
 function record(value) {
-    return typeof value === 'object' && value !== null ? value : {};
+    return 'object' === typeof value && value !== null ? value : {};
 }
 /**
  * Does this CSP permit the bridge WebSocket on `port`?
@@ -72,7 +72,7 @@ function diagnoseTauri(read, port) {
     if (conf === undefined)
         return [];
     const security = record(record(conf['app'])['security']);
-    const csp = typeof security['csp'] === 'string' ? security['csp'] : undefined;
+    const csp = 'string' === typeof security['csp'] ? security['csp'] : undefined;
     const findings = [];
     if (!cspAllowsBridge(csp, port)) {
         findings.push({
@@ -193,6 +193,6 @@ export function diagnoseDesktop(read, port) {
     const deps = { ...record(pkg['dependencies']), ...record(pkg['devDependencies']) };
     if (deps['electron'] === undefined)
         return [];
-    const main = typeof pkg['main'] === 'string' ? pkg['main'] : undefined;
+    const main = 'string' === typeof pkg['main'] ? pkg['main'] : undefined;
     return main === undefined ? [] : diagnoseElectron(read, main);
 }

package/dist/init/detect.d.ts

@@ -6,6 +6,9 @@ export declare const Framework: {
     readonly NEXT: "next";
     readonly VITE: "vite";
     readonly SVELTEKIT: "sveltekit";
+    readonly ASTRO: "astro";
+    /** Create React App. No config file exists, so `react-scripts` in the dependencies is the signal. */
+    readonly CRA: "cra";
     readonly HTML: "html";
 };
 export type Framework = (typeof Framework)[keyof typeof Framework];
@@ -27,9 +30,31 @@ export interface DetectInput {
     configFiles: ReadonlySet<string>;
     /** Lockfile basenames present in the project root. */
     lockfiles: ReadonlySet<string>;
+    /** Marker basenames inside `node_modules` (`.modules.yaml`, `.yarn-state.yml`, …), if installed. */
+    nodeModulesMarkers?: ReadonlySet<string>;
 }
+/**
+ * The UI library the app renders with. Detection used to key on "vite is in package.json" and stop
+ * there, so a Vue or Preact app got `@reticlehq/react` installed and an all-green report with no
+ * mention that the React adapter has nothing to attach to.
+ */
+export declare const UiLibrary: {
+    readonly REACT: "react";
+    readonly PREACT: "preact";
+    readonly VUE: "vue";
+    readonly SVELTE: "svelte";
+    readonly UNKNOWN: "unknown";
+};
+export type UiLibrary = (typeof UiLibrary)[keyof typeof UiLibrary];
 export interface Detection {
     framework: Framework;
+    uiLibrary: UiLibrary;
+    /**
+     * Whether the project is TypeScript. Not cosmetic: generating a `.tsx` file into a JavaScript
+     * project makes Next auto-install TypeScript on the next `next dev`, which on Next 13 takes its
+     * require-hook down with it and the dev server never starts.
+     */
+    typescript: boolean;
     reactMajor: number | undefined;
     /** React 19 dropped _debugSource, so it needs the build-time source-map stamp. */
     needsSourceMapping: boolean;
@@ -37,6 +62,7 @@ export interface Detection {
 }
 /** Extract the leading major version from a semver range like "^19.0.0" or "19.1.1". */
 export declare function parseMajor(range: string | undefined): number | undefined;
+export declare function detectPackageManager(lockfiles: ReadonlySet<string>, nodeModulesMarkers: ReadonlySet<string>): PackageManager;
 export declare function detect(input: DetectInput): Detection;
 interface InstallCommand {
     command: string;

package/dist/init/detect.js

@@ -6,6 +6,9 @@ export const Framework = {
     NEXT: 'next',
     VITE: 'vite',
     SVELTEKIT: 'sveltekit',
+    ASTRO: 'astro',
+    /** Create React App. No config file exists, so `react-scripts` in the dependencies is the signal. */
+    CRA: 'cra',
     HTML: 'html',
 };
 export const PackageManager = {
@@ -14,9 +17,27 @@ export const PackageManager = {
     BUN: 'bun',
     NPM: 'npm',
 };
+/**
+ * The UI library the app renders with. Detection used to key on "vite is in package.json" and stop
+ * there, so a Vue or Preact app got `@reticlehq/react` installed and an all-green report with no
+ * mention that the React adapter has nothing to attach to.
+ */
+export const UiLibrary = {
+    REACT: 'react',
+    PREACT: 'preact',
+    VUE: 'vue',
+    SVELTE: 'svelte',
+    UNKNOWN: 'unknown',
+};
 const NEXT_CONFIGS = ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs'];
 const VITE_CONFIGS = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts'];
 const SVELTE_CONFIGS = ['svelte.config.js', 'svelte.config.ts', 'svelte.config.mjs'];
+const ASTRO_CONFIGS = [
+    'astro.config.mjs',
+    'astro.config.js',
+    'astro.config.ts',
+    'astro.config.cjs',
+];
 function depVersion(pkg, name) {
     return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? pkg.peerDependencies?.[name];
 }
@@ -28,19 +49,41 @@ export function parseMajor(range) {
     if (range === undefined)
         return undefined;
     const match = range.match(/(\d+)/);
-    if (match === null || match[1] === undefined)
+    if (null === match || match[1] === undefined)
         return undefined;
     const major = parseInt(match[1], 10);
     return isNaN(major) ? undefined : major;
 }
-function detectPackageManager(lockfiles) {
+/**
+ * Markers each package manager leaves INSIDE `node_modules`. An installed tree is the strongest
+ * evidence there is — stronger than a lockfile, which may simply not be committed.
+ *
+ * Without this, a pnpm-installed project with no committed lockfile was read as npm, and `npm i -D`
+ * then died on pnpm's symlink layout with `Cannot read properties of null (reading 'matches')`. Worse,
+ * it left the package present in `node_modules` but absent from `package.json`, so every later run
+ * reported the same failure — a setup that could not be retried into working.
+ */
+const NODE_MODULES_MARKERS = [
+    ['.modules.yaml', PackageManager.PNPM],
+    ['.yarn-state.yml', PackageManager.YARN],
+    ['.package-lock.json', PackageManager.NPM],
+];
+/** Marker basenames present inside the project's `node_modules`, if it has one. */
+function packageManagerFromNodeModules(markers) {
+    for (const [name, pm] of NODE_MODULES_MARKERS)
+        if (markers.has(name))
+            return pm;
+    return undefined;
+}
+export function detectPackageManager(lockfiles, nodeModulesMarkers) {
     if (lockfiles.has('pnpm-lock.yaml'))
         return PackageManager.PNPM;
     if (lockfiles.has('yarn.lock'))
         return PackageManager.YARN;
     if (lockfiles.has('bun.lockb') || lockfiles.has('bun.lock'))
         return PackageManager.BUN;
-    return PackageManager.NPM;
+    // No lockfile is not the same as "npm". An already-installed tree says which manager built it.
+    return packageManagerFromNodeModules(nodeModulesMarkers) ?? PackageManager.NPM;
 }
 function detectFramework(input) {
     const { pkg, configFiles } = input;
@@ -52,18 +95,48 @@ function detectFramework(input) {
     if (depVersion(pkg, '@sveltejs/kit') !== undefined || hasAnyConfig(configFiles, SVELTE_CONFIGS)) {
         return Framework.SVELTEKIT;
     }
+    // Astro is Vite-based but SSRs its own HTML, so the plugin's index.html injection never fires and
+    // `vite` is not a direct dependency — it used to fall all the way through to HTML and be handed
+    // connect instructions for a bundler it does not have. Check BEFORE the generic Vite branch.
+    if (depVersion(pkg, 'astro') !== undefined || hasAnyConfig(configFiles, ASTRO_CONFIGS)) {
+        return Framework.ASTRO;
+    }
     if (depVersion(pkg, 'vite') !== undefined || hasAnyConfig(configFiles, VITE_CONFIGS)) {
         return Framework.VITE;
     }
+    // Checked after Vite, never before: a project migrating off CRA can carry both, and the Vite path
+    // is the one that works. CRA has no config file at all, so the dependency is the only signal.
+    if (depVersion(pkg, 'react-scripts') !== undefined)
+        return Framework.CRA;
     return Framework.HTML;
 }
+/**
+ * React first: a Preact app using preact/compat aliases React, and Next/Remix apps list both. The
+ * order is the precedence — whichever the app actually renders through is the one it depends on
+ * directly.
+ */
+function detectUiLibrary(pkg) {
+    if (depVersion(pkg, 'react') !== undefined)
+        return UiLibrary.REACT;
+    if (depVersion(pkg, 'preact') !== undefined)
+        return UiLibrary.PREACT;
+    if (depVersion(pkg, 'vue') !== undefined)
+        return UiLibrary.VUE;
+    if (depVersion(pkg, 'svelte') !== undefined)
+        return UiLibrary.SVELTE;
+    return UiLibrary.UNKNOWN;
+}
+const TS_CONFIGS = ['tsconfig.json'];
 export function detect(input) {
     const reactMajor = parseMajor(depVersion(input.pkg, 'react'));
     return {
         framework: detectFramework(input),
+        uiLibrary: detectUiLibrary(input.pkg),
+        typescript: hasAnyConfig(input.configFiles, TS_CONFIGS) ||
+            depVersion(input.pkg, 'typescript') !== undefined,
         reactMajor,
         needsSourceMapping: reactMajor !== undefined && reactMajor >= 19,
-        packageManager: detectPackageManager(input.lockfiles),
+        packageManager: detectPackageManager(input.lockfiles, input.nodeModulesMarkers ?? new Set()),
     };
 }
 const INSTALL_ARGS = {
@@ -74,7 +147,7 @@ const INSTALL_ARGS = {
 };
 /** Build a dev-dependency install command for one or more packages (e.g. the kit + its build plugin). */
 export function installCommandParts(pm, pkgs) {
-    const list = typeof pkgs === 'string' ? [pkgs] : pkgs;
+    const list = 'string' === typeof pkgs ? [pkgs] : pkgs;
     return { command: pm, args: [...INSTALL_ARGS[pm], ...list] };
 }
 export function installCommand(pm, pkgs) {

package/dist/init/mcp-registered.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Did `reticle init` actually register the MCP server?
+ *
+ * This was `!failed.has(MCP_TARGET)` — the negation of one narrow failure set — so a step that was
+ * SKIPPED (`--no-mcp`) or left MANUAL (the user has to run a command themselves) reported success,
+ * because neither is a failure. Under `--no-mcp` every run claimed registration.
+ *
+ * It is the onboarding funnel's most important field, and it was wrong in the flattering direction
+ * on exactly the runs least likely to have a working install.
+ */
+import { StepStatus } from './plan.js';
+export declare function wasMcpRegistered(status: StepStatus | undefined): boolean;

package/dist/init/mcp-registered.js

@@ -0,0 +1,14 @@
+/**
+ * Did `reticle init` actually register the MCP server?
+ *
+ * This was `!failed.has(MCP_TARGET)` — the negation of one narrow failure set — so a step that was
+ * SKIPPED (`--no-mcp`) or left MANUAL (the user has to run a command themselves) reported success,
+ * because neither is a failure. Under `--no-mcp` every run claimed registration.
+ *
+ * It is the onboarding funnel's most important field, and it was wrong in the flattering direction
+ * on exactly the runs least likely to have a working install.
+ */
+import { StepStatus } from './plan.js';
+export function wasMcpRegistered(status) {
+    return status === StepStatus.APPLY || status === StepStatus.ALREADY;
+}

package/dist/init/mcp.d.ts

@@ -12,9 +12,34 @@
  * global agent config.
  */
 export declare const MCP_SERVER_NAME = "reticle";
+/**
+ * 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.
+ */
 export declare const NPX = "npx";
-/** 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. */
+/**
+ * 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.
+ *
+ * DELIBERATELY UNPINNED, and the trade is worth stating. `reticle init` pins the SDK to the CLI's
+ * exact version, so on release day the app can be on the new one while npx serves a cached older
+ * build — a real skew, reported from the field. Pinning this entry would remove that window.
+ *
+ * It would also freeze the agent's MCP server at whatever version was installed the day `init` ran,
+ * for as long as that entry survives — and `reticle update` upgrades the CLI, not a global agent
+ * config. Reticle's biggest measured problem is fixes not reaching people (2.4.0 reached zero users
+ * before its nudge existed), and a permanent pin makes that worse for every install, to close a
+ * window that lasts until the next npx cache miss.
+ *
+ * So it stays unpinned, and the skew is handled where it actually shows up: the contract fingerprint
+ * makes a real mismatch loud on the next tool result (see version-skew), and a stale entry of our own
+ * shape is now repaired on re-run rather than reported "already registered" (see cursor.ts).
+ */
 export declare function npxServerArgs(): string[];
 interface ClaudeAddCommand {
     command: string;

package/dist/init/mcp.js

@@ -11,16 +11,41 @@
  * project's `.reticle.json` in its CWD (see cli-port.ts). The port belongs to the project, not the
  * global agent config.
  */
-import { RETICLE_NPM_PACKAGE } from '../server-version.js';
+import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
 export const MCP_SERVER_NAME = 'reticle';
+/**
+ * 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.
+ */
 export const NPX = 'npx';
 // The `reticle` bin lives in the server package, so `npx <pkg> mcp` runs the bridge without the
 // retired `core` umbrella. Sourced from the single derived identity so it can never drift.
 const RETICLE_PACKAGE = RETICLE_NPM_PACKAGE;
 const MCP_SUBCOMMAND = 'mcp';
 const CLAUDE_CLI = 'claude';
-/** 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. */
+/**
+ * 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.
+ *
+ * DELIBERATELY UNPINNED, and the trade is worth stating. `reticle init` pins the SDK to the CLI's
+ * exact version, so on release day the app can be on the new one while npx serves a cached older
+ * build — a real skew, reported from the field. Pinning this entry would remove that window.
+ *
+ * It would also freeze the agent's MCP server at whatever version was installed the day `init` ran,
+ * for as long as that entry survives — and `reticle update` upgrades the CLI, not a global agent
+ * config. Reticle's biggest measured problem is fixes not reaching people (2.4.0 reached zero users
+ * before its nudge existed), and a permanent pin makes that worse for every install, to close a
+ * window that lasts until the next npx cache miss.
+ *
+ * So it stays unpinned, and the skew is handled where it actually shows up: the contract fingerprint
+ * makes a real mismatch loud on the next tool result (see version-skew), and a stale entry of our own
+ * shape is now repaired on re-run rather than reported "already registered" (see cursor.ts).
+ */
 export function npxServerArgs() {
     return [RETICLE_PACKAGE, MCP_SUBCOMMAND];
 }
@@ -36,6 +61,11 @@ export function claudeAddCommand() {
 }
 /** Probe args that tell us whether an `reticle` server already exists in any scope (exit 0 = exists). */
 export function claudeExistsProbe() {
+    // NO `-s`: `claude mcp get` takes no options at all, so passing one exits 1 with "unknown option
+    // '-s'" — the probe answered "not registered" on EVERY machine, init then ran `claude mcp add`,
+    // which exits 1 with "already exists", and a re-run reported `[⚠] step failed` plus a manual
+    // command that fails the same way. A false positive from a project-scoped entry costs one skipped
+    // registration; the flag cost every re-run a failed step.
     return { command: CLAUDE_CLI, args: [MCP_SUBCOMMAND, 'get', MCP_SERVER_NAME] };
 }
 /** Probe args for whether the `claude` CLI is installed at all. */
@@ -51,5 +81,11 @@ export function mcpManual() {
 
 Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.cursor/mcp.json):
 
-  "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }`;
+  "${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)])} }`;
 }