@reticlehq/server 2.5.0 → 2.7.0

package/dist/init/plan.js

@@ -6,15 +6,18 @@
 import { Framework, PackageManager, UiLibrary, installCommand, installCommandParts, } from './detect.js';
 import { claudeAddCommand, mcpManual } from './mcp.js';
 import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.js';
+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';
 /**
@@ -32,7 +35,7 @@ export function pinnedPackages(packages, version) {
     return packages.map((p) => `${p}@${version}`);
 }
 /** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
-function frameworkPackages(framework) {
+export function frameworkPackages(framework) {
     switch (framework) {
         case Framework.NEXT:
             return [RETICLE_REACT_KIT, RETICLE_NEXT_PLUGIN];
@@ -40,6 +43,11 @@ 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).
@@ -67,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',
@@ -142,6 +151,49 @@ function cursorMcpStep(input) {
         write: { path: input.cursorConfigPath, content: r.content },
     };
 }
+/**
+ * One step per OTHER detected client.
+ *
+ * The shapes differ enough that a shared "write mcp.json" would be wrong for three of them — see
+ * mcp-clients.ts. What is shared is the DECISION: already-correct is left alone, a file we cannot
+ * parse is reported with a paste-able block rather than overwritten, and everything else is written.
+ */
+function otherClientSteps(input) {
+    const steps = [];
+    for (const detected of input.detectedClients ?? []) {
+        const spec = clientSpec(detected.id);
+        const merged = mergeClientConfig(spec, detected.existing);
+        const title = `MCP server (${spec.label})`;
+        if (merged.status === ClientMergeStatus.ALREADY) {
+            steps.push({
+                title,
+                target: detected.configPath,
+                status: StepStatus.ALREADY,
+                detail: `reticle already registered with ${spec.label}`,
+            });
+            continue;
+        }
+        if (merged.status === ClientMergeStatus.MANUAL) {
+            // Either the file did not parse, or the format is one we refuse to edit blind (TOML). Both
+            // end the same way: say so, and hand over the exact block.
+            steps.push({
+                title,
+                target: detected.configPath,
+                status: StepStatus.MANUAL,
+                detail: `add this to ${detected.configPath} by hand:\n${clientSnippet(spec)}`,
+            });
+            continue;
+        }
+        steps.push({
+            title,
+            target: detected.configPath,
+            status: StepStatus.APPLY,
+            detail: `register reticle with ${spec.label}`,
+            write: { path: detected.configPath, content: merged.content },
+        });
+    }
+    return steps;
+}
 /** One global registration per detected agent (Claude + Cursor). Falls back to a manual note. */
 function mcpSteps(input) {
     if (!input.options.mcp) {
@@ -157,7 +209,10 @@ function mcpSteps(input) {
             },
         ];
     }
-    const steps = stepsForAgents(input, (a) => a.mcpStep);
+    // Claude and Cursor first (they have their own registration paths), then every other detected
+    // client. A machine with Cursor AND Windsurf gets both — registering only the first one found is
+    // how a user ends up with Reticle in the editor they were not using.
+    const steps = [...stepsForAgents(input, (a) => a.mcpStep), ...otherClientSteps(input)];
     if (steps.length > 0)
         return steps;
     // No supported agent detected — print the one-time global instructions. Reached when the `claude`
