@reticlehq/server 2.6.0 → 2.7.0

package/dist/honesty/honesty.d.ts

@@ -5,6 +5,7 @@
  * block. Harnesses gate on it (e.g. "grade ≥ net AND integrity clean"). This is pure composition +
  * assessment — all five components already exist individually; wiring it onto results is a later step.
  */
+import type { CaptureLoss } from '@reticlehq/core';
 /** Assertion grade, strongest first — the tier the verdict actually proved. */
 export declare const HonestyGrade: {
     readonly SIGNAL: "signal";
@@ -23,6 +24,15 @@ interface HonestyInputs {
     coveragePartial?: boolean;
     truncated?: boolean;
     blindSpots?: readonly string[];
+    /**
+     * The machine-readable half of `issues` — WHICH kind of loss, from core's closed `CaptureLoss`.
+     *
+     * `issues` is prose built for an agent to read, and prose is not something a dashboard can group
+     * by: `unclean_capture` became a large share of all field verdicts with no way to ask which of its three
+     * causes produced them. Passed by the caller rather than derived here, because only the caller
+     * knows whether a blind-spot note came from the browser transport or from a boundary in the page.
+     */
+    losses?: readonly CaptureLoss[];
 }
 export interface HonestyBlock {
     grade: HonestyGrade;
@@ -40,6 +50,7 @@ export interface HonestyBlock {
     integrity: {
         clean: boolean;
         issues: string[];
+        losses?: CaptureLoss[];
     };
 }
 export declare function buildHonestyBlock(inputs: HonestyInputs): HonestyBlock;

package/dist/honesty/honesty.js

@@ -46,7 +46,15 @@ export function buildHonestyBlock(inputs) {
             ? {}
             : { envelope: { samples, sufficient: samples >= MIN_ENVELOPE_SAMPLES } }),
         coverage: { ...(pct === undefined ? {} : { pct }), partial },
-        integrity: { clean: 0 === issues.length, issues },
+        integrity: {
+            clean: 0 === issues.length,
+            issues,
+            // Only when something was actually lost. An empty array beside `clean: true` would be a field
+            // that is always present and always says nothing, which is how a signal gets tuned out.
+            ...(0 === issues.length || undefined === inputs.losses || 0 === inputs.losses.length
+                ? {}
+                : { losses: [...new Set(inputs.losses)] }),
+        },
     };
 }
 /** Whether a verdict's honesty block clears the harness's bar. Reasons list every failed criterion. */

package/dist/honesty/verified.js

