@reticlehq/server 2.7.0 → 2.9.0

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/non-js-project.js

@@ -29,7 +29,13 @@ const ECOSYSTEM_MARKERS = [
     ['pom.xml', 'Java'],
     ['build.gradle', 'Java'],
     ['mix.exs', 'Elixir'],
+    // Not like the others. Every ecosystem above can grow a JS front end that Reticle instruments
+    // perfectly well, so their message ends with a lead. Flutter web paints into a canvas, and there
+    // is no DOM behind it at any path, so the honest answer is a named refusal.
+    ['pubspec.yaml', 'Flutter'],
 ];
+/** The one ecosystem where no directory, front end or flag could ever help. */
+const FLUTTER = 'Flutter';
 /** The ecosystem this directory looks like, or undefined when nothing says. */
 export function detectNonJsEcosystem(exists) {
     for (const [marker, name] of ECOSYSTEM_MARKERS) {
@@ -51,10 +57,28 @@ export function noPackageJsonMessage(exists) {
         return ('No package.json found here, and no app directory beneath it either. Run `reticle init` from ' +
             "your app's directory, or from a repo root that contains it.");
     }
+    if (ecosystem === FLUTTER) {
+        // An agent on a Flutter workspace asked us to "support Flutter, or clearly identify it as
+        // unsupported during init". The second is the truthful one, and saying it by name in one line
+        // is the difference between an agent that stops and an agent that spends an hour looking for
+        // the package.json we told it was missing.
+        return ('This is a Flutter project. Reticle cannot instrument it, and no directory or flag will ' +
+            'change that: Reticle reads the DOM of a running page, and Flutter web paints its entire UI ' +
+            'into a single canvas element with no DOM behind it. Nothing here is missing or misconfigured. ' +
+            'If this repo also contains an ordinary web app with its own package.json, run `reticle init` ' +
+            'inside that directory instead.');
+    }
     return (`This looks like a ${ecosystem} project, and there is no package.json here or in any app ` +
-        'directory beneath it. Reticle instruments a page by having its SDK imported into the app’s own ' +
-        'JavaScript build — so a server-rendered app with no JS build has nowhere to load it from, and ' +
-        'there is no directory you could run this from that would change that. ' +
-        'If this project does have a JS front end (a `frontend/`, `client/` or `assets/` directory with ' +
-        'its own package.json), run `reticle init` there, or point at it with `--app <dir>`.');
+        'directory beneath it. That is not a blocker: Reticle needs its SDK loaded by the page, not ' +
+        'built by npm, and a page with no build step can load it from a URL. ' +
+        // The old message ended at "there is no directory you could run this from that would change
+        // that", which read as a refusal and was acted on as one — agents went looking for a bundler,
+        // or for a standalone build to inject by hand, or gave up and used a different tool. The
+        // capability was there the whole time; only the sentence was missing. Proven end to end on a
+        // page served by `python3 -m http.server` before this line was written.
+        'Add the script-tag snippet below to a template you only serve in development, then reload the ' +
+        'page. ' +
+        'If this project ALSO has a JS front end (a `frontend/`, `client/` or `assets/` directory with ' +
+        'its own package.json), running `reticle init` there instead gives you source mapping and ' +
+        'framework state as well: point at it with `--app <dir>`.');
 }

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. */
@@ -23,6 +25,36 @@ export const VITE_PLUGIN_DETAIL = {
     SVELTEKIT: 'add reticle() to plugins (stamps data-reticle-source in .svelte components)',
 };
 const CAPABILITIES_TITLE = 'Capabilities + store';
