@reticlehq/init 3.1.0 → 3.3.0

package/dist/plan/plan-framework.js

@@ -6,7 +6,7 @@
 import { bridgeWsUrl } from '@reticlehq/core';
 import { patchViteConfig, VitePatchKind, VITE_IMPORT } from '../patch/vite-config.js';
 import { patchNextConfig, patchRootLayout, patchPagesApp } from '../patch/next-patch.js';
-import { ASTRO_ENV_DTS_PATH, patchAstroConfig, patchAstroEnvDts, patchAstroLayout, } from '../patch/astro-patch.js';
+import { ASTRO_ENV_DTS_PATH, ASTRO_RETICLE_DEV_PATH, astroReticleDevFile, patchAstroConfig, patchAstroEnvDts, patchAstroLayout, } from '../patch/astro-patch.js';
 import { CRA_DEV_MODULE_IMPORT, CRA_ENV_PATH, CRA_TOKEN_PER_MACHINE_NOTICE, TOKEN_VAR, craDevModuleFile, craDevModulePath, craEnvPatch, craImportPatch, } from '../patch/cra.js';
 import { PatchKind } from '../patch/patch-kind.js';
 import { viteManual, NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, viteDevModuleFile, VITE_DEV_MODULE_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, astroManual, nuxtManual, nuxtPluginFile, nuxtPluginPath, NUXT_PLUGIN_NOTICE, webpack4TranspileNote, WEBPACK4_REACT_SCRIPTS_MAJOR, reactRouterEntryFile, reactRouterEntryPatch, REACT_ROUTER_ENTRY_PATH, UNVERIFIED_TANSTACK_START_NOTE, htmlManual, } from '../patch/snippets.js';
