@reticlehq/init 2.14.0 → 3.2.0

package/dist/run-types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * What `init` is asked for, what it is given to do it with, and what it reports back.
+ *
+ * A leaf. Three detectors under `detect/` name `InitIo` to declare their own parameters, and had to
+ * import it out of `run.ts` — the module that calls them. The shapes are the contract between the
+ * scaffolder and its host; they belong under both, not inside one of them.
+ */
+import type { InitHost } from './host.js';
+import type { InitOutcome } from '@reticlehq/core/telemetry';
+export interface InitOptions {
+    /** `--capture-bodies`: write `captureNetworkBodies: true` into the app's config. Off by default (#705). */
+    captureBodies?: boolean | undefined;
+    cwd: string;
+    port: number | undefined;
+    mcp: boolean;
+    dryRun: boolean;
+    install: boolean;
+    /**
+     * Which app in a monorepo to wire, when several are found. Without it `init` refuses to guess, and
+     * "re-run inside the one you want" is not an instruction a script or an agent can follow.
+     */
+    app?: string;
+    /** Set on the recursive call after a workspace redirect, so the search happens at most once. */
+    redirected?: boolean;
+    /**
+     * `--url`: the address the app is ALREADY served on, so init starts nothing.
+     *
+     * Parsed by the CLI since the flag existed and never handed to `init`, which made the
+     * package-manager refusal name it as the escape hatch while being unable to see it. The value
+     * itself is not read here — only whether one was given — but it is typed as the URL rather than a
+     * boolean so the option means the same thing everywhere the flag does.
+     */
+    url?: string | undefined;
+    /**
+     * Where the human ran the command, carried across a workspace redirect.
+     *
+     * The agent rule and `/reticle` command files are read by the AGENT, whose session runs where the
+     * human started it — the repo root. Writing them beside the app instead is how a repo with its app
+     * at `src/admin` ended up with no `/reticle` at all (#318).
+     */
+    agentRoot?: string;
+    /**
+     * Hand the telemetry outcome back rather than emitting it here.
+     *
+     * `init` now stays to watch for an app to connect, and whether it saw one belongs on the SAME
+     * `init_completed` event — the funnel it exists to measure would be double-counted by a second
+     * emit and unjoinable as a second event kind. Only the CLI sets this; every other caller keeps
+     * today's fire-and-forget behaviour, so no path loses its event by forgetting to report.
+     */
+    deferOutcome?: boolean;
+    /**
+     * Whether the caller carries on into booting the app and driving it.
+     *
+     * Only affects the closing hint, which otherwise tells the reader to restart their dev server and
+     * drive a flow by hand — three lines before this command does both.
+     */
+    continuesToRuntime?: boolean;
+}
+export interface InitIo {
+    /** Returns file content or null if it does not exist. Path is project-relative or absolute. */
+    readFile(relPath: string): string | null;
+    /** Writes content, creating parent directories. Path is project-relative or absolute. */
+    writeFile(relPath: string, content: string): void;
+    exists(relPath: string): boolean;
+    /** The user's home directory (for global agent config like ~/.cursor/mcp.json). */
+    homeDir(): string;
+    /** Absolute path of the directory `init` is running in — the project's own root. */
+    cwd(): string;
+    /** Basenames present in the project root. */
+    rootFiles(): readonly string[];
+    /** Subdirectory names inside a project-relative directory; empty when it isn't one. */
+    listDirs(relPath: string): readonly string[];
+    /** File (non-directory) basenames inside a project-relative directory, including dotfiles. */
+    listFiles(relPath: string): readonly string[];
+    /** The same IO re-rooted at a project-relative subdirectory (used for the workspace redirect). */
+    scoped(relPath: string): InitIo;
+    /** Runs a subprocess to completion (inherits stdio); returns true on exit code 0. */
+    exec(command: string, args: readonly string[]): boolean;
+    /** Runs a subprocess quietly (no stdio) for a yes/no check; returns true on exit code 0. */
+    probe(command: string, args: readonly string[]): boolean;
+    /** Can this process write into the project root — see preflight.ts. */
+    canWrite(): boolean;
+    print(line: string): void;
+    /**
+     * The capabilities only the daemon has: the release version's tracer, the outcome reporter, the
+     * bridge pairing token and the declared install channel. See host.ts for why they are carried
+     * here rather than as a second parameter, and why none of them is optional.
+     */
+    host: InitHost;
+}
+/**
+ * What a run established, for a caller that means to continue where init stopped.
+ *
+ * Everything here was already computed and then thrown away. That was fine while init only wrote
+ * files: nobody downstream existed. A caller that goes on to boot the app needs the same answers,
+ * and re-deriving them is how two parts of one command end up disagreeing about which directory
+ * they are in — which is not hypothetical, because a monorepo redirect re-enters `runInit` with a
+ * different cwd and the outer caller never learns that it happened.
+ */
+export interface InitContext {
+    /** The directory actually wired, AFTER any monorepo redirect. */
+    readonly appDir: string;
+    readonly framework: string;
+    readonly packageManager: string;
+    /** The project's own dev command, when its scripts name one. Never composed. */
+    readonly devCommand?: string | undefined;
+    /** Set when init redirected into a workspace app, naming the one it chose. */
+    readonly redirectedTo?: string | undefined;
+}
+export interface InitResult {
+    ok: boolean;
+    applied: number;
+    manual: number;
+    /**
+     * The MCP server was registered by THIS run, rather than having been there already.
+     *
+     * `outcome.mcpRegistered` cannot answer this: it is true for both APPLY and ALREADY, and the two
+     * have opposite answers to the only question that matters here — must the agent reading this
+     * restart before it can call a `reticle_*` tool. An agent client reads its server list when it
+     * STARTS and never re-reads it, so on the run that first registers Reticle on a machine the tools
+     * are not in the session that just asked for them.
+     */
+    mcpNewlyRegistered?: boolean;
+    /** What this run established. Absent only where init exits before establishing anything. */
+    context?: InitContext;
+    /**
+     * The event body this run would report, handed to the caller instead of emitted, when
+     * `deferOutcome` is set. Absent on a dry run and on the exits that report for themselves.
+     */
+    outcome?: InitOutcome;
+}