+/**
+ * The one step `init` genuinely cannot finish, addressed to the AGENT reading this report.
+ *
+ * It used to read "Capabilities are empty until you edit that file" and describe the consequence to
+ * a human — homework, in a report a human mostly does not read, naming no file to open and no thing
+ * to look for. The agent that ran `init` is right there, has the codebase, and can finish this in
+ * the same minute; what it needed was the specific instruction, not the rationale.
+ *
+ * What is left is exactly what could not be PROVEN from source: which atoms/actor/queryClient an
+ * adapter-wrapped store should be built from, and which elements matter enough to name. `init`
+ * emits nothing it cannot prove, because a wrong import here throws on every dev page load — worse
+ * than an empty file.
+ */
+const CAPABILITIES_TODO_TITLE = 'AGENT: finish the capabilities file';
+function capabilitiesTodo(path, stores) {
+    const store = stores.length > 0
+        ? `This app depends on a state library init cannot wire on its own (it needs an argument only ` +
+            `reading the code can supply). Uncomment the suggested line in that file and complete it: ` +
+            `${stores.join('; ')}.`
+        : `No state library was detected. If the app holds state somewhere init cannot see, register ` +
+            `it — see node_modules/@reticlehq/server/docs/usage.md.`;
+    return (`${path} was written but registers nothing, so \`hasCapabilities\` stays false and reticle_state ` +
+        `has nothing to read.\n` +
+        `Do this now, before driving anything:\n` +
+        `  1. ${store}\n` +
+        `  2. Open the app's main flow and add \`testids\` for the elements it touches (or add ` +
+        `data-testid attributes where there are none).\n` +
+        `  3. Prove it: drive one flow and check reticle_state returns your keys. An empty state read ` +
+        `means this file is still not doing anything, whatever else went green.`);
+}
 /**
  * The dev module carrying `registerCapabilities` / `registerStore`.
  *
@@ -37,23 +69,32 @@ function capabilitiesStep(input) {
                 title: CAPABILITIES_TITLE,
                 target: VITE_DEV_MODULE_PATH,
                 status: StepStatus.ALREADY,
-                detail: 'file exists — left alone, it is yours to edit',
+                detail: 'file exists, left alone, it is yours to edit',
             },
         ];
     }
     const testids = input.testids ?? [];
     const stores = input.storeHints ?? [];
+    const wired = input.foundStores ?? [];
     const found = testids.length > 0
         ? `${String(testids.length)} data-testid values`
         : 'no data-testid values yet';
-    const nothingToRegister = 0 === testids.length && 0 === stores.length;
+    // A store we found and wired IS a registration, so the "registers nothing" notice must not fire.
+    const nothingToRegister = 0 === testids.length && 0 === stores.length && 0 === wired.length;
     return [
         {
             title: CAPABILITIES_TITLE,
             target: VITE_DEV_MODULE_PATH,
             status: StepStatus.APPLY,
-            detail: `${found}; ${stores.length > 0 ? `store: uncomment the ${String(stores.length)} suggested line(s)` : 'no state library detected'}`,
-            write: { path: VITE_DEV_MODULE_PATH, content: viteDevModuleFile(testids, stores) },
+            detail: `${found}; ${wired.length > 0
+                ? `registered ${wired.map((s) => `'${s.key}'`).join(', ')} from your source`
+                : stores.length > 0
+                    ? `store: uncomment the ${String(stores.length)} suggested line(s)`
+                    : 'no state library detected'}`,
+            write: {
+                path: VITE_DEV_MODULE_PATH,
+                content: viteDevModuleFile(testids, stores, wired, input.detection.uiLibrary),
+            },
             dependsOnInstall: true,
         },
         // The write is real; what it registers is not. `registerCapabilities({ testids: [], signals: [],
@@ -67,14 +108,10 @@ function capabilitiesStep(input) {
         ...(nothingToRegister
             ? [
                 {
-                    title: 'Capabilities are empty until you edit that file',
+                    title: CAPABILITIES_TODO_TITLE,
                     target: VITE_DEV_MODULE_PATH,
                     status: StepStatus.NOTICE,
-                    detail: 'the module was written but registers nothing — no data-testid values were found and ' +
-                        'no state library was detected, so `hasCapabilities` stays false and reticle_state ' +
-                        'has nothing to read. Add data-testid to the elements your main flow touches, or ' +
-                        'register a store in that file, and the agent gains what the app BELIEVES rather than ' +
-                        'only what it rendered.',
+                    detail: capabilitiesTodo(VITE_DEV_MODULE_PATH, stores),
                 },
             ]
             : []),
@@ -94,7 +131,7 @@ function viteConfigSteps(input, detail) {
                 title: 'Vite plugin',
                 target: 'vite.config',
                 status: StepStatus.MANUAL,
-                detail: viteManual(port),
+                detail: viteManual(port, input.detection.uiLibrary),
             },
         ];
     }
@@ -115,7 +152,7 @@ function viteConfigSteps(input, detail) {
                 title: 'Vite plugin',
                 target: cfg.path,
                 status: StepStatus.MANUAL,
-                detail: `${patch.reason}\n\n${viteManual(port)}`,
+                detail: `${patch.reason}\n\n${viteManual(port, input.detection.uiLibrary)}`,
             },
         ];
     }
@@ -177,7 +214,10 @@ export function nextSteps(input) {
             detail: 'create dev-only connect component',
             write: {
                 path: devPath,
-                content: nextReticleDevFile(input.options.port, input.options.projectId, input.testids ?? [], input.storeHints ?? []),
+                content: nextReticleDevFile(input.options.port, input.options.projectId, input.testids ?? [], input.storeHints ?? [], 
+                // Next's dev module is not a sibling of `src/` — its imports are resolved from wherever
+                // the component actually lands (`app/`, or `src/app/` in a --src-dir app).
+                input.nextFoundStores ?? []),
             },
             dependsOnInstall: true,
         };
@@ -338,7 +378,7 @@ export function svelteKitSteps(input) {
             detail: 'create dev-only client connect (SvelteKit renders via app.html)',
             write: {
                 path: SVELTEKIT_HOOKS_PATH,
-                content: svelteKitHooksFile(input.options.port, input.options.projectId),
+                content: svelteKitHooksFile(input.options.port, input.options.projectId, input.detection.uiLibrary),
             },
             dependsOnInstall: true,
         },
@@ -375,7 +415,7 @@ export function astroSteps(input) {
     // single recipe that does the whole job.
     const manualWithLayout = astroManual(input.options.port, input.options.projectId, layout.path);
     const configPatch = patchAstroConfig(config.source);
-    const layoutPatch = patchAstroLayout(layout.source, input.options.port, input.options.projectId);
+    const layoutPatch = patchAstroLayout(layout.source, input.options.port, input.options.projectId, input.detection.uiLibrary);
     if (configPatch.kind === PatchKind.MANUAL || layoutPatch.kind === PatchKind.MANUAL) {
         return [
             {
@@ -391,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

@@ -3,7 +3,8 @@
  * 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 { Framework, type Detection } from './detect.js';
+import { Framework, UiLibrary, type Detection } from './detect.js';
+import type { FoundStore } from './capabilities.js';
 import { type McpClient } from './mcp-clients.js';
 /**
  * Pin the SDK to the CLI's own version.
@@ -15,14 +16,20 @@ import { type McpClient } from './mcp-clients.js';
  * irrelevant, and a skewed pair impossible to install by accident.
  */
 export declare function pinnedPackages(packages: readonly string[], version: string | undefined): readonly string[];
