@reticlehq/init 3.3.0 → 3.5.0

package/dist/plan/preflight.js

@@ -11,8 +11,38 @@
  * npm ships with node, so refusing for its absence would refuse on a machine that is fine.
  */
 const ALWAYS_PRESENT = 'npm';
+/** The one program allowed to run a package manager it cannot find on PATH itself. */
+const COREPACK = 'corepack';
 /**
- * The refusal to print, or undefined when this machine can run the install.
+ * The prefix this run can actually invoke `packageManager` through, or undefined when neither the
+ * bare binary nor corepack can.
+ *
+ * Reported from the field (#1149): a Windows machine with a corepack-managed pnpm — no `pnpm` on
+ * PATH, only `corepack`, which resolves it from the project's `packageManager` field — failed the
+ * bare `pnpm --version` probe and refused, even though `corepack pnpm --version` succeeds and every
+ * later step could have run through it. `corepack <pm>` is not a fallback guess: corepack shipped
+ * with node and does exactly what the bare binary would have, so a machine that can only reach it
+ * that way is not missing the tool, only the shim. Every other place in this codebase that needs to
+ * talk about a corepack-only machine (`Detection.packageManagerCommand` and its readers) points back
+ * here rather than re-explaining it.
+ */
+function resolvedPmCommand(io, packageManager) {
+    if (ALWAYS_PRESENT === packageManager)
+        return packageManager;
+    if (io.probe(packageManager, ['--version']))
+        return packageManager;
+    if (io.probe(COREPACK, [packageManager, '--version']))
+        return `${COREPACK} ${packageManager}`;
+    return undefined;
+}
+/**
+ * The one place this run decides whether — and how — it can invoke the package manager.
+ *
+ * Resolves the invocation ONCE: earlier, `preflightRefusal` probed the machine to decide whether to
+ * refuse, and callers that got past it probed AGAIN, separately, to learn what the resolved command
+ * actually was — two subprocesses (the bare binary, then corepack) doing the same test twice on every
+ * ordinary run. This is the single call site: it returns either the command every later step should
+ * invoke, or the refusal to print, never both and never neither.
  *
  * `packageManager` is the one init RESOLVED, never a raw lockfile check. An inherited
  * `pnpm-lock.yaml` at a monorepo root does not mean the app in `frontend/` uses pnpm — that app's own
@@ -20,33 +50,33 @@ const ALWAYS_PRESENT = 'npm';
  * here from `exists('pnpm-lock.yaml')` refused an npm app sitting under a pnpm monorepo on a machine
  * with no pnpm, which the install gate proves must succeed.
  */
