@reticlehq/init 2.14.0

package/dist/mcp-clients.d.ts

@@ -0,0 +1,94 @@
+export declare const McpClient: {
+    readonly CLAUDE_CODE: "claude-code";
+    readonly CURSOR: "cursor";
+    readonly WINDSURF: "windsurf";
+    readonly OPENCODE: "opencode";
+    readonly ANTIGRAVITY: "antigravity";
+    readonly CODEX: "codex";
+    readonly GEMINI: "gemini";
+    readonly VSCODE: "vscode";
+};
+export type McpClient = (typeof McpClient)[keyof typeof McpClient];
+/** Where the config lives. `cli` means the client owns registration and we shell out to it. */
+export declare const ConfigScope: {
+    readonly HOME: "home";
+    readonly PROJECT: "project";
+    readonly CLI: "cli";
+};
+export type ConfigScope = (typeof ConfigScope)[keyof typeof ConfigScope];
+/** How the file is written. `toml` is deliberately never auto-merged — see mergeClientConfig. */
+export declare const ConfigFormat: {
+    readonly JSON: "json";
+    readonly TOML: "toml";
+    readonly CLI: "cli";
+};
+export type ConfigFormat = (typeof ConfigFormat)[keyof typeof ConfigFormat];
+export interface ClientSpec {
+    id: McpClient;
+    label: string;
+    scope: ConfigScope;
+    /** Relative to `$HOME` for `home`, to the project root for `project`. Empty for `cli`. */
+    relPath: string;
+    format: ConfigFormat;
+    /** The object key holding the server map — `mcpServers`, `servers`, or `mcp`. */
+    serversKey: string;
+    /** Our entry, in THIS client's shape. */
+    entry: () => unknown;
+    /** Where the shape came from, so the next person can re-check it rather than trust this file. */
+    docs: string;
+}
+export declare const MCP_CLIENTS: readonly ClientSpec[];
+export declare function clientSpec(id: McpClient): ClientSpec;
+export declare const ClientMergeStatus: {
+    readonly APPLY: "apply";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+};
+export type ClientMergeStatus = (typeof ClientMergeStatus)[keyof typeof ClientMergeStatus];
+interface ClientMergeResult {
+    status: ClientMergeStatus;
+    /** Full file content to write. Byte-identical to `existing` when not `apply`. */
+    content: string;
+}
+/**
+ * Merge our server into this client's config.
+ *
+ * TOML is never auto-merged. Editing TOML without a parser is how a config file gets corrupted, and
+ * a corrupted `~/.codex/config.toml` costs the user every server they had, not just ours. Printing
+ * the exact block is honest; writing a guess is not — so Codex returns MANUAL with a snippet.
+ *
+ * Not writing it is no reason not to READ it, though. Reporting `add this by hand` to somebody who
+ * 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;
+/**
+ * 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;
+/**
+ * The path whose existence means "this user has this client".
+ *
+ * Detection is deliberately conservative and one-directional: we write into a config a client
+ * ALREADY has, and never create `~/.gemini/` or `~/.codeium/` for somebody who does not use them.
+ * Littering a home directory to register a server nobody asked for is worse than printing a snippet.
+ *
+ * For a `home` client this is the directory above its config; for a `project` client it is the
+ * config file (or its directory) inside the repo, which is unambiguous evidence somebody uses it
+ * here. Same reasoning as Cursor's existing rule, which also accepts a project-level `.cursor/`
+ * because a fresh Cursor profile has not written `~/.cursor` yet.
+ */
+export declare function clientMarkerRelPath(spec: ClientSpec): string;
+/**
+ * Project-relative directory whose presence signals Cursor is in use for this repo.
+ *
+ * A fresh Cursor profile has not written `~/.cursor` yet, so the home marker alone misses real
+ * users. A project-level `.cursor/` is unambiguous evidence somebody uses Cursor here.
+ */
+export declare const CURSOR_PROJECT_MARKER = ".cursor";
+/** Clients `init` can wire by writing a file — everything but the CLI-registered one. */
+export declare function fileBackedClients(): readonly ClientSpec[];
+export {};