package/dist/run-types.js

@@ -0,0 +1,8 @@
+/**
+ * What `init` is asked for, what it is given to do it with, and what it reports back.
+ *
+ * A leaf. Three detectors under `detect/` name `InitIo` to declare their own parameters, and had to
+ * import it out of `run.ts` — the module that calls them. The shapes are the contract between the
+ * scaffolder and its host; they belong under both, not inside one of them.
+ */
+export {};

package/dist/run.d.ts

@@ -1,122 +1,5 @@
-/**
- * The impure shell for `reticle init`: gather project files via an injected IO surface, build the
- * plan (pure), optionally write the apply-steps, and print a human-readable report. All filesystem
- * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
- */
-import type { InitHost } from './host.js';
-import type { InitOutcome } from '@reticlehq/core/telemetry';
-import { resolveLockfiles } from './lockfiles.js';
+import type { InitOptions, InitIo, InitResult } from './run-types.js';
+export type { InitOptions, InitIo, InitResult } from './run-types.js';
+import { resolveLockfiles } from './detect/lockfiles.js';
 export { resolveLockfiles };
-export interface InitOptions {
-    /** `--capture-bodies`: write `captureNetworkBodies: true` into the app's config. Off by default (#705). */
-    captureBodies?: boolean | undefined;
-    cwd: string;
-    port: number | undefined;
-    mcp: boolean;
-    dryRun: boolean;
-    install: boolean;
-    /**
-     * Which app in a monorepo to wire, when several are found. Without it `init` refuses to guess, and
-     * "re-run inside the one you want" is not an instruction a script or an agent can follow.
-     */
-    app?: string;
-    /** Set on the recursive call after a workspace redirect, so the search happens at most once. */
-    redirected?: boolean;
-    /**
-     * `--url`: the address the app is ALREADY served on, so init starts nothing.
-     *
-     * Parsed by the CLI since the flag existed and never handed to `init`, which made the
-     * package-manager refusal name it as the escape hatch while being unable to see it. The value
-     * itself is not read here — only whether one was given — but it is typed as the URL rather than a
-     * boolean so the option means the same thing everywhere the flag does.
-     */
-    url?: string | undefined;
-    /**
-     * Where the human ran the command, carried across a workspace redirect.
-     *
-     * The agent rule and `/reticle` command files are read by the AGENT, whose session runs where the
-     * human started it — the repo root. Writing them beside the app instead is how a repo with its app
-     * at `src/admin` ended up with no `/reticle` at all (#318).
-     */
-    agentRoot?: string;
-    /**
-     * Hand the telemetry outcome back rather than emitting it here.
-     *
-     * `init` now stays to watch for an app to connect, and whether it saw one belongs on the SAME
-     * `init_completed` event — the funnel it exists to measure would be double-counted by a second
-     * emit and unjoinable as a second event kind. Only the CLI sets this; every other caller keeps
-     * today's fire-and-forget behaviour, so no path loses its event by forgetting to report.
-     */
-    deferOutcome?: boolean;
-    /**
-     * Whether the caller carries on into booting the app and driving it.
-     *
-     * Only affects the closing hint, which otherwise tells the reader to restart their dev server and
-     * drive a flow by hand — three lines before this command does both.
-     */
-    continuesToRuntime?: boolean;
-}
-export interface InitIo {
-    /** Returns file content or null if it does not exist. Path is project-relative or absolute. */
-    readFile(relPath: string): string | null;
-    /** Writes content, creating parent directories. Path is project-relative or absolute. */
-    writeFile(relPath: string, content: string): void;
-    exists(relPath: string): boolean;
-    /** The user's home directory (for global agent config like ~/.cursor/mcp.json). */
-    homeDir(): string;
-    /** Absolute path of the directory `init` is running in — the project's own root. */
-    cwd(): string;
-    /** Basenames present in the project root. */
-    rootFiles(): readonly string[];
-    /** Subdirectory names inside a project-relative directory; empty when it isn't one. */
-    listDirs(relPath: string): readonly string[];
-    /** File (non-directory) basenames inside a project-relative directory, including dotfiles. */
-    listFiles(relPath: string): readonly string[];
-    /** The same IO re-rooted at a project-relative subdirectory (used for the workspace redirect). */
-    scoped(relPath: string): InitIo;
-    /** Runs a subprocess to completion (inherits stdio); returns true on exit code 0. */
-    exec(command: string, args: readonly string[]): boolean;
-    /** Runs a subprocess quietly (no stdio) for a yes/no check; returns true on exit code 0. */
-    probe(command: string, args: readonly string[]): boolean;
-    /** Can this process write into the project root — see preflight.ts. */
-    canWrite(): boolean;
-    print(line: string): void;
-    /**
-     * The capabilities only the daemon has: the release version's tracer, the outcome reporter, the
-     * bridge pairing token and the declared install channel. See host.ts for why they are carried
-     * here rather than as a second parameter, and why none of them is optional.
-     */
-    host: InitHost;
-}
-/**
- * What a run established, for a caller that means to continue where init stopped.
- *
- * Everything here was already computed and then thrown away. That was fine while init only wrote
- * files: nobody downstream existed. A caller that goes on to boot the app needs the same answers,
- * and re-deriving them is how two parts of one command end up disagreeing about which directory
- * they are in — which is not hypothetical, because a monorepo redirect re-enters `runInit` with a
- * different cwd and the outer caller never learns that it happened.
- */
-interface InitContext {
-    /** The directory actually wired, AFTER any monorepo redirect. */
-    readonly appDir: string;
-    readonly framework: string;
-    readonly packageManager: string;
-    /** The project's own dev command, when its scripts name one. Never composed. */
-    readonly devCommand?: string | undefined;
-    /** Set when init redirected into a workspace app, naming the one it chose. */
-    readonly redirectedTo?: string | undefined;
-}
-export interface InitResult {
-    ok: boolean;
-    applied: number;
-    manual: number;
-    /** What this run established. Absent only where init exits before establishing anything. */
-    context?: InitContext;
-    /**
-     * The event body this run would report, handed to the caller instead of emitted, when
-     * `deferOutcome` is set. Absent on a dry run and on the exits that report for themselves.
-     */
-    outcome?: InitOutcome;
-}
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;