@@ -636,7 +636,7 @@ export function svelteKitSteps(input) {
     ];
 }
 /**
- * Astro: the config define + build target, and the connect script in ONE layout.
+ * Astro: the config build target, and the connect script (with the pairing token) in ONE layout.
  *
  * Astro was the last gated stack left printing a recipe it did not apply. It still falls back to the
  * printed one whenever the choice is not obvious — no config, no single layout, or a shape the
@@ -659,14 +659,15 @@ export function astroSteps(input) {
             },
         ];
     }
-    // ATOMIC. The connect snippet is useless without the config: the token is inlined by the config,
-    // so a layout patched on its own gives an app that dials the bridge and is refused. Measured on a
-    // real fixture — config ⚠, layout ✓ — which reads as one step done and one caveat when it is
-    // actually a guaranteed non-connection. If either half cannot be applied, BOTH go manual with the
-    // single recipe that does the whole job.
+    // ATOMIC. The connect snippet is useless without the config: without `build.target: 'es2022'`
+    // Astro down-levels the SDK and the dynamic import dies, and without `optimizeDeps.include` the
+    // first load 404s the hashed module. The token itself now lives in the layout frontmatter (#1008),
+    // but a layout patched on its own still cannot connect. Measured on a real fixture — config ⚠,
+    // layout ✓ — which reads as one step done and one caveat when it is actually a guaranteed
+    // non-connection. If either half cannot be applied, BOTH go manual with the single recipe.
     const manualWithLayout = astroManual(input.options.port, input.options.projectId, layout.path);
     const configPatch = patchAstroConfig(config.source);
-    const layoutPatch = patchAstroLayout(layout.source, input.options.port, input.options.projectId, input.detection.uiLibrary, input.testids ?? []);
+    const layoutPatch = patchAstroLayout(layout.source, layout.path);
     if (configPatch.kind === PatchKind.MANUAL || layoutPatch.kind === PatchKind.MANUAL) {
         return [
             {
@@ -678,13 +679,34 @@ export function astroSteps(input) {
         ];
     }
     const envPatch = patchAstroEnvDts(input.astroEnvDts ?? null);
+    const existingDev = input.astroReticleDev ?? null;
+    const devAlready = 'string' === typeof existingDev && existingDev.includes('reticle.connect');
+    const devStep = devAlready
+        ? {
+            title: StepTitle.ASTRO_RETICLE_DEV,
+            target: ASTRO_RETICLE_DEV_PATH,
+            status: StepStatus.ALREADY,
+            detail: 'file exists, left alone',
+        }
+        : {
+            title: StepTitle.ASTRO_RETICLE_DEV,
+            target: ASTRO_RETICLE_DEV_PATH,
+            status: StepStatus.APPLY,
+            detail: 'write the local connect module (static SDK import, token from <meta>)',
+            write: {
+                path: ASTRO_RETICLE_DEV_PATH,
+                content: astroReticleDevFile(input.options.port, input.options.projectId, input.detection.uiLibrary, input.testids ?? []),
+            },
+            dependsOnInstall: true,
+        };
     return [
-        patchStep(StepTitle.ASTRO_CONFIG, config.path, configPatch, 'inline the pairing token and raise build.target to es2022', manualWithLayout),
-        patchStep(StepTitle.CONNECT_SNIPPET_ASTRO, layout.path, layoutPatch, 'add the dev-only connect <script> before </body>', manualWithLayout),
+        patchStep(StepTitle.ASTRO_CONFIG, config.path, configPatch, 'raise build.target to es2022 and keep .reticle/ out of the watcher', manualWithLayout),
+        patchStep(StepTitle.CONNECT_SNIPPET_ASTRO, layout.path, layoutPatch, 'add the pairing-token <meta> and a script that statically imports ReticleDev', manualWithLayout),
+        devStep,
         // Declares the Vite define names so `astro check` (create-astro's default build) can see them
         // (#677). Independent of the two halves above: even an ALREADY config/layout still needs this
         // when the env file was never written.
-        patchStep(StepTitle.ASTRO_ENV_DTS, ASTRO_ENV_DTS_PATH, envPatch, 'declare __RETICLE_TOKEN__ / __RETICLE_ROOT__ for astro check', manualWithLayout),
+        patchStep(StepTitle.ASTRO_ENV_DTS, ASTRO_ENV_DTS_PATH, envPatch, 'declare window.__RETICLE_TOKEN__ / __RETICLE_ROOT__ for astro check', manualWithLayout),
     ];
 }
 /**

package/dist/plan/plan-types.d.ts

@@ -114,6 +114,13 @@ export interface PlanInput {
     claudeCli: boolean;
     /** Whether an `reticle` MCP server is already registered with Claude (any scope) — idempotency. */
     mcpExists: boolean;
+    /**
+     * Whether `init` is running inside Claude Code itself, which is the one case where writing its
+     * project-scope `.mcp.json` is known to be wanted. See `CLAUDE_PROJECT_SPEC`.
+     */
+    insideClaudeCode?: boolean | undefined;
+    /** The project `.mcp.json` at the agent's root, read so the merge stays idempotent. */
+    claudeProjectConfig?: string | null | undefined;
     /** `process.platform`. Injected so this module stays pure. Windows is the only branch. */
     platform?: string;
     /**
@@ -175,10 +182,15 @@ export interface PlanInput {
         source: string;
     } | null | undefined;
     /**
-     * Existing `src/env.d.ts` content, when present — where the Vite-define ambient declarations go
-     * so `astro check` can see `__RETICLE_TOKEN__` / `__RETICLE_ROOT__` (#677).
+     * Existing `src/env.d.ts` content, when present — where the window ambient declarations go
+     * so `astro check` can see `__RETICLE_TOKEN__` / `__RETICLE_ROOT__` (#677, #1008).
      */
     astroEnvDts?: string | null | undefined;
+    /**
+     * Existing `src/components/ReticleDev.ts` content, when present — the local module whose
+     * static SDK import is what actually dials the daemon.
+     */
+    astroReticleDev?: string | null | undefined;
     /** Discovered Next config filename (e.g. 'next.config.mjs'), or null. */
     nextConfigFile: string | null;
     /** Source of that Next config, so the export can be wrapped in withReticle. */
