@reticlehq/init 2.14.0 → 3.2.0

package/dist/{detect.d.ts → detect/detect.d.ts}

@@ -40,7 +40,7 @@ export declare const Framework: {
      * TanStack Start SSRs `<html>` from `src/routes/__root.tsx` and never sends Vite's index.html, so
      * the plugin's `transformIndexHtml` injection never fires. It used to fall through to
      * `Framework.VITE`, where `init` wired the plugin, reported every step green ("also injects
-     * connect()"), and produced zero sessions — confirmed in the field as ~13 minutes of "still
+     * connect()"), and produced zero sessions — confirmed in the field as many minutes of "still
      * verifying" against a daemon showing none (#773).
      *
      * Keyed on `@tanstack/react-start` or the older `@tanstack/start`, never on

package/dist/{detect.js → detect/detect.js}

@@ -40,7 +40,7 @@ export const Framework = {
      * TanStack Start SSRs `<html>` from `src/routes/__root.tsx` and never sends Vite's index.html, so
      * the plugin's `transformIndexHtml` injection never fires. It used to fall through to
      * `Framework.VITE`, where `init` wired the plugin, reported every step green ("also injects
-     * connect()"), and produced zero sessions — confirmed in the field as ~13 minutes of "still
+     * connect()"), and produced zero sessions — confirmed in the field as many minutes of "still
      * verifying" against a daemon showing none (#773).
      *
      * Keyed on `@tanstack/react-start` or the older `@tanstack/start`, never on
@@ -301,7 +301,11 @@ const INSTALL_ARGS = {
  * hard failure, which is the opposite of the problem being fixed.
  */
 const QUIET_INSTALL_ARGS = {
-    [PackageManager.NPM]: ['--no-audit', '--no-fund'],
+    // `--no-update-notifier` joined the other two for the same reason and from the same measurement:
+    // a re-capture of a pristine Vite first run spent five of its lines on an `npm notice` block
+    // announcing a newer npm, its changelog url and the command to install it. Advice about npm,
+    // printed in the middle of somebody wiring up a different tool.
+    [PackageManager.NPM]: ['--no-audit', '--no-fund', '--no-update-notifier'],
 };
 /** Build a dev-dependency install command for one or more packages (e.g. the kit + its build plugin). */
 export function installCommandParts(pm, pkgs, 

package/dist/{dev-server-ports.js → detect/dev-server-ports.js}

@@ -35,6 +35,14 @@ export const DEV_SERVER_PORTS = new Set([
     5175, // Vite, third instance
     7860, // Gradio
     8501, // Streamlit
+    // The same lesson again, from a run against Reticle's own bench-app: the scan reported "nothing is
+    // listening" while the app was serving on 4310. Absence is stated here as a fact, so a port left
+    // out is not a gap in the answer, it is a wrong answer delivered confidently.
+    1234, // Parcel
+    4000, // the common Node/GraphQL dev default
+    4310, // Reticle's own bench-app, the fixture its agents drive
+    6006, // Storybook
+    19006, // Expo web
 ]);
 export function isLikelyDevServerPort(port) {
     return DEV_SERVER_PORTS.has(port);

package/dist/{existing-config.d.ts → detect/existing-config.d.ts}

@@ -3,10 +3,8 @@ export declare const RETICLE_CONFIG_FILE = ".reticle.json";
 /**
  * Reading a `.reticle.json` that is ALREADY on disk.
  *
- * Split out of plan.ts when it crossed the line cap. These two are one job -- looking at a config
- * somebody else wrote and deciding what it tells us -- and neither knows anything about steps,
- * plans or the shape of a report, which is what made them the cohesive piece to lift rather than
- * the nearest thousand-line boundary.
+ * These two are one job -- looking at a config somebody else wrote and deciding what it tells us --
+ * and neither knows anything about steps, plans or the shape of a report.
  */
 /**
  * What is wrong with the config that is already there, if anything.

package/dist/{existing-config.js → detect/existing-config.js}

@@ -4,10 +4,8 @@ export const RETICLE_CONFIG_FILE = '.reticle.json';
 /**
  * Reading a `.reticle.json` that is ALREADY on disk.
  *
- * Split out of plan.ts when it crossed the line cap. These two are one job -- looking at a config
- * somebody else wrote and deciding what it tells us -- and neither knows anything about steps,
- * plans or the shape of a report, which is what made them the cohesive piece to lift rather than
- * the nearest thousand-line boundary.
+ * These two are one job -- looking at a config somebody else wrote and deciding what it tells us --
+ * and neither knows anything about steps, plans or the shape of a report.
  */
 /**
  * What is wrong with the config that is already there, if anything.

package/dist/{lockfiles.d.ts → detect/lockfiles.d.ts}

@@ -1,4 +1,4 @@
-import type { InitIo } from './run.js';
+import type { InitIo } from '../run-types.js';
 /**
  * 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

package/dist/{lockfiles.js → detect/lockfiles.js}

@@ -1,8 +1,7 @@
 /**
  * Which lockfile decides the package manager `init` will tell the user to run.
  *
- * Split out of `run.ts` when that file crossed the 1000-line cap: this is one self-contained
- * question with its own test block, and `run.ts` is the orchestration around it.
+ * One self-contained question with its own test block; `run.ts` is the orchestration around it.
  */
 import { dirname, join } from 'node:path';
 import { namesAPackageManager } from './detect.js';

package/dist/{workspace-apps.d.ts → detect/workspace-apps.d.ts}

@@ -1,4 +1,4 @@
-import type { InitIo } from './run.js';
+import type { InitIo } from '../run-types.js';
 /**
  * The file names that say what a directory IS, shared by everything that has to ask.
  *
@@ -21,10 +21,8 @@ export declare function workspaceParents(sources: WorkspaceSources): string[];
 /**
  * Which directories under this workspace are runnable apps.
  *
- * Moved here from run.ts, which was over the 1000-line cap and had carried a note saying it was at
- * its cohesion limit. `library-path-boundary.test.ts` had already written down that this function
- * "squats in init/ for historical reasons" — it is a general-purpose question about a repository's
- * shape, next to `workspaceParents`, which answers the other half of it.
+ * A general-purpose question about a repository's shape, so it lives next to `workspaceParents`,
+ * which answers the other half of it.
  */
 /** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
 export declare const APP_DEPS: readonly ["next", "vite", "electron-vite"];

package/dist/{workspace-apps.js → detect/workspace-apps.js}

@@ -96,10 +96,8 @@ export function workspaceParents(sources) {
 /**
  * Which directories under this workspace are runnable apps.
  *
- * Moved here from run.ts, which was over the 1000-line cap and had carried a note saying it was at
- * its cohesion limit. `library-path-boundary.test.ts` had already written down that this function
- * "squats in init/ for historical reasons" — it is a general-purpose question about a repository's
- * shape, next to `workspaceParents`, which answers the other half of it.
+ * A general-purpose question about a repository's shape, so it lives next to `workspaceParents`,
+ * which answers the other half of it.
  */
 /** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
 export const APP_DEPS = ['next', 'vite', 'electron-vite'];

package/dist/{workspace-redirect.d.ts → detect/workspace-redirect.d.ts}

@@ -1,16 +1,14 @@
 /**
  * Workspace redirect: when `init` is run at a monorepo ROOT, wire the app rather than the root.
  *
- * Split out of `run.ts`, which sits one line under the 1000-line backstop — every init change that
- * touches the orchestration now trips the cap before it can be reviewed. This is the part of that
- * file that answers a single, separable question ("is the app somewhere else, and where?"), so it
- * is the seam that costs nothing to move.
+ * Its own module because it answers a single, separable question: is the app somewhere else, and
+ * where?
  *
  * `runInit` arrives as a parameter rather than an import: re-entering init is the whole point of a
  * redirect, and taking it as an argument keeps this module a leaf instead of forming a cycle with
  * the file it was cut from.
  */
-import type { InitIo, InitOptions, InitResult } from './run.js';
+import type { InitIo, InitOptions, InitResult } from '../run-types.js';
 /** Re-enter `init`, scoped to one directory of the workspace. */
 export type RunInit = (options: InitOptions, io: InitIo) => InitResult;
 /**

package/dist/{workspace-redirect.js → detect/workspace-redirect.js}

@@ -1,10 +1,8 @@
 /**
  * Workspace redirect: when `init` is run at a monorepo ROOT, wire the app rather than the root.
  *
- * Split out of `run.ts`, which sits one line under the 1000-line backstop — every init change that
- * touches the orchestration now trips the cap before it can be reviewed. This is the part of that
- * file that answers a single, separable question ("is the app somewhere else, and where?"), so it
- * is the seam that costs nothing to move.
+ * Its own module because it answers a single, separable question: is the app somewhere else, and
+ * where?
  *
  * `runInit` arrives as a parameter rather than an import: re-entering init is the whole point of a
  * redirect, and taking it as an argument keeps this module a leaf instead of forming a cycle with
@@ -13,7 +11,7 @@
 import { join } from 'node:path';
 import { detect, Framework } from './detect.js';
 import { findWorkspaceApps, PACKAGE_JSON } from './workspace-apps.js';
-import { chooseWorkspaceApp, withoutTrailingSlashes } from './app-choice.js';
+import { chooseWorkspaceApp, withoutTrailingSlashes } from './declared/app-choice.js';
 const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle init` inside the one you want:';
 /**
  * When the current directory is a workspace root with no app of its own, wire the app instead of the
@@ -33,13 +31,11 @@ export function redirectToWorkspaceApp(options, io, pkg, runInit) {
     // `--app` is an INSTRUCTION, and it is read before the guess below. The guess answers "where is
     // the app?" for somebody who did not say; when somebody said, there is nothing left to infer.
     //
-    // It used to be read after, and the check underneath returns early for any directory that looks
-    // like an app — which a JS monorepo ROOT does, because shared tooling puts `vite` in its
-    // devDependencies. So on a real pnpm+turbo monorepo (measured on nuclear, a Tauri v2 app at
-    // product scale) `reticle init --app packages/player` silently ignored the flag, installed the
-    // SDK into the root's package.json, wrote `.reticle.json` and a whole `src/reticle-dev.ts` into a
-    // repository root that has no `src/`, left `packages/player` untouched — and reported three ✓ and
-    // one ⚠. The one flag documented for this shape wired the wrong directory and said it worked.
+    // Read BEFORE the check underneath, which returns early for any directory that looks like an app —
+    // which a JS monorepo ROOT does, because shared tooling puts `vite` in its devDependencies. Read
+    // after, `reticle init --app packages/player` silently ignored the flag on a pnpm+turbo monorepo:
+    // it installed the SDK into the root's package.json, wrote `.reticle.json` and `src/reticle-dev.ts`
+    // into a repository root that has no `src/`, left the named app untouched, and reported success.
     //
     // Existence is the test, not membership of the discovered list: discovery scans conventional
     // directories, and somebody who names a path knows their own layout better than the scan does.

package/dist/{closing-hint.d.ts → diagnose/closing-hint.d.ts}

@@ -1,12 +1,11 @@
 /**
  * The last thing `init` prints, and the only part of it a user is asked to act on.
  *
- * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
- * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
- * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * Its own file because it is its own concern: everything else in `run.ts` decides what to write,
+ * and this decides what to say afterwards. The failure modes differ too — a wrong write breaks an
  * install, a wrong sentence loses a user quietly.
  */
-import { StepStatus } from './plan.js';
+import { StepStatus } from '../plan/plan.js';
 /**
  * The standing ask, printed at the end of every `init`.
  *

package/dist/{closing-hint.js → diagnose/closing-hint.js}

@@ -1,14 +1,13 @@
 /**
  * The last thing `init` prints, and the only part of it a user is asked to act on.
  *
- * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
- * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
- * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * Its own file because it is its own concern: everything else in `run.ts` decides what to write,
+ * and this decides what to say afterwards. The failure modes differ too — a wrong write breaks an
  * install, a wrong sentence loses a user quietly.
  */
-import { StepStatus } from './plan.js';
-import { wasMcpRegistered } from './mcp-registered.js';
-import { CLI } from './agent-rules.js';
+import { StepStatus } from '../plan/plan.js';
+import { wasMcpRegistered } from '../register/mcp-registered.js';
+import { CLI } from '../project/agent-rules.js';
 /**
  * The standing ask, printed at the end of every `init`.
  *
@@ -59,14 +58,13 @@ devCommand) {
     // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
     //
     // `init` writes files and stops; the install is not finished until an app carrying the SDK has
-    // actually dialled the daemon, and nothing here confirmed that. The field shape is unambiguous:
-    // people complete the agent half, never complete the app half, and keep a daemon running for
-    // weeks with nothing to drive — so this is the last instruction most of them read.
+    // actually dialled the daemon, and nothing here confirmed that — so this is the last instruction
+    // a user reads before the half that can still fail.
     //
     // "Ask your agent: List Reticle sessions" asks a question whose failure is a dead end. `reticle
-    // status` ANSWERS it: as of 2.7.0 it reports the session, or says why there is none — no app
-    // running, an app running that never dialled us, a tab that closed — with the fix for each.
-    // The one thing that works BEFORE the restart, so it goes before it.
+    // status` ANSWERS it: it reports the session, or says why there is none — no app running, an app
+    // running that never dialled us, a tab that closed — with the fix for each. It works BEFORE the
+    // restart, so it goes before it.
     //
     // What comes after the restart, named as a JOB rather than as a capability.
     //
@@ -89,13 +87,10 @@ devCommand) {
         return `${dev}\n${demo}\n${prove}`;
     // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
     //
-    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is correct for the funnel field it
-    // was written for and wrong here, because the two cases have opposite answers to "must anybody
-    // restart". Every second project on a machine, and every Claude Code plugin install, took the
-    // APPLY text: "restart your agent — the tools only appear after that". An agent reads this AFTER
-    // whatever its skill file said, and it describes the output in front of it, so it wins. The agent
-    // stops with the project wired and nothing driven, which is the exact failure the install path
-    // exists to prevent, caused by the install path itself.
+    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is wrong here: the two cases have
+    // opposite answers to "must anybody restart". ALREADY used to take the APPLY text — "restart your
+    // agent, the tools only appear after that" — and an agent believes the output in front of it over
+    // whatever its skill file said, so it stops with the project wired and nothing driven.
     if (mcpStatus === StepStatus.ALREADY) {
         return (`${dev}\n` +
             `${demo}\n` +

package/dist/diagnose/containerised-dev-server.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The install shape Reticle assumes, stated once, for the projects that do not have it.
+ *
+ * Everything in `init` assumes the CLI and the dev server share a filesystem: the daemon writes
+ * `~/.reticle/pairing-token`, the build plugin reads it at config time and inlines it into the page,
+ * and the bridge checks that they match. When the dev server runs in a container that assumption is
+ * silently false — `$HOME` in there is the image's throwaway root, so the plugin finds no token,
+ * mints its own, and every page it serves is refused with `authentication failed`.
+ *
+ * Measured in the field: six minutes to diagnose, ending in a grep through the plugin's shipped
+ * `dist/` inside the container for an environment variable that appeared in no documentation. The
+ * daemon now says all this when it happens (see no-session-next-action). This says it BEFORE it
+ * happens, which is the difference between a note and a debugging session.
+ *
+ * It also names the rebuild. A containerised dev server usually installs its own `node_modules` into
+ * an anonymous volume, so `init` adding two dependencies is not picked up by restarting the
+ * container — it needs an image rebuild and a fresh volume. The same field install lost two and a
+ * half minutes discovering that through a failed build.
+ *
+ * DETECTION IS DELIBERATELY CHEAP AND OVER-EAGER. A Dockerfile or a compose file near the app is not
+ * proof the dev server runs in one — plenty of repos containerise only production. But this step
+ * asks for nothing and changes nothing, so a false positive costs one paragraph the reader skips,
+ * while a false negative costs what it cost in the field.
+ */
+/** Files whose presence means this repo builds a container image somewhere near the app. */
+export declare const CONTAINER_MARKERS: readonly ["Dockerfile", "dockerfile", "docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml", ".devcontainer/devcontainer.json"];
+export declare const CONTAINERISED_TITLE = "Containerised dev server";
+/**
+ * The note itself. Both halves are things that go wrong at the same moment and look identical from
+ * the page — the SDK loads, the socket opens, no session appears — so they are told together.
+ */
+export declare function containerisedDevServerNote(marker: string): string;

package/dist/diagnose/containerised-dev-server.js

@@ -0,0 +1,56 @@
+/**
+ * The install shape Reticle assumes, stated once, for the projects that do not have it.
+ *
+ * Everything in `init` assumes the CLI and the dev server share a filesystem: the daemon writes
+ * `~/.reticle/pairing-token`, the build plugin reads it at config time and inlines it into the page,
+ * and the bridge checks that they match. When the dev server runs in a container that assumption is
+ * silently false — `$HOME` in there is the image's throwaway root, so the plugin finds no token,
+ * mints its own, and every page it serves is refused with `authentication failed`.
+ *
+ * Measured in the field: six minutes to diagnose, ending in a grep through the plugin's shipped
+ * `dist/` inside the container for an environment variable that appeared in no documentation. The
+ * daemon now says all this when it happens (see no-session-next-action). This says it BEFORE it
+ * happens, which is the difference between a note and a debugging session.
+ *
+ * It also names the rebuild. A containerised dev server usually installs its own `node_modules` into
+ * an anonymous volume, so `init` adding two dependencies is not picked up by restarting the
+ * container — it needs an image rebuild and a fresh volume. The same field install lost two and a
+ * half minutes discovering that through a failed build.
+ *
+ * DETECTION IS DELIBERATELY CHEAP AND OVER-EAGER. A Dockerfile or a compose file near the app is not
+ * proof the dev server runs in one — plenty of repos containerise only production. But this step
+ * asks for nothing and changes nothing, so a false positive costs one paragraph the reader skips,
+ * while a false negative costs what it cost in the field.
+ */
+import { ReticleEnv } from '@reticlehq/core';
+/** Files whose presence means this repo builds a container image somewhere near the app. */
+export const CONTAINER_MARKERS = [
+    'Dockerfile',
+    'dockerfile',
+    'docker-compose.yml',
+    'docker-compose.yaml',
+    'compose.yml',
+    'compose.yaml',
+    '.devcontainer/devcontainer.json',
+];
+export const CONTAINERISED_TITLE = 'Containerised dev server';
+/**
+ * The note itself. Both halves are things that go wrong at the same moment and look identical from
+ * the page — the SDK loads, the socket opens, no session appears — so they are told together.
+ */
+export function containerisedDevServerNote(marker) {
+    return (`this project has a \`${marker}\`, so IF your dev server runs in a container two things about ` +
+        'this install are different, and both of them end in "no session" with nothing looking broken.\n' +
+        '  1. DEPENDENCIES. A container that installs its own node_modules will not see the two packages ' +
+        'added here by restarting — rebuild the image and renew the volume ' +
+        '(`docker compose build <service> && docker compose up -d --renew-anon-volumes <service>`).\n' +
+        '  2. THE PAIRING TOKEN. The daemon writes `~/.reticle/pairing-token` on the HOST; the build ' +
+        'plugin reads it from `$HOME` INSIDE the container, does not find it, and mints a different one — ' +
+        'which the bridge then refuses. Mount the host file read-only and point the plugin at it:\n' +
+        '       environment:\n' +
+        `         ${ReticleEnv.PAIRING_TOKEN_DIR}: /reticle-state\n` +
+        '       volumes:\n' +
+        '         - ~/.reticle/pairing-token:/reticle-state/pairing-token:ro\n' +
+        '     The token is inlined when the dev server resolves its config, so restart it afterwards. ' +
+        'Run the Reticle daemon at least once first, or Docker creates a DIRECTORY at that host path.');
+}

package/dist/{csp-check.d.ts → diagnose/csp-check.d.ts}

@@ -5,8 +5,8 @@
  * the dial URL was correct, and the app never connected because a strict `connect-src` excluded
  * `ws://localhost:<port>`. The browser blocks the WebSocket and says so in its own console, which
  * nothing on the Reticle side reads — so `status` and `doctor` reported perfect health at an app
- * that could not connect at all, forever. A setup step that exits 0 while leaving the user broken is
- * the worst failure mode this repo has.
+ * that could not connect at all. A setup step that exits 0 while leaving the user broken is the
+ * failure mode this file exists to prevent.
  *
  * A TEXT SCAN, deliberately. `headers()` is a function; `init` cannot execute a user's Next config
  * without importing their whole app, and the thing worth finding is the policy string a developer

package/dist/{csp-check.js → diagnose/csp-check.js}

@@ -5,8 +5,8 @@
  * the dial URL was correct, and the app never connected because a strict `connect-src` excluded
  * `ws://localhost:<port>`. The browser blocks the WebSocket and says so in its own console, which
  * nothing on the Reticle side reads — so `status` and `doctor` reported perfect health at an app
- * that could not connect at all, forever. A setup step that exits 0 while leaving the user broken is
- * the worst failure mode this repo has.
+ * that could not connect at all. A setup step that exits 0 while leaving the user broken is the
+ * failure mode this file exists to prevent.
  *
  * A TEXT SCAN, deliberately. `headers()` is a function; `init` cannot execute a user's Next config
  * without importing their whole app, and the thing worth finding is the policy string a developer

package/dist/{desktop-doctor.js → diagnose/desktop-doctor.js}

@@ -1,4 +1,4 @@
-import { RETICLE_IPC_GLOBAL } from '@reticlehq/core';
+import { RETICLE_IPC_GLOBAL, realmOf, realmOfProject } from '@reticlehq/core';
 /**
  * Setup RCA for desktop apps.
  *
@@ -177,13 +177,19 @@ function diagnoseElectron(read, main) {
 }
 /** Is this project a desktop shell at all? Used to print a positive result instead of silence. */
 export function isDesktopProject(read) {
-    if (read(TAURI_CONF) !== undefined)
-        return true;
+    // Asked of the realm table rather than answered here. Which file or dependency marks a realm is a
+    // fact about that realm, and the copy of it that lived in this function was the second one -- so a
+    // realm added to the table but not to this line would have been reported as an ordinary web app,
+    // which is the answer least likely to look wrong.
+    const found = realmOfProject((path) => read(path) !== undefined, (name) => dependenciesOf(read)[name] !== undefined);
+    return found !== undefined && realmOf(found).isDesktopShell;
+}
+/** Every dependency a project declares, both kinds, in one record. */
+function dependenciesOf(read) {
     const pkg = parseJson(read('package.json'));
     if (pkg === undefined)
-        return false;
-    const deps = { ...record(pkg['dependencies']), ...record(pkg['devDependencies']) };
-    return deps['electron'] !== undefined;
+        return {};
+    return { ...record(pkg['dependencies']), ...record(pkg['devDependencies']) };
 }
 /** Which desktop shell (if any) this project is, and what is missing from its Reticle wiring. */
 export function diagnoseDesktop(read, port) {

package/dist/{init-failure.d.ts → diagnose/init-failure.d.ts}

@@ -2,8 +2,7 @@
  * Classified `reticle init` failures — our own vocabulary, never a raw error or a path.
  *
  * Lives here rather than beside the telemetry client because `run.ts` is what classifies a failed
- * run, and `@reticlehq/init` must not depend on the daemon. `@reticlehq/server`'s
- * `telemetry/init-telemetry.ts` re-exports it, so every existing consumer is unchanged.
+ * run, and `@reticlehq/init` must not depend on the daemon.
  */
 export declare const InitFailure: {
     /** Run outside a project root. The single most common first-run mistake. */

package/dist/{init-failure.js → diagnose/init-failure.js}

@@ -2,8 +2,7 @@
  * Classified `reticle init` failures — our own vocabulary, never a raw error or a path.
  *
  * Lives here rather than beside the telemetry client because `run.ts` is what classifies a failed
- * run, and `@reticlehq/init` must not depend on the daemon. `@reticlehq/server`'s
- * `telemetry/init-telemetry.ts` re-exports it, so every existing consumer is unchanged.
+ * run, and `@reticlehq/init` must not depend on the daemon.
  */
 export const InitFailure = {
     /** Run outside a project root. The single most common first-run mistake. */

package/dist/diagnose/install-hint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What to say when the dependency install fails.
+ *
+ * A cohesive unit on its own: prose about one step's failure modes, and the only thing it needs is
+ * which package manager was used.
+ */
+import { PackageManager } from '../detect/detect.js';
+export declare function installFailureHint(pm: PackageManager): string;

package/dist/{install-hint.js → diagnose/install-hint.js}

@@ -1,11 +1,10 @@
 /**
  * What to say when the dependency install fails.
  *
- * Split out of plan.ts, which was at the 1000-line backstop. A cohesive unit rather than an
- * arbitrary cut: it is prose about one step's failure modes, and the only thing it needs is which
- * package manager was used.
+ * A cohesive unit on its own: prose about one step's failure modes, and the only thing it needs is
+ * which package manager was used.
  */
-import { PackageManager } from './detect.js';
+import { PackageManager } from '../detect/detect.js';
 /**
  * Every package manager fetches, so every one of them can fail for a reason that is nothing to do
  * with the project: offline, a proxy that blocks npmjs, a corporate mirror that is down.

package/dist/{install-retries.d.ts → diagnose/install-retries.d.ts}

@@ -2,11 +2,10 @@
  * The weaker install attempts, in the order they are tried.
  *
  * Ordered by how much each one gives up, cheapest concession first, because the first that succeeds
- * is the one that stands. Split out of plan.ts: the ladder is its own subject — two unrelated
- * install failures, each with a different cost and a different sentence to say afterwards — and
- * plan.ts is at its file cap.
+ * is the one that stands. The ladder is its own subject: two unrelated install failures, each with
+ * a different cost and a different sentence to say afterwards.
  */
-import { PackageManager } from './detect.js';
+import { PackageManager } from '../detect/detect.js';
 export interface InstallRetry {
     command: string;
     args: string[];

package/dist/{install-retries.js → diagnose/install-retries.js}

@@ -2,11 +2,10 @@
  * The weaker install attempts, in the order they are tried.
  *
  * Ordered by how much each one gives up, cheapest concession first, because the first that succeeds
- * is the one that stands. Split out of plan.ts: the ladder is its own subject — two unrelated
- * install failures, each with a different cost and a different sentence to say afterwards — and
- * plan.ts is at its file cap.
+ * is the one that stands. The ladder is its own subject: two unrelated install failures, each with
+ * a different cost and a different sentence to say afterwards.
  */
-import { PackageManager, installCommandParts } from './detect.js';
+import { PackageManager, installCommandParts } from '../detect/detect.js';
 const LEGACY_PEER_DEPS = '--legacy-peer-deps';
 /**
  * What the peer-conflict retry gives up, said out loud.
@@ -23,10 +22,9 @@ const LEGACY_PEER_NOTE = `the pinned install failed and succeeded with ${LEGACY_
 /**
  * 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.
+ * It used to assert a cause it cannot know: every fixture app got the same sentence, blaming pnpm's
+ * `minimumReleaseAge`, when the actual cause 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

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import type { InitOutcome } from '@reticlehq/core/telemetry';
+import type { InitOutcome, OnboardingStep } from '@reticlehq/core/telemetry';
 /**
  * Everything the scaffolder needs that only the daemon knows.
  *
@@ -20,6 +20,19 @@ export interface InitHost {
     span<T>(name: string, fields: Record<string, unknown>, fn: () => T): T;
     /** Report how the run went. Best-effort — setup must never fail because a metric did. */
     reportOutcome(outcome: InitOutcome): void;
+    /**
+     * Report ONE step of the setup funnel, as it happens.
+     *
+     * `reportOutcome` fires once, at the end, and says whether the whole run succeeded. That cannot
+     * answer the question the funnel exists for — WHERE people stop — because a run that dies at the
+     * MCP registration and one that dies before it ever looked for a package.json are the same single
+     * row. A step reported as it happens is the difference between "init failed" and "init failed at
+     * this step, on this stack, after this long".
+     *
+     * REQUIRED for the same reason `reportOutcome` is: an optional reporter is one somebody forgets to
+     * pass and nobody notices is missing, because telemetry fails silently.
+     */
+    reportStep(step: OnboardingStep): void;
     /**
      * The daemon's pairing token, minted if nothing has written one yet.
      *

package/dist/host.js

@@ -12,6 +12,9 @@ export const SILENT_HOST = {
     reportOutcome() {
         /* nothing to report to */
     },
+    reportStep() {
+        /* nothing to report to */
+    },
     pairingToken() {
         return '';
     },

package/dist/index.d.ts

@@ -9,17 +9,37 @@
  * ends up unable to move a file.
  */
 export { runInit, resolveLockfiles, type InitIo, type InitOptions, type InitResult, } from './run.js';
-export { buildNodeIo } from './node-io.js';
+/**
+ * Exported for the ONE other place in this repo that spawns a package manager: `reticle update`.
+ *
+ * It is a pure string rule with its own tests, and it was private while a second caller needed it
+ * -- which is exactly the shape that let `reticle setup mcp` reimplement the spawn as a bare
+ * `execFileSync` and break on Windows. Two copies of a quoting rule is the version of this bug that
+ * is hardest to see, so there is one.
+ */
+export { windowsShellArg } from './register/windows-quote.js';
+export { buildNodeIo, probeCli } from './node-io.js';
 export { type InitHost, SILENT_HOST } from './host.js';
 export { RETICLE_VERSION, RETICLE_NPM_PACKAGE } from './version.js';
-export { InitFailure } from './init-failure.js';
-export { NodePlatform } from './platform.js';
-export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from './dev-server-ports.js';
-export { configWithInstallSource } from './install-source-config.js';
-export { projectIdOf, rememberProjectOnDisk, type RegistryIo } from './remember-project.js';
-export { detectPackageManager, installCommandParts, parseMajor, PackageManager } from './detect.js';
-export { findWorkspaceApps } from './workspace-apps.js';
-export { refreshAgentRules } from './refresh-rules.js';
-export { diagnoseDesktop, isDesktopProject } from './desktop-doctor.js';
-export { diagnoseWebCsp } from './csp-doctor.js';
-export { reticleConfigContent } from './snippets.js';
+export { InitFailure } from './diagnose/init-failure.js';
+export { NodePlatform } from './detect/platform.js';
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from './detect/dev-server-ports.js';
+export { configWithInstallSource } from './project/install-source-config.js';
+export { projectIdOf, rememberProjectOnDisk, type RegistryIo } from './project/remember-project.js';
+export { detectPackageManager, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
+export { findWorkspaceApps } from './detect/workspace-apps.js';
+export { refreshAgentRules } from './project/refresh-rules.js';
+export { diagnoseDesktop, isDesktopProject } from './diagnose/desktop-doctor.js';
+export { diagnoseWebCsp } from './diagnose/csp-doctor.js';
+export { reticleConfigContent } from './patch/snippets.js';
+/**
+ * MCP registration, for a caller that has no project.
+ *
+ * `reticle setup mcp` registers the server for the USER across every agent on the machine, which is
+ * what the one-line installer runs before any project exists. It needs the same client table and
+ * the same detection `init` uses — a second copy would be a second answer to "which agents are
+ * here", and the two would disagree the first time a client was added to one of them.
+ */
+export { McpClient, ConfigScope, MCP_CLIENTS, ClientMergeStatus, clientSpec, mergeClientConfig, } from './register/mcp-clients.js';
+export { claudeAddCommand, claudeAvailableProbe, claudeExistsProbe, } from './register/mcp.js';
+export { detectMcpClients, type DetectedClient } from './register/detect-clients.js';