package/dist/run.js

@@ -3,23 +3,26 @@
  * plan (pure), optionally write the apply-steps, and print a human-readable report. All filesystem
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
+import { OnboardingPhase, OnboardingStepStatus } from '@reticlehq/core/telemetry';
+import { detectMcpClients } from './register/detect-clients.js';
 import { dirname, join } from 'node:path';
-import { CSP_FILES } from './csp-doctor.js';
-import { preflightRefusal } from './preflight.js';
-import { detectDjangoProject, detectStreamlitProject, djangoSetupMessage, noPackageJsonMessage, streamlitSetupMessage, } from './non-js-project.js';
-import { devCommandFrom } from './dev-script.js';
-import { restartHint, FEEDBACK_HINT } from './closing-hint.js';
-import { projectIdOf, rememberProjectOnDisk } from './remember-project.js';
-import { detect, Framework, UiLibrary } from './detect.js';
-import { wasMcpRegistered } from './mcp-registered.js';
-import { pickAstroHost } from './astro-host.js';
-import { ELECTRON_VITE_CONFIG_CANDIDATES, NEXT_CONFIG_CANDIDATES, PACKAGE_JSON, VITE_CONFIG_CANDIDATES, } from './workspace-apps.js';
-import { redirectToWorkspaceApp } from './workspace-redirect.js';
-import { isConnectStep } from './connect-steps.js';
-import { CURSOR_RULE_PATH, RETICLE_MD_PATH } from './agent-rules.js';
-import { CRA_ENV_PATH } from './cra.js';
-import { NEXT_LAYOUT_CANDIDATES, NEXT_PAGES_APP_CANDIDATES } from './next-patch.js';
-import { formatGeneratedSource } from './format-generated.js';
+import { CONTAINER_MARKERS } from './diagnose/containerised-dev-server.js';
+import { CSP_FILES } from './diagnose/csp-doctor.js';
+import { preflightRefusal } from './plan/preflight.js';
+import { detectDjangoProject, detectStreamlitProject, djangoSetupMessage, noPackageJsonMessage, streamlitSetupMessage, } from './detect/non-js-project.js';
+import { devCommandFrom } from './detect/dev-script.js';
+import { restartHint, FEEDBACK_HINT } from './diagnose/closing-hint.js';
+import { projectIdOf, rememberProjectOnDisk } from './project/remember-project.js';
+import { detect, Framework, UiLibrary } from './detect/detect.js';
+import { wasMcpRegistered } from './register/mcp-registered.js';
+import { pickAstroHost } from './patch/astro-host.js';
+import { ELECTRON_VITE_CONFIG_CANDIDATES, NEXT_CONFIG_CANDIDATES, PACKAGE_JSON, VITE_CONFIG_CANDIDATES, } from './detect/workspace-apps.js';
+import { redirectToWorkspaceApp } from './detect/workspace-redirect.js';
+import { isConnectStep } from './plan/connect-steps.js';
+import { CURSOR_RULE_PATH, RETICLE_MD_PATH } from './project/agent-rules.js';
+import { CRA_ENV_PATH } from './patch/cra.js';
+import { NEXT_LAYOUT_CANDIDATES, NEXT_PAGES_APP_CANDIDATES } from './patch/next-patch.js';
+import { formatGeneratedSource } from './patch/format-generated.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'];
 function craEntryOf(io) {
@@ -30,19 +33,19 @@ function craEntryOf(io) {
     }
     return null;
 }