package/dist/mcp-clients.js

@@ -0,0 +1,327 @@
+/**
+ * Where each agent keeps its MCP config, and how to write ours into it.
+ *
+ * `init` knew two clients: Claude Code (a CLI shell-out) and Cursor (a JSON merge). Everything else
+ * got a printed snippet. That is the blocker under the whole release matrix — a per-client release
+ * artifact for a client `init` cannot wire measures whether somebody pasted JSON correctly, not
+ * whether the product works.
+ *
+ * Every path and shape below was read from the client's own documentation rather than recalled,
+ * because they differ in ways that look like they should not:
+ *
+ *   Cursor / Windsurf / Gemini   `mcpServers: { name: { command, args } }` — one shape, three paths
+ *   VS Code                      `servers:` — a different key entirely
+ *   OpenCode                     `mcp: { name: { type, command: [cmd, ...args] } }` — an ARRAY
+ *   Codex                        TOML
+ *
+ * A single "write mcp.json" assuming the Cursor shape would produce a file three of these ignore:
+ * 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 { codexServerTokens } from './codex-toml.js';
+export const McpClient = {
+    CLAUDE_CODE: 'claude-code',
+    CURSOR: 'cursor',
+    WINDSURF: 'windsurf',
+    OPENCODE: 'opencode',
+    ANTIGRAVITY: 'antigravity',
+    CODEX: 'codex',
+    GEMINI: 'gemini',
+    VSCODE: 'vscode',
+};
+/** Where the config lives. `cli` means the client owns registration and we shell out to it. */
+export const ConfigScope = {
+    HOME: 'home',
+    PROJECT: 'project',
+    CLI: 'cli',
+};
+/** How the file is written. `toml` is deliberately never auto-merged — see mergeClientConfig. */
+export const ConfigFormat = {
+    JSON: 'json',
+    TOML: 'toml',
+    CLI: 'cli',
+};
+/** The `{ command, args }` entry Cursor, Windsurf, Gemini and VS Code all take. */
+function commandArgsEntry() {
+    return { command: NPX, args: npxServerArgs() };
+}
+/**
+ * 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 };
+}
+export const MCP_CLIENTS = [
+    {
+        id: McpClient.CLAUDE_CODE,
+        label: 'Claude Code',
+        scope: ConfigScope.CLI,
+        relPath: '',
+        format: ConfigFormat.CLI,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'registered via `claude mcp add -s user` — see init/mcp.ts',
+    },
+    {
+        id: McpClient.CURSOR,
+        label: 'Cursor',
+        scope: ConfigScope.HOME,
+        relPath: '.cursor/mcp.json',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'https://docs.cursor.com — global ~/.cursor/mcp.json, or ./.cursor/mcp.json per project',
+    },
+    {
+        id: McpClient.WINDSURF,
+        label: 'Windsurf',
+        scope: ConfigScope.HOME,
+        relPath: '.codeium/windsurf/mcp_config.json',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'Windsurf docs — ~/.codeium/windsurf/mcp_config.json (same shape as Cursor, different path)',
+    },
+    {
+        id: McpClient.GEMINI,
+        label: 'Gemini CLI',
+        scope: ConfigScope.HOME,
+        relPath: '.gemini/settings.json',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html',
+    },
+    {
+        id: McpClient.VSCODE,
+        label: 'VS Code (Copilot)',
+        scope: ConfigScope.PROJECT,
+        relPath: '.vscode/mcp.json',
+        format: ConfigFormat.JSON,
+        // NOT `mcpServers`. Writing that key here registers nothing and reports success.
+        serversKey: 'servers',
+        entry: commandArgsEntry,
+        docs: 'VS Code MCP docs — .vscode/mcp.json, key is `servers`',
+    },
+    {
+        id: McpClient.OPENCODE,
+        label: 'OpenCode',
+        /**
+         * HOME, not PROJECT — OpenCode is installed globally and configured globally, like Cursor.
+         *
+         * It was project-scoped as `opencode.json`, and registration is gated on the marker already
+         * existing, so a project that had never written one was skipped in SILENCE: the user has OpenCode
+         * installed, `init` says nothing about it, and the tools never appear. In the field every OpenCode
+         * user connected a client and produced zero tool calls and zero app connections, which is what
+         * "you were never wired" looks like from outside.
+         *
+         * Path verified against a real install (OpenCode 1.3.17), not recalled. The extension is `.jsonc`,
+         * which the old project marker could not have matched even where a project config existed. JSONC
+         * permits comments, and a config that genuinely has them fails to parse — which `mergeClientConfig`
+         * already answers with MANUAL and a printed block, rather than rewriting somebody's file and
+         * dropping their comments.
+         */
+        scope: ConfigScope.HOME,
+        relPath: '.config/opencode/opencode.jsonc',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcp',
+        entry: openCodeEntry,
+        docs: 'https://opencode.ai/docs/config — `mcp` key, type:"local", command is an array',
+    },
+    {
+        id: McpClient.ANTIGRAVITY,
+        label: 'Antigravity',
+        /**
+         * Nine users connected an MCP client through Antigravity and drove nothing at all.
+         *
+         * `init` did not know this client, so they hand-wired a registration - the connections are in the
+         * field data, so they got that far - and then never ran `init`, never instrumented an app, and
+         * never called a tool. Nothing in that state tells anyone there is a second half.
+         *
+         * Path and shape from Google's documentation rather than recall: `mcpServers`, at
+         * `~/.gemini/config/mcp_config.json`, and one file serves the 2.0 IDE, the CLI and the SDK. Same
+         * `command`/`args` object Cursor, Windsurf and Gemini CLI already use.
+         *
+         * It shares the `~/.gemini` tree with Gemini CLI, which is why the marker matters: registration is
+         * gated on the marker DIRECTORY, and these resolve to `.gemini/config` and `.gemini` respectively,
+         * so having one installed cannot make `init` write a config for the other.
+         *
+         * NOT verified against a running install. The path is documented, the merge is the shared JSON
+         * path that every other client here uses, and an unparseable config still degrades to a printed
+         * block rather than a rewrite.
+         */
+        scope: ConfigScope.HOME,
+        relPath: '.gemini/config/mcp_config.json',
+        format: ConfigFormat.JSON,
+        serversKey: 'mcpServers',
+        entry: commandArgsEntry,
+        docs: 'https://antigravity.google/docs/mcp — ~/.gemini/config/mcp_config.json, `mcpServers` key',
+    },
+    {
+        id: McpClient.CODEX,
+        label: 'Codex CLI',
+        scope: ConfigScope.HOME,
+        relPath: '.codex/config.toml',
+        format: ConfigFormat.TOML,
+        serversKey: 'mcp_servers',
+        entry: commandArgsEntry,
+        docs: 'https://developers.openai.com/codex/mcp — ~/.codex/config.toml, [mcp_servers.<name>]',
+    },
+];
+export function clientSpec(id) {
+    const found = MCP_CLIENTS.find((spec) => spec.id === id);
+    if (found === undefined)
+        throw new Error(`no MCP client spec for '${id}'`);
+    return found;
+}
+export const ClientMergeStatus = {
+    APPLY: 'apply',
+    ALREADY: 'already',
+    MANUAL: 'manual',
+};
+function parseConfig(existing) {
+    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))
+            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 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 made a
+ *     deliberate choice, and replacing it with the published npx command breaks a setup to fix a
+ *     problem they do not have.
+ *
+ * What IS repaired is a stale entry of our own shape — an old pin, a moved command — which
+ * presence-only idempotency reported as "already registered" and never fixed, so an upgrade could
+ * 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()))
+        return true;
+    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);
+    return !isReticleRegistration(tokens);
+}
+/**
+ * Is this TOML config's existing entry one we should leave exactly as it is?
+ *
+ * The TOML half of {@link leaveEntryAlone}, over the strings the config declares rather than a
+ * parsed object. `false` when the table is absent, when it is a Reticle registration that has
+ * 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) {
+    const tokens = codexServerTokens(existing, spec.serversKey);
+    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)))
+        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);
+}
+/**
+ * Merge our server into this client's config.
+ *
+ * TOML is never auto-merged. Editing TOML without a parser is how a config file gets corrupted, and
+ * a corrupted `~/.codex/config.toml` costs the user every server they had, not just ours. Printing
+ * the exact block is honest; writing a guess is not — so Codex returns MANUAL with a snippet.
+ *
+ * Not writing it is no reason not to READ it, though. Reporting `add this by hand` to somebody who
+ * 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) {
+    if (spec.format !== ConfigFormat.JSON) {
+        if (ConfigFormat.TOML === spec.format && tomlEntryIsSettled(spec, existing)) {
+            return { status: ClientMergeStatus.ALREADY, content: existing ?? '' };
+        }
+        return { status: ClientMergeStatus.MANUAL, content: existing ?? '' };
+    }
+    const parsed = parseConfig(existing);
+    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)) {
+        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() },
+    };
+    return { status: ClientMergeStatus.APPLY, content: `${JSON.stringify(merged, null, 2)}\n` };
+}
+/**
+ * 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 function clientSnippet(spec) {
+    if (spec.format === ConfigFormat.TOML) {
+        const args = npxServerArgs()
+            .map((a) => `"${a}"`)
+            .join(', ');
+        return `[mcp_servers.${MCP_SERVER_NAME}]\ncommand = "${NPX}"\nargs = [${args}]\n`;
+    }
+    if (spec.format === ConfigFormat.CLI) {
+        return `claude mcp add -s user ${MCP_SERVER_NAME} -- ${NPX} ${npxServerArgs().join(' ')}\n`;
+    }
+    return `${JSON.stringify({ [spec.serversKey]: { [MCP_SERVER_NAME]: spec.entry() } }, null, 2)}\n`;
+}
+/**
+ * The path whose existence means "this user has this client".
+ *
+ * Detection is deliberately conservative and one-directional: we write into a config a client
+ * ALREADY has, and never create `~/.gemini/` or `~/.codeium/` for somebody who does not use them.
+ * Littering a home directory to register a server nobody asked for is worse than printing a snippet.
+ *
+ * For a `home` client this is the directory above its config; for a `project` client it is the
+ * config file (or its directory) inside the repo, which is unambiguous evidence somebody uses it
+ * here. Same reasoning as Cursor's existing rule, which also accepts a project-level `.cursor/`
+ * because a fresh Cursor profile has not written `~/.cursor` yet.
+ */
+export function clientMarkerRelPath(spec) {
+    if (spec.scope === ConfigScope.CLI)
+        return '';
+    const parts = spec.relPath.split('/');
+    return parts.length > 1 ? parts.slice(0, -1).join('/') : spec.relPath;
+}
+/**
+ * Project-relative directory whose presence signals Cursor is in use for this repo.
+ *
+ * A fresh Cursor profile has not written `~/.cursor` yet, so the home marker alone misses real
+ * users. A project-level `.cursor/` is unambiguous evidence somebody uses Cursor here.
+ */
+export const CURSOR_PROJECT_MARKER = '.cursor';
+/** Clients `init` can wire by writing a file — everything but the CLI-registered one. */
+export function fileBackedClients() {
+    return MCP_CLIENTS.filter((spec) => spec.scope !== ConfigScope.CLI);
+}

