@reticlehq/server 2.6.0 → 2.8.0

package/dist/init/confirm.js

@@ -0,0 +1,138 @@
+/**
+ * The step `init` never took: stay and watch for an app to connect.
+ *
+ * The install has two halves. Registering the MCP server gives the agent the tools; getting the SDK
+ * into a running page gives it something to look at. Almost everyone finishes the first, and nothing
+ * joined "init finished" to "an app connected" — so `init` exited 0 having written files, and the
+ * person left with a config file and no instrumented page was never told (#269).
+ *
+ * The capability existed in three places and was used together by none of them: the poll behind
+ * `reticle open`, the install gate (which calls this exact check "the only step that proves the
+ * install works"), and the event that measures whether it ever happened.
+ *
+ * WHY NO FLAG, and no dev-server management:
+ *
+ *  - No flag, because the people this is for are the ones who do not know to ask. `--verify` would
+ *    be typed by the users who already run `status` afterwards, which is exactly the cohort that is
+ *    not being lost. The gate instead is whether a HUMAN IS AT THE TERMINAL: `init` waits when
+ *    stdout is a TTY and skips the wait entirely otherwise, so a scripted or agent-driven `init`
+ *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
+ *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
+ *    also keeps `init`'s documented flag surface where it is.
+ *  - It never starts anything. Reticle attaches to what is already running and does not manage a
+ *    dev server; that rule holds here too. So the honest shape is: confirm the app if it connects,
+ *    otherwise name the ONE command that is outstanding and the one that proves it worked.
+ */
+import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { fetchStatus, summarizeStatus } from '../cli/cli-launch.js';
+import { reportInitOutcome } from '../telemetry/init-telemetry.js';
+/**
+ * How long a human is asked to wait.
+ *
+ * Long enough for a page that is already loading to finish dialling, short enough that somebody who
+ * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
+ * have not typed the command that would make it succeed, and the message tells them which one.
+ */
+export const CONFIRM_WINDOW_MS = 12_000;
+export const CONFIRM_POLL_MS = 500;
+/**
+ * Poll until an app connects or the window runs out.
+ *
+ * A session that was ALREADY there when the wait began does not count, and this is the whole reason
+ * the check reads ids rather than a count. A daemon is shared across every project on the machine,
+ * so "a session exists" is satisfied by another app, by a stray tab, by yesterday's work — and
+ * confirming this install on somebody else's session is a false green in the one message a user
+ * reads to decide whether they are done. `reticle open` refuses the same way, for the same reason.
+ *
+ * The conservative direction is deliberate: an app that reconnects under an id it already held is
+ * reported as not-yet-connected, and the message it gets sends them to `status`, which shows it. A
+ * missed confirmation costs one command; a false one costs the whole point of confirming.
+ */
+export async function confirmAppConnected(deps) {
+    const deadline = deps.now() + (deps.windowMs ?? CONFIRM_WINDOW_MS);
+    let before;
+    for (;;) {
+        const ids = await deps.listSessionIds();
+        // A port nobody is listening on cannot receive a session, and no amount of waiting changes that.
+        // One look settles it; polling on would spend the whole window to re-learn the first answer.
+        if (null === ids)
+            return InitConfirmation.NO_DAEMON;
+        const baseline = before;
+        if (baseline === undefined)
+            before = new Set(ids);
+        else if (ids.some((id) => !baseline.has(id)))
+            return InitConfirmation.CONNECTED;
+        if (deadline <= deps.now())
+            return InitConfirmation.NO_SESSION;
+        await deps.sleep(deps.pollMs ?? CONFIRM_POLL_MS);
+    }
+}
+const PROVE_COMMAND = '`npx @reticlehq/server status`';
+/**
+ * What the user reads, in the marks the rest of the report already uses: `⚠` means work left to do
+ * and nothing else, `ℹ` is worth reading but is not work, `✓` happened.
+ *
+ * Only NO_SESSION earns a `⚠`, and it earns it honestly: the app is wired and has not connected, so
+ * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
+ * up when the agent loads the tools — so it is a notice.
+ */
+export function confirmationMessage(confirmation, port) {
+    if (confirmation === InitConfirmation.CONNECTED) {
+        return ('  [✓] an app is connected — that is the install finished, not just written.\n' +
+            '      Ask your agent to drive a flow.');
+    }
+    if (confirmation === InitConfirmation.NO_DAEMON) {
+        return (`  [ℹ] nothing is listening on port ${String(port)} yet, so no app could have connected and ` +
+            'this run did not wait for one.\n' +
+            '      The daemon starts on its own when your agent loads the Reticle tools. After that, ' +
+            `${PROVE_COMMAND} confirms the app.`);
+    }
+    return ('  [⚠] no app has connected yet — the files are written, the page half of the install is not ' +
+        'done.\n' +
+        '      Restart your dev server (Reticle attaches to it, it never starts it for you) and load ' +
+        'the app in a browser.\n' +
+        `      ${PROVE_COMMAND} then confirms it, or says exactly why it has not connected.`);
+}
+const WATCHING = (windowMs) => `  watching for an app to connect (up to ${String(Math.round(windowMs / 1000))}s) — Ctrl-C is safe, ` +
+    'everything above is already written.';
+/**
+ * Finish `init` on evidence rather than on a write.
+ *
+ * The telemetry report happens HERE rather than inside `runInit`, so the one `init_completed` event
+ * carries what was seen. Emitting inside `runInit` and again after the wait would double-count the
+ * funnel it exists to measure, and a second event kind for the same command would need joining back
+ * to the first before anybody could read either.
+ */
+export async function confirmInstall(result, io, deps, report = reportInitOutcome) {
+    const outcome = result.outcome;
+    // No outcome means a dry run or an exit that already reported for itself (no package.json). A
+    // preview is not an install and must not land in the funnel as either a success or a failure.
+    if (outcome === undefined)
+        return;
+    if (!deps.interactive) {
+        report(outcome);
+        return;
+    }
+    io.print('');
+    io.print(WATCHING(deps.windowMs ?? CONFIRM_WINDOW_MS));
+    const confirmation = await confirmAppConnected(deps);
+    io.print(confirmationMessage(confirmation, deps.port));
+    report({ ...outcome, confirmation });
+}
+/** The real deps: the daemon's own status endpoint, and whether a human is watching. */
+export function nodeConfirmDeps(port = RETICLE_DEFAULT_PORT) {
+    return {
+        listSessionIds: async () => {
+            const payload = await fetchStatus(port);
+            // `fetchStatus` resolves undefined when nothing answered, which is precisely the "no daemon"
+            // case — a zero-session daemon and an absent one need opposite messages.
+            if (payload === undefined)
+                return null;
+            return summarizeStatus(payload).sessions.map((s) => s.sessionId);
+        },
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        interactive: true === process.stdout.isTTY,
+        port,
+    };
+}