@@ -1,4 +1,4 @@
-import { Verified, VerifiedReason } from '@reticlehq/core';
+import { Verified, VerifiedReason, isAbsenceDerived } from '@reticlehq/core';
 import { HonestyGrade } from './honesty.js';
 export function decideVerified(inputs) {
     const { pass, honesty, contradictions = [], settled, outcomePending, outcomeUnread } = inputs;
@@ -41,14 +41,37 @@ export function decideVerified(inputs) {
     // this product exists to catch is a green assertion sitting on top of a failed write. Measured on
     // the bench app — `ui-advanced-request-failed` arrived with verdict.pass true and every other
     // channel agreeing. Letting `pass` win there would report exactly the false green being detected.
-    if (contradictions.length > 0) {
-        const kinds = contradictions.map((c) => c.kind).join(', ');
+    // ...but ONLY for contradictions we positively OBSERVED. A kind inferred from the absence of
+    // evidence — the request had not settled, the response had not been applied yet — is a statement
+    // about when we stopped looking, not about whether the action worked, and the window closes the
+    // moment the predicate first passes. Reproduced on the bench app: `auth:granted` fired with
+    // matching data, state changed, the token was stored, the capture was clean and the grade was
+    // `signal`, and the verdict was still NO because one POST was in flight. That inverts the grade
+    // hierarchy — a timing observation beat a consequence observation — and it is the shape of half of
+    // every `no` verdict in the field. See ABSENCE_DERIVED_CONTRADICTIONS for why a false negative
+    // costs more than it looks: it makes an agent redo work that succeeded, or stop believing the
+    // verdict channel, which is the product.
+    const observed = contradictions.filter((c) => !isAbsenceDerived(c.kind));
+    if (observed.length > 0) {
+        const kinds = observed.map((c) => c.kind).join(', ');
         return {
             verified: Verified.NO,
             verifiedReason: VerifiedReason.CONTRADICTED,
             because: `channels disagree about this action (${kinds}) even though the assertion passed`,
         };
     }
+    // Absence-derived only: report it, do not assert failure. UNKNOWN is the honest answer — Reticle
+    // drove the app and could not yet tell. The finding still rides out in `contradictions`, so an
+    // agent that wants to wait and re-check has everything it needs.
+    if (contradictions.length > 0) {
+        const kinds = contradictions.map((c) => c.kind).join(', ');
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.UNSETTLED,
+            because: `the assertion held, but this window closed before the app finished (${kinds}) — ` +
+                `re-check, or assert a consequence that settles`,
+        };
+    }
     // Below the contradiction clause, and for the same reason a contradiction outranks a dirty
     // capture: evidence AGAINST beats absence of evidence, whichever absence it is. Both can hold at
     // once — assert `{ text: 'Saved' }` that was already on screen while the write 500s — and ordering

package/dist/http-server.js

@@ -150,8 +150,18 @@ export function createSharedServer(options = {}) {
         transports.clear();
         await new Promise((resolve, reject) => {
             httpServer.close((err) => {
-                if (err !== undefined && err !== null)
+                // A server that never listened is already closed, and saying so is not an error worth
+                // propagating. It matters because this close() runs on the CLEANUP path of a failed
+                // `--drive`: when the app URL is unreachable, the daemon tears down before `listen()` has
+                // been called, Node rejects with ERR_SERVER_NOT_RUNNING, and that rejection REPLACES the
+                // real cause. The user's app is down and the message they read is "Server is not running",
+                // which blames Reticle for their dev server — traced live, where swallowing this turned the
+                // same failure back into "net::ERR_CONNECTION_REFUSED at http://localhost:4312/".
+                if (err !== undefined &&
+                    err !== null &&
+                    'ERR_SERVER_NOT_RUNNING' !== err.code) {
                     reject(err);
+                }
                 else
                     resolve();
             });

package/dist/index.js

@@ -5,6 +5,8 @@ import { originOf } from './session/session-manager.js';
 import { setBrowserMode, BrowserMode } from './telemetry/browser-mode.js';
 import { replayNamedFlow } from './flows/flow-tools.js';
 import { createSharedServer } from './http-server.js';
+import { openLoopbackAlias } from './daemon/loopback-alias.js';
+import { reportAppInstrumented } from './telemetry/app-instrumented.js';
 import { resolveBridgeSecurityWithAutoToken } from './bridge/bridge-security.js';
 import { Bridge } from './bridge/bridge.js';
 import { BaselineStore } from './project/baselines.js';
@@ -14,6 +16,7 @@ import { buildFlowChips } from './flows/flow-scope.js';
 import { ProjectStore } from './project/project-store.js';
 import { AnnotationStore } from './flows/annotation-store.js';
 import { createNodeFileSystem } from './project/fs-port.js';
+import { cleanupCaptureDirectories } from './visual/capture-cleanup.js';
 import { ReticleRunner } from './runs/reticle-runner.js';
 import { createRunnerPort } from './runs/runner-port.js';
 import { RunStore } from './runs/run-store.js';
@@ -287,6 +290,7 @@ export async function start(options = {}) {
         ...(security.token !== undefined ? { token: security.token } : {}),
         close: async () => {
             reaper.stop();
+            await cleanupCaptureDirectories();
             leaseReaper?.stop();
             await pool?.shutdown();
             await owned?.dispose();
@@ -309,7 +313,9 @@ export async function startDaemon(options = {}) {
     // mirror rejection so a port collision can't surface as an unhandled promise rejection.
     void bridge.ready.catch(() => undefined);
     // `reticle status` GETs this for a live, at-a-glance view of connected tabs + their health.
-    shared.attachStatus(() => statusPayload(bridge.sessions.count(), bridge.sessions.list()));
+    // The same diagnosis agents get on an empty `reticle_sessions`, so `reticle status` — the
+    // most-run command in the field — stops answering "sessionCount: 0" and nothing else.
+    shared.attachStatus(() => statusPayload(bridge.sessions.count(), bridge.sessions.list(), bridge.sessions.noSessionHint()));
     // Agent-independent presence: the daemon outlives any single agent, so when the LAST agent's MCP
     // connection drops (it stopped, or is waiting on the human), end every session and push a clear
     // "go to your terminal" notice to the panel — the human is on the browser and must not lose a typed
@@ -389,6 +395,16 @@ export async function startDaemon(options = {}) {
     // connecting session's project (a shared daemon serves many apps; each panel shows only its own
     // flows + legacy untagged ones). Each chip carries a `start` hint (the first step's testid anchor)
     // so the HUD shows a flow only on the page it can begin from — the panel re-scopes per route.
+    // The first instrumented app of this daemon run — the funnel step nothing could measure before.
+    // Inside the existing session-ready hook rather than beside it: this fires exactly when a page
+    // carrying the SDK has completed its handshake, which is the definition of "instrumented", and
+    // `reportAppInstrumented` is idempotent so later sessions cost a boolean check.
+    bridge.attachSessionReady(() => {
+        reportAppInstrumented({
+            initialized: readProjectId(process.cwd()) !== undefined,
+            agentAttached: agentConnected,
+        });
+    });
     bridge.attachSessionReady((session) => {
         flows
             .list(session.projectId)
@@ -417,7 +433,13 @@ export async function startDaemon(options = {}) {
         shared.httpServer.once('listening', onListening);
         shared.httpServer.listen(port, security.host ?? LOOPBACK_HOST);
     });
-    log('mcp_daemon_started', { port });
+    // `localhost` is a name with two answers, and Windows/Chrome tries the IPv6 one first. Only alias
+    // when we are on the default loopback bind: an explicit RETICLE_HOST is a deliberate choice about
+    // reachability, and quietly adding a second listener to it would be the opposite of deliberate.
+    const loopbackAlias = security.host === undefined
+        ? await openLoopbackAlias(port)
+        : { opened: false, close: undefined };
+    log('mcp_daemon_started', { port, loopbackAlias: loopbackAlias.opened });
     return {
         bridge,
         ...(realInput !== undefined ? { realInput } : {}),
@@ -431,10 +453,12 @@ export async function startDaemon(options = {}) {
         agentAttached: () => agentConnected,
         close: async () => {
             reaper.stop();
+            await cleanupCaptureDirectories();
             const vh = verifyHttp;
             if (vh !== undefined)
                 await new Promise((resolve) => vh.server.close(() => resolve()));
             leaseReaper.stop();
+            await loopbackAlias.close?.();
             await pool.shutdown();
             await owned?.dispose();
             await bridge.close();

package/dist/init/agent-rules.js

@@ -44,10 +44,15 @@ const RULE_BODY = `## Verifying with Reticle
 This app is instrumented by **Reticle** — an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`${CLI}\` CLI (run it through npx — Reticle's server is not installed into this project). Verifying is part of "done", not an optional extra.
 
 - **When:** after you build or change any user-facing feature, flow, or UI, verify it with Reticle **before** telling the user it is complete. Reading the code or passing unit tests is not enough — drive the real running app.
-- **How:** drive the actual flow (\`reticle_act\` / \`reticle_act_and_wait\`), then read the observable effect (\`reticle_assert\`, \`reticle_snapshot\`, \`reticle_state\`, \`reticle_network\`). Confirm the change produced the effect it was meant to, with no new console errors or failed requests.
+- **How:** drive the flow with \`reticle_act_and_wait({ ref, action, until })\` — it names the consequence you expect BEFORE the action, which is the difference between a check and a rationalisation. Batch a multi-step flow (a login, a form) into one \`reticle_act_sequence\` rather than one round trip per field. Read the surrounding evidence with \`reticle_snapshot\`, \`reticle_state\`, \`reticle_network\`, \`reticle_console\`.
+- **Only \`reticle_act_and_wait\` and \`reticle_assert\` produce a verdict.** \`reticle_act\` and everything else move or read the app and prove nothing, so a session that ends without one of those two has no result however many tools it used. In practice \`reticle_act\` is reached for far more often and proves nothing; \`act_and_wait\` is where the defects actually get caught.
+- **\`verified: "unknown"\` is not a pass.** It means Reticle drove the app and could not tell what happened; \`verifiedReason\` says which of eleven clauses decided that and what to do about it. Report it as unknown — never as working.
+- **If a tool result carries \`verify_next\`, do what it says next.** It means you have driven this page several times without asking for a verdict, so nothing you have done so far is proven.
 - **Covered flows:** run \`${CLI} gate\` — it reports which recorded flows the changed files affect and whether they still pass.
 - **Never weaken a check to make it green.** Downgrading, skipping, or deleting an assertion is a finding, not a fix.
 - **If Reticle can't run** (no daemon, or this is not a running web app), say so — do not skip verification silently.
+- **If the \`reticle_*\` tools are missing entirely, they have not been loaded yet — not broken.** \`init\` registers the MCP server, but a client reads its tool list at startup and does not re-read it. Ask the human to reload their MCP tools (\`/mcp\` in Claude Code, or reload the window in Cursor/VS Code), wait, then carry on. \`npx ${RETICLE_NPM_PACKAGE} status\` works meanwhile and says whether the daemon is up and whether the app has connected.
+- **Setup is not finished until one real flow has been driven and produced a verdict.** \`init\` exiting 0 means files were written; the tools appearing means your client can reach a daemon; a listed session means the app dialled in. None of those is evidence that anything works. If you are blocked before a verdict, say which step and what you tried — never report a clean install you did not verify.
 - **If a tool result carries \`version_skew\`, act on it before trusting anything else.** Two pieces of Reticle are on different wire contracts, so tools can misbehave in ways neither side reports — a green here is not evidence. The field says which pair disagrees and names the exact fix: run \`${CLI} stop\` and retry when the DAEMON is stale, or tell the human to install the matching SDK and restart their dev server when the PAGE is. Do that first, then redo whatever you were verifying.
 - **If a tool result carries \`update_available\`, say so.** Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`${CLI} update\` — between tasks, never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
 

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,60 @@
+/**
+ * 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'],
+];
+/** 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.");
+    }
+    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>`.');
+}

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 = {
@@ -291,6 +291,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',

package/dist/init/plan.js

@@ -9,13 +9,15 @@ import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './curso
 import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, } from './mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from './slash-command.js';
 import { mergeMarkedInstruction, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
-import { viteSteps, nextSteps, craSteps, svelteKitSteps, astroSteps, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
+import { viteSteps, nextSteps, craSteps, svelteKitSteps, nuxtSteps, astroSteps, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
 import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote } from './snippets.js';
 // An app dev installs exactly the audience-scoped browser-side dependencies — never the retired
 // `@reticlehq/core` umbrella (which dragged the Node MCP server + ws into every app). The kit is the
 // framework adapter (it re-exports the browser sensor), paired with that framework's dev-only build
 // plugin for source mapping + connect injection.
 const RETICLE_REACT_KIT = '@reticlehq/react';
+/** The framework-neutral sensor, for stacks the React adapter has nothing to attach to. */
+const RETICLE_BROWSER_SDK = '@reticlehq/browser';
 const RETICLE_VITE_PLUGIN = '@reticlehq/vite-plugin';
 const RETICLE_NEXT_PLUGIN = '@reticlehq/next';
 /**
@@ -41,6 +43,11 @@ export function frameworkPackages(framework) {
         case Framework.SVELTEKIT:
             // SvelteKit builds on Vite; until a dedicated Svelte kit exists it uses the Vite build plugin.
             return [RETICLE_REACT_KIT, RETICLE_VITE_PLUGIN];
+        case Framework.NUXT:
+            // The framework-neutral sensor, NOT the React kit. Nuxt renders Vue, and installing a package
+            // named @reticlehq/react — with `react` in its peer dependencies — into a Vue codebase is the
+            // single thing most likely to make someone abandon the setup, whether or not it works.
+            return [RETICLE_BROWSER_SDK];
         case Framework.ASTRO:
             // Astro owns its own Vite instance and renders its own HTML, so there is no config for the
             // plugin to attach to — the kit alone, connected from a page <script> (see astroManual).
@@ -68,6 +75,7 @@ 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',
@@ -484,8 +492,14 @@ function reticleConfigStep(input) {
  */
 function uiLibraryStep(input) {
     const lib = input.detection.uiLibrary;
-    if (lib === UiLibrary.REACT || input.detection.framework === Framework.SVELTEKIT)
+    // Nuxt and SvelteKit each carry their own unverified wording inside the recipe, so a second,
+    // more generic notice beside it would only argue with the specific one.
+    const framework = input.detection.framework;
+    if (lib === UiLibrary.REACT ||
+        framework === Framework.SVELTEKIT ||
+        framework === Framework.NUXT) {
         return [];
+    }
     if (lib === UiLibrary.UNKNOWN)
         return [];
     return [
@@ -518,6 +532,9 @@ export function buildPlan(input) {
     else if (input.detection.framework === Framework.CRA) {
         steps.push(...craSteps(input));
     }
+    else if (input.detection.framework === Framework.NUXT) {
+        steps.push(...nuxtSteps(input));
+    }
     else if (input.detection.framework === Framework.SVELTEKIT) {
         steps.push(...svelteKitSteps(input));
         // The Vite plugin as well as the client hook. `init` already INSTALLS @reticlehq/vite-plugin for
@@ -530,7 +547,7 @@ export function buildPlan(input) {
             title: 'Connect snippet',
             target: 'index.html',
             status: StepStatus.MANUAL,
-            detail: htmlManual(input.options.port, input.options.projectId),
+            detail: htmlManual(input.options.port, input.options.projectId, input.pairingToken),
         });
     }
     return { framework: input.detection.framework, steps };

package/dist/init/run.js

@@ -4,6 +4,7 @@
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
 import { dirname, join } from 'node:path';
+import { noPackageJsonMessage } from './non-js-project.js';
 import { spanSync } from '../trace.js';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -402,16 +403,39 @@ export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this se
     'one thing that decides what gets fixed:\n' +
     `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
     `  ${CLI} feedback "what worked, what didn't"   (humans)`;
-function restartHint(framework) {
+function devServerRestart(framework) {
     if (framework === Framework.NEXT)
-        return 'Restart `next dev`, then ask your agent: "List Reticle sessions".';
+        return 'Restart `next dev`';
     if (framework === Framework.VITE)
-        return 'Restart `vite`, then ask your agent: "List Reticle sessions".';
+        return 'Restart `vite`';
     if (framework === Framework.ASTRO)
-        return 'Restart `astro dev`, then ask your agent: "List Reticle sessions".';
+        return 'Restart `astro dev`';
     if (framework === Framework.SVELTEKIT)
-        return 'Restart your dev server (`npm run dev`), then ask your agent: "List Reticle sessions".';
-    return 'Reload your app on localhost, then ask your agent: "List Reticle sessions".';
+        return 'Restart your dev server (`npm run dev`)';
+    return 'Reload your app on localhost';
+}
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+function restartHint(framework, mcpRegistered) {
+    const dev = `${devServerRestart(framework)}.`;
+    if (!mcpRegistered)
+        return `${dev} Then ask your agent: "List Reticle sessions".`;
+    return (`${dev}\n` +
+        "Then reload your agent's MCP tools — `/mcp` in Claude Code, or reload the window in " +
+        'Cursor/VS Code.\n' +
+        'The tools only appear after that: your agent read its tool list before Reticle existed.\n' +
+        'Then ask it: "List Reticle sessions".');
 }
 const SKIPPED_DETAIL = 'skipped — the dependency install above failed, and wiring the app to a package that is not ' +
     'installed stops it booting. Run that install, then re-run `reticle init`.';
@@ -470,7 +494,7 @@ function report(plan, dryRun, failed, skipped, degraded, io, projectDir) {
             '"no browser session connected" until then. Everything else is already in place.');
         io.print('');
     }
-    io.print(restartHint(plan.framework));
+    io.print(restartHint(plan.framework, wasMcpRegistered(resolvedStatus(plan, MCP_TARGET, failed, skipped))));
     return { ok: !connectPending, applied, manual };
 }
 /**
@@ -655,8 +679,13 @@ function runInitSteps(options, io) {
     if (redirectedEarly !== null)
         return redirectedEarly;
     if (null === pkgRaw) {
-        io.print('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.");
+        io.print(
+        // Two genuinely different situations used to share one sentence: a JS developer in the wrong
+        // directory, and a project that is not JavaScript at all. The second reads the old wording as
+        // a path problem and goes looking for a directory that cannot exist — reported from a
+        // Streamlit app, where the search continued into hunting for a browser bundle to inject by
+        // hand before the real answer surfaced.
+        noPackageJsonMessage((file) => io.exists(join(options.cwd, file))));
         // The onboarding funnel had NO instrumentation, so a setup that died here was indistinguishable
         // from someone who never ran the command — the two failure modes with the most different fixes.
         reportInitOutcome({ ok: false, reason: InitFailure.NO_PACKAGE_JSON });

package/dist/init/snippets.d.ts

@@ -47,7 +47,7 @@ export declare const NEXT_LAYOUT_MANUAL = "Mount <ReticleDev /> in your root lay
  * where a bare `@reticlehq/react` import resolves. A bare import in a plain index.html does NOT resolve in
  * the browser, so we never tell a bundled app to do that (the old advice silently failed for CRA).
  */
-export declare function htmlManual(port: number | undefined, projectId?: string): string;
+export declare function htmlManual(port: number | undefined, projectId?: string, pairingToken?: string): string;
 export declare const NEXT_RETICLE_DEV_PATH = "app/reticle-dev.tsx";
 export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
 /**
@@ -68,6 +68,25 @@ export declare const UNVERIFIED_FRAMEWORK_NOTE = "Reticle has no SvelteKit app a
  * a client hook is the reliable path. SvelteKit runs src/hooks.client.ts on the client at startup.
  */
 export declare function svelteKitHooksFile(port: number | undefined, projectId?: string): string;
+/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
+export declare const NUXT_PLUGIN_PATH = "app/plugins/reticle.client.ts";
+/**
+ * The Nuxt recipe, written out in full because every trap in it is one somebody actually hit.
+ *
+ * Reported from the field, in the order they were hit: `init` classified a Nuxt 4 app as `html`, so
+ * it installed a package named `@reticlehq/react` (with `react` in its peer dependencies) into a Vue
+ * codebase — the reporter only continued after auditing our dist to confirm there are no React
+ * imports at runtime, which most people will not do. It then handed over a snippet guarded on
+ * `window.location.hostname === 'localhost'`, which fails twice over in Nuxt: `window` does not
+ * exist during SSR, and the dev host here was a hosts-file alias (required for the backend's
+ * white-label origin detection), so the guard was false and the connect never ran — no error, no log
+ * line, nothing to debug. And nothing said a running dev server does not pick up a new plugin.
+ *
+ * So: `import.meta.dev` (build-time, host-independent) instead of a hostname check, `.client.ts`
+ * instead of an SSR guard, the framework-neutral sensor instead of the React kit, the non-localhost
+ * flag named up front, and the restart said out loud.
+ */
+export declare function nuxtManual(port: number | undefined, projectId?: string): string;
 /**
  * Root-level project config for Reticle. Written by `reticle init`; read by `reticle mcp` for the port
  * and by tooling for the stable projectId (the app's identity across port changes).