-export function preflightRefusal(io, packageManager, options = {}) {
+export function preflight(io, packageManager, options = {}) {
     // First: on a read-only checkout nothing else matters, and one access check is cheaper and
     // quieter than spawning a subprocess to discover the same thing.
     if (!io.canWrite()) {
-        return (`${io.cwd()} is not writable, and init has to write into it (.reticle.json, the build config, ` +
-            'a capabilities file). Fix the permissions, or run init from a checkout you own.');
+        return {
+            refusal: `${io.cwd()} is not writable, and init has to write into it (.reticle.json, the build config, ` +
+                'a capabilities file). Fix the permissions, or run init from a checkout you own.',
+        };
     }
+    const resolved = resolvedPmCommand(io, packageManager);
+    if (resolved !== undefined)
+        return { command: resolved };
     // What the project resolves to says nothing about what the machine HAS, and a project committed to
     // pnpm on an npm-only box is an ordinary Monday.
     //
-    // `alreadyServed` is `--url`, and skipping the check for it is the message keeping its own promise.
-    // This guard exists for the DEV SERVER — to stop `spawn pnpm ENOENT` surfacing inside "the dev
-    // server exited" — and `--url` says the app is already up, so init starts nothing and the failure
-    // it protects against cannot happen. Reported from the field as a circle: the refusal named `--url`
-    // as the way past it while `--url` was being passed, because the flag was parsed and then never
-    // handed to init at all.
-    //
-    // The dependency install can still fail without the package manager. That is one step reporting ⚠,
-    // which is what a step that cannot complete is for, and is a better outcome than writing nothing:
-    // the config, the connect module and `.reticle.json` all land, and the user is told the one thing
-    // left to do rather than being sent to install a package manager they were trying to avoid.
-    if (true !== options.alreadyServed &&
-        ALWAYS_PRESENT !== packageManager &&
-        !io.probe(packageManager, ['--version'])) {
-        return (`this project uses ${packageManager} (its lockfile says so) and ${packageManager} is not ` +
-            `installed on this machine. Install it (npm i -g ${packageManager}, or corepack enable), or ` +
-            'pass --url with the address the app already serves.');
-    }
-    return undefined;
+    // `alreadyServed` is `--url`. This guard exists for the DEV SERVER — to stop `spawn pnpm ENOENT`
+    // surfacing inside "the dev server exited" — and `--url` says the app is already up, so init starts
+    // nothing and the failure it protects against cannot happen. The dependency install can still fail
+    // without the package manager (one step reporting ⚠, a better outcome than writing nothing), so a
+    // command is still returned here — the bare name, since neither probe above found one — rather than
+    // refusing a run that `--url` already made safe.
+    if (true === options.alreadyServed)
+        return { command: packageManager };
+    return {
+        refusal: `this project uses ${packageManager} (its lockfile says so) and ${packageManager} is not ` +
+            `installed on this machine — and corepack ${packageManager} could not run it either. Install ` +
+            `it (npm i -g ${packageManager}), or enable corepack for it (corepack enable — on Windows this ` +
+            'needs an elevated shell), or pass --url with the address the app already serves.',
+    };
 }

package/dist/register/mcp-clients.js

@@ -162,9 +162,8 @@ export const MCP_CLIENTS = [
          * `~/.gemini/config/mcp_config.json`, and one file serves the 2.0 IDE, the CLI and the SDK. Same
          * `command`/`args` object Cursor, Windsurf and Gemini CLI already use.
          *
-         * It shares the `~/.gemini` tree with Gemini CLI, which is why the marker matters: registration is
-         * gated on the marker DIRECTORY, and these resolve to `.gemini/config` and `.gemini` respectively,
-         * so having one installed cannot make `init` write a config for the other.
+         * It shares the `~/.gemini` tree with Gemini CLI. Gemini detection requires its settings file:
+         * checking only the parent directory also matches an Antigravity-only installation.
          *
          * NOT verified against a running install. The path is documented, the merge is the shared JSON
          * path that every other client here uses, and an unparseable config still degrades to a printed
@@ -329,6 +328,9 @@ export function clientSnippet(spec) {
 export function clientMarkerRelPath(spec) {
     if (spec.scope === ConfigScope.CLI)
         return '';
+    // Antigravity also creates ~/.gemini. The shared parent is not evidence of Gemini CLI.
+    if (spec.id === McpClient.GEMINI)
+        return spec.relPath;
     const parts = spec.relPath.split('/');
     return parts.length > 1 ? parts.slice(0, -1).join('/') : spec.relPath;
 }

package/dist/register/mcp.d.ts

@@ -66,11 +66,24 @@ interface ClaudeAddCommand {
 }
 /** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
 export declare function claudeAddCommand(): ClaudeAddCommand;
-/** Probe args that tell us whether an `reticle` server already exists in any scope (exit 0 = exists). */
-export declare function claudeExistsProbe(): {
-    command: string;
-    args: string[];
-};
+/**
+ * Is a `reticle` server already registered with Claude Code, in any scope this project sees?
+ *
+ * READ FROM CLAUDE'S OWN CONFIG, never asked of the CLI. `claude mcp get reticle` health-checks the
+ * entry by LAUNCHING it — `npx @reticlehq/server mcp` in the project — which starts a daemon on
+ * whatever `.reticle.json` says before `init` has rewritten it. A re-run moving the port brought the
+ * old-port daemon back about two seconds after it was stopped. `claude mcp list` health-checks
+ * every server the same way.
+ *
+ * The three scopes `claude mcp add` writes: user (`mcpServers` at the top of the state file), local
+ * (`projects[<dir>].mcpServers`, keyed by absolute path) and project (`<dir>/.mcp.json`). Without a
+ * project directory only user scope is looked at. An unreadable file answers "not registered",
+ * which costs at worst a `claude mcp add` that reports the entry already exists.
+ */
+export declare function claudeHasReticle(io: {
+    readFile(path: string): string | null;
+    homeDir(): string;
+}, projectDir: string | undefined, configDir?: string | undefined): boolean;
 /** Probe args for whether the `claude` CLI is installed at all. */
 export declare function claudeAvailableProbe(): {
     command: string;

package/dist/register/mcp.js

@@ -11,6 +11,7 @@
  * project's `.reticle.json` in its CWD (see cli-port.ts). The port belongs to the project, not the
  * global agent config.
  */
+import { join } from 'node:path';
 import { RETICLE_NPM_PACKAGE } from '../version.js';
 // The name is a wire identity and lives in the contract; re-exported here so the registration writers
 // below (and their tests) keep reading it from the module that USES it.
@@ -87,14 +88,53 @@ export function claudeAddCommand() {
     const args = [MCP_SUBCOMMAND, 'add', MCP_SERVER_NAME, '-s', 'user', '--', ...tail];
     return { command: CLAUDE_CLI, args, display: `${CLAUDE_CLI} ${args.join(' ')}` };
 }
-/** Probe args that tell us whether an `reticle` server already exists in any scope (exit 0 = exists). */
-export function claudeExistsProbe() {
-    // NO `-s`: `claude mcp get` takes no options at all, so passing one exits 1 with "unknown option
-    // '-s'" — the probe answered "not registered" on EVERY machine, init then ran `claude mcp add`,
-    // which exits 1 with "already exists", and a re-run reported `[⚠] step failed` plus a manual
-    // command that fails the same way. A false positive from a project-scoped entry costs one skipped
-    // registration; the flag cost every re-run a failed step.
-    return { command: CLAUDE_CLI, args: [MCP_SUBCOMMAND, 'get', MCP_SERVER_NAME] };
+/** Where Claude Code keeps its state: `$CLAUDE_CONFIG_DIR/.claude.json`, else `~/.claude.json`. */
+const CLAUDE_STATE_FILE = '.claude.json';
+/** `mcpServers` holds a `reticle` entry. */
+function namesReticle(scope) {
+    if ('object' !== typeof scope || null === scope)
+        return false;
+    const servers = scope.mcpServers;
+    return 'object' === typeof servers && null !== servers && MCP_SERVER_NAME in servers;
+}
+function parsed(source) {
+    if (null === source)
+        return undefined;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is a `reticle` server already registered with Claude Code, in any scope this project sees?
+ *
+ * READ FROM CLAUDE'S OWN CONFIG, never asked of the CLI. `claude mcp get reticle` health-checks the
+ * entry by LAUNCHING it — `npx @reticlehq/server mcp` in the project — which starts a daemon on
+ * whatever `.reticle.json` says before `init` has rewritten it. A re-run moving the port brought the
+ * old-port daemon back about two seconds after it was stopped. `claude mcp list` health-checks
+ * every server the same way.
+ *
+ * The three scopes `claude mcp add` writes: user (`mcpServers` at the top of the state file), local
+ * (`projects[<dir>].mcpServers`, keyed by absolute path) and project (`<dir>/.mcp.json`). Without a
+ * project directory only user scope is looked at. An unreadable file answers "not registered",
+ * which costs at worst a `claude mcp add` that reports the entry already exists.
+ */
+export function claudeHasReticle(io, projectDir, configDir = process.env['CLAUDE_CONFIG_DIR']) {
+    const state = parsed(io.readFile(join(configDir ?? io.homeDir(), CLAUDE_STATE_FILE)));
+    if (namesReticle(state))
+        return true;
+    if (projectDir === undefined)
+        return false;
+    const projects = 'object' === typeof state && null !== state
+        ? state.projects
+        : undefined;
+    if ('object' === typeof projects && null !== projects) {
+        if (namesReticle(projects[projectDir]))
+            return true;
+    }
+    return namesReticle(parsed(io.readFile(join(projectDir, CLAUDE_PROJECT_CONFIG))));
 }
 /** Probe args for whether the `claude` CLI is installed at all. */
 export function claudeAvailableProbe() {

package/dist/run-types.d.ts

@@ -78,6 +78,14 @@ export interface InitIo {
     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 and returns its combined output — for a failure whose text names its
+     * cause (see explainInstallFailure). Optional: without it the generic failure text stands.
+     */
+    capture?(command: string, args: readonly string[]): {
+        ok: boolean;
+        output: string;
+    };
     /** 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. */

package/dist/run.js

@@ -6,26 +6,34 @@
 import { OnboardingPhase, OnboardingStepStatus } from '@reticlehq/core/telemetry';
 import { detectMcpClients } from './register/detect-clients.js';
 import { dirname, join } from 'node:path';
-import { CONTAINER_MARKERS } from './diagnose/containerised-dev-server.js';
+import { CONTAINER_MARKERS, runsDevServer } from './diagnose/containerised-dev-server.js';
+import { explainInstallFailure } from './diagnose/install-retries.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 { preflight } from './plan/preflight.js';
+import { devCommandFrom, devScriptBody } 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 { ANGULAR_WORKSPACE_FILE, detect, FORGE_RENDERER_CONFIGS, Framework, UiLibrary, } from './detect/detect.js';
+import { ANGULAR_PROXY_PATH, angularEntry } from './patch/angular.js';
+import { HTML_INDEX_PATH } from './patch/static-page.js';
+import { initWithoutPackageJson } from './no-package-json.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 { enclosingWorkspaceRoot } from './detect/workspace-apps.js';
 import { isConnectStep } from './plan/connect-steps.js';
 import { CURSOR_RULE_PATH, RETICLE_MD_PATH } from './project/agent-rules.js';
 import { CLAUDE_SETTINGS_PATH } from './plan/stop-hook-step.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';
+import { tanstackStartConnectPath } from './patch/tanstack-start.js';
+import { installedViteMajor } from './patch/vite-owning-config.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'];
+/** Preview snippets must not mint a real machine credential or imply this token is usable. */
+const DRY_RUN_PAIRING_TOKEN = 'DRY_RUN_TOKEN_NOT_FOR_USE';
 function craEntryOf(io) {
     for (const path of CRA_ENTRY_CANDIDATES) {
         const source = io.readFile(path);
@@ -35,12 +43,12 @@ function craEntryOf(io) {
     return null;
 }
 import { DEPS_TARGET, RETICLE_CONFIG_FILE, frameworkPackages, MCP_TARGET, buildPlan, StepStatus, } from './plan/plan.js';
-import { claudeAvailableProbe, claudeExistsProbe } from './register/mcp.js';
+import { claudeAvailableProbe, claudeHasReticle } from './register/mcp.js';
 import { reticleDevLocation } from './patch/next-patch.js';
 import { scanTestids, storeHints, scanStores } from './detect/capabilities.js';
 import { CLAUDE_PROJECT_CONFIG, 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 { VITE_DEV_MODULE_PATH, ELECTRON_VITE_DEV_MODULE_PATH, nuxtPluginPath, } 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';
@@ -219,6 +227,17 @@ function agentRootOf(options) {
     const root = options.agentRoot;
     return root === undefined || root === options.cwd ? undefined : root;
 }
+/** What the Angular steps read: the workspace file, the entry it names, and our proxy module. */
+function angularInputs(io) {
+    const workspace = io.readFile(ANGULAR_WORKSPACE_FILE);
+    const entryPath = angularEntry(workspace);
+    const entry = io.readFile(entryPath);
+    return {
+        angularWorkspace: null === workspace ? null : { path: ANGULAR_WORKSPACE_FILE, source: workspace },
+        angularEntry: null === entry ? null : { path: entryPath, source: entry },
+        angularProxySource: io.readFile(ANGULAR_PROXY_PATH),
+    };
+}
 function gatherPlanInput(options, io, pkg) {
     // Stable identity derived from the app's package.json name + root, so it survives port changes.
     const projectId = deriveProjectId(packageName(pkg), options.cwd);
@@ -234,7 +253,11 @@ function gatherPlanInput(options, io, pkg) {
         nodeModulesMarkers,
     };
     const detection = detect(detectInput);
-    const vitePath = firstPresent(rootFiles, VITE_CONFIG_CANDIDATES);
+    // Forge has no `vite.config.*`; its renderer config IS the Vite config the plugin belongs in, and
+    // handing it over under that name is what lets the ordinary Vite patcher do the work.
+    const vitePath = firstPresent(rootFiles, Framework.ELECTRON_FORGE === detection.framework
+        ? FORGE_RENDERER_CONFIGS
+        : VITE_CONFIG_CANDIDATES);
     const viteSource = null === vitePath ? null : io.readFile(vitePath);
     const viteConfig = vitePath !== null && viteSource !== null ? { path: vitePath, source: viteSource } : null;
     const electronVitePath = firstPresent(rootFiles, ELECTRON_VITE_CONFIG_CANDIDATES);
@@ -248,8 +271,8 @@ function gatherPlanInput(options, io, pkg) {
     // global config file. Only probe when the MCP step is in play.
     const availableProbe = claudeAvailableProbe();
     const claudeCli = options.mcp ? io.probe(availableProbe.command, availableProbe.args) : false;
-    const existsProbe = claudeExistsProbe();
-    const mcpExists = claudeCli ? io.probe(existsProbe.command, existsProbe.args) : false;
+    // Read from Claude's config, never `claude mcp get`: that launches the server — see claudeHasReticle.
+    const mcpExists = claudeCli ? claudeHasReticle(io, io.cwd()) : false;
     // 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.
@@ -308,7 +331,13 @@ function gatherPlanInput(options, io, pkg) {
         // 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)));
+            // Only a file that RUNS the dev server: a production-only image is the common case, and
+            // React Router's template ships one. See runsDevServer.
+            const devScript = devScriptBody(pkg);
+            const marker = CONTAINER_MARKERS.find((name) => [name, join('..', name)].some((path) => {
+                const content = io.readFile(path);
+                return null !== content && runsDevServer(name, content, devScript);
+            }));
             return marker === undefined ? {} : { containerMarker: marker };
         })(),
         viteConfig,
@@ -328,7 +357,7 @@ function gatherPlanInput(options, io, pkg) {
             : null,
         // Capabilities: scanned, never asked for. Bounded — a hint for the agent, not a repo index.
         testids: scanTestids(sourceFiles.map((f) => f.source)),
-        storeHints: storeHints(dependencyNames(pkg)),
+        storeHints: storeHints(dependencyNames(pkg), sourceFiles),
         foundStores: scanStores(sourceFiles, dependencyNames(pkg)),
         nextFoundStores: scanStores(sourceFiles, dependencyNames(pkg), dirname(devLocation.path)),
         viteDevModuleExists: io.exists(detection.framework === Framework.ELECTRON_VITE
@@ -339,6 +368,7 @@ function gatherPlanInput(options, io, pkg) {
         nextReticleDevExists: io.exists(devLocation.path),
         nextReticleDevSource: io.readFile(devLocation.path),
         svelteKitHooksExists: io.exists(SVELTEKIT_HOOKS),
+        svelteKitHooksSource: io.readFile(SVELTEKIT_HOOKS),
         reactRouterEntryExists: io.exists(REACT_ROUTER_ENTRY),
         // The SOURCE, so an entry the app already owns is ADDED TO rather than replaced — it is an
         // override of React Router's default, and everything in it is load-bearing.
@@ -347,11 +377,27 @@ function gatherPlanInput(options, io, pkg) {
             ? { path: nuxtConfigPath, source: nuxtConfigSource }
             : null,
         nuxtHasAppDir,
+        viteMajor: installedViteMajor(io, detectInput.pkg),
         nuxtPluginExists: io.exists(nuxtPluginPath(nuxtHasAppDir)),
-        tanstackStartRoot: TANSTACK_START_ROOT_CANDIDATES.find((file) => io.exists(file)),
+        nuxtPluginSource: io.readFile(nuxtPluginPath(nuxtHasAppDir)),
+        ...(() => {
+            const root = TANSTACK_START_ROOT_CANDIDATES.find((file) => io.exists(file));
+            return root === undefined
+                ? {}
+                : {
+                    tanstackStartRoot: root,
+                    tanstackStartRootSource: io.readFile(root),
+                    tanstackStartConnectExists: io.exists(tanstackStartConnectPath(root)),
+                    tanstackStartConnectSource: io.readFile(tanstackStartConnectPath(root)),
+                };
+        })(),
+        ...(Framework.ANGULAR === detection.framework ? angularInputs(io) : {}),
+        ...(Framework.HTML === detection.framework
+            ? { htmlIndexSource: io.readFile(HTML_INDEX_PATH) }
+            : {}),
         craEntry: craEntryOf(io),
         craEnv: io.readFile(CRA_ENV_PATH),
-        pairingToken: io.host.pairingToken(),
+        pairingToken: options.dryRun ? DRY_RUN_PAIRING_TOKEN : io.host.pairingToken(),
         installSource: io.host.installSource(),
         reticleConfigExists: io.exists(RETICLE_CONFIG_FILE),
         // The CONTENT, so a config that exists can be checked rather than trusted — a `"port"` set to
@@ -388,7 +434,7 @@ function gatherPlanInput(options, io, pkg) {
 /** pnpm's workspace declaration, read when present — it is authoritative about where packages live. */
 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, projectDir, agentRoot, 
+function report(plan, dryRun, failed, skipped, degraded, why, io, projectDir, agentRoot, 
 /** The project's own dev command, so the closing line names what a human would type. */
 devCommand, 
 /**
@@ -412,7 +458,7 @@ continuesToRuntime = false) {
      * On the REAL run only. In a dry run the reader has already found the flag.
      */
     if (!dryRun) {
-        io.print('  --dry-run shows this plan and writes nothing · --app <dir> picks the app · --no-mcp skips agent registration');
+        io.print('  --dry-run previews · --app <dir> picks the app · --no-mcp skips agent registration');
     }
     // 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
@@ -447,7 +493,7 @@ continuesToRuntime = false) {
         const detail = skipped.has(s.target)
             ? SKIPPED_DETAIL
             : downgraded && s.exec !== undefined
-                ? `step failed — run manually: ${s.exec.fallback}`
+                ? (why.get(s.target) ?? `step failed — run manually: ${s.exec.fallback}`)
                 : s.detail;
         io.print(`  [${STATUS_SYMBOL[status]}] ${s.title} → ${s.target}`);
         if (status === StepStatus.APPLY)
@@ -520,7 +566,8 @@ function sdkPackagesPresent(framework, uiLibrary, io) {
     return (packages.length > 0 &&
         packages.every((p) => io.exists(`${NODE_MODULES_DIR}/${p}/${PACKAGE_JSON}`)));
 }
-function applyEffects(plan, io) {
+function applyEffects(plan, io, packageManager) {
+    const why = new Map();
     const failed = new Set();
     const skipped = new Set();
     const degraded = new Map();
@@ -594,8 +641,12 @@ function applyEffects(plan, io) {
             failed.add(s.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)
+            if (s.target === DEPS_TARGET) {
                 installFailed = true;
+                const explained = explainInstallFailure(io, packageManager, exec, s.detail);
+                if (explained !== undefined)
+                    why.set(s.target, explained);
+            }
         }
     }
     // Where this project lives, remembered for a daemon that will be started somewhere else.
@@ -609,7 +660,7 @@ function applyEffects(plan, io) {
     if (projectId !== undefined) {
         rememberProjectOnDisk(io, projectId, io.cwd(), Date.now());
     }
-    return { failed, skipped, degraded };
+    return { failed, skipped, degraded, why };
 }
 /**
  * Which STEP failed, from the step targets — not from an error string, which would carry paths.
@@ -626,8 +677,20 @@ function classifyInitFailure(failed) {
         return InitFailure.MCP_REGISTRATION;
     return InitFailure.OTHER;
 }
+/**
+ * Where the agent stands when `init` runs inside a workspace package: the workspace root.
+ *
+ * The same answer `--app` from the root already gives (see enterApp), so both routes into one app
+ * leave the root in one state — a pointer config and the agent files an agent opened there reads.
+ */
+function withWorkspaceRoot(options, io) {
+    if (options.agentRoot !== undefined || true === options.redirected)
+        return options;
+    const root = enclosingWorkspaceRoot(options.cwd, io);
+    return root === undefined ? options : { ...options, agentRoot: root };
+}
 export function runInit(options, io) {
-    const result = runInitSteps(options, io);
+    const result = runInitSteps(withWorkspaceRoot(options, io), 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
@@ -635,7 +698,10 @@ export function runInit(options, io) {
     //
     // `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) {
+    //
+    // And not when the runtime follows: it asks once it has finished, as the last thing printed,
+    // rather than here in the middle, before the dev server has even started.
+    if (true !== options.redirected && true !== options.continuesToRuntime) {
         io.print('');
         io.print(FEEDBACK_HINT);
     }
@@ -673,7 +739,8 @@ function runInitSteps(options, io) {
         io.print(`${PACKAGE_JSON} is not valid JSON (${manifest.error}). Fix it and re-run — init reads the ` +
             'framework, the dev script and the package manager from it, and will not guess at any of ' +
             'them from a file it cannot read.');
-        io.host.reportOutcome({ ok: false, reason: InitFailure.MALFORMED_PACKAGE_JSON });
+        if (!options.dryRun)
+            io.host.reportOutcome({ ok: false, reason: InitFailure.MALFORMED_PACKAGE_JSON });
         return { ok: false, applied: 0, manual: 0 };
     }
     const pkgRaw = manifest.pkg;
@@ -692,52 +759,8 @@ function runInitSteps(options, io) {
     const redirectedEarly = redirectToWorkspaceApp(options, io, pkgRaw ?? {}, runInit);
     if (redirectedEarly !== null)
         return redirectedEarly;
-    if (null === pkgRaw) {
-        const streamlit = detectStreamlitProject((file) => io.readFile(file), io.rootFiles());
-        // Asked only when Streamlit already said no, so the two can never both claim the page.
-        const django = !streamlit &&
-            detectDjangoProject((file) => io.exists(join(options.cwd, file)), io.rootFiles());
-        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.
-        streamlit
-            ? streamlitSetupMessage()
-            : django
-                ? djangoSetupMessage()
-                : noPackageJsonMessage((file) => io.exists(join(options.cwd, file))));
-        // The message says "add the snippet below". Print the snippet, or the message is the same
-        // broken promise in the other direction. `connectArg` carries the port; there is no projectId
-        // to bake, because a projectId is derived from the package.json that does not exist here.
-        // Scope the project on disk before printing anything, so the daemon can serve this page.
-        //
-        // This path used to print and exit, leaving no `.reticle.json` at all — and the reporter who
-        // asked for the Django path had to hand-write one alongside the middleware. Without it the
-        // daemon has no config in its own directory, refuses the page's dial, and every downstream
-        // symptom points somewhere other than the cause (see #685). The projectId derivation already
-        // handles the no-package case: it falls back to the root folder name, fingerprinted by the
-        // absolute path so two checkouts stay distinct.
-        //
-        // Written only when absent. A config a user or an earlier run already placed here is theirs.
-        const nonJsProjectId = deriveProjectId(undefined, io.cwd());
-        if (!io.exists(RETICLE_CONFIG_FILE)) {
-            io.writeFile(RETICLE_CONFIG_FILE, reticleConfigContent(Framework.HTML, options.port, nonJsProjectId, io.host.installSource()));
-            rememberProjectOnDisk(io, nonJsProjectId, io.cwd(), Date.now());
-            io.print(`Wrote ${RETICLE_CONFIG_FILE} (project "${nonJsProjectId}").`);
-        }
-        const connect = connectArgWithToken(options.port, nonJsProjectId, io.host.pairingToken());
-        io.print(streamlit
-            ? streamlitPageSnippet(connect)
-            : django
-                ? djangoMiddlewareSnippet(connect)
-                : staticPageSnippet(connect));
-        // 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.
-        io.host.reportOutcome({ ok: false, reason: InitFailure.NO_PACKAGE_JSON });
-        return { ok: false, applied: 0, manual: 0 };
-    }
+    if (null === pkgRaw)
+        return initWithoutPackageJson(options, io);
     // 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).
@@ -747,23 +770,34 @@ function runInitSteps(options, io) {
     // the app in frontend/ uses pnpm, and checking the file refused a scaffold the install gate proves
     // must succeed. Both conditions make every later phase fail, and each arrives far from its cause
     // when it is not checked here. See preflight.ts.
-    const refusal = preflightRefusal({
+    const preflightIo = {
         cwd: () => io.cwd(),
         canWrite: () => io.canWrite(),
         probe: (command, args) => io.probe(command, args),
-    }, planInput.detection.packageManager, { alreadyServed: options.url !== undefined && '' !== options.url });
-    if (refusal !== undefined) {
-        io.print(refusal);
+    };
+    const resolved = preflight(preflightIo, planInput.detection.packageManager, {
+        alreadyServed: options.url !== undefined && '' !== options.url,
+    });
+    if (resolved.refusal !== undefined) {
+        io.print(resolved.refusal);
+        if (!options.dryRun)
+            io.host.reportOutcome({ ok: false, reason: InitFailure.PREFLIGHT });
         return { ok: false, applied: 0, manual: 1 };
     }
+    // The prefix that can actually run it on THIS machine — `pnpm`, or `corepack pnpm` where preflight
+    // just proved only corepack can. Threaded onto detection (never recomputed by `detect`, which is
+    // pure and never probes) so the install step, its retries and the dev command all spawn and print
+    // the same thing preflight just confirmed works, instead of a bare binary it already ruled out.
+    const packageManagerCommand = resolved.command;
+    planInput.detection = { ...planInput.detection, packageManagerCommand };
     const plan = io.host.span('init.plan', {}, () => buildPlan(planInput));
     const effects = options.dryRun
-        ? { failed: new Set(), skipped: new Set(), degraded: new Map() }
-        : io.host.span('init.apply', { steps: plan.steps.length }, () => applyEffects(plan, io));
-    const { failed, skipped, degraded } = effects;
+        ? { failed: new Set(), skipped: new Set(), degraded: new Map(), why: new Map() }
+        : io.host.span('init.apply', { steps: plan.steps.length }, () => applyEffects(plan, io, planInput.detection.packageManager));
+    const { failed, skipped, degraded, why } = effects;
     // The project's own dev command, so the closing line names what a human would actually type.
-    const devCommand = devCommandFrom(pkgRaw, planInput.detection.packageManager);
-    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd, agentRootOf(options), devCommand, true === options.continuesToRuntime);
+    const devCommand = devCommandFrom(pkgRaw, packageManagerCommand);
+    const result = report(plan, options.dryRun, failed, skipped, degraded, why, io, options.cwd, agentRootOf(options), devCommand, true === options.continuesToRuntime);
     // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
     if (options.dryRun)
         return result;
@@ -831,8 +865,12 @@ function runInitSteps(options, io) {
         stack: plan.framework,
         ...(result.ok ? {} : { reason: classifyInitFailure(failed) }),
     });
+    // A failed dependency install skipped every wiring step, so there is no instrumented app to boot:
+    // without a context the runtime stops at this report, rather than starting the dev server and
+    // diagnosing an SDK that was never installed as a dev server that needs restarting.
+    const handover = failed.has(DEPS_TARGET) ? {} : { context };
     if (true === options.deferOutcome)
-        return { ...result, context, outcome };
+        return { ...result, ...handover, outcome };
     io.host.reportOutcome(outcome);
-    return { ...result, context };
+    return { ...result, ...handover };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/init",
-  "version": "3.3.0",
+  "version": "3.5.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,7 +13,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@reticlehq/core": "3.3.0"
+    "@reticlehq/core": "3.5.0"
   },
   "license": "FSL-1.1-ALv2",
   "author": "Reticle contributors",
@@ -27,8 +27,7 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE",
-    "NOTICE"
+    "LICENSE"
   ],
   "sideEffects": false,
   "keywords": [