-import { DEPS_TARGET, RETICLE_CONFIG_FILE, frameworkPackages, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
-import { claudeAvailableProbe, claudeExistsProbe } from './mcp.js';
-import { reticleDevLocation } from './next-patch.js';
-import { scanTestids, storeHints, scanStores } from './capabilities.js';
-import { fileBackedClients, clientMarkerRelPath, ConfigScope, McpClient, CURSOR_PROJECT_MARKER, } from './mcp-clients.js';
-import { deriveProjectId, packageName } from './project-id.js';
-import { VITE_DEV_MODULE_PATH, ELECTRON_VITE_DEV_MODULE_PATH, connectArgWithToken, nuxtPluginPath, staticPageSnippet, djangoMiddlewareSnippet, reticleConfigContent, streamlitPageSnippet, } from './snippets.js';
-import { NUXT_CONFIG_CANDIDATES } from './nuxt-patch.js';
-import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH } from './slash-command.js';
+import { DEPS_TARGET, RETICLE_CONFIG_FILE, frameworkPackages, MCP_TARGET, buildPlan, StepStatus, } from './plan/plan.js';
+import { claudeAvailableProbe, claudeExistsProbe } from './register/mcp.js';
+import { reticleDevLocation } from './patch/next-patch.js';
+import { scanTestids, storeHints, scanStores } from './detect/capabilities.js';
+import { CURSOR_PROJECT_MARKER } from './register/mcp-clients.js';
+import { deriveProjectId, packageName } from './project/project-id.js';
+import { VITE_DEV_MODULE_PATH, ELECTRON_VITE_DEV_MODULE_PATH, connectArgWithToken, nuxtPluginPath, staticPageSnippet, djangoMiddlewareSnippet, reticleConfigContent, streamlitPageSnippet, } from './patch/snippets.js';
+import { NUXT_CONFIG_CANDIDATES } from './patch/nuxt-patch.js';
+import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH } from './register/slash-command.js';
 import { RETICLE_VERSION } from './version.js';