-/** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
-export declare function frameworkPackages(framework: Framework): readonly string[];
+/**
+ * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
+ *
+ * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
+ * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
+ * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
+ * right after `init` had detected the real UI library and said so on screen.
+ */
+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";
@@ -77,6 +84,13 @@ export interface Step {
 }
 export interface Plan {
     framework: Framework;
+    /**
+     * The renderer this app actually uses, carried so every consumer agrees on WHICH packages the
+     * plan installed. The retry guard checks node_modules for exactly those names; without this it
+     * looked for `@reticlehq/react` in a Vue app that had correctly been given the sensor, decided the
+     * install had failed, and skipped every wiring step on the retry.
+     */
+    uiLibrary: UiLibrary;
     steps: Step[];
 }
 export interface PlanInput {
@@ -144,6 +158,10 @@ export interface PlanInput {
     testids?: readonly string[] | undefined;
     /** Ready-to-uncomment `registerStore` lines for the state libraries the app actually depends on. */
     storeHints?: readonly string[] | undefined;
+    /** Store instances found in the app's own source — imported and registered outright, not hinted. */
+    foundStores?: readonly FoundStore[] | undefined;
+    /** The same stores, with specifiers resolved from Next's dev-module directory instead of `src/`. */
+    nextFoundStores?: readonly FoundStore[] | undefined;
     /** Whether src/reticle-dev.ts already exists — it is the one generated file users are meant to edit. */
     viteDevModuleExists?: boolean | undefined;
     /** Whether src/hooks.client.ts already exists (SvelteKit idempotency). */
@@ -159,10 +177,19 @@ export interface PlanInput {
     pairingToken?: string;
     /** Whether .reticle.json already exists in the project root (idempotency). */
     reticleConfigExists?: boolean;
+    /**
+     * Its CONTENT, so an existing config can be checked instead of trusted.
+     *
+     * Existence alone said "a file is present" and was reported as "this is configured correctly" —
+     * see reticleConfigStep for the port that survived every re-run because of it.
+     */
+    reticleConfigSource?: string | null | undefined;
     /** Current project-root CLAUDE.md content (for the idempotent agent-rule merge), or null/undefined. */
     claudeMdContent?: string | null | undefined;
-    /** Current project-root AGENTS.md content (cross-agent fallback rule), or null/undefined. */
+    /** Current project-root AGENTS.md content (the cross-agent rule), or null/undefined. */
     agentsMdContent?: string | null | undefined;
+    /** Current project-root RETICLE.md content (the full rules), or null when absent. */
+    reticleMdContent?: string | null | undefined;
     /**
      * Current .cursor/rules/reticle.mdc content, or null when absent.
      *
@@ -175,6 +202,20 @@ export interface PlanInput {
     claudeCommandContent?: string | null | undefined;
     /** Current .cursor/commands/reticle.md content, or null when absent. */
     cursorCommandContent?: string | null | undefined;
+    /**
+     * Absolute directory the AGENT runs in, when that is not the app's directory.
+     *
+     * The rule and command files are read by the agent, not by the app, so a monorepo whose app is a
+     * directory down must still get its `/reticle` where the human's session actually stands. Absent
+     * (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;