package/dist/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/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/mcp.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Global (user-scope) MCP registration for `reticle init`. The bridge + MCP server is a single
+ * process that serves every project, so it is registered ONCE at user scope — not per-project via
+ * a checked-in `.mcp.json`. We shell out to the official `claude mcp add -s user` CLI rather than
+ * 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
+ * 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
+ * global agent config.
+ */
+export { MCP_SERVER_NAME } from '@reticlehq/core';
+/**
+ * The registered command is STILL bare `npx` on every platform, deliberately.
+ *
+ * Windows is most of Reticle's users and, when this was written, had no CI. There is Windows CI
+ * now, so the `cmd /c` fallback is testable. Defaulting the majority platform to that launch
+ * command is still the riskier change: `.cmd` has spawn caveats in some hosts, and a registration
+ * that works on the machines we can test can still fail in the hosts we cannot. So the fallback
+ * stays documented rather than defaulted.
+ *
+ * What DID change is when it is printed. `mcpManual` used to run only when the `claude` CLI was
+ * absent. The reported Windows install had `claude mcp add` succeed, so the one paragraph that
+ * would have unblocked zero tools never appeared. `mcpWindowsNote` is that paragraph, and init
+ * prints it on every Windows run — including the ones that look like a clean registration.
+ */
+export declare const NPX = "npx";
+/**
+ * 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 mcp-clients.ts).
+ */
+export declare function npxServerArgs(): string[];
+/**
+ * Is this existing registration one WE are responsible for?
+ *
+ * Deliberately the SCOPE and not the server package. An entry naming any `@reticlehq/*` package is
+ * ours to repair — including one naming the WRONG package, which is the case this widened for:
+ * `args: ["@reticlehq/core","mcp"]` was reported from the field, where `core` has no `mcp` bin, so
+ * the client showed the server errored with zero tools while `init` reported it already wired and
+ * left it alone on every re-run. Every `reticle_*` tool was blocked until a human edited that file.
+ *
+ * An entry that names no Reticle package at all — a local build, a wrapper script — is still someone
+ * else's deliberate choice and is left exactly as it is.
+ *
+ * @param tokens every string in the entry's command + args, in any of the client shapes.
+ */
+export declare function isReticleRegistration(tokens: readonly string[]): boolean;
+interface ClaudeAddCommand {
+    command: string;
+    args: string[];
+    /** Human-readable form of the same command, for reports and manual fallback. */
+    display: string;
+}
+/** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
+export declare function claudeAddCommand(): ClaudeAddCommand;
+/** Probe args that tell us whether an `reticle` server already exists in any scope (exit 0 = exists). */
+export declare function claudeExistsProbe(): {
+    command: string;
+    args: string[];
+};
+/** Probe args for whether the `claude` CLI is installed at all. */
+export declare function claudeAvailableProbe(): {
+    command: string;
+    args: string[];
+};
+/**
+ * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
+ * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported
+ * as a clean install with zero tools.
+ */
+export declare function mcpWindowsNote(): string;
+/** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
+export declare function mcpManual(): string;

package/dist/mcp.js

@@ -0,0 +1,129 @@
+/**
+ * Global (user-scope) MCP registration for `reticle init`. The bridge + MCP server is a single
+ * process that serves every project, so it is registered ONCE at user scope — not per-project via
+ * a checked-in `.mcp.json`. We shell out to the official `claude mcp add -s user` CLI rather than
+ * 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
+ * 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
+ * global agent config.
+ */
+import { RETICLE_NPM_PACKAGE } from './version.js';
+// The name is a wire identity and lives in the contract; re-exported here so the registration writers
+// below (and their tests) keep reading it from the module that USES it.
+export { MCP_SERVER_NAME } from '@reticlehq/core';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
+/**
+ * The registered command is STILL bare `npx` on every platform, deliberately.
+ *
+ * Windows is most of Reticle's users and, when this was written, had no CI. There is Windows CI
+ * now, so the `cmd /c` fallback is testable. Defaulting the majority platform to that launch
+ * command is still the riskier change: `.cmd` has spawn caveats in some hosts, and a registration
+ * that works on the machines we can test can still fail in the hosts we cannot. So the fallback
+ * stays documented rather than defaulted.
+ *
+ * What DID change is when it is printed. `mcpManual` used to run only when the `claude` CLI was
+ * absent. The reported Windows install had `claude mcp add` succeed, so the one paragraph that
+ * would have unblocked zero tools never appeared. `mcpWindowsNote` is that paragraph, and init
+ * prints it on every Windows run — including the ones that look like a clean registration.
+ */
+export const NPX = 'npx';
+// The `reticle` bin lives in the server package, so `npx <pkg> mcp` runs the bridge without the
+// 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';
+/** Windows `cmd /c` — the spawn that PowerShell's execution policy does not gate. */
+const WINDOWS_SHELL = 'cmd';
+const WINDOWS_SHELL_C = '/c';
+/**
+ * Args after `npx` that launch the bridge: `@reticlehq/server mcp`. Portless — the port comes from
+ * the project's `.reticle.json` at runtime, so one global entry works for every project.
+ *
+ * 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 mcp-clients.ts).
+ */
+export function npxServerArgs() {
+    return [RETICLE_PACKAGE, MCP_SUBCOMMAND];
+}
+/** The npm scope every Reticle package shares — the marker of a registration we are entitled to fix. */
+const RETICLE_SCOPE = '@reticlehq/';
+/**
+ * Is this existing registration one WE are responsible for?
+ *
+ * Deliberately the SCOPE and not the server package. An entry naming any `@reticlehq/*` package is
+ * ours to repair — including one naming the WRONG package, which is the case this widened for:
+ * `args: ["@reticlehq/core","mcp"]` was reported from the field, where `core` has no `mcp` bin, so
+ * the client showed the server errored with zero tools while `init` reported it already wired and
+ * left it alone on every re-run. Every `reticle_*` tool was blocked until a human edited that file.
+ *
+ * An entry that names no Reticle package at all — a local build, a wrapper script — is still someone
+ * else's deliberate choice and is left exactly as it is.
+ *
+ * @param tokens every string in the entry's command + args, in any of the client shapes.
+ */
+export function isReticleRegistration(tokens) {
+    return tokens.includes(NPX) && tokens.some((t) => t.includes(RETICLE_SCOPE));
+}
+/** The full `npx …` invocation — the tail after `claude mcp add … --`. */
+function serverInvocation() {
+    return [NPX, ...npxServerArgs()];
+}
+/** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
+export function claudeAddCommand() {
+    const tail = serverInvocation();
+    const args = [MCP_SUBCOMMAND, 'add', MCP_SERVER_NAME, '-s', 'user', '--', ...tail];
+    return { command: CLAUDE_CLI, args, display: `${CLAUDE_CLI} ${args.join(' ')}` };
+}
+/** 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. */
+export function claudeAvailableProbe() {
+    return { command: CLAUDE_CLI, args: ['--version'] };
+}
+/**
+ * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
+ * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported
+ * as a clean install with zero tools.
+ */
+export function mcpWindowsNote() {
+    return `On Windows, if the agent cannot start Reticle because npx is blocked ("running scripts is disabled
+on this system" — a PowerShell execution policy), register it through cmd instead, which that policy
+does not gate:
+
+  "${MCP_SERVER_NAME}": { "command": "${WINDOWS_SHELL}", "args": ${JSON.stringify([WINDOWS_SHELL_C, NPX, ...serverInvocation().slice(1)])} }`;
+}
+/** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
+export function mcpManual() {
+    const tail = serverInvocation().join(' ');
+    return `Register the Reticle MCP server ONCE, globally (so every project gets it):
+
+  ${CLAUDE_CLI} ${MCP_SUBCOMMAND} add ${MCP_SERVER_NAME} -s user -- ${tail}
+
+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))} }
+
+${mcpWindowsNote()}`;
+}