-import { InitFailure } from './init-failure.js';
-import { resolveLockfiles } from './lockfiles.js';
-// Re-exported so the existing import site (and its test block) keeps working after the split.
+import { InitFailure } from './diagnose/init-failure.js';
+import { resolveLockfiles } from './detect/lockfiles.js';
+// Re-exported: it moved to its own module, and every existing importer says `run.js`.
 export { resolveLockfiles };
 const NODE_MODULES_DIR = 'node_modules';
 const SVELTEKIT_HOOKS = 'src/hooks.client.ts';
@@ -80,8 +83,8 @@ const MAX_SCAN_DEPTH = 5;
  * the app's and correctly reported finding nothing in them, so `init` said "no data-testid values
  * yet" about an app with several — which makes an agent go and write the ones already there. That
  * list had already grown once for a `frontend/` app, and a third report of the same shape is what
- * says the answer is not another name in a list. So: walk the app root, bounded by depth and by the
- * same file cap as before.
+ * says the answer is not another name in a list. So: walk the app root, bounded by depth and by a
+ * file count.
  */
 function readSourceFiles(io) {
     const out = [];
@@ -249,27 +252,7 @@ function gatherPlanInput(options, io, pkg) {
     // Every 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.
-    const detectedClients = options.mcp
-        ? fileBackedClients()
-            .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;
-            // A fresh Cursor profile has not written ~/.cursor yet; the project-level .cursor/ is the
-            // fallback that kept that real case working. Same signal, project scope.
-            const projectFallback = spec.id === McpClient.CURSOR && !io.exists(markerPath)
-                ? io.exists(CURSOR_PROJECT_MARKER)
-                : false;
-            if (!io.exists(markerPath) && !projectFallback)
-                return null;
-            return {
-                id: spec.id,
-                configPath: absolute,
-                existing: io.readFile(absolute),
-            };
-        })
-            .filter((entry) => entry !== null)
-        : [];
+    const detectedClients = options.mcp ? detectMcpClients(io) : [];
     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
@@ -317,6 +300,13 @@ function gatherPlanInput(options, io, pkg) {
         platform: process.platform,
         detectedClients,
         cursorProjectPresent: io.exists(CURSOR_PROJECT_MARKER),
+        // Looked for beside the app AND one level up, because the app is routinely a subdirectory of the
+        // repo that containerises it — `frontend/` under a root `docker-compose.yml` is the shape this
+        // came from. Only the first match is reported; the note is the same whichever file found it.
+        ...(() => {
+            const marker = CONTAINER_MARKERS.find((name) => io.exists(name) || io.exists(join('..', name)));
+            return marker === undefined ? {} : { containerMarker: marker };
+        })(),
         viteConfig,
         electronViteConfig,
         electronPreload,
@@ -451,9 +441,14 @@ continuesToRuntime = false) {
             for (const line of detail.split('\n'))
                 io.print(`      ${line}`);
         }