@@ -283,6 +295,10 @@ export interface PlanInput {
     claudeCommandContent?: string | null | undefined;
     /** Current .cursor/commands/reticle.md content, or null when absent. */
     cursorCommandContent?: string | null | undefined;
+    /** `--hooks`: install the print-only Claude Code Stop hook. Off unless asked. */
+    hooks?: boolean | undefined;
+    /** Current .claude/settings.json content, or null when absent (the hook is MERGED into it). */
+    claudeSettingsContent?: string | null | undefined;
     /**
      * Absolute directory the AGENT runs in, when that is not the app's directory.
      *

package/dist/plan/plan.js

@@ -6,8 +6,8 @@
 import { Framework, UiLibrary, installCommand, installCommandParts, } from '../detect/detect.js';
 import { installFailureHint } from '../diagnose/install-hint.js';
 import { installRetries } from '../diagnose/install-retries.js';
-import { claudeAddCommand, mcpManual } from '../register/mcp.js';
-import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, McpClient, } from '../register/mcp-clients.js';
+import { claudeAddCommand, claudeProjectMcpJson, mcpManual } from '../register/mcp.js';
+import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, CLAUDE_PROJECT_CONFIG, CLAUDE_PROJECT_SPEC, McpClient, } from '../register/mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from '../register/slash-command.js';
 import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, markedBlock, AGENTS_MD_PATH, RETICLE_MD_PATH, CURSOR_RULE_PATH, } from '../project/agent-rules.js';
 import { cspStep } from './plan-framework.js';
@@ -20,6 +20,7 @@ import { reticleConfigContent } from '../patch/snippets.js';
 import { configWithInstallSource } from '../project/install-source-config.js';
 import { containerisedStep, uiLibraryStep, webGlCanvasStep, windowsMcpNoteStep } from './notices.js';
 import { existingConfigProblem, projectIdOf, RETICLE_CONFIG_FILE } from '../detect/existing-config.js';
+import { CLAUDE_SETTINGS_PATH, stopHookStep } from './stop-hook-step.js';
 // Re-exported: it moved to the module that reads it, and every existing importer says `plan.js`.
 export { RETICLE_CONFIG_FILE };
 /**
@@ -104,40 +105,49 @@ function claudeMcpStep(input) {
  * parse is reported with a paste-able block rather than overwritten, and everything else is written.
  */
 function otherClientSteps(input) {
-    const steps = [];
-    for (const detected of input.detectedClients ?? []) {
-        const spec = clientSpec(detected.id);
-        const merged = mergeClientConfig(spec, detected.existing);
-        const title = `MCP server (${spec.label})`;
-        if (merged.status === ClientMergeStatus.ALREADY) {
-            steps.push({
-                title,
-                target: detected.configPath,
-                status: StepStatus.ALREADY,
-                detail: `reticle already registered with ${spec.label}`,
-            });
-            continue;
-        }
-        if (merged.status === ClientMergeStatus.MANUAL) {
-            // Either the file did not parse, or the format is one we refuse to edit blind (TOML). Both
-            // end the same way: say so, and hand over the exact block.
-            steps.push({
-                title,
-                target: detected.configPath,
-                status: StepStatus.MANUAL,
-                detail: `add this to ${detected.configPath} by hand:\n${clientSnippet(spec)}`,
-            });
-            continue;
-        }
-        steps.push({
+    return (input.detectedClients ?? []).map((detected) => clientStep(clientSpec(detected.id), detected.configPath, detected.existing));
+}
+/** One client's step: already-correct is left alone, an unparseable file gets a paste-able block. */
+function clientStep(spec, configPath, existing) {
+    const merged = mergeClientConfig(spec, existing);
+    const title = `MCP server (${spec.label})`;
+    if (merged.status === ClientMergeStatus.ALREADY) {
+        return {
             title,
-            target: detected.configPath,
-            status: StepStatus.APPLY,
-            detail: `register reticle with ${spec.label}`,
-            write: { path: detected.configPath, content: merged.content },
-        });
+            target: configPath,
+            status: StepStatus.ALREADY,
+            detail: `reticle already registered with ${spec.label}`,
+        };
     }
-    return steps;
+    if (merged.status === ClientMergeStatus.MANUAL) {
+        // Either the file did not parse, or the format is one we refuse to edit blind (TOML). Both
+        // end the same way: say so, and hand over the exact block.
+        return {
+            title,
+            target: configPath,
+            status: StepStatus.MANUAL,
+            detail: `add this to ${configPath} by hand:\n${clientSnippet(spec)}`,
+        };
+    }
+    return {
+        title,
+        target: configPath,
+        status: StepStatus.APPLY,
+        detail: `register reticle with ${spec.label}`,
+        write: { path: configPath, content: merged.content },
+    };
+}
+/**
+ * Claude Code's project `.mcp.json`, written only when `init` runs inside Claude Code with no CLI on
+ * PATH (a VS Code extension session). There the reporter had to write this file by hand (#1071,
+ * #1078); anywhere else a `.mcp.json` is a file in somebody's repo for a client they may not use, so
+ * they get the notice instead.
+ */
+function claudeProjectStep(input) {
+    if (input.claudeCli || true !== input.insideClaudeCode)
+        return null;
+    const path = agentFile(input, CLAUDE_PROJECT_CONFIG);
+    return clientStep(CLAUDE_PROJECT_SPEC, path, input.claudeProjectConfig ?? null);
 }
 /** One global registration per detected agent (Claude + Cursor). Falls back to a manual note. */
 function mcpSteps(input) {
@@ -157,7 +167,12 @@ function mcpSteps(input) {
     // Claude and Cursor first (they have their own registration paths), then every other detected
     // client. A machine with Cursor AND Windsurf gets both — registering only the first one found is
     // how a user ends up with Reticle in the editor they were not using.
-    const steps = [...stepsForAgents(input, (a) => a.mcpStep), ...otherClientSteps(input)];
+    const claudeProject = claudeProjectStep(input);
+    const steps = [
+        ...stepsForAgents(input, (a) => a.mcpStep),
+        ...(null === claudeProject ? [] : [claudeProject]),
+        ...otherClientSteps(input),
+    ];
     if (0 === steps.length) {
         // No agent detected. mcpManual already carries the Windows cmd fallback — do not append it again.
         return [
@@ -169,6 +184,32 @@ function mcpSteps(input) {
             },
         ];
     }
+    /*
+     * Claude Code never leaves the plan without a word (#1071).
+     *
+     * It is the only client detected by CLI-on-PATH rather than by its config, so inside a Claude Code
+     * VS Code extension session — where `claude` is not on PATH — it reads as absent while the user is
+     * sitting in it. `claudeMcpStep` then returned null, and the manual fallback below only fires when
+     * NO agent at all was found. With Gemini and Codex present, Claude Code vanished from the plan
+     * entirely and nothing said so. A step that disappears is exactly what the install gate's baseline
+     * diff exists to catch, and the plan is the one artifact a person reads to learn what init did.
+     *
+     * Only when something else WAS found. With nothing found, the generic note below already says how
+     * to register, so nothing has silently vanished — and leaving that path untouched keeps every
+     * pristine scaffold in the install baseline reading exactly as it did.
+     */
+    if (!input.claudeCli && null === claudeProject && steps.length > 0) {
+        steps.push({
+            title: CLAUDE_MCP_TITLE,
+            target: MCP_TARGET,
+            // NOTICE, not MANUAL. Nothing here FAILED and the reader may not use Claude Code at all, so
+            // this is something to know rather than work owed — and the install gate asserts zero `⚠`,
+            // which would turn an informational line into a gate failure on any machine that happens to
+            // have another agent's config. A notice prints in full exactly like a manual step.
+            status: StepStatus.NOTICE,
+            detail: `no \`claude\` on PATH, so it could not be registered from here. Inside a Claude Code VS Code extension session the CLI is genuinely absent while the editor is not — add ${claudeProjectMcpJson()}`,
+        });
+    }
     const windowsNote = windowsMcpNoteStep(input);
     if (windowsNote !== null)
         steps.push(windowsNote);
@@ -415,10 +456,48 @@ function agentRuleSteps(input) {
  * with nothing naming a version. Pinning turns that into this loud failure, which is the better
  * trade — but only if the message says what to do about it.
  */
+/**
+ * Is this package already declared at the version we would pin?
+ *
+ * The caret is the point. `npm i -D pkg@3.2.0` WRITES `^3.2.0`, so on every later run the pinned
+ * `3.2.0` failed a string comparison against the range npm had just created, and init re-installed
+ * for ever. Only the two forms a package manager writes by itself are read - an exact version, and
+ * `^`/`~` over that same version.
+ *
+ * Everything else installs. A false "already" leaves somebody with no SDK and an install that
+ * claims to have run; a redundant install only costs time, so the unreadable cases go the safe way.
+ */
+function alreadyDeclared(declared, pinned) {
+    if (declared === undefined)
+        return false;
+    if (pinned === undefined || 0 === pinned.length)
+        return true;
+    return declared === pinned || `^${pinned}` === declared || `~${pinned}` === declared;
+}
 function installStep(input) {
     const pm = input.detection.packageManager;
     const packages = pinnedPackages(frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion);
     const command = installCommand(pm, packages);
+    /*
+     * A re-run over an already-wired project does NO dependency work.
+     *
+     * Reported from the field: `init` on an instrumented npm-workspaces project ran a pnpm dependency
+     * migration, which moved the existing `node_modules` aside and broke the dev server. Whatever
+     * manager gets chosen, the redundant install is the step that touches the tree — so the fix that
+     * matters is not running one that nothing needs. `init` is documented as idempotent; this is the
+     * step that was not.
+     */
+    const declared = input.detection.dependencies ?? {};
+    const version = input.options.sdkVersion;
+    const names = frameworkPackages(input.detection.framework, input.detection.uiLibrary);
+    if (names.length > 0 && names.every((n) => alreadyDeclared(declared[n], version))) {
+        return {
+            title: 'Install dependencies',
+            target: 'package.json',
+            status: StepStatus.ALREADY,
+            detail: `${names.join(', ')} already declared${version === undefined || 0 === version.length ? '' : ` at ${version}`}`,
+        };
+    }
     if (!input.options.install) {
         return {
             title: 'Install dependencies',
@@ -574,6 +653,9 @@ export function buildPlan(input) {
         ...mcpSteps(input),
         ...agentRuleSteps(input),
         ...slashCommandSteps(input),
+        ...(true === input.hooks
+            ? [stopHookStep(agentFile(input, CLAUDE_SETTINGS_PATH), input.claudeSettingsContent)]
+            : []),
         ...uiLibraryStep(input),
         ...webGlCanvasStep(input),
         installStep(input),

package/dist/plan/stop-hook-step.d.ts

@@ -0,0 +1,4 @@
+import { type Step } from './plan-types.js';
+export declare const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
+export declare const STOP_HOOK_COMMAND = "npx @reticlehq/server report --hook";
+export declare function stopHookStep(path: string, existing: string | null | undefined): Step;

package/dist/plan/stop-hook-step.js

@@ -0,0 +1,49 @@
+/**
+ * `init --hooks`: the print-only Claude Code Stop hook, merged into `.claude/settings.json`.
+ *
+ * Opt-in, because it writes into a file the user and other tools own. When the agent stops without a
+ * single claim having held, the hook prints one line saying so; it never blocks the agent. The line
+ * itself is `reticle report --hook`, which reads the session journal on disk.
+ */
+import { RETICLE_NPM_PACKAGE } from '../version.js';
+import { StepStatus } from './plan-types.js';
+export const CLAUDE_SETTINGS_PATH = '.claude/settings.json';
+export const STOP_HOOK_COMMAND = `npx ${RETICLE_NPM_PACKAGE} report --hook`;
+const TITLE = 'Claude Code Stop hook';
+const STOP_EVENT = 'Stop';
+const HOOK_ENTRY = { hooks: [{ type: 'command', command: STOP_HOOK_COMMAND }] };
+const isObject = (value) => 'object' === typeof value && null !== value && !Array.isArray(value);
+/** The settings as an object, or undefined when the text is not one. */
+function parseSettings(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return isObject(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function stopHookStep(path, existing) {
+    const settings = null === existing || undefined === existing ? {} : parseSettings(existing);
+    if (settings === undefined) {
+        return {
+            title: TITLE,
+            target: path,
+            status: StepStatus.MANUAL,
+            detail: `${CLAUDE_SETTINGS_PATH} is not a JSON object, so it was left alone. Add a Stop hook running \`${STOP_HOOK_COMMAND}\``,
+        };
+    }
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const stop = Array.isArray(hooks[STOP_EVENT]) ? hooks[STOP_EVENT] : [];
+    if (JSON.stringify(stop).includes(STOP_HOOK_COMMAND)) {
+        return { title: TITLE, target: path, status: StepStatus.ALREADY, detail: 'hook already installed' };
+    }
+    const merged = { ...settings, hooks: { ...hooks, [STOP_EVENT]: [...stop, HOOK_ENTRY] } };
+    return {
+        title: TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: 'print one line when the agent stops without a claim that held; never blocks it',
+        write: { path, content: `${JSON.stringify(merged, null, 2)}\n`, expect: [STOP_HOOK_COMMAND] },
+    };
+}

package/dist/project/agent-rules.js

@@ -19,6 +19,7 @@
  */
 import { NPX } from '../register/mcp.js';
 import { RETICLE_NPM_PACKAGE } from '../version.js';
+import { DISCOVERY_CALL_URL, DISCOVERY_EMAIL_COMMAND } from '@reticlehq/core';
 /** Project-root instruction files the agent re-reads every session. */
 export const CLAUDE_MD_PATH = 'CLAUDE.md';
 export const AGENTS_MD_PATH = 'AGENTS.md';
@@ -206,6 +207,7 @@ Finish that file when you see it. It is what lets you check what the app BELIEVE
 - **Working around a Reticle defect in silence is the one thing not to do.** A silent workaround is how the same defect survives to the next user.
 - **Report defects in *Reticle*, not in the app under test.** A bug you find in this app is Reticle working as intended; that one belongs in your report to the user.
 - **Never include app source, secrets, user data, or customer records** in a report.
+- **When the person you work with is stuck, or Reticle got in their way, offer them a call with the founder** (${DISCOVERY_CALL_URL}) or leaving an email with \`${DISCOVERY_EMAIL_COMMAND}\`. That conversation is where Reticle's direction comes from. Offer it; never book a call or submit an email for them.
 
 ## More
 

package/dist/register/mcp-clients.d.ts

@@ -37,6 +37,19 @@ export interface ClientSpec {
     /** Where the shape came from, so the next person can re-check it rather than trust this file. */
     docs: string;
 }
+/**
+ * Claude Code's project-scope MCP config, which needs no CLI on PATH.
+ *
+ * Named here beside the client specs because it IS one of Claude Code's two config routes, and a
+ * free string for it is the reason nobody noticed the other route existed when the CLI one failed.
+ */
+export declare const CLAUDE_PROJECT_CONFIG = ".mcp.json";
+/**
+ * Claude Code's project-scope registration, as a client spec so it goes through the same merge
+ * (already / manual / apply) as every other client. Not in `MCP_CLIENTS`: that list is DETECTED by
+ * its config existing, and this one is only ever written from inside Claude Code (see plan.ts).
+ */
+export declare const CLAUDE_PROJECT_SPEC: ClientSpec;
 export declare const MCP_CLIENTS: readonly ClientSpec[];
 export declare function clientSpec(id: McpClient): ClientSpec;
 export declare const ClientMergeStatus: {

package/dist/register/mcp-clients.js

@@ -53,6 +53,28 @@ function commandArgsEntry() {
 function openCodeEntry() {
     return { type: 'local', command: [NPX, ...npxServerArgs()], enabled: true };
 }
+/**
+ * Claude Code's project-scope MCP config, which needs no CLI on PATH.
+ *
+ * Named here beside the client specs because it IS one of Claude Code's two config routes, and a
+ * free string for it is the reason nobody noticed the other route existed when the CLI one failed.
+ */
+export const CLAUDE_PROJECT_CONFIG = '.mcp.json';
+/**
+ * Claude Code's project-scope registration, as a client spec so it goes through the same merge
+ * (already / manual / apply) as every other client. Not in `MCP_CLIENTS`: that list is DETECTED by
+ * its config existing, and this one is only ever written from inside Claude Code (see plan.ts).
+ */
+export const CLAUDE_PROJECT_SPEC = {
+    id: McpClient.CLAUDE_CODE,
+    label: 'Claude Code, project',
+    scope: ConfigScope.PROJECT,
+    relPath: CLAUDE_PROJECT_CONFIG,
+    format: ConfigFormat.JSON,
+    serversKey: 'mcpServers',
+    entry: commandArgsEntry,
+    docs: 'https://docs.claude.com/en/docs/claude-code/mcp: project scope, .mcp.json at the project root',
+};
 export const MCP_CLIENTS = [
     {
         id: McpClient.CLAUDE_CODE,

package/dist/register/mcp.d.ts

@@ -83,4 +83,12 @@ export declare function claudeAvailableProbe(): {
  */
 export declare function mcpWindowsNote(): string;
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
+/**
+ * Claude Code's PROJECT-scope config, which needs no CLI on PATH.
+ *
+ * The remedy a reporter had to work out for themselves: inside a Claude Code VS Code extension
+ * session the `claude` binary is not on PATH, so every CLI-based route is shut and `.mcp.json` in
+ * the project root is the one that still works.
+ */
+export declare function claudeProjectMcpJson(): string;
 export declare function mcpManual(): string;

package/dist/register/mcp.js

@@ -16,6 +16,7 @@ import { RETICLE_NPM_PACKAGE } from '../version.js';
 // below (and their tests) keep reading it from the module that USES it.
 export { MCP_SERVER_NAME } from '@reticlehq/core';
 import { MCP_SERVER_NAME } from '@reticlehq/core';
+import { CLAUDE_PROJECT_CONFIG } from './mcp-clients.js';
 /**
  * The registered command is STILL bare `npx` on every platform, deliberately.
  *
@@ -112,12 +113,27 @@ does not gate:
   "${MCP_SERVER_NAME}": { "command": "${WINDOWS_SHELL}", "args": ${JSON.stringify([WINDOWS_SHELL_C, NPX, ...serverInvocation().slice(1)])} }`;
 }
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
+/**
+ * Claude Code's PROJECT-scope config, which needs no CLI on PATH.
+ *
+ * The remedy a reporter had to work out for themselves: inside a Claude Code VS Code extension
+ * session the `claude` binary is not on PATH, so every CLI-based route is shut and `.mcp.json` in
+ * the project root is the one that still works.
+ */
+export function claudeProjectMcpJson() {
+    const [command, ...args] = serverInvocation();
+    return `${CLAUDE_PROJECT_CONFIG} (project root):
+
+  { "mcpServers": { "${MCP_SERVER_NAME}": { "command": "${command ?? NPX}", "args": ${JSON.stringify(args)} } } }`;
+}
 export function mcpManual() {
     const tail = serverInvocation().join(' ');
     return `Register the Reticle MCP server ONCE, globally (so every project gets it):
 
   ${CLAUDE_CLI} ${MCP_SUBCOMMAND} add ${MCP_SERVER_NAME} -s user -- ${tail}
 
+Or, in Claude Code with no \`claude\` on PATH (a VS Code extension session), write ${claudeProjectMcpJson()}
+
 Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.cursor/mcp.json):
 
   "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }

package/dist/run-types.d.ts

@@ -10,6 +10,8 @@ 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;
+    /** `--hooks`: also install the print-only Claude Code Stop hook. Off by default. */
+    hooks?: boolean | undefined;
     cwd: string;
     port: number | undefined;
     mcp: boolean;
@@ -111,6 +113,16 @@ 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;
     /**

package/dist/run.js

@@ -20,6 +20,7 @@ import { ELECTRON_VITE_CONFIG_CANDIDATES, NEXT_CONFIG_CANDIDATES, PACKAGE_JSON,
 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 { 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';
@@ -37,7 +38,7 @@ import { DEPS_TARGET, RETICLE_CONFIG_FILE, frameworkPackages, MCP_TARGET, buildP
 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 { 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 { NUXT_CONFIG_CANDIDATES } from './patch/nuxt-patch.js';
@@ -294,9 +295,12 @@ function gatherPlanInput(options, io, pkg) {
     return {
         detection,
         captureBodies: options.captureBodies,
+        hooks: options.hooks,
         cspSources,
         claudeCli,
         mcpExists,
+        insideClaudeCode: io.host.insideClaudeCode(),
+        claudeProjectConfig: options.mcp ? io.readFile(agentFile(CLAUDE_PROJECT_CONFIG)) : undefined,
         platform: process.platform,
         detectedClients,
         cursorProjectPresent: io.exists(CURSOR_PROJECT_MARKER),
@@ -316,6 +320,7 @@ function gatherPlanInput(options, io, pkg) {
             ? { path: layoutRelPath, source: astroLayoutSource }
             : null,
         astroEnvDts: io.readFile('src/env.d.ts'),
+        astroReticleDev: io.readFile('src/components/ReticleDev.ts'),
         nextConfigFile,
         nextConfigSource: null === nextConfigFile ? null : io.readFile(nextConfigFile),
         nextLayout: layoutPath !== null && layoutSource !== null
@@ -360,6 +365,8 @@ function gatherPlanInput(options, io, pkg) {
         cursorRuleContent: io.readFile(agentFile(CURSOR_RULE_PATH)),
         claudeCommandContent: io.readFile(agentFile(CLAUDE_COMMAND_PATH)),
         cursorCommandContent: io.readFile(agentFile(CURSOR_COMMAND_PATH)),
+        // Read only to MERGE into: the settings file is the user's, and other tools write in it too.
+        claudeSettingsContent: true === options.hooks ? io.readFile(agentFile(CLAUDE_SETTINGS_PATH)) : undefined,
         ...(agentRoot === undefined
             ? {}
             : {
@@ -393,6 +400,20 @@ devCommand,
  */
 continuesToRuntime = false) {
     io.print(dryRun ? 'reticle init (dry run, no files written)' : 'reticle init');
+    /*
+     * The escape hatches, named by the command that needs them, at the moment it needs them.
+     *
+     * `--dry-run`, `--app` and `--no-mcp` all exist and all work, and they were discoverable only
+     * from `--help`. A prospective user's agent refused to run this at all — correctly, since it was
+     * being asked to let a third-party package edit a build config and register itself with every
+     * agent on the machine, and nothing it could see offered a way to look first. It had already
+     * decided by the time `--help` would have told it.
+     *
+     * 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');
+    }
     // Every path below is printed RELATIVE, and until now nothing said what to. Reported from the
     // field as "[✓] Reticle config → .reticle.json" followed by the file not being there: the app was
     // in `frontend/`, init redirected into it, and the report's `.reticle.json` was true about a
@@ -441,9 +462,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) {
@@ -451,10 +477,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.