@reticlehq/server 2.8.0 → 2.9.0

package/dist/init/connect-steps.js

@@ -0,0 +1,50 @@
+/**
+ * Which `init` steps decide whether the app can dial the daemon.
+ *
+ * Lifted out of `plan.ts` when that file reached the size backstop. A cohesive unit on its own
+ * terms: one question, asked of a step title, with one consequence — a manual step in this set makes
+ * `init` exit non-zero instead of reporting a success over an app that can never connect.
+ *
+ * Matched on TITLES, which is the fragile part and worth stating: renaming a step in
+ * `plan-framework.ts` silently drops it out of this set and nothing goes red. `connect-steps.test.ts`
+ * pins the membership for exactly that reason.
+ */
+/**
+ * Titles of the steps WITHOUT which no session ever appears.
+ *
+ * A ⚠ on one of these is not a warning, it is a guaranteed failure: nothing performs the manual step,
+ * so the app will not connect and every Reticle tool will answer "no browser session connected".
+ * Reported from a field sweep, where the ⚠ count and "did it connect" were treated as independent
+ * signals and are not.
+ */
+const CONNECT_STEP_TITLES = new Set([
+    'Connect snippet',
+    'Connect snippet (CRA)',
+    'Connect snippet (Astro)',
+    'Connect snippet (Nuxt)',
+    'Reticle client hook',
+    'Reticle connect module',
+    'ReticleDev component',
+    // Writing the component and MOUNTING it are two steps, and only the write was here. A root layout
+    // whose shape `init` does not recognise leaves the component on disk and never rendered: the SDK
+    // is in the project, nothing imports it, and `init` exited 0 over an app that could not connect.
+    'Mount ReticleDev',
+    // NOT here, and the reason is worth keeping: 'Pairing token'.
+    //
+    // It is a genuine connect step — CRA inlines only REACT_APP_*, so without the token in the env
+    // file the bridge refuses every connection and the app boots, looks correct, and never pairs. But
+    // it goes MANUAL in exactly one situation: no daemon has ever run on this machine, so there is no
+    // token to inline. That is the FIRST CRA install on a fresh machine, i.e. the first-time user —
+    // and making that exit non-zero reports a broken install to the one person least able to tell
+    // that it is not.
+    //
+    // The real fix is for `init` to mint the token rather than only read it, which is what both the
+    // daemon and the Vite plugin already do. `runInit` is synchronous and the existing helpers are
+    // not, and `gate:install` scaffolds no CRA app, so that change would ship with no coverage of the
+    // path it changes. It is worth doing, and worth doing with a scaffold behind it.
+    'Vite plugin',
+]);
+/** True when this step is what makes the app dial the daemon. */
+export function isConnectStep(title) {
+    return CONNECT_STEP_TITLES.has(title);
+}

package/dist/init/csp-check.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Does this app's Content-Security-Policy let the browser reach the Reticle bridge?
+ *
+ * Two independent field reports, both Next: `init` reported every step successful, the SDK mounted,
+ * the dial URL was correct, and the app never connected because a strict `connect-src` excluded
+ * `ws://localhost:<port>`. The browser blocks the WebSocket and says so in its own console, which
+ * nothing on the Reticle side reads — so `status` and `doctor` reported perfect health at an app
+ * that could not connect at all, forever. A setup step that exits 0 while leaving the user broken is
+ * the worst failure mode this repo has.
+ *
+ * A TEXT SCAN, deliberately. `headers()` is a function; `init` cannot execute a user's Next config
+ * without importing their whole app, and the thing worth finding is the policy string a developer
+ * typed — in `next.config.*`, in middleware, or in a `<meta http-equiv>` tag. The scan finds the
+ * string wherever it is written.
+ *
+ * NARROW on purpose: it fires only when a `connect-src` exists AND does not admit the bridge. No
+ * CSP, or one that already covers us, produces nothing. A warning that fires on a working setup
+ * costs precisely what a green check on a broken one costs, and this file exists because of the
+ * second kind.
+ */
+/**
+ * The problem with this app's `connect-src`, or undefined if there is not one.
+ *
+ * `https:` counts as a wildcard here only in the sense that a policy written that loosely will not
+ * be the thing blocking a dev WebSocket; the check stays quiet rather than arguing about it.
+ */
+export declare function cspConnectSrcProblem(text: string, port: number): string | undefined;
+/** The exact addition to paste. Text to copy, not advice to interpret. */
+export declare function devCspAddition(port: number): string;
+/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
+export declare const CSP_STEP_TITLE = "Content-Security-Policy";
+/**
+ * The first blocking policy among the sources `init` already has in hand, or undefined.
+ *
+ * At most one finding: a second copy of the same policy in a second file is the same problem, and
+ * two identical notices read as two problems.
+ */
+export declare function cspPlanProblem(sources: readonly (string | null | undefined)[], port: number): string | undefined;