-        else if (detail.length > 0) {
-            io.print(`      ${detail}`);
-        }
+        // Everything else gets its row and nothing more. The detail on a step that needs no decision
+        // restates its own title — "reticle already registered with Cursor" under
+        // `[·] MCP server (Cursor)` — and a measured Vite first run spent twelve of its forty-six lines
+        // that way, six tool names deep, before saying anything about the reader's own app.
+        //
+        // The ROW stays on every step: `apps/e2e/install-gate.mjs` reads `[mark] title → target` out of
+        // this report and diffs the shape against a recorded baseline, so a row that stopped printing
+        // would take that guard down with it while looking like tidying.
     }
     io.print('');
     if (connectPending) {
@@ -461,10 +456,20 @@ continuesToRuntime = false) {
             '"no browser session connected" until then. Everything else is already in place.');
         io.print('');
     }
+    const mcpStatus = resolvedStatus(plan, MCP_TARGET, failed, skipped);
     if (!continuesToRuntime) {
-        io.print(restartHint(resolvedStatus(plan, MCP_TARGET, failed, skipped), devCommand));
+        io.print(restartHint(mcpStatus, devCommand));
     }
-    return { ok: !connectPending, applied, manual };
+    // Carried out even when the hint above was printed, because the RUNTIME path needs the same fact
+    // and could not reach it: `restartHint` is only printed when this run stops at the files, and the
+    // full run -- the one the installer sends everybody to -- ended by telling an agent to call
+    // `reticle_act_and_wait` in a session whose tool list was read before Reticle existed.
+    return {
+        ok: !connectPending,
+        applied,
+        manual,
+        ...(StepStatus.APPLY === mcpStatus ? { mcpNewlyRegistered: true } : {}),
+    };
 }
 /**
  * Perform the apply-step side effects; return the targets whose side effect failed.
@@ -755,6 +760,56 @@ function runInitSteps(options, io) {
         ...(undefined === devCommand ? {} : { devCommand }),
         ...(true === options.redirected ? { redirectedTo: options.cwd } : {}),
     };
+    /*
+     * The two INSTALL steps `init` is the only thing that can answer.
+     *
+     * `mcp_registered` reads the step's REAL resolved status rather than "nothing failed" — the same
+     * distinction `mcpRegistered` above already makes, and for the same reason: a step that was
+     * SKIPPED never registered anything, and reporting it as success is how a funnel shows an install
+     * completing that never gave the agent any tools.
+     *
+     * `instrumented` is FILES WRITTEN and nothing more. The page still has to load and dial the
+     * bridge, which `app_connected` reports minutes later from the daemon — keeping them separate is
+     * the whole reason this funnel exists.
+     */
+    /*
+     * REPORTED HERE, not where detection happens, and the reason is a measured one.
+     *
+     * These are fire-and-forget POSTs. Emitted mid-run, `project_detected` never arrived: the CLI
+     * exited before the request landed, exactly as `daemon_stopped` once did microseconds before
+     * `process.exit(0)` — the failure the telemetry contract opens with. The steps below survive
+     * because init keeps working after them, so the request has time to complete.
+     *
+     * Grouping them is a workaround and worth naming as one: the real fix is a flush before exit, and
+     * until there is one, ANY emit that is not followed by work is a coin toss. Nothing fails loudly
+     * when it loses; the data is just quietly absent.
+     */
+    io.host.reportStep({
+        phase: OnboardingPhase.FIRST_RUN,
+        step: 'project_detected',
+        status: OnboardingStepStatus.COMPLETED,
+        stack: planInput.detection.framework,
+    });
+    const mcpOk = wasMcpRegistered(resolvedStatus(plan, MCP_TARGET, failed, skipped));
+    io.host.reportStep({
+        phase: OnboardingPhase.INSTALL,
+        step: 'agents_detected',
+        status: OnboardingStepStatus.COMPLETED,
+        stack: plan.framework,
+    });
+    io.host.reportStep({
+        phase: OnboardingPhase.INSTALL,
+        step: 'mcp_registered',
+        status: mcpOk ? OnboardingStepStatus.COMPLETED : OnboardingStepStatus.SKIPPED,
+        stack: plan.framework,
+    });
+    io.host.reportStep({
+        phase: OnboardingPhase.FIRST_RUN,
+        step: 'instrumented',
+        status: result.ok ? OnboardingStepStatus.COMPLETED : OnboardingStepStatus.FAILED,
+        stack: plan.framework,
+        ...(result.ok ? {} : { reason: classifyInitFailure(failed) }),
+    });
     if (true === options.deferOutcome)
         return { ...result, context, outcome };
     io.host.reportOutcome(outcome);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/init",