@@ -348,13 +403,30 @@ function agentRuleSteps(input) {
  * with nothing naming a version. Pinning turns that into this loud failure, which is the better
  * trade — but only if the message says what to do about it.
  */
-/** Said out loud when the exact-version install was refused and the unpinned one worked. */
-function unpinnedRetryNote(version) {
+/**
+ * Said out loud when the exact-version install failed and the unpinned one worked.
+ *
+ * It used to assert a cause it cannot know. Every one of nine fixture apps got the same sentence —
+ * "the registry refused 2.5.0 (pnpm's minimumReleaseAge holds new releases back)" — when the actual
+ * cause on that run was that the version did not exist yet, and the remedy offered was a `pnpm
+ * config` command handed to a yarn 1 project that will never read it.
+ *
+ * This note is built at PLAN time, before anything runs, and `io.exec` returns a bare boolean, so
+ * the apply layer has no failure text to hand back either. The honest move is therefore to report
+ * the CONSEQUENCE (which is certain and is the part that bites) and offer the remedy that belongs to
+ * the manager actually in use — rather than name a cause that is one possibility among several.
+ */
+function unpinnedRetryNote(version, pm) {
     const wanted = version === undefined ? 'the exact version' : version;
-    return (`the registry refused ${wanted} (pnpm's minimumReleaseAge holds new releases back), so the ` +
-        `newest ACCEPTED version was installed instead. That may not match the daemon — if the agent ` +
-        `reports protocol errors, check \`versionSkew\` in reticle_sessions, then either wait out the ` +
-        `window or allow these packages: pnpm config set minimumReleaseAgeExclude "@reticlehq/*"`);
+    // Kept verbatim for pnpm, where minimumReleaseAge is a real and common cause with a real remedy.
+    const remedy = pm === PackageManager.PNPM
+        ? ' One common cause on pnpm is minimumReleaseAge holding a new release back; if pnpm ' +
+            'reported ERR_PNPM_NO_MATURE_MATCHING_VERSION, either wait out the window or allow these ' +
+            'packages: pnpm config set minimumReleaseAgeExclude "@reticlehq/*"'
+        : '';
+    return (`the pinned install of ${wanted} failed, so the newest version the registry WOULD accept was ` +
+        `installed instead. That may not match the daemon — if the agent reports protocol errors, check ` +
+        `\`versionSkew\` in reticle_sessions.${remedy}`);
 }
 function installFailureHint(pm) {
     if (pm !== PackageManager.PNPM)
@@ -392,7 +464,7 @@ function installStep(input) {
         // release-age hold gets a working install instead of no install.
         retry: {
             ...installCommandParts(pm, frameworkPackages(input.detection.framework)),
-            note: unpinnedRetryNote(input.options.sdkVersion),
+            note: unpinnedRetryNote(input.options.sdkVersion, pm),
         },
     };
 }
@@ -420,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 [
@@ -454,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
@@ -466,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.d.ts

@@ -7,8 +7,15 @@
  * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
  * otherwise we walk UP the directory tree (monorepos keep the lockfile at the workspace root, not in
  * each package) so `reticle init` in a sub-package suggests `pnpm add` instead of defaulting to `npm i`.
+ *
+ * The walk is skipped when the project has its own installed tree, because an INHERITED lockfile is
+ * weaker evidence than a `node_modules` sitting right there — the ancestor describes the workspace,
+ * the tree describes THIS package. Reported from the field: `init` in a `frontend/` app installed
+ * with npm emitted `pnpm add -D` off a repo-root `pnpm-lock.yaml`, pnpm was not on PATH, and the
+ * failed install took every downstream wiring step with it. A LOCAL lockfile still wins over the
+ * tree — it is a deliberate statement about this package, not an inheritance.
  */
-export declare function resolveLockfiles(rootFiles: ReadonlySet<string>, cwd: string, io: Pick<InitIo, 'exists'>): Set<string>;
+export declare function resolveLockfiles(rootFiles: ReadonlySet<string>, cwd: string, io: Pick<InitIo, 'exists'>, nodeModulesMarkers?: ReadonlySet<string>): Set<string>;
 export interface InitOptions {
     cwd: string;
     port: number | undefined;
@@ -59,5 +66,15 @@ interface InitResult {
  * it knows it is in a workspace; this is the matching walk DOWN.
  */
 export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export declare const FEEDBACK_HINT: string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;
 export {};

package/dist/init/run.js

@@ -4,16 +4,17 @@
  * 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';
-import { detect, Framework } from './detect.js';
+import { detect, Framework, namesAPackageManager } from './detect.js';
 import { wasMcpRegistered } from './mcp-registered.js';
 import { pickAstroHost } from './astro-host.js';
 import { workspaceParents } from './workspace-apps.js';
 import { chooseWorkspaceApp } from './app-choice.js';
 import { isConnectStep } from './plan.js';
-import { CURSOR_RULE_PATH } from './agent-rules.js';
+import { CLI, CURSOR_RULE_PATH } from './agent-rules.js';
 import { CRA_ENV_PATH } from './cra.js';
 /** CRA's bundled entry, in the order create-react-app itself generates them. */
 const CRA_ENTRY_CANDIDATES = ['src/index.tsx', 'src/index.jsx', 'src/index.ts', 'src/index.js'];
@@ -40,11 +41,12 @@ function readPairingToken() {
         return '';
     }
 }
-import { DEPS_TARGET, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
+import { DEPS_TARGET, frameworkPackages, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
 import { claudeAvailableProbe, claudeExistsProbe } from './mcp.js';
 import { reticleDevLocation } from './next-patch.js';
 import { scanTestids, storeHints } from './capabilities.js';
 import { CURSOR_DIR_RELPATH, CURSOR_MCP_RELPATH } from './cursor.js';
+import { fileBackedClients, clientMarkerRelPath, ConfigScope, McpClient } from './mcp-clients.js';
 import { deriveProjectId, packageName } from './project-id.js';
 import { VITE_DEV_MODULE_PATH } from './snippets.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH } from './slash-command.js';
@@ -62,11 +64,20 @@ const LOCKFILE_NAMES = [
  * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
  * otherwise we walk UP the directory tree (monorepos keep the lockfile at the workspace root, not in
  * each package) so `reticle init` in a sub-package suggests `pnpm add` instead of defaulting to `npm i`.
+ *
+ * The walk is skipped when the project has its own installed tree, because an INHERITED lockfile is
+ * weaker evidence than a `node_modules` sitting right there — the ancestor describes the workspace,
+ * the tree describes THIS package. Reported from the field: `init` in a `frontend/` app installed
+ * with npm emitted `pnpm add -D` off a repo-root `pnpm-lock.yaml`, pnpm was not on PATH, and the
+ * failed install took every downstream wiring step with it. A LOCAL lockfile still wins over the
+ * tree — it is a deliberate statement about this package, not an inheritance.
  */
-export function resolveLockfiles(rootFiles, cwd, io) {
+export function resolveLockfiles(rootFiles, cwd, io, nodeModulesMarkers = new Set()) {
     const set = new Set(rootFiles);
     if (LOCKFILE_NAMES.some((name) => set.has(name)))
         return set; // local lockfile is authoritative
+    if (namesAPackageManager(nodeModulesMarkers))
+        return set;
     let dir = cwd;
     for (let depth = 0; depth < 50; depth++) {
         for (const name of LOCKFILE_NAMES) {
@@ -83,6 +94,7 @@ export function resolveLockfiles(rootFiles, cwd, io) {
     return set;
 }
 const PACKAGE_JSON = 'package.json';
+const NODE_MODULES_DIR = 'node_modules';
 /**
  * Root-layout candidates, App Router only. `--src-dir` apps keep theirs under `src/app`, and the
  * ReticleDev component has to land NEXT TO the layout or the relative import it generates is dead.
@@ -197,13 +209,15 @@ function gatherPlanInput(options, io, pkgRaw) {
     // Stable identity derived from the app's package.json name + root, so it survives port changes.
     const projectId = deriveProjectId(packageName(pkg), options.cwd);
     const rootFiles = new Set(io.rootFiles());
+    const nodeModulesMarkers = new Set(io.listFiles('node_modules'));
     const detectInput = {
         pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
         configFiles: rootFiles,
-        // Walk up for the lockfile so a monorepo sub-package picks the workspace's package manager.
-        lockfiles: resolveLockfiles(rootFiles, options.cwd, io),
+        // Walk up for the lockfile so a monorepo sub-package picks the workspace's package manager —
+        // unless this package's own installed tree already answers it, which outranks an inherited one.
+        lockfiles: resolveLockfiles(rootFiles, options.cwd, io, nodeModulesMarkers),
         // An already-installed tree names its own manager, which matters when no lockfile is committed.
-        nodeModulesMarkers: new Set(io.listFiles('node_modules')),
+        nodeModulesMarkers,
     };
     const detection = detect(detectInput);
     const vitePath = firstPresent(rootFiles, VITE_CONFIG_CANDIDATES);
@@ -225,6 +239,27 @@ function gatherPlanInput(options, io, pkgRaw) {
     // project-level .cursor/ is unambiguous evidence somebody uses it here.
     const cursorPresent = options.mcp && (io.exists(cursorDir) || io.exists(CURSOR_DIR_RELPATH));
     const cursorConfig = cursorPresent ? io.readFile(cursorConfigPath) : null;
+    // Every OTHER MCP client this machine shows evidence of. Conservative and one-directional: we
+    // write into a config a client ALREADY has, and never create ~/.gemini or ~/.codeium for somebody
+    // who does not use them. Cursor and Claude are handled above by their own steps.
+    const detectedClients = options.mcp
+        ? fileBackedClients()
+            .filter((spec) => spec.id !== McpClient.CURSOR)
+            .map((spec) => {
+            const marker = clientMarkerRelPath(spec);
+            const absolute = spec.scope === ConfigScope.HOME ? join(io.homeDir(), spec.relPath) : spec.relPath;
+            const markerPath = spec.scope === ConfigScope.HOME ? join(io.homeDir(), marker) : marker;
+            if (!io.exists(markerPath))
+                return null;
+            return {
+                id: spec.id,
+                configPath: absolute,
+                // io.readFile passes absolute paths through unchanged, so one call covers both scopes.
+                existing: io.readFile(absolute),
+            };
+        })
+            .filter((entry) => entry !== null)
+        : [];
     const astroPath = firstPresent(rootFiles, ASTRO_CONFIG_CANDIDATES);
     const astroSource = null === astroPath ? null : io.readFile(astroPath);
     // Which file owns the DOCUMENT, not how many files sit in a directory. The old rule ("exactly one
@@ -253,6 +288,7 @@ function gatherPlanInput(options, io, pkgRaw) {
         claudeCli,
         mcpExists,
         cursorPresent,
+        detectedClients,
         cursorProjectPresent: io.exists(CURSOR_DIR_RELPATH),
         cursorConfig,
         cursorConfigPath,
@@ -354,21 +390,62 @@ export function findWorkspaceApps(io) {
     }
     return [...new Set(found)];
 }
-function restartHint(framework) {
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
+    '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 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`.';
-function report(plan, dryRun, failed, skipped, degraded, io) {
+function report(plan, dryRun, failed, skipped, degraded, io, projectDir) {
     io.print(dryRun ? 'reticle init (dry run — no files written)' : 'reticle init');
+    // Every path below is printed RELATIVE, and until now nothing said what to. Reported from the
+    // field as "[✓] Reticle config → .reticle.json" followed by the file not being there: the app was
+    // in `frontend/`, init redirected into it, and the report's `.reticle.json` was true about a
+    // directory the reader was not standing in. One line makes every path in the report unambiguous.
+    io.print(`  in ${projectDir}`);
     io.print('');
     let applied = 0;
     let manual = 0;
@@ -417,7 +494,7 @@ function report(plan, dryRun, failed, skipped, degraded, io) {
             '"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 };
 }
 /**
@@ -429,6 +506,25 @@ function report(plan, dryRun, failed, skipped, degraded, io) {
  * MODULE_NOT_FOUND, so the app stops booting *because* Reticle was installed. A skipped step is a
  * message; a half-wired app is a broken project.
  */
+/**
+ * Are the SDK packages actually on disk, whatever the install step reported?
+ *
+ * `dependsOnInstall` exists to stop init writing a `next.config.ts` that imports a package which is
+ * not there — that took a dev server down once, and installing Reticle must never be why an app
+ * stops booting. The invariant it protects is "the import RESOLVES", but it was gated on "our
+ * install subprocess exited 0", and those come apart in exactly the situation the failure creates:
+ * init tells the user to install by hand, they do, they re-run init, the install step fails again
+ * (wrong package manager, not on PATH) and every wiring step is skipped a second time. Reported from
+ * a Next 16 app where npm had already installed both packages successfully — leaving an init that
+ * could not be retried into working, which is the shape this guard was written to prevent.
+ *
+ * Reading node_modules answers the real question and costs one `exists` call per package.
+ */
+function sdkPackagesPresent(framework, io) {
+    const packages = frameworkPackages(framework);
+    return (packages.length > 0 &&
+        packages.every((p) => io.exists(`${NODE_MODULES_DIR}/${p}/${PACKAGE_JSON}`)));
+}
 function applyEffects(plan, io) {
     const failed = new Set();
     const skipped = new Set();
@@ -443,9 +539,24 @@ function applyEffects(plan, io) {
         }
         const write = s.write;
         if (write !== undefined) {
-            spanSync('init.write', { target: s.target, path: write.path }, () => {
-                io.writeFile(write.path, write.content);
+            // Confirm the EFFECT, not the intention. Reported from the field (#160): init printed
+            // `[✓] Reticle config → .reticle.json` and the file was not there afterward. Nothing checked —
+            // no arrangement of the filesystem (a read-only mount, a full disk, an antivirus quarantining
+            // a new dotfile) could have turned that tick into anything else. A checkmark that cannot fail
+            // is decoration, and this one is the first thing a new user reads. Same shape as #139.
+            const wrote = spanSync('init.write', { target: s.target, path: write.path }, () => {
+                try {
+                    io.writeFile(write.path, write.content);
+                }
+                catch {
+                    return false; // a throw is the loud version of the same failure
+                }
+                return io.exists(write.path);
             });
+            if (!wrote) {
+                failed.add(s.target);
+                continue; // do not run this step's exec against a file that is not there
+            }
         }
         // Bound once so the traced call cannot need a `?? ''` fallback — a default there would turn a
         // narrowing mistake into an empty command that silently "succeeds".
@@ -469,7 +580,9 @@ function applyEffects(plan, io) {
                 continue;
             }
             failed.add(s.target);
-            if (s.target === DEPS_TARGET)
+            // A failed install only blocks the wiring when the packages are genuinely ABSENT. See
+            // sdkPackagesPresent: the guard protects "the import resolves", not "our subprocess exited 0".
+            if (s.target === DEPS_TARGET && !sdkPackagesPresent(plan.framework, io))
                 installFailed = true;
         }
     }
@@ -534,17 +647,50 @@ function redirectToWorkspaceApp(options, io, pkgRaw) {
     return runInit({ ...options, cwd: join(options.cwd, target), redirected: true }, io.scoped(target));
 }
 export function runInit(options, io) {
+    const result = runInitSteps(options, io);
+    // The ask goes here, not in report(): report() is only the success-shaped path, and the exits that
+    // matter most are the ones that never reach it — no package.json, an ambiguous workspace — where
+    // setup died before anything ran and the person holding the report has the least to go on. This
+    // wrapper is the one point every exit passes through.
+    //
+    // `redirected` is what keeps it to ONE print: wiring an app in a monorepo re-enters runInit for the
+    // chosen directory, and the inner call must not ask again.
+    if (true !== options.redirected) {
+        io.print('');
+        io.print(FEEDBACK_HINT);
+    }
+    return result;
+}
+function runInitSteps(options, io) {
     const pkgRaw = io.readFile(PACKAGE_JSON);
+    // Look for the app BEFORE concluding there isn't one.
+    //
+    // A root with no package.json is not a dead end — it is the ordinary shape of a repo whose app
+    // lives one directory down (`frontend/`, `web/`, `client/`) with no manifest at the top. Bailing
+    // first made that repo un-instrumentable: `reticle init` said "No package.json found", and
+    // `--app frontend`, the flag that exists for exactly this, was never read because the bail came
+    // first. Reported twice by the same user, who tried the documented workaround and hit the same
+    // wall. Discovery already handles the case (it scans top-level directories, not just declared
+    // workspaces); it was simply unreachable.
+    //
+    // `'{}'` because the redirect only needs the manifest to ask "is THIS directory the app", and a
+    // directory with no package.json is definitively not.
+    const redirectedEarly = redirectToWorkspaceApp(options, io, pkgRaw ?? '{}');
+    if (redirectedEarly !== null)
+        return redirectedEarly;
     if (null === pkgRaw) {
-        io.print('No package.json found. Run `reticle init` from your project root.');
+        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 });
         return { ok: false, applied: 0, manual: 0 };
     }
-    const redirected = redirectToWorkspaceApp(options, io, pkgRaw);
-    if (redirected !== null)
-        return redirected;
     // Init is the flow a user experiences the wait of personally, and the fixture gate measures it at
     // 1–6s per app with no explanation of the spread. These three spans split that number into detect
     // (filesystem probing), plan (pure), and apply (writes + package-manager and CLI subprocesses).
@@ -553,7 +699,7 @@ export function runInit(options, io) {
         ? { failed: new Set(), skipped: new Set(), degraded: new Map() }
         : spanSync('init.apply', { steps: plan.steps.length }, () => applyEffects(plan, io));
     const { failed, skipped, degraded } = effects;
-    const result = report(plan, options.dryRun, failed, skipped, degraded, io);
+    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd);
     // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
     if (!options.dryRun) {
         reportInitOutcome({

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).