package/dist/init/csp-check.js

@@ -0,0 +1,92 @@
+/**
+ * Does this app's Content-Security-Policy let the browser reach the Reticle bridge?
+ *
+ * Two independent field reports, both Next: `init` reported every step successful, the SDK mounted,
+ * the dial URL was correct, and the app never connected because a strict `connect-src` excluded
+ * `ws://localhost:<port>`. The browser blocks the WebSocket and says so in its own console, which
+ * nothing on the Reticle side reads — so `status` and `doctor` reported perfect health at an app
+ * that could not connect at all, forever. A setup step that exits 0 while leaving the user broken is
+ * the worst failure mode this repo has.
+ *
+ * A TEXT SCAN, deliberately. `headers()` is a function; `init` cannot execute a user's Next config
+ * without importing their whole app, and the thing worth finding is the policy string a developer
+ * typed — in `next.config.*`, in middleware, or in a `<meta http-equiv>` tag. The scan finds the
+ * string wherever it is written.
+ *
+ * NARROW on purpose: it fires only when a `connect-src` exists AND does not admit the bridge. No
+ * CSP, or one that already covers us, produces nothing. A warning that fires on a working setup
+ * costs precisely what a green check on a broken one costs, and this file exists because of the
+ * second kind.
+ */
+/** Sources that admit any ws origin, so the bridge is already reachable. */
+const WILDCARDS = ['*', 'ws:', 'wss:', 'ws://*', 'https:'];
+/** The two hosts the SDK may dial. `localhost` and the IPv4 loopback are different CSP sources. */
+function bridgeOrigins(port) {
+    return [`ws://localhost:${String(port)}`, `ws://127.0.0.1:${String(port)}`];
+}
+/**
+ * The `connect-src` directive's source list, or undefined when the text declares none.
+ *
+ * Matches to the end of the directive (`;`) or the end of the enclosing quoted string, which is how
+ * these are written in both a Next `headers()` value and a `<meta content="...">`.
+ */
+function connectSrcSources(text) {
+    // Stops at the directive separator or the closing double quote of the enclosing string. Single
+    // quotes are NOT terminators: `'self'` is a source, not the end of the list.
+    const match = /connect-src([^;"]*)/i.exec(text);
+    const list = match?.[1];
+    if (list === undefined)
+        return undefined;
+    return list
+        .split(/\s+/)
+        .map((source) => source.trim())
+        .filter((source) => source.length > 0);
+}
+/**
+ * The problem with this app's `connect-src`, or undefined if there is not one.
+ *
+ * `https:` counts as a wildcard here only in the sense that a policy written that loosely will not
+ * be the thing blocking a dev WebSocket; the check stays quiet rather than arguing about it.
+ */
+export function cspConnectSrcProblem(text, port) {
+    const sources = connectSrcSources(text);
+    if (sources === undefined || 0 === sources.length)
+        return undefined;
+    if (sources.some((source) => WILDCARDS.includes(source)))
+        return undefined;
+    const wanted = bridgeOrigins(port);
+    // BOTH, not either: the SDK picks its host from how the page was served, and a policy that admits
+    // one is a coin flip. A coin flip that fails is indistinguishable from every other silent
+    // non-connect, which is the whole cost being avoided here.
+    if (wanted.every((origin) => sources.includes(origin)))
+        return undefined;
+    const missing = wanted.filter((origin) => !sources.includes(origin));
+    return (`this app declares a Content-Security-Policy whose \`connect-src\` does not admit the Reticle ` +
+        `bridge: ${missing.join(' and ')} ${1 === missing.length ? 'is' : 'are'} missing. The browser ` +
+        `will block the WebSocket and report it in ITS console only — every check on the Reticle side ` +
+        `will pass while the app never connects. ${devCspAddition(port)}`);
+}
+/** The exact addition to paste. Text to copy, not advice to interpret. */
+export function devCspAddition(port) {
+    return (`Add to \`connect-src\` in development only (e.g. behind ` +
+        `\`process.env.NODE_ENV === 'development'\`): ` +
+        `${bridgeOrigins(port).join(' ')}`);
+}
+/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
+export const CSP_STEP_TITLE = 'Content-Security-Policy';
+/**
+ * The first blocking policy among the sources `init` already has in hand, or undefined.
+ *
+ * At most one finding: a second copy of the same policy in a second file is the same problem, and
+ * two identical notices read as two problems.
+ */
+export function cspPlanProblem(sources, port) {
+    for (const source of sources) {
+        if ('string' !== typeof source)
+            continue;
+        const problem = cspConnectSrcProblem(source, port);
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * `doctor`'s web CSP check — the sibling of the desktop one next door.
+ *
+ * The desktop findings exist because a Tauri app with the default CSP runs perfectly and never
+ * connects. The WEB version of that failure had no check at all, and it arrived twice in one batch
+ * of field reports: two Next apps where `init` printed success for every step, the SDK mounted, the
+ * dial URL was right, and the browser silently refused the WebSocket because `connect-src` excluded
+ * the bridge. The violation is reported in the browser's console and nowhere else, so every check on
+ * this side stayed green while the app was permanently unreachable.
+ *
+ * Reads the files a CSP is actually written in, by name — a full source scan would be slower and
+ * would find policy strings in test fixtures and documentation.
+ */
+/** Read a project-relative file, or undefined when it is absent/unreadable. */
+type ReadFile = (relative: string) => string | undefined;
+export interface CspDiagnosis {
+    /** Which file to look at. */
+    file: string;
+    /** What is wrong, in one line. */
+    problem: string;
+    /** Exactly what to add — copy-pasteable, with the port actually in use. */
+    fix: string;
+}
+export declare function diagnoseWebCsp(read: ReadFile, port: number): CspDiagnosis[];
+export {};

package/dist/init/csp-doctor.js

@@ -0,0 +1,49 @@
+/**
+ * `doctor`'s web CSP check — the sibling of the desktop one next door.
+ *
+ * The desktop findings exist because a Tauri app with the default CSP runs perfectly and never
+ * connects. The WEB version of that failure had no check at all, and it arrived twice in one batch
+ * of field reports: two Next apps where `init` printed success for every step, the SDK mounted, the
+ * dial URL was right, and the browser silently refused the WebSocket because `connect-src` excluded
+ * the bridge. The violation is reported in the browser's console and nowhere else, so every check on
+ * this side stayed green while the app was permanently unreachable.
+ *
+ * Reads the files a CSP is actually written in, by name — a full source scan would be slower and
+ * would find policy strings in test fixtures and documentation.
+ */
+import { cspConnectSrcProblem, devCspAddition } from './csp-check.js';
+/**
+ * The places a Content-Security-Policy gets written in a JS app.
+ *
+ * Next config and middleware cover `headers()` and the edge-middleware style; the layouts and the
+ * plain `index.html` cover the `<meta http-equiv>` style. Both reported cases were in this list.
+ */
+const CSP_FILES = [
+    'next.config.js',
+    'next.config.mjs',
+    'next.config.ts',
+    'middleware.ts',
+    'middleware.js',
+    'src/middleware.ts',
+    'app/layout.tsx',
+    'app/layout.js',
+    'pages/_document.tsx',
+    'pages/_document.js',
+    'index.html',
+    'public/index.html',
+    'vercel.json',
+    'netlify.toml',
+];
+export function diagnoseWebCsp(read, port) {
+    const findings = [];
+    for (const file of CSP_FILES) {
+        const source = read(file);
+        if (source === undefined)
+            continue;
+        const problem = cspConnectSrcProblem(source, port);
+        if (problem === undefined)
+            continue;
+        findings.push({ file, problem, fix: devCspAddition(port) });
+    }
+    return findings;
+}

package/dist/init/cursor.js

@@ -4,8 +4,7 @@
  * We add the `reticle` server once at this global path so every project picks it up. Unparseable
  * (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';
+import { NPX, MCP_SERVER_NAME, npxServerArgs, isReticleRegistration } from './mcp.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. */
@@ -46,19 +45,17 @@ function parseConfig(existing) {
  *
  * 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.
+ * not repair the thing an upgrade exists to repair. A WRONG entry counts as ours to repair too:
+ * `["@reticlehq/core","mcp"]` was reported from the field, and `core` has no MCP server in it.
  */
 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;
+    const record = existing;
+    const tokens = [record.command, record.args].flat().filter((v) => 'string' === typeof v);
+    return !isReticleRegistration(tokens);
 }
 export function mergeCursorConfig(existing) {
     const parsed = parseConfig(existing);

package/dist/init/detect.d.ts

@@ -84,5 +84,13 @@ interface InstallCommand {
 }
 /** Build a dev-dependency install command for one or more packages (e.g. the kit + its build plugin). */
 export declare function installCommandParts(pm: PackageManager, pkgs: string | readonly string[]): InstallCommand;
+/**
+ * The install command as a human reads it — and deliberately NOT `installCommandParts` joined.
+ *
+ * This string is what the plan prints and what a user retypes when running the step by hand, so it
+ * must not carry the flags we add only to quieten our own child process. Built from `INSTALL_ARGS`
+ * directly for that reason; routing it through the parts would put `--no-audit --no-fund` in front of
+ * every reader and teach them our noise-suppression as if it were part of installing Reticle.
+ */
 export declare function installCommand(pm: PackageManager, pkgs: string | readonly string[]): string;
 export {};

package/dist/init/detect.js

@@ -168,12 +168,42 @@ const INSTALL_ARGS = {
     [PackageManager.BUN]: ['add', '-d'],
     [PackageManager.NPM]: ['i', '-D'],
 };
+/**
+ * Flags added only to the install we RUN, never to the one we print.
+ *
+ * The install is a child process whose output lands above ours. Measured on a real install: the run
+ * opened with "added 602 packages", a funding notice, and "14 vulnerabilities (7 moderate, 7 high)"
+ * with `npm audit fix` advice, before one line of Reticle output. A user's first impression of a
+ * verification tool was a wall of somebody else's security warnings, at exactly the moment they are
+ * deciding whether this tool is careful — and that audit summary describes their existing dependency
+ * tree, which our two dev packages neither caused nor can fix.
+ *
+ * Kept off `installCommand`, which is the string shown in the plan and the one a user copies when
+ * running it by hand: nobody should be taught to type our noise-suppression flags.
+ *
+ * Quieted, never silenced — the exit code and stderr are untouched, so a real failure of the step
+ * everything downstream depends on stays as loud as it was.
+ *
+ * npm only: pnpm, yarn and bun reject these, and an unknown flag would turn a working install into a
+ * hard failure, which is the opposite of the problem being fixed.
+ */
+const QUIET_INSTALL_ARGS = {
+    [PackageManager.NPM]: ['--no-audit', '--no-fund'],
+};
 /** 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 = 'string' === typeof pkgs ? [pkgs] : pkgs;
-    return { command: pm, args: [...INSTALL_ARGS[pm], ...list] };
+    return { command: pm, args: [...INSTALL_ARGS[pm], ...list, ...(QUIET_INSTALL_ARGS[pm] ?? [])] };
 }
+/**
+ * The install command as a human reads it — and deliberately NOT `installCommandParts` joined.
+ *
+ * This string is what the plan prints and what a user retypes when running the step by hand, so it
+ * must not carry the flags we add only to quieten our own child process. Built from `INSTALL_ARGS`
+ * directly for that reason; routing it through the parts would put `--no-audit --no-fund` in front of
+ * every reader and teach them our noise-suppression as if it were part of installing Reticle.
+ */
 export function installCommand(pm, pkgs) {
-    const { command, args } = installCommandParts(pm, pkgs);
-    return `${command} ${args.join(' ')}`;
+    const list = 'string' === typeof pkgs ? [pkgs] : pkgs;
+    return `${pm} ${[...INSTALL_ARGS[pm], ...list].join(' ')}`;
 }

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

@@ -3,6 +3,7 @@ export declare const McpClient: {
     readonly CURSOR: "cursor";
     readonly WINDSURF: "windsurf";
     readonly OPENCODE: "opencode";
+    readonly ANTIGRAVITY: "antigravity";
     readonly CODEX: "codex";
     readonly GEMINI: "gemini";
     readonly VSCODE: "vscode";

package/dist/init/mcp-clients.js

@@ -18,13 +18,13 @@
  * 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 } from './mcp.js';
-import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
+import { NPX, MCP_SERVER_NAME, npxServerArgs, isReticleRegistration } from './mcp.js';
 export const McpClient = {
     CLAUDE_CODE: 'claude-code',
     CURSOR: 'cursor',
     WINDSURF: 'windsurf',
     OPENCODE: 'opencode',
+    ANTIGRAVITY: 'antigravity',
     CODEX: 'codex',
     GEMINI: 'gemini',
     VSCODE: 'vscode',
@@ -107,13 +107,57 @@ export const MCP_CLIENTS = [
     {
         id: McpClient.OPENCODE,
         label: 'OpenCode',
-        scope: ConfigScope.PROJECT,
-        relPath: 'opencode.json',
+        /**
+         * 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',
@@ -163,7 +207,8 @@ function parseConfig(existing) {
  *
  * 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.
+ * 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()))
@@ -173,8 +218,7 @@ function leaveEntryAlone(existing, spec) {
     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);
-    const ours = tokens.some((t) => t === NPX) && tokens.some((t) => t.includes(RETICLE_NPM_PACKAGE));
-    return !ours;
+    return !isReticleRegistration(tokens);
 }
 /**
  * Merge our server into this client's config.

package/dist/init/mcp.d.ts

@@ -41,6 +41,21 @@ export declare const NPX = "npx";
  * shape is now repaired on re-run rather than reported "already registered" (see cursor.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[];

package/dist/init/mcp.js

@@ -49,6 +49,25 @@ const CLAUDE_CLI = 'claude';
 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()];

package/dist/init/plan-framework.d.ts

@@ -57,3 +57,13 @@ export declare function svelteKitSteps(input: PlanInput): Step[];
  * and a half-edited build config is worse than a documented manual step.
  */
 export declare function astroSteps(input: PlanInput): Step[];
+/**
+ * A Content-Security-Policy whose `connect-src` excludes the bridge, said out loud at install time.
+ *
+ * Both reported cases were Next apps where `init` printed success for every step and the app then
+ * never connected: the browser blocked the WebSocket and reported it in its own console, which
+ * nothing on this side reads. A NOTICE rather than a step, because editing someone's security policy
+ * is theirs to do — but it carries the exact text to paste, which is the difference between a
+ * warning and a fix.
+ */
+export declare function cspStep(input: PlanInput): Step[];

package/dist/init/plan-framework.js

@@ -9,7 +9,9 @@ import { patchAstroConfig, patchAstroLayout } from './astro-patch.js';
 import { CRA_DEV_MODULE_IMPORT, CRA_DEV_MODULE_PATH, CRA_ENV_PATH, CRA_TOKEN_PER_MACHINE_NOTICE, TOKEN_VAR, craDevModuleFile, craEnvPatch, craImportPatch, } from './cra.js';
 import { PatchKind } from './patch-kind.js';
 import { viteManual, NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, viteDevModuleFile, VITE_DEV_MODULE_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, astroManual, nuxtManual, NUXT_PLUGIN_PATH, } from './snippets.js';
-import { StepStatus } from './plan.js';
+import { RETICLE_CONFIG_FILE, StepStatus } from './plan.js';
+import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { CSP_STEP_TITLE, cspPlanProblem } from './csp-check.js';
 /** What adding `reticle()` to a Vite config buys, which differs by framework. */
 export const VITE_PLUGIN_DETAIL = {
     /** A plain Vite app gets both halves from the plugin. */
@@ -429,3 +431,25 @@ export function astroSteps(input) {
         patchStep('Connect snippet (Astro)', layout.path, layoutPatch, 'add the dev-only connect <script> before </body>', manualWithLayout),
     ];
 }
+/**
+ * A Content-Security-Policy whose `connect-src` excludes the bridge, said out loud at install time.
+ *
+ * Both reported cases were Next apps where `init` printed success for every step and the app then
+ * never connected: the browser blocked the WebSocket and reported it in its own console, which
+ * nothing on this side reads. A NOTICE rather than a step, because editing someone's security policy
+ * is theirs to do — but it carries the exact text to paste, which is the difference between a
+ * warning and a fix.
+ */
+export function cspStep(input) {
+    const problem = cspPlanProblem([input.nextConfigSource, input.nextLayout?.source], input.options.port ?? RETICLE_DEFAULT_PORT);
+    if (problem === undefined)
+        return [];
+    return [
+        {
+            title: CSP_STEP_TITLE,
+            target: input.nextConfigFile ?? RETICLE_CONFIG_FILE,
+            status: StepStatus.NOTICE,
+            detail: problem,
+        },
+    ];
+}

package/dist/init/plan.d.ts

@@ -27,10 +27,9 @@ export declare function pinnedPackages(packages: readonly string[], version: str
 export declare function frameworkPackages(framework: Framework, uiLibrary?: UiLibrary): readonly string[];
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
 export declare const MCP_TARGET = "global (claude user scope)";
-/** True when this step is what makes the app dial the daemon. */
-export declare function isConnectStep(title: string): boolean;
 /** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
 export declare const DEPS_TARGET = "package.json";
+export declare const RETICLE_CONFIG_FILE = ".reticle.json";
 export declare const StepStatus: {
     readonly APPLY: "apply";
     readonly MANUAL: "manual";
@@ -211,6 +210,12 @@ export interface PlanInput {
      * (the single-package case) leaves every path project-relative exactly as before.
      */
     agentFileRoot?: string | undefined;
+    /**
+     * Content of the `.reticle.json` already sitting at that agent root, or null/undefined when there
+     * is none. Content rather than existence, for the reason `reticleConfigSource` is: a root config
+     * that disagrees with the app's is worse than no root config, and only reading it can tell.
+     */
+    agentRootConfigSource?: string | null | undefined;
     options: {
         port: number | undefined;
         mcp: boolean;