@reticlehq/init 3.8.2 → 3.10.0

package/dist/plan/plan-types.d.ts

@@ -125,6 +125,12 @@ export interface PlanInput {
     claudeCli: boolean;
     /** Whether an `reticle` MCP server is already registered with Claude (any scope) — idempotency. */
     mcpExists: boolean;
+    /** The Reticle Claude Code plugin is installed, and it brings its own `reticle` server. */
+    claudePlugin?: boolean | undefined;
+    /** A user-scope `reticle` entry exists too. Next to the plugin, that is a duplicate. */
+    claudeUserEntry?: boolean | undefined;
+    /** The user-scope `reticle` entry is the floating npx form. Reported, never replaced. */
+    claudeUserEntryFloating?: boolean | undefined;
     /**
      * Whether `init` is running inside Claude Code itself, which is the one case where writing its
      * project-scope `.mcp.json` is known to be wanted. See `CLAUDE_PROJECT_SPEC`.
@@ -372,6 +378,8 @@ export interface PlanInput {
     promptHooks?: readonly PromptHookTarget[] | undefined;
     /** See `InitHost.hookBin`. */
     hookBin?: string | undefined;
+    /** See `InitHost.mcpLauncher`. Absent: the MCP registration uses the pinned npx command. */
+    mcpLauncher?: string | undefined;
     /**
      * Absolute directory the AGENT runs in, when that is not the app's directory.
      *

package/dist/plan/plan-vite.js

@@ -7,7 +7,7 @@
  * Start, the Electron renderers) composes these steps, while the rest of `plan-framework.ts` is one
  * builder per framework that has its own files to write.
  */
-import { newViteConfig, patchViteConfig, VitePatchKind, VITE_IMPORT } from '../patch/vite-config.js';
+import { DefineConfigSource, newViteConfig, patchViteConfig, VitePatchKind, VITE_IMPORT, } from '../patch/vite-config.js';
 import { viteManual, viteDevModuleFile, VITE_DEV_MODULE_PATH } from '../patch/snippets.js';
 import { hasOptOut, OPT_OUT_MARKER } from '../detect/declared/init-opt-out.js';
 import { Framework } from '../detect/detect.js';
@@ -228,7 +228,9 @@ function viteConfigSteps(input, detail, inject = true) {
                 detail,
                 write: {
                     path,
-                    content: newViteConfig(port, true === input.captureBodies, inject, stampSource),
+                    content: newViteConfig(port, true === input.captureBodies, inject, stampSource, undefined === input.detection.dependencies?.[DefineConfigSource.VITE_PLUS]
+                        ? DefineConfigSource.VITE
+                        : DefineConfigSource.VITE_PLUS),
                     expect: [VITE_IMPORT, 'reticle('],
                 },
                 dependsOnInstall: true,

package/dist/plan/plan.js

@@ -3,7 +3,7 @@
  * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
-import { claudeAddCommand, claudeProjectMcpJson, codexAddCommand, mcpManual, } from '../register/mcp.js';
+import { claudeAddCommand, claudeProjectMcpJson, claudeRemoveUserCommand, claudeStaleEntryNote, codexAddCommand, mcpManual, } from '../register/mcp.js';
 import { codexNamesOurServer } from '../register/codex-toml.js';
 import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, CLAUDE_PROJECT_CONFIG, CLAUDE_PROJECT_SPEC, McpClient, } from '../register/mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from '../register/slash-command.js';
@@ -39,7 +39,47 @@ function agentFile(input, relPath) {
     return root === undefined || 0 === root.length ? relPath : join(root, relPath);
 }
 const CLAUDE_MCP_TITLE = 'MCP server (Claude, global)';
+/**
+ * The Reticle plugin brings its own `reticle` server. A user-scope entry next to it gives Claude
+ * Code two servers with the same tools, so none is added. An old one is named, not removed.
+ */
+function claudePluginStep(input) {
+    if (true === input.claudeUserEntry) {
+        return {
+            title: CLAUDE_MCP_TITLE,
+            target: MCP_TARGET,
+            status: StepStatus.MANUAL,
+            detail: `the Reticle plugin is active and a user-scope reticle server is registered too, so Claude Code has two. Remove the user-scope one: ${claudeRemoveUserCommand()}`,
+        };
+    }
+    return {
+        title: CLAUDE_MCP_TITLE,
+        target: MCP_TARGET,
+        status: StepStatus.ALREADY,
+        detail: 'the Reticle plugin is active and gives Claude Code its server; no user-scope entry added',
+    };
+}
+/**
+ * The floating npx entry, kept and named. A NOTICE after the Claude Code step, so the step that
+ * decides the closing hint still reads ALREADY.
+ */
+function claudeFloatingSteps(input) {
+    if (true !== input.claudeUserEntryFloating) {
+        return [];
+    }
+    return [
+        {
+            title: 'Old MCP entry (Claude, global)',
+            target: MCP_TARGET,
+            status: StepStatus.NOTICE,
+            detail: claudeStaleEntryNote(input.mcpLauncher),
+        },
+    ];
+}
 function claudeMcpStep(input) {
+    if (true === input.claudePlugin) {
+        return claudePluginStep(input);
+    }
     if (!input.claudeCli) {
         return null;
     }
@@ -51,7 +91,7 @@ function claudeMcpStep(input) {
             detail: 'reticle already registered (install once, used by every project)',
         };
     }
-    const cmd = claudeAddCommand();
+    const cmd = claudeAddCommand(input.mcpLauncher);
     return {
         title: CLAUDE_MCP_TITLE,
         target: MCP_TARGET,
@@ -71,7 +111,7 @@ function otherClientSteps(input) {
     return (input.detectedClients ?? []).map((detected) => {
         const spec = clientSpec(detected.id);
         return (codexCliStep(spec, detected.configPath, detected.existing, input) ??
-            clientStep(spec, detected.configPath, detected.existing));
+            clientStep(spec, detected.configPath, detected.existing, input.mcpLauncher));
     });
 }
 /**
@@ -90,7 +130,7 @@ function codexCliStep(spec, configPath, existing, input) {
     if (codexNamesOurServer(existing, spec.serversKey)) {
         return null;
     }
-    const cmd = codexAddCommand();
+    const cmd = codexAddCommand(input.mcpLauncher);
     return {
         title: `MCP server (${spec.label})`,
         target: configPath,
@@ -100,8 +140,8 @@ function codexCliStep(spec, configPath, existing, input) {
     };
 }
 /** One client's step: already-correct is left alone, an unparseable file gets a paste-able block. */
-function clientStep(spec, configPath, existing) {
-    const merged = mergeClientConfig(spec, existing);
+function clientStep(spec, configPath, existing, launcher) {
+    const merged = mergeClientConfig(spec, existing, launcher);
     const title = `MCP server (${spec.label})`;
     if (merged.status === ClientMergeStatus.ALREADY) {
         return {
@@ -118,7 +158,7 @@ function clientStep(spec, configPath, existing) {
             title,
             target: configPath,
             status: StepStatus.MANUAL,
-            detail: `add this to ${configPath} by hand:\n${clientSnippet(spec)}`,
+            detail: `add this to ${configPath} by hand:\n${clientSnippet(spec, launcher)}`,
         };
     }
     return {
@@ -136,11 +176,11 @@ function clientStep(spec, configPath, existing) {
  * they get the notice instead.
  */
 function claudeProjectStep(input) {
-    if (input.claudeCli || true !== input.insideClaudeCode) {
+    if (input.claudeCli || true !== input.insideClaudeCode || true === input.claudePlugin) {
         return null;
     }
     const path = agentFile(input, CLAUDE_PROJECT_CONFIG);
-    return clientStep(CLAUDE_PROJECT_SPEC, path, input.claudeProjectConfig ?? null);
+    return clientStep(CLAUDE_PROJECT_SPEC, path, input.claudeProjectConfig ?? null, input.mcpLauncher);
 }
 /** One global registration per detected agent (Claude + Cursor). Falls back to a manual note. */
 function mcpSteps(input) {
@@ -163,6 +203,7 @@ function mcpSteps(input) {
     const claudeProject = claudeProjectStep(input);
     const steps = [
         ...stepsForAgents(input, (a) => a.mcpStep),
+        ...claudeFloatingSteps(input),
         ...(null === claudeProject ? [] : [claudeProject]),
         ...otherClientSteps(input),
     ];
@@ -173,7 +214,7 @@ function mcpSteps(input) {
                 title: 'MCP server (global)',
                 target: MCP_TARGET,
                 status: StepStatus.MANUAL,
-                detail: mcpManual(),
+                detail: mcpManual(input.mcpLauncher),
             },
         ];
     }
@@ -191,7 +232,10 @@ function mcpSteps(input) {
      * to register, so nothing has silently vanished — and leaving that path untouched keeps every
      * pristine scaffold in the install baseline reading exactly as it did.
      */
-    if (!input.claudeCli && null === claudeProject && steps.length > 0) {
+    if (!input.claudeCli &&
+        true !== input.claudePlugin &&
+        null === claudeProject &&
+        steps.length > 0) {
         steps.push({
             title: CLAUDE_MCP_TITLE,
             target: MCP_TARGET,
@@ -200,7 +244,7 @@ function mcpSteps(input) {
             // which would turn an informational line into a gate failure on any machine that happens to
             // have another agent's config. A notice prints in full exactly like a manual step.
             status: StepStatus.NOTICE,
-            detail: `no \`claude\` on PATH, so it could not be registered from here. Inside a Claude Code VS Code extension session the CLI is genuinely absent while the editor is not — add ${claudeProjectMcpJson()}`,
+            detail: `no \`claude\` on PATH, so it could not be registered from here. Inside a Claude Code VS Code extension session the CLI is genuinely absent while the editor is not — add ${claudeProjectMcpJson(input.mcpLauncher)}`,
         });
     }
     const windowsNote = windowsMcpNoteStep(input);

package/dist/register/mcp-clients.d.ts

@@ -32,8 +32,8 @@ export interface ClientSpec {
     format: ConfigFormat;
     /** The object key holding the server map — `mcpServers`, `servers`, or `mcp`. */
     serversKey: string;
-    /** Our entry, in THIS client's shape. */
-    entry: () => unknown;
+    /** Our entry, in THIS client's shape. `launcher`: see `serverInvocation`. */
+    entry: (launcher?: string) => unknown;
     /** Where the shape came from, so the next person can re-check it rather than trust this file. */
     docs: string;
 }
@@ -74,14 +74,14 @@ interface ClientMergeResult {
  * already has the table is a warning they must not act on, and the setup contract makes a `⚠`
  * blocking (#681). Detection is read-only and cannot corrupt anything.
  */
-export declare function mergeClientConfig(spec: ClientSpec, existing: string | null): ClientMergeResult;
+export declare function mergeClientConfig(spec: ClientSpec, existing: string | null, launcher?: string): ClientMergeResult;
 /**
  * A block the user can paste, for a client we could not write.
  *
  * Every client gets one, including the ones we CAN write: when a merge comes back MANUAL because the
  * file could not be parsed, the snippet is the only actionable thing left to give.
  */
-export declare function clientSnippet(spec: ClientSpec): string;
+export declare function clientSnippet(spec: ClientSpec, launcher?: string): string;
 /**
  * The path whose existence means "this user has this client".
  *

package/dist/register/mcp-clients.js

@@ -18,7 +18,7 @@
  * an install that reports success and registers nothing, which is the exact failure class this
  * repo's install gate exists to catch.
  */
-import { NPX, MCP_SERVER_NAME, npxServerArgs, isReticleRegistration } from './mcp.js';
+import { MCP_SERVER_NAME, isReticleRegistration, serverInvocation } from './mcp.js';
 import { codexServerTokens } from './codex-toml.js';
 export const McpClient = {
     CLAUDE_CODE: 'claude-code',
@@ -43,15 +43,16 @@ export const ConfigFormat = {
     CLI: 'cli',
 };
 /** The `{ command, args }` entry Cursor, Windsurf, Gemini and VS Code all take. */
-function commandArgsEntry() {
-    return { command: NPX, args: npxServerArgs() };
+function commandArgsEntry(launcher) {
+    const [command, ...args] = serverInvocation(launcher);
+    return { command, args };
 }
 /**
  * OpenCode's entry. `command` is a single ARRAY containing the executable and its arguments, and
  * `enabled` is explicit — a server registered but disabled is the quietest possible failure.
  */
-function openCodeEntry() {
-    return { type: 'local', command: [NPX, ...npxServerArgs()], enabled: true };
+function openCodeEntry(launcher) {
+    return { type: 'local', command: serverInvocation(launcher), enabled: true };
 }
 /**
  * Claude Code's project-scope MCP config, which needs no CLI on PATH.
@@ -189,8 +190,9 @@ export const MCP_CLIENTS = [
 ];
 export function clientSpec(id) {
     const found = MCP_CLIENTS.find((spec) => spec.id === id);
-    if (found === undefined)
+    if (found === undefined) {
         throw new Error(`no MCP client spec for '${id}'`);
+    }
     return found;
 }
 export const ClientMergeStatus = {
@@ -199,15 +201,17 @@ export const ClientMergeStatus = {
     MANUAL: 'manual',
 };
 function parseConfig(existing) {
-    if (null === existing || 0 === existing.trim().length)
+    if (null === existing || 0 === existing.trim().length) {
         return { ok: true, config: {} };
+    }
     try {
         const parsed = JSON.parse(existing);
         // Valid JSON that is not a PLAIN OBJECT — `[]`, `3`, `"x"`, `null` — must not fall through to an
         // empty config, because the file then gets rewritten wholesale. Unparseable JSON was always
         // handled conservatively; this adjacent case destroyed the file instead.
-        if (typeof parsed !== 'object' || null === parsed || Array.isArray(parsed))
+        if (typeof parsed !== 'object' || null === parsed || Array.isArray(parsed)) {
             return { ok: false };
+        }
         return { ok: true, config: parsed };
     }
     catch {
@@ -228,11 +232,13 @@ function parseConfig(existing) {
  * not repair the thing an upgrade exists to repair — and a WRONG one, naming a Reticle package that
  * has no MCP server in it (see isReticleRegistration).
  */
-function leaveEntryAlone(existing, spec) {
-    if (JSON.stringify(existing) === JSON.stringify(spec.entry()))
+function leaveEntryAlone(existing, spec, launcher) {
+    if (JSON.stringify(existing) === JSON.stringify(spec.entry(launcher))) {
         return true;
-    if (typeof existing !== 'object' || null === existing)
+    }
+    if (typeof existing !== 'object' || null === existing) {
         return true;
+    }
     const record = existing;
     // Both shapes carry the package name somewhere in a string; find it without assuming which field.
     const tokens = [record.command, record.args].flat().filter((v) => 'string' === typeof v);
@@ -246,14 +252,23 @@ function leaveEntryAlone(existing, spec) {
  * drifted from what we would write, and when the shape was not one the scanner reads — every one of
  * those keeps today's MANUAL answer, and the snippet is then the actionable thing to print.
  */
-function tomlEntryIsSettled(spec, existing) {
+/** `@reticlehq/server@3.8.2` → `@reticlehq/server`. Every other string is returned as it is. */
+const unpinned = (token) => token.replace(/^(@reticlehq\/server)@.*$/, '$1');
+function tomlEntryIsSettled(spec, existing, launcher) {
     const tokens = codexServerTokens(existing, spec.serversKey);
-    if (0 === tokens.length)
+    if (0 === tokens.length) {
         return false;
-    const expected = [NPX, ...npxServerArgs()];
+    }
     // Same strings, and no others: an entry carrying an extra flag is not the one we would write.
-    if (tokens.length === expected.length && expected.every((t) => tokens.includes(t)))
+    const same = (a, b) => a.length === b.length && b.every((t) => a.includes(t));
+    if (same(tokens, serverInvocation(launcher))) {
         return true;
+    }
+    // An npx entry of an older version still starts Reticle. TOML is never written by us, so asking
+    // for a hand edit at each release is a warning with no defect behind it.
+    if (same(tokens.map(unpinned), serverInvocation().map(unpinned))) {
+        return true;
+    }
     // Not ours to touch. Somebody pointing `reticle` at their own local build made a deliberate
     // choice, and telling them to hand-edit it back is the same wrong answer as overwriting it.
     return !isReticleRegistration(tokens);
@@ -269,29 +284,30 @@ function tomlEntryIsSettled(spec, existing) {
  * already has the table is a warning they must not act on, and the setup contract makes a `⚠`
  * blocking (#681). Detection is read-only and cannot corrupt anything.
  */
-export function mergeClientConfig(spec, existing) {
+export function mergeClientConfig(spec, existing, launcher) {
     if (spec.format !== ConfigFormat.JSON) {
-        if (ConfigFormat.TOML === spec.format && tomlEntryIsSettled(spec, existing)) {
+        if (ConfigFormat.TOML === spec.format && tomlEntryIsSettled(spec, existing, launcher)) {
             return { status: ClientMergeStatus.ALREADY, content: existing ?? '' };
         }
         return { status: ClientMergeStatus.MANUAL, content: existing ?? '' };
     }
     const parsed = parseConfig(existing);
-    if (!parsed.ok)
+    if (!parsed.ok) {
         return { status: ClientMergeStatus.MANUAL, content: existing ?? '' };
+    }
     const config = parsed.config;
     const current = config[spec.serversKey];
     const servers = 'object' === typeof current && null !== current && !Array.isArray(current)
         ? current
         : {};
     if (Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME) &&
-        leaveEntryAlone(servers[MCP_SERVER_NAME], spec)) {
+        leaveEntryAlone(servers[MCP_SERVER_NAME], spec, launcher)) {
         return { status: ClientMergeStatus.ALREADY, content: existing ?? '' };
     }
     // Only OUR key is replaced; every other server and top-level key is carried through untouched.
     const merged = {
         ...config,
-        [spec.serversKey]: { ...servers, [MCP_SERVER_NAME]: spec.entry() },
+        [spec.serversKey]: { ...servers, [MCP_SERVER_NAME]: spec.entry(launcher) },
     };
     return { status: ClientMergeStatus.APPLY, content: `${JSON.stringify(merged, null, 2)}\n` };
 }
@@ -301,17 +317,17 @@ export function mergeClientConfig(spec, existing) {
  * Every client gets one, including the ones we CAN write: when a merge comes back MANUAL because the
  * file could not be parsed, the snippet is the only actionable thing left to give.
  */
-export function clientSnippet(spec) {
+export function clientSnippet(spec, launcher) {
+    const [command, ...rest] = serverInvocation(launcher);
     if (spec.format === ConfigFormat.TOML) {
-        const args = npxServerArgs()
-            .map((a) => `"${a}"`)
-            .join(', ');
-        return `[mcp_servers.${MCP_SERVER_NAME}]\ncommand = "${NPX}"\nargs = [${args}]\n`;
+        // JSON string escapes are valid TOML basic-string escapes, so a Windows path stays valid.
+        const args = rest.map((a) => JSON.stringify(a)).join(', ');
+        return `[mcp_servers.${MCP_SERVER_NAME}]\ncommand = ${JSON.stringify(command)}\nargs = [${args}]\n`;
     }
     if (spec.format === ConfigFormat.CLI) {
-        return `claude mcp add -s user ${MCP_SERVER_NAME} -- ${NPX} ${npxServerArgs().join(' ')}\n`;
+        return `claude mcp add -s user ${MCP_SERVER_NAME} -- ${[command, ...rest].join(' ')}\n`;
     }
-    return `${JSON.stringify({ [spec.serversKey]: { [MCP_SERVER_NAME]: spec.entry() } }, null, 2)}\n`;
+    return `${JSON.stringify({ [spec.serversKey]: { [MCP_SERVER_NAME]: spec.entry(launcher) } }, null, 2)}\n`;
 }
 /**
  * The path whose existence means "this user has this client".
@@ -326,11 +342,13 @@ export function clientSnippet(spec) {
  * because a fresh Cursor profile has not written `~/.cursor` yet.
  */
 export function clientMarkerRelPath(spec) {
-    if (spec.scope === ConfigScope.CLI)
+    if (spec.scope === ConfigScope.CLI) {
         return '';
+    }
     // Antigravity also creates ~/.gemini. The shared parent is not evidence of Gemini CLI.
-    if (spec.id === McpClient.GEMINI)
+    if (spec.id === McpClient.GEMINI) {
         return spec.relPath;
+    }
     const parts = spec.relPath.split('/');
     return parts.length > 1 ? parts.slice(0, -1).join('/') : spec.relPath;
 }

package/dist/register/mcp.d.ts

@@ -5,7 +5,7 @@
  * hand-editing `~/.claude.json` (a large stateful file). When the `claude` CLI is absent we print a
  * manual instruction instead.
  *
- * The registration is intentionally PORTLESS — `npx @reticlehq/server mcp`, never `--port N`. A single
+ * The registration is intentionally PORTLESS — it never carries `--port N`. A single
  * global entry serves every project, so baking a port into it would pin every project to one port
  * and defeat per-project isolation. Instead `reticle mcp` resolves the port at runtime from the
  * project's `.reticle.json` in its CWD (see cli-port.ts). The port belongs to the project, not the
@@ -26,23 +26,26 @@ export { MCP_SERVER_NAME } from '@reticlehq/core';
  */
 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@<this version> 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. A permanent pin trades a window that lasts until the next npx cache miss for one that
- * lasts forever.
- *
- * 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 mcp-clients.ts).
+ * PINNED to one exact version. With a floating `@reticlehq/server`, npx asks the registry on every
+ * start. A fresh sandbox (an empty npm cache) downloaded about 131 MB before the MCP server
+ * answered: 3.9 s to 5.6 s on each boot, against 0.6 s warm. With an exact version, an image that
+ * ran it once uses its cache again. A re-run of `init` or `reticle setup mcp` writes the new
+ * version into a stale entry of our own shape (see mcp-clients.ts), and the contract fingerprint
+ * makes a real mismatch loud on the next tool result (see version-skew).
  */
 export declare function npxServerArgs(): string[];
+/** Is this string the bin of an installed `@reticlehq/server`? */
+export declare function isReticleLauncher(token: string): boolean;
+/**
+ * The bin to register, when the CLI that runs now is an install that stays on disk: a global
+ * install, or one in a project's `node_modules`. `undefined` for a run-once copy and for a source
+ * checkout. Registration then uses the pinned npx command.
+ */
+export declare function installedLauncher(bin: string | undefined): string | undefined;
 /**
  * Is this existing registration one WE are responsible for?
  *
@@ -58,6 +61,11 @@ export declare function npxServerArgs(): string[];
  * @param tokens every string in the entry's command + args, in any of the client shapes.
  */
 export declare function isReticleRegistration(tokens: readonly string[]): boolean;
+/**
+ * The command that starts the MCP server: `node <launcher> mcp` for an installed copy, else the
+ * pinned npx command. `node` is a real executable on Windows too, so it needs no `cmd /c`.
+ */
+export declare function serverInvocation(launcher?: string): string[];
 interface CliAddCommand {
     command: string;
     args: string[];
@@ -65,7 +73,7 @@ interface CliAddCommand {
     display: string;
 }
 /** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
-export declare function claudeAddCommand(): CliAddCommand;
+export declare function claudeAddCommand(launcher?: string): CliAddCommand;
 /**
  * Is a `reticle` server already registered with Claude Code, in any scope this project sees?
  *
@@ -84,6 +92,33 @@ export declare function claudeHasReticle(io: {
     readFile(path: string): string | null;
     homeDir(): string;
 }, projectDir: string | undefined, configDir?: string | undefined): boolean;
+/** The `reticle` entries Claude Code has, in the scopes `claudeHasReticle` reads. */
+export declare function claudeReticleEntries(io: {
+    readFile(path: string): string | null;
+    homeDir(): string;
+}, projectDir: string | undefined, configDir?: string | undefined): unknown[];
+/**
+ * Is the Reticle Claude Code plugin installed? The plugin brings its own `reticle` MCP server, so a
+ * `claude mcp add` next to it gives Claude Code two servers with the same tools. An unreadable
+ * record reads as "not installed".
+ */
+export declare function claudePluginInstalled(io: {
+    readFile(path: string): string | null;
+    homeDir(): string;
+}, configDir?: string | undefined): boolean;
+/** The one command that removes a user-scope `reticle` entry left next to the plugin. */
+export declare function claudeRemoveUserCommand(): string;
+/**
+ * Claude Code's user-scope `reticle` entry is the floating npx form that registration wrote before
+ * it pinned a version or used the installed launcher. `claudeHasReticle` reads it as registered, so
+ * nothing replaced it. Reported only: a Claude Code entry is changed only by the person.
+ */
+export declare function claudeUserEntryIsFloating(io: {
+    readFile(path: string): string | null;
+    homeDir(): string;
+}, configDir?: string | undefined): boolean;
+/** The one sentence about a floating entry, and the commands that replace it. */
+export declare function claudeStaleEntryNote(launcher?: string): string;
 /** Probe args for whether the `claude` CLI is installed at all. */
 export declare function claudeAvailableProbe(): {
     command: string;
@@ -96,7 +131,7 @@ export declare function claudeAvailableProbe(): {
  * It REPLACES an existing entry of the same name and still exits 0, so callers run it only when the
  * config names no `reticle` server at all (see `codexNamesOurServer`).
  */
-export declare function codexAddCommand(): CliAddCommand;
+export declare function codexAddCommand(launcher?: string): CliAddCommand;
 /** Probe args for whether the `codex` CLI is installed at all. */
 export declare function codexAvailableProbe(): {
     command: string;
@@ -116,5 +151,5 @@ export declare function mcpWindowsNote(): string;
  * session the `claude` binary is not on PATH, so every CLI-based route is shut and `.mcp.json` in
  * the project root is the one that still works.
  */
-export declare function claudeProjectMcpJson(): string;
-export declare function mcpManual(): string;
+export declare function claudeProjectMcpJson(launcher?: string): string;
+export declare function mcpManual(launcher?: string): string;