-  "version": "2.14.0",
+  "version": "3.2.0",
   "description": "Reticle project scaffolder — detects the framework, writes the config, patches the build and registers the MCP server. The build-time half of `reticle init`.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,14 +13,14 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@reticlehq/core": "2.14.0"
+    "@reticlehq/core": "3.2.0"
   },
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "FSL-1.1-ALv2",
   "author": "Reticle contributors",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reticlehq/reticle.git",
-    "directory": "packages/init"
+    "directory": "init"
   },
   "homepage": "https://github.com/reticlehq/reticle#readme",
   "bugs": "https://github.com/reticlehq/reticle/issues",
@@ -44,7 +44,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsc -b",
+    "build": "tsc -b && node ../scripts/alias-dist.mjs",
     "typecheck": "tsc -b",
     "lint": "eslint src",
     "test:unit": "vitest run src --passWithNoTests",

package/dist/install-hint.d.ts

@@ -1,9 +0,0 @@
-/**
- * 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.
- */
-import { PackageManager } from './detect.js';
-export declare function installFailureHint(pm: PackageManager): string;

package/dist/install-source-config.d.ts

@@ -1,18 +0,0 @@
-/**
- * The same `.reticle.json` with `installSource` added, or `undefined` when there is nothing to add.
- *
- * `installSource` is written only when `.reticle.json` is CREATED, and `init` reports that file as
- * `already exists` on every re-run — so everyone who was already here when the marker shipped, and
- * everyone who ran `init` once without one, keeps `unknown` forever with no way to fix it. That is
- * most of the population the field exists to describe.
- *
- * An EXISTING value is never overwritten. The first channel is the one that brought the user in, and
- * a later `init` through a different route must not take credit for an acquisition it did not make.
- * Anything unparseable is left exactly as it is: a config is user data, and `init` rewriting a file
- * it could not read would be a far worse failure than a missing dimension.
- *
- * Lives here because `init` is the only thing that writes this file. Deciding WHICH channel declared
- * itself stays in the server's `telemetry/install-source.ts`, which re-exports this for its own
- * tests; the value arrives as `PlanInput.installSource`.
- */
-export declare function configWithInstallSource(source: string | null | undefined, declared: string | undefined): string | undefined;

package/dist/remember-project.js