package/dist/init/cra.js

@@ -12,6 +12,7 @@
  * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
  * mechanism and is gitignored by CRA's own template.
  */
+import { CLI } from './agent-rules.js';
 /** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
 export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
 export const CRA_DEV_MODULE_PATH = 'src/reticle-dev.ts';
@@ -30,7 +31,7 @@ export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
  */
 export const CRA_TOKEN_MISSING_NOTE = `${TOKEN_VAR} is not set, so Reticle cannot pair with the daemon. ` +
     `The pairing token is per-machine and ${CRA_ENV_PATH} is gitignored by CRA's template, ` +
-    'so it does not survive a clone. Run `npx reticle init` in this project to write it for this machine.';
+    `so it does not survive a clone. Run \`${CLI} init\` in this project to write it for this machine.`;
 /**
  * Said as its own NOTICE line, beside the write — not inside it.
  *
@@ -46,7 +47,7 @@ export const CRA_TOKEN_MISSING_NOTE = `${TOKEN_VAR} is not set, so Reticle canno
 export const CRA_TOKEN_PER_MACHINE_NOTICE = `${CRA_ENV_PATH} is in CRA's own .gitignore, so the token just written does not travel. ` +
     'It works on THIS machine and nowhere else: a teammate cloning the repo, CI, or a container ' +
     'gets an app that boots, never pairs, and reports it only in the browser console. ' +
-    'Each developer runs `npx reticle init` once locally.';
+    `Each developer runs \`${CLI} init\` once locally.`;
 /** Add the import after the last existing one, or null when it is already present. */
 export function craImportPatch(source) {
     if (source.includes(CRA_DEV_MODULE_IMPORT))

package/dist/init/detect.d.ts

@@ -4,6 +4,14 @@
  */
 export declare const Framework: {
     readonly NEXT: "next";
+    /**
+     * Nuxt owns its own Vite instance and has no `vite.config`, so it used to fall all the way through
+     * to HTML — and then be handed a React kit and a connect snippet guarded on
+     * `window.location.hostname === 'localhost'`, which cannot work in a Vue app (the guard throws
+     * during SSR, and never runs at all on a non-localhost dev host). Detected in its own right so it
+     * gets the package and the recipe that actually fit it.
+     */
+    readonly NUXT: "nuxt";
     readonly VITE: "vite";
     readonly SVELTEKIT: "sveltekit";
     readonly ASTRO: "astro";

package/dist/init/detect.js

@@ -4,6 +4,14 @@
  */
 export const Framework = {
     NEXT: 'next',
+    /**
+     * Nuxt owns its own Vite instance and has no `vite.config`, so it used to fall all the way through
+     * to HTML — and then be handed a React kit and a connect snippet guarded on
+     * `window.location.hostname === 'localhost'`, which cannot work in a Vue app (the guard throws
+     * during SSR, and never runs at all on a non-localhost dev host). Detected in its own right so it
+     * gets the package and the recipe that actually fit it.
+     */
+    NUXT: 'nuxt',
     VITE: 'vite',
     SVELTEKIT: 'sveltekit',
     ASTRO: 'astro',
@@ -32,6 +40,7 @@ export const UiLibrary = {
 const NEXT_CONFIGS = ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs'];
 const VITE_CONFIGS = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts'];
 const SVELTE_CONFIGS = ['svelte.config.js', 'svelte.config.ts', 'svelte.config.mjs'];
+const NUXT_CONFIGS = ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs'];
 const ASTRO_CONFIGS = [
     'astro.config.mjs',
     'astro.config.js',
@@ -98,6 +107,12 @@ function detectFramework(input) {
     if (depVersion(pkg, 'next') !== undefined || hasAnyConfig(configFiles, NEXT_CONFIGS)) {
         return Framework.NEXT;
     }
+    // Nuxt before Vite: Nuxt apps can carry a `vite` dependency and even a vite.config, but the
+    // generic Vite path would wire a plugin into a config Nuxt does not read, and inject connect into
+    // an index.html Nuxt does not serve.
+    if (depVersion(pkg, 'nuxt') !== undefined || hasAnyConfig(configFiles, NUXT_CONFIGS)) {
+        return Framework.NUXT;
+    }
     // SvelteKit is Vite-based but renders through app.html, so the Vite plugin's index.html injection
     // never fires (verified) — it needs a manual client connect. Check BEFORE the generic Vite branch.
     if (depVersion(pkg, '@sveltejs/kit') !== undefined || hasAnyConfig(configFiles, SVELTE_CONFIGS)) {

package/dist/init/non-js-project.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Telling a Python (or Ruby, or Go, or PHP) developer why Reticle cannot wire their app.
+ *
+ * `reticle init` answered "No package.json found here, and no app directory beneath it either",
+ * which reads as *you are in the wrong directory* — so an agent on a Streamlit app went looking for
+ * a directory that does not exist, then went looking for a standalone browser bundle to inject by
+ * hand, and only worked out the real answer several steps later.
+ *
+ * The real answer is not about directories at all: Reticle's SDK has to be imported by the app's own
+ * JS build, and a server-rendered Python app has no JS build to import it from. That is a property
+ * of the project, it is knowable from one look at the filesystem, and saying it plainly costs the
+ * reader nothing while the directory message costs them the whole investigation.
+ *
+ * Deliberately a hint, not a refusal: a Django or Rails app with a `frontend/` package.json is a
+ * perfectly ordinary Reticle install, and this only ever speaks when there is no package.json to be
+ * found anywhere.
+ */
+/** The ecosystem this directory looks like, or undefined when nothing says. */
+export declare function detectNonJsEcosystem(exists: (file: string) => boolean): string | undefined;
+/**
+ * What `init` should say when there is no package.json.
+ *
+ * Two genuinely different situations behind one old sentence: a JS developer standing in the wrong
+ * directory, and a developer whose project is not JavaScript at all. The first needs a path; the
+ * second needs to know that no path exists and why.
+ */
+export declare function noPackageJsonMessage(exists: (file: string) => boolean): string;

package/dist/init/non-js-project.js

@@ -0,0 +1,84 @@
+/**
+ * Telling a Python (or Ruby, or Go, or PHP) developer why Reticle cannot wire their app.
+ *
+ * `reticle init` answered "No package.json found here, and no app directory beneath it either",
+ * which reads as *you are in the wrong directory* — so an agent on a Streamlit app went looking for
+ * a directory that does not exist, then went looking for a standalone browser bundle to inject by
+ * hand, and only worked out the real answer several steps later.
+ *
+ * The real answer is not about directories at all: Reticle's SDK has to be imported by the app's own
+ * JS build, and a server-rendered Python app has no JS build to import it from. That is a property
+ * of the project, it is knowable from one look at the filesystem, and saying it plainly costs the
+ * reader nothing while the directory message costs them the whole investigation.
+ *
+ * Deliberately a hint, not a refusal: a Django or Rails app with a `frontend/` package.json is a
+ * perfectly ordinary Reticle install, and this only ever speaks when there is no package.json to be
+ * found anywhere.
+ */
+/** Marker files that identify an ecosystem, and what to call it. */
+const ECOSYSTEM_MARKERS = [
+    ['requirements.txt', 'Python'],
+    ['pyproject.toml', 'Python'],
+    ['Pipfile', 'Python'],
+    ['setup.py', 'Python'],
+    ['manage.py', 'Python (Django)'],
+    ['Gemfile', 'Ruby'],
+    ['go.mod', 'Go'],
+    ['composer.json', 'PHP'],
+    ['Cargo.toml', 'Rust'],
+    ['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) {
+        if (exists(marker))
+            return name;
+    }
+    return undefined;
+}
+/**
+ * What `init` should say when there is no package.json.
+ *
+ * Two genuinely different situations behind one old sentence: a JS developer standing in the wrong
+ * directory, and a developer whose project is not JavaScript at all. The first needs a path; the
+ * second needs to know that no path exists and why.
+ */
+export function noPackageJsonMessage(exists) {
+    const ecosystem = detectNonJsEcosystem(exists);
+    if (ecosystem === undefined) {
+        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. 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

@@ -38,6 +38,15 @@ export declare function nextSteps(input: PlanInput): Step[];
  * bundler never processes for modules. Reported from a real cra-redux-saga app.
  */
 export declare function craSteps(input: PlanInput): Step[];
+/**
+ * Nuxt: one manual step carrying the whole recipe, and no pretence of more.
+ *
+ * There is no Nuxt app in `apps/` and no CI gate for one, so an auto-written plugin would be a
+ * support claim nothing backs — the same reasoning SvelteKit already carries. What this DOES fix is
+ * everything that made the previous fall-through actively wrong: Nuxt was classified as `html`, so
+ * it was handed the React kit and a localhost-guarded snippet that cannot run in a Vue app.
+ */
+export declare function nuxtSteps(input: PlanInput): Step[];
 export declare function svelteKitSteps(input: PlanInput): Step[];
 /**
  * Astro: the config define + build target, and the connect script in ONE layout.

package/dist/init/plan-framework.js

@@ -8,7 +8,7 @@ import { patchNextConfig, patchRootLayout, patchPagesApp } from './next-patch.js
 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, } from './snippets.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';
 /** What adding `reticle()` to a Vite config buys, which differs by framework. */
 export const VITE_PLUGIN_DETAIL = {
@@ -23,6 +23,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 +67,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 +106,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 +129,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 +150,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 +212,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,
         };
@@ -291,6 +329,24 @@ export function craSteps(input) {
         });
     return steps;
 }
+/**
+ * Nuxt: one manual step carrying the whole recipe, and no pretence of more.
+ *
+ * There is no Nuxt app in `apps/` and no CI gate for one, so an auto-written plugin would be a
+ * support claim nothing backs — the same reasoning SvelteKit already carries. What this DOES fix is
+ * everything that made the previous fall-through actively wrong: Nuxt was classified as `html`, so
+ * it was handed the React kit and a localhost-guarded snippet that cannot run in a Vue app.
+ */
+export function nuxtSteps(input) {
+    return [
+        {
+            title: 'Connect snippet (Nuxt)',
+            target: NUXT_PLUGIN_PATH,
+            status: StepStatus.MANUAL,
+            detail: nuxtManual(input.options.port, input.options.projectId),
+        },
+    ];
+}
 export function svelteKitSteps(input) {
     const unverified = {
         title: 'SvelteKit is UNVERIFIED',
@@ -320,7 +376,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,
         },
@@ -357,7 +413,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 [
             {

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,8 +16,15 @@ 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. */
@@ -77,6 +85,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 +159,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 +178,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 +203,14 @@ 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;
     options: {
         port: number | undefined;
         mcp: boolean;