@@ -1,40 +0,0 @@
-import { join } from 'node:path';
-import { PROJECT_REGISTRY_FILE, ReticleDir, emptyProjectRegistry, parseProjectRegistry, rememberProject, } from '@reticlehq/core';
-/** The `projectId` a `.reticle.json` declares, or undefined when it declares none we can use. */
-export function projectIdOf(configSource) {
-    if (null === configSource || 0 === configSource.length)
-        return undefined;
-    try {
-        const parsed = JSON.parse(configSource);
-        if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
-            return undefined;
-        const id = parsed['projectId'];
-        return 'string' === typeof id && id.length > 0 ? id : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-export function rememberProjectOnDisk(io, projectId, directory, now) {
-    if (0 === projectId.length || 0 === directory.length)
-        return false;
-    try {
-        const path = join(io.homeDir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
-        const existing = io.exists(path) ? io.readFile(path) : null;
-        const registry = null === existing ? emptyProjectRegistry() : parseProjectRegistry(safeJson(existing));
-        const next = rememberProject(registry, projectId, directory, now);
-        io.writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function safeJson(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-}

package/dist/slash-command.d.ts

@@ -1,27 +0,0 @@
-/**
- * The `/reticle` slash command — the entry point the docs have been promising and nothing created.
- *
- * SKILL.md tells the user "Type `/reticle` anytime to verify the app" in three places, and `init`
- * never wrote the file that makes it exist. So the one obvious way in was a command that silently did
- * nothing in every tool. Claude Code and Cursor both read custom commands from a markdown file per
- * command; the body is the prompt the agent receives.
- *
- * Deliberately SCOPED to one flow. A user installing Reticle has an existing app with many flows, and
- * an agent told to "verify the app" will try to instrument all of them — slow, noisy, and nothing to
- * see for minutes. One flow, driven where the human can watch it, is the whole difference between a
- * two-minute first impression and an afternoon.
- */
-/** Claude Code reads project commands from `.claude/commands/<name>.md`. */
-export declare const CLAUDE_COMMAND_PATH = ".claude/commands/reticle.md";
-/** Cursor reads them from `.cursor/commands/<name>.md`. */
-export declare const CURSOR_COMMAND_PATH = ".cursor/commands/reticle.md";
-/**
- * The frontmatter line that marks a command file as OURS.
- *
- * A stale command has to be refreshable — a file frozen at whatever release created it can never be
- * improved for anyone who already ran init — but the path is one a human may have claimed for their
- * own `/reticle`, and overwriting that would be destroying somebody's work. This line is how the two
- * are told apart.
- */
-export declare const SLASH_COMMAND_SIGNATURE = "description: Verify this app in the browser with Reticle";
-export declare const SLASH_COMMAND_BODY = "---\ndescription: Verify this app in the browser with Reticle \u2014 drive one real flow and report what happened.\n---\n\nVerify this running app with Reticle. Drive it; do not read the code and guess.\n\n## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Every step below is yours to do without them. Work these in order, and say which one you are\non, one line each:\n\n0. **Is Reticle even wired into this project?** `cat .reticle.json`. If it is not there, this\n   project was never set up: run `npx @reticlehq/server@latest init`,\n   fix every `\u26A0` and `\u2139` it prints, and carry on. Do not ask first, and do not ask which\n   framework or port \u2014 both come out of the repo you are sitting in.\n\n1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 2 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_sessions` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.\n\n2. **Is a page open on it?** Do not ask the user to open a browser \u2014 open it:\n\n   ```bash\n   npx @reticlehq/server open <the url the dev server is serving>\n   ```\n\n   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a\n   machine with no browser to open, take a tab Reticle owns instead:\n   `reticle_run({ tool: \"reticle_lease\", args: { action: \"acquire\", url: \"<the same url>\" } })`.\n\nThen, once something is serving the app and a page is on it:\n\n3. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n4. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n5. **Is the dev server serving that entry?** Look in `reticle_console`, or in the page you opened in\n   step 2, for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n6. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all of those, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\n\n## Pick ONE flow\n\nNot the whole app. Pick the single most important flow you can complete in a handful of steps \u2014 the\none a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or\njust changed some code, use that one instead.\n\nState which flow you picked in one line before you start.\n\n## Drive it where the human can see\n\n1. `reticle_snapshot` \u2014 read the accessibility tree and locate the elements the flow needs. Elements\n   are addressable by role and name; you do **not** need `data-testid` to drive them.\n2. Walk the flow with `reticle_act_and_wait`, one step at a time. Narrate each step first \u2014 the human\n   is watching the page, and the HUD shows what you say.\n3. After each step, check the effect with `reticle_assert` \u2014 not just that the click dispatched, but\n   that the thing it was supposed to do actually happened.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\n\n## Report\n\n- What you drove, step by step, and what each step actually produced.\n- Anything broken, with the `file:line` Reticle gave you.\n- If a step could not be verified, say so plainly. \"Unknown\" is a real answer; a green verdict you\n  cannot back is not.\n\nDo not weaken or skip an assertion to make the run pass \u2014 that is a finding, not a fix.\n\n## If the user handed you a license key\n\nAppend `RETICLE_LICENSE_KEY=<key>` to the project's `.env` (create it if absent), make sure `.env`\nis in `.gitignore`, and confirm with `npx @reticlehq/server license`. The CLI folds a project-local\n`.env` in on every invocation, so nothing else changes. Never echo the key back, and never put it in\na commit, a comment, or a feedback report.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";