@reticlehq/init 3.6.0 → 3.7.0

package/dist/patch/snippets.js

@@ -675,9 +675,9 @@ export function unverifiedUiLibraryNote(library, installGated = false) {
     const identity = 'preact' === library
         ? 'React component identity — component names and stacks — comes from `@reticlehq/react`, which reaches Preact through `preact/compat`. That path is not covered by a CI gate here, so treat it as expected-to-work rather than proven.'
         : 'What `@reticlehq/react` adds and you will NOT get is React component identity: component names and component stacks.';
-    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here. ${'vue' === library ? 'Source `file:line` does NOT come through: the build plugin stamps JSX and, separately, Svelte components, and a Vue single-file component is neither — measured, a Svelte counter reports `src/lib/Counter.svelte:5` and the same drive on Vue reports no source at all.' : 'Source `file:line` does too — the build plugin stamps it for this library (measured on preact and svelte).'} ${identity} ${installGated ? `The install gate scaffolds this ${library} stack from scratch on every change, so this SETUP is proven; no gate drives it to a verdict, so the drive is not.` : `No CI gate covers ${library}.`} Driven on every change: Vite + React, Next.js, Astro. If something doesn't work, please open an issue.`;
+    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here. ${'vue' === library ? 'Source `file:line` does NOT come through: the build plugin stamps JSX and, separately, Svelte components, and a Vue single-file component is neither — measured, a Svelte counter reports `src/lib/Counter.svelte:5` and the same drive on Vue reports no source at all.' : 'Source `file:line` does too — the build plugin stamps it for this library (measured on preact and svelte).'} ${identity} ${installGated ? `The install gate scaffolds this ${library} stack from scratch whenever the install path changes, so this SETUP is proven; no gate drives it to a verdict, so the drive is not.` : `No CI gate covers ${library}.`} Driven to a verdict in CI: Vite + React and Next.js; Astro is checked for a connected session. If something doesn't work, please open an issue.`;
 }
-export const SVELTEKIT_SETUP_GATED_NOTE = 'The install gate scaffolds a SvelteKit app on every release and requires this hook to connect a session, so the wiring is proven; driving flows on SvelteKit to a verdict is not. If the hook does not register a session, please open an issue.';
+export const SVELTEKIT_SETUP_GATED_NOTE = 'The install gate scaffolds a SvelteKit app whenever the install path changes and requires this hook to connect a session, so the wiring is proven; driving flows on SvelteKit to a verdict is not. If the hook does not register a session, please open an issue.';
 export const UNVERIFIED_TANSTACK_START_NOTE = 'Reticle has no TanStack Start app and no CI gate for one, so this wiring is untested — it may work, but nothing proves it and nothing will tell us if it breaks. Gated today: Vite (React, Vue), Next.js, Nuxt, React Router, Remix, Astro, SvelteKit, Create React App and Angular. If the client effect does not register a session, please open an issue.';
 /**
  * Printed when init detects react-three-fiber. Reticle's model is DOM + store + network; a WebGL

package/dist/patch/static-page.d.ts

@@ -22,6 +22,7 @@
 export declare const HTML_INDEX_PATH = "index.html";
 /** The gitignored module beside the page that holds this machine's pairing token. */
 export declare const STATIC_TOKEN_MODULE = "reticle.local.js";
+export declare const STATIC_GITIGNORE_PATH = ".gitignore";
 /** Opens the block `init` writes; a re-run looks for it. */
 export declare const STATIC_SNIPPET_MARKER = "<!-- reticle:connect (dev only, written by reticle init) -->";
 /** Whether this page already carries a Reticle connect. */

package/dist/patch/static-page.js

@@ -23,7 +23,7 @@ import { CDN_SDK_URL } from './snippets.js';
 export const HTML_INDEX_PATH = 'index.html';
 /** The gitignored module beside the page that holds this machine's pairing token. */
 export const STATIC_TOKEN_MODULE = 'reticle.local.js';
-const GITIGNORE_PATH = '.gitignore';
+export const STATIC_GITIGNORE_PATH = '.gitignore';
 /** Opens the block `init` writes; a re-run looks for it. */
 export const STATIC_SNIPPET_MARKER = '<!-- reticle:connect (dev only, written by reticle init) -->';
 const STATIC_SNIPPET_END = '<!-- /reticle:connect -->';
@@ -71,12 +71,12 @@ export function staticTokenFiles(pairingToken, readFile) {
     const module = staticTokenModule(pairingToken);
     if (readFile(STATIC_TOKEN_MODULE) !== module)
         files[STATIC_TOKEN_MODULE] = module;
-    const ignore = readFile(GITIGNORE_PATH) ?? '';
+    const ignore = readFile(STATIC_GITIGNORE_PATH) ?? '';
     const covered = ignore
         .split('\n')
         .some((l) => [STATIC_TOKEN_MODULE, `/${STATIC_TOKEN_MODULE}`].includes(l.trim()));
     if (!covered) {
-        files[GITIGNORE_PATH] =
+        files[STATIC_GITIGNORE_PATH] =
             `${'' === ignore ? '' : ignore.replace(/\n*$/, '\n')}${STATIC_TOKEN_MODULE}\n`;
     }
     return files;

package/dist/plan/connect-steps.d.ts

@@ -21,6 +21,7 @@ export declare const StepTitle: {
     readonly CONNECT_MODULE: "Reticle connect module";
     readonly PAIRING_TOKEN: "Pairing token";
     readonly PAIRING_TOKEN_PER_MACHINE: "Pairing token is per-machine";
+    readonly STATIC_PAIRING_TOKEN: "Pairing token (static page)";
     readonly CONNECT_SNIPPET_CRA: "Connect snippet (CRA)";
     readonly CONNECT_SNIPPET_NUXT: "Connect snippet (Nuxt)";
     readonly NUXT_CONFIG: "Nuxt config (token + watcher)";

package/dist/plan/connect-steps.js

@@ -22,6 +22,7 @@ export const StepTitle = {
     CONNECT_MODULE: 'Reticle connect module',
     PAIRING_TOKEN: 'Pairing token',
     PAIRING_TOKEN_PER_MACHINE: 'Pairing token is per-machine',
+    STATIC_PAIRING_TOKEN: 'Pairing token (static page)',
     CONNECT_SNIPPET_CRA: 'Connect snippet (CRA)',
     CONNECT_SNIPPET_NUXT: 'Connect snippet (Nuxt)',
     NUXT_CONFIG: 'Nuxt config (token + watcher)',
@@ -98,6 +99,10 @@ export const CONNECT_STEP_TITLES = new Set([
     // not, and `gate:install` scaffolds no CRA app, so that change would ship with no coverage of the
     // path it changes. It is worth doing, and worth doing with a scaffold behind it.
     StepTitle.VITE_PLUGIN,
+    // A plain page imports its token from a gitignored sibling module. Unlike CRA's, this step never
+    // goes MANUAL by plan: it is ⚠ only when the write itself failed — no token module means the page
+    // is refused, and no ignore entry means the token is on disk without the protection we promised.
+    StepTitle.STATIC_PAIRING_TOKEN,
     // electron-vite's connect IS the renderer plugin. Without it the SDK never injects, and the
     // preload/capture steps are not enough to produce a session.
     StepTitle.ELECTRON_VITE_PLUGIN,

package/dist/plan/framework-adapter.js

@@ -223,10 +223,10 @@ export const FRAMEWORK_ADAPTERS = {
         carriesOwnUnverifiedNote: false,
     },
     [Framework.HTML]: {
-        // No bundler plugin to install — just the kit; connect is wired by hand (see htmlManual).
+        // No bundler plugin to install — write the static connect into index.html when it is present.
         packages: (kit) => [kit],
         steps: htmlSteps,
-        connectStepTitles: [StepTitle.CONNECT_SNIPPET],
+        connectStepTitles: [StepTitle.CONNECT_SNIPPET, StepTitle.STATIC_PAIRING_TOKEN],
         carriesOwnUnverifiedNote: false,
     },
 };

package/dist/plan/plan-angular.js

@@ -9,7 +9,7 @@ import { StepTitle } from './connect-steps.js';
 import { patchStep } from './plan-framework.js';
 import { alreadyOrMovedPort, retargetPort } from './port-steps.js';
 import { StepStatus } from './plan-types.js';
-const ANGULAR_SETUP_GATED_NOTE = 'The install gate scaffolds an Angular app (Angular 21, no SSR) on every release and requires a ' +
+const ANGULAR_SETUP_GATED_NOTE = 'The install gate scaffolds an Angular app (Angular 21, no SSR) whenever the install path changes and requires a ' +
     'session, and this wiring was proven by hand on Angular 22 with and without SSR; nothing yet ' +
     'drives an Angular app to a verdict on each change. DOM, network, console and state ' +
     'tools work here; component identity does not (that is the React adapter). If no session ' +

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

@@ -66,7 +66,7 @@ export declare function svelteKitSteps(input: PlanInput): Step[];
  */
 export declare function astroSteps(input: PlanInput): Step[];
 /**
- * The plain-HTML path: no bundler to hook, so the connect snippet is printed for a hand edit.
+ * The plain-HTML path: write the static connect when the page exists, otherwise print the recipe.
  *
  * A function of its own, and NOT a fallthrough. Every framework is sent here on purpose or not at
  * all — a member of `Framework` with no adapter entry is a compile error in `FRAMEWORK_ADAPTERS`,

package/dist/plan/plan-framework.js

@@ -9,14 +9,25 @@ import { patchNextConfig, patchRootLayout, patchPagesApp } from '../patch/next-p
 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 { NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, SVELTEKIT_SETUP_GATED_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';
+import { NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, SVELTEKIT_SETUP_GATED_NOTE, astroManual, nuxtManual, nuxtPluginFile, nuxtPluginPath, NUXT_PLUGIN_NOTICE, webpack4TranspileNote, WEBPACK4_REACT_SCRIPTS_MAJOR, reactRouterEntryFile, reactRouterEntryPatch, REACT_ROUTER_ENTRY_PATH, UNVERIFIED_TANSTACK_START_NOTE, htmlManual, connectArg, } from '../patch/snippets.js';
 import { StepStatus } from './plan-types.js';
 import { StepTitle } from './connect-steps.js';
 import { patchTanstackStartRoot, tanstackStartConnectFile, tanstackStartConnectPath, tanstackStartManual, TANSTACK_START_ROOT_PATH, } from '../patch/tanstack-start.js';
 import { patchNuxtConfig } from '../patch/nuxt-patch.js';
 import { alreadyOrMovedPort } from './port-steps.js';
 import { capabilitiesTodo, needsManualStore } from './plan-vite.js';
-import { HTML_INDEX_PATH, hasStaticSnippet } from '../patch/static-page.js';
+import { HTML_INDEX_PATH, STATIC_GITIGNORE_PATH, STATIC_SNIPPET_MARKER, STATIC_TOKEN_MODULE, staticTokenFiles, withStaticSnippet, } from '../patch/static-page.js';
+/*
+ * Threat model for the static page's token module. `reticle.local.js` sits beside `index.html`, so
+ * whatever serves the page serves it too, to any client that can reach that server. That is the same
+ * exposure every other dev path already has: the Vite plugin bakes the token into the connect module
+ * it serves, and the no-package.json path writes this very file. The dev server's bind address is
+ * the boundary; the module is gitignored so it never reaches a commit or a published build.
+ */
+const STATIC_TOKEN_DETAIL = `write this machine’s pairing token to ${STATIC_TOKEN_MODULE} beside the page`;
+const STATIC_IGNORE_DETAIL = `add ${STATIC_TOKEN_MODULE} to ${STATIC_GITIGNORE_PATH} — it holds this machine’s pairing token`;
+const STATIC_CONNECT_DETAIL = 'write the dev-only connect snippet (loopback hosts only)';
+const STATIC_CONNECT_ALREADY_DETAIL = `${HTML_INDEX_PATH} already loads the Reticle SDK`;
 /**
  * Turn a conservative source patch into a step: applied when it patched, already when the wiring is
  * there, and the hand-edit instructions when the file shape wasn't one we recognise.
@@ -106,8 +117,14 @@ export function nextSteps(input) {
     // Pages Router mounts through pages/_app, App Router through the root layout — different edits,
     // and picking by path is what stops a Pages app being handed the layout patch that cannot apply.
     const isPagesRouter = layout !== null && /(^|\/)pages\/_app\.[jt]sx?$/.test(layout.path);
+    const candidates = input.nextLayoutCandidates ?? [];
     const layoutPatch = null === layout
-        ? { kind: PatchKind.MANUAL, reason: 'no root layout (app/layout.tsx) or pages/_app found' }
+        ? {
+            kind: PatchKind.MANUAL,
+            reason: 0 === candidates.length
+                ? 'no root layout (app/layout.tsx) or pages/_app found'
+                : `no app/layout.tsx; route-group root layouts ${candidates.join(', ')}, and none of them alone renders /`,
+        }
         : isPagesRouter
             ? patchPagesApp(layout.source, input.nextReticleDevImport)
             : patchRootLayout(layout.source);
@@ -513,24 +530,41 @@ export function astroSteps(input) {
     ];
 }
 /**
- * The plain-HTML path: no bundler to hook, so the connect snippet is printed for a hand edit.
+ * The plain-HTML path: write the static connect when the page exists, otherwise print the recipe.
  *
  * A function of its own, and NOT a fallthrough. Every framework is sent here on purpose or not at
  * all — a member of `Framework` with no adapter entry is a compile error in `FRAMEWORK_ADAPTERS`,
  * where the if/else chain this replaced used to hand it these instructions silently.
  */
 export function htmlSteps(input) {
-    // Read the page before calling the step undone. It used to be MANUAL unconditionally, so a re-run
-    // over a page that already connects said "This app will NOT connect until the ⚠ step".
     const index = input.htmlIndexSource ?? null;
-    if (null !== index && hasStaticSnippet(index)) {
+    if (null !== index) {
+        // The page is publishable; the pairing token belongs in its gitignored sibling module instead.
+        // Refresh that module even when the connect block itself is already in place.
+        const steps = Object.entries(staticTokenFiles(input.pairingToken, (path) => input.htmlLocalSources?.[path] ?? null)).map(([path, content]) => ({
+            title: StepTitle.STATIC_PAIRING_TOKEN,
+            target: path,
+            status: StepStatus.APPLY,
+            detail: STATIC_GITIGNORE_PATH === path ? STATIC_IGNORE_DETAIL : STATIC_TOKEN_DETAIL,
+            write: { path, content },
+        }));
+        const written = withStaticSnippet(index, connectArg(input.options.port, input.options.projectId));
         return [
-            alreadyOrMovedPort({
-                title: StepTitle.CONNECT_SNIPPET,
-                target: HTML_INDEX_PATH,
-                status: StepStatus.ALREADY,
-                detail: 'index.html already loads the Reticle SDK',
-            }, index, input.options.port),
+            ...steps,
+            null !== written
+                ? {
+                    title: StepTitle.CONNECT_SNIPPET,
+                    target: HTML_INDEX_PATH,
+                    status: StepStatus.APPLY,
+                    detail: STATIC_CONNECT_DETAIL,
+                    write: { path: HTML_INDEX_PATH, content: written, expect: [STATIC_SNIPPET_MARKER] },
+                }
+                : alreadyOrMovedPort({
+                    title: StepTitle.CONNECT_SNIPPET,
+                    target: HTML_INDEX_PATH,
+                    status: StepStatus.ALREADY,
+                    detail: STATIC_CONNECT_ALREADY_DETAIL,
+                }, index, input.options.port),
         ];
     }
     return [

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

@@ -96,6 +96,11 @@ export interface Plan {
 }
 export interface PlanInput {
     detection: Detection;
+    /**
+     * `node_modules` is a link to another tree (a workspace's, a shared cache). A package manager run
+     * here replaces the link with a fresh tree, so the install is skipped and named instead.
+     */
+    nodeModulesLinked?: boolean | undefined;
     /**
      * Write `captureNetworkBodies: true` into the app's config. Off unless the caller asked (#705).
      *
@@ -145,11 +150,18 @@ export interface PlanInput {
         configPath: string;
         existing: string | null;
     }[] | undefined;
+    /**
+     * Whether the `codex` CLI is on PATH. Only probed when Codex was detected, and absent otherwise.
+     * With it, Codex registers through `codex mcp add` instead of a block to paste.
+     */
+    codexCli?: boolean | undefined;
     /** Discovered Vite config: its path + source, or null if none found. */
     viteConfig: {
         path: string;
         source: string;
     } | null;
+    /** Config paths found but not safely attributable to the selected dev command. */
+    viteConfigCandidates?: readonly string[] | undefined;
     /** Discovered electron-vite config: its path + source, or null if none found. */
     electronViteConfig?: {
         path: string;
@@ -200,6 +212,11 @@ export interface PlanInput {
         path: string;
         source: string;
     } | null | undefined;
+    /**
+     * Route-group root layouts `init` could not choose between (`app/(a)/layout.tsx`, ...), set only
+     * when there is no top-level layout and no single group renders `/` (#1538).
+     */
+    nextLayoutCandidates?: readonly string[] | undefined;
     /** Where the dev-only connect component goes — never inside `pages/`, which routes on presence. */
     nextReticleDevPath?: string | undefined;
     /** What the mount file should import — a sibling for App Router, `../components/…` for Pages. */
@@ -277,10 +294,12 @@ export interface PlanInput {
     /** The generated `reticle.proxy.mjs`, when a previous run left one (idempotency). */
     angularProxySource?: string | null | undefined;
     /**
-     * The plain-HTML app's `index.html`, when it has one — so a re-run over a page that already
-     * carries the connect snippet reports it as done instead of "will NOT connect".
+     * The plain-HTML app's `index.html`, when it has one — patched on the first run, recognised on
+     * later runs, and left manual only when there is no page to write into.
      */
     htmlIndexSource?: string | null | undefined;
+    /** Current token module and .gitignore beside the HTML page, for idempotent token-file writes. */
+    htmlLocalSources?: Record<string, string | null> | undefined;
     /** CRA's bundled entry (src/index.tsx or .js) — where the connect import has to go. */
     craEntry?: {
         path: string;
@@ -342,6 +361,8 @@ export interface PlanInput {
      * that disagrees with the app's is worse than no root config, and only reading it can tell.
      */
     agentRootConfigSource?: string | null | undefined;
+    /** The agent root holds several apps, so its config would name one and mislead about the rest. */
+    agentRootSeveralApps?: boolean | undefined;
     options: {
         port: number | undefined;
         mcp: boolean;

package/dist/plan/plan-vite.js

@@ -194,6 +194,21 @@ function viteConfigSteps(input, detail, inject = true) {
     // plugin, and a file carrying ours alone would not boot the app.
     const plainVite = Framework.VITE === input.detection.framework;
     if (null === cfg) {
+        const candidates = input.viteConfigCandidates ?? [];
+        if (candidates.length > 0) {
+            const named = candidates.map((path) => `\`${path}\``).join(', ');
+            return [
+                {
+                    title: StepTitle.VITE_PLUGIN,
+                    target: candidates[0] ?? 'vite.config',
+                    status: StepStatus.MANUAL,
+                    detail: `Reticle could not safely patch the Vite config used by the dev server. ` +
+                        `Candidate config(s): ${named}. ` +
+                        `Add the Reticle plugin to the config passed to createServer().\n\n` +
+                        viteManual(port, input.detection.uiLibrary, inject, stampSource),
+                },
+            ];
+        }
         if (!plainVite) {
             return [
                 {

package/dist/plan/plan.js

@@ -6,11 +6,13 @@
 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, claudeProjectMcpJson, mcpManual } from '../register/mcp.js';
+import { claudeAddCommand, claudeProjectMcpJson, codexAddCommand, mcpManual, } from '../register/mcp.js';
+import { codexNamesOurServer } from '../register/codex-toml.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 '../diagnose/csp-step.js';
+import { HTML_INDEX_PATH } from '../patch/static-page.js';
 import { frameworkSteps } from './framework-adapter.js';
 import { FRAMEWORK_ADAPTERS, RETICLE_BROWSER_SDK, RETICLE_REACT_KIT } from './framework-adapter.js';
 import { MCP_TARGET, StepStatus } from './plan-types.js';
@@ -21,7 +23,7 @@ import { configWithInstallSource } from '../project/install-source-config.js';
 import { portMoveDetail, retargetConfigPort } from './port-steps.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';
+import { CLAUDE_SETTINGS_PATH, claudeSettingsSteps } 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 };
 /**
@@ -92,7 +94,34 @@ function claudeMcpStep(input) {
  * parse is reported with a paste-able block rather than overwritten, and everything else is written.
  */
 function otherClientSteps(input) {
-    return (input.detectedClients ?? []).map((detected) => clientStep(clientSpec(detected.id), detected.configPath, detected.existing));
+    return (input.detectedClients ?? []).map((detected) => {
+        const spec = clientSpec(detected.id);
+        return (codexCliStep(spec, detected.configPath, detected.existing, input) ??
+            clientStep(spec, detected.configPath, detected.existing));
+    });
+}
+/**
+ * Codex, registered through its own CLI instead of a printed block (#1238).
+ *
+ * `mergeClientConfig` answers MANUAL for TOML, since we never edit it blind. `codex mcp add` does
+ * the editing, so with the binary on PATH nothing is left for a human. It REPLACES an entry of the
+ * same name and exits 0, so this answers only when the config names no `reticle` server at all, in
+ * any shape. An entry somebody wrote — a local build, a `url` — falls through to `clientStep`, which
+ * leaves it alone (ALREADY) or hands over the block (MANUAL), exactly as before.
+ */
+function codexCliStep(spec, configPath, existing, input) {
+    if (McpClient.CODEX !== spec.id || true !== input.codexCli)
+        return null;
+    if (codexNamesOurServer(existing, spec.serversKey))
+        return null;
+    const cmd = codexAddCommand();
+    return {
+        title: `MCP server (${spec.label})`,
+        target: configPath,
+        status: StepStatus.APPLY,
+        detail: `register reticle with ${spec.label} (${cmd.display})`,
+        exec: { command: cmd.command, args: cmd.args, fallback: cmd.display },
+    };
 }
 /** One client's step: already-correct is left alone, an unparseable file gets a paste-able block. */
 function clientStep(spec, configPath, existing) {
@@ -488,12 +517,22 @@ function installStep(input) {
             detail: `${names.join(', ')} already declared${version === undefined || 0 === version.length ? '' : ` at ${version}`}`,
         };
     }
+    // Never install into a linked tree: the package manager replaces the link (a workspace's tree).
+    if (true === input.nodeModulesLinked) {
+        return {
+            title: 'Install dependencies',
+            target: 'package.json',
+            status: StepStatus.SKIP,
+            detail: `skipped: node_modules is a link to another tree, which an install here would replace; install them where it points: ${command}`,
+        };
+    }
+    // The person said `--no-install`: a choice, not a step left undone, so not a ⚠.
     if (!input.options.install) {
         return {
             title: 'Install dependencies',
             target: 'package.json',
-            status: StepStatus.MANUAL,
-            detail: command,
+            status: StepStatus.SKIP,
+            detail: `skipped (--no-install); install them yourself: ${command}`,
         };
     }
     const parts = installCommandParts(pm, packages, [], pmCommand);
@@ -561,6 +600,19 @@ function agentRootConfigStep(input, content) {
             },
         ];
     }
+    // Several apps: a root config names one and is wrong for the rest. Not written; an agent at the
+    // root is served whichever app's daemon is live, and one started in an app reads that app's.
+    if (true === input.agentRootSeveralApps && existingProject === undefined) {
+        return [
+            {
+                title: AGENT_ROOT_CONFIG_TITLE,
+                target: path,
+                status: StepStatus.NOTICE,
+                detail: 'not written: this workspace has several apps and the root can name only one. Run the ' +
+                    "agent from an app's directory to pin it to that app.",
+            },
+        ];
+    }
     if (input.agentRootConfigSource === content) {
         return [
             {
@@ -652,20 +704,26 @@ function reticleConfigSteps(input) {
     ];
 }
 export function buildPlan(input) {
+    const cspSteps = cspStep(input);
     const steps = [
-        ...cspStep(input),
+        ...cspSteps,
         ...mcpSteps(input),
         ...agentRuleSteps(input),
         ...slashCommandSteps(input),
-        ...(true === input.hooks
-            ? [stopHookStep(agentFile(input, CLAUDE_SETTINGS_PATH), input.claudeSettingsContent)]
-            : []),
+        ...claudeSettingsSteps(agentFile(input, CLAUDE_SETTINGS_PATH), input.claudeSettingsContent, {
+            stop: true === input.hooks,
+            // Beside the CLAUDE.md rule: the same agent, the same consent to write its instruction files.
+            compact: input.options.mcp && input.claudeCli,
+        }),
         ...uiLibraryStep(input),
         ...webGlCanvasStep(input),
         installStep(input),
         ...reticleConfigSteps(input),
     ];
-    steps.push(...frameworkSteps(input));
+    // Both steps can patch index.html: the connect write must keep the CSP edit that runs first.
+    const patchedIndex = cspSteps.find((step) => step.write?.path === HTML_INDEX_PATH)?.write
+        ?.content;
+    steps.push(...frameworkSteps(patchedIndex === undefined ? input : { ...input, htmlIndexSource: patchedIndex }));
     // LAST, and a notice rather than an action: it is a statement about this machine's shape, and it
     // only matters once every file above has been written. See containerised-dev-server.ts.
     const container = containerisedStep(input);

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

@@ -2,3 +2,22 @@ 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;
+/**
+ * The Claude Code `SessionStart` hook with matcher `compact`: right after a compaction it prints
+ * `reticle context --compact` — what this session proved, what failed, what is still owed — back
+ * into the agent's fresh context. Reticle holds the memory; this is how it is handed back without
+ * the agent having to remember to ask.
+ *
+ * Written by default wherever the CLAUDE.md rule is (it only reads the project's own `.reticle/`, and
+ * prints nothing where there is none). Removable like any hook: delete the entry.
+ */
+export declare const COMPACT_HOOK_COMMAND = "npx @reticlehq/server context --compact";
+export declare function compactHookStep(path: string, existing: string | null | undefined): Step;
+/**
+ * Every hook this run writes into `.claude/settings.json`, each merged on top of the one before, so
+ * two steps writing the same file cannot undo each other.
+ */
+export declare function claudeSettingsSteps(path: string, existing: string | null | undefined, options: {
+    stop: boolean;
+    compact: boolean;
+}): Step[];

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

@@ -36,7 +36,12 @@ export function stopHookStep(path, existing) {
     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' };
+        return {
+            title: TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'hook already installed',
+        };
     }
     const merged = { ...settings, hooks: { ...hooks, [STOP_EVENT]: [...stop, HOOK_ENTRY] } };
     return {
@@ -47,3 +52,71 @@ export function stopHookStep(path, existing) {
         write: { path, content: `${JSON.stringify(merged, null, 2)}\n`, expect: [STOP_HOOK_COMMAND] },
     };
 }
+/**
+ * The Claude Code `SessionStart` hook with matcher `compact`: right after a compaction it prints
+ * `reticle context --compact` — what this session proved, what failed, what is still owed — back
+ * into the agent's fresh context. Reticle holds the memory; this is how it is handed back without
+ * the agent having to remember to ask.
+ *
+ * Written by default wherever the CLAUDE.md rule is (it only reads the project's own `.reticle/`, and
+ * prints nothing where there is none). Removable like any hook: delete the entry.
+ */
+export const COMPACT_HOOK_COMMAND = `npx ${RETICLE_NPM_PACKAGE} context --compact`;
+const COMPACT_TITLE = 'Claude Code resume-after-compaction hook';
+const SESSION_START_EVENT = 'SessionStart';
+const COMPACT_MATCHER = 'compact';
+export function compactHookStep(path, existing) {
+    const settings = null === existing || undefined === existing ? {} : parseSettings(existing);
+    if (settings === undefined) {
+        return {
+            title: COMPACT_TITLE,
+            target: path,
+            status: StepStatus.MANUAL,
+            detail: `${CLAUDE_SETTINGS_PATH} is not a JSON object, so it was left alone. Add a SessionStart hook (matcher "${COMPACT_MATCHER}") running \`${COMPACT_HOOK_COMMAND}\``,
+        };
+    }
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const start = Array.isArray(hooks[SESSION_START_EVENT])
+        ? hooks[SESSION_START_EVENT]
+        : [];
+    if (JSON.stringify(start).includes(COMPACT_HOOK_COMMAND)) {
+        return {
+            title: COMPACT_TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'hook already installed',
+        };
+    }
+    const entry = {
+        matcher: COMPACT_MATCHER,
+        hooks: [{ type: 'command', command: COMPACT_HOOK_COMMAND }],
+    };
+    const merged = { ...settings, hooks: { ...hooks, [SESSION_START_EVENT]: [...start, entry] } };
+    return {
+        title: COMPACT_TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: 'after a context compaction, hand the agent back what this session proved and still owes',
+        write: {
+            path,
+            content: `${JSON.stringify(merged, null, 2)}\n`,
+            expect: [COMPACT_HOOK_COMMAND],
+        },
+    };
+}
+/**
+ * Every hook this run writes into `.claude/settings.json`, each merged on top of the one before, so
+ * two steps writing the same file cannot undo each other.
+ */
+export function claudeSettingsSteps(path, existing, options) {
+    const steps = [];
+    let current = existing;
+    if (options.stop) {
+        const stop = stopHookStep(path, current);
+        steps.push(stop);
+        current = stop.write?.content ?? current;
+    }
+    if (options.compact)
+        steps.push(compactHookStep(path, current));
+    return steps;
+}

package/dist/project/agent-rules.d.ts

@@ -90,7 +90,7 @@ export declare const DEV_SERVER_POLICY = "**A dev server already running when `r
  * NOT to, how, and the guards against calling something proven when it is not. Everything an agent
  * needs only at the moment it hits a specific situation lives in RETICLE.md, named at the end.
  */
-export declare const RULE_BODY = "## Verifying with Reticle\n\nThis app is instrumented by **Reticle**, an in-app verification layer exposed as `reticle_*` MCP tools and the `npx @reticlehq/server` CLI (always through npx: Reticle's server is not installed into this project). Verifying is part of \"done\", not an optional extra.\n\n**Verify when you have changed something a user can see or do.** A component, a form, a route, a request, a piece of state that reaches the screen. Do it BEFORE telling the user it is complete. Reading the diff proves nothing and unit tests do not run the app.\n\n**Do not reach for Reticle when the change cannot show up in the running app.** It costs tool calls and the user's patience, and a verdict over an unrelated flow proves nothing about what you changed. Skip it for: documentation, comments, tests, build config, CI, dependency bumps with no user-facing effect, backend or CLI work with no UI surface, and any change to a project that is not a running web app. Say in one line that you skipped verification and why, rather than silently not doing it.\n\n**How to verify:**\n\n- Drive the flow with `reticle_act_and_wait({ ref, action, until })`. It names the consequence you expect BEFORE the action, which is the difference between a check and a rationalisation.\n- Batch a multi-step journey (a login, a form) into one `reticle_act { steps: [...] }` rather than one round trip per field.\n- Read the surrounding evidence with `reticle_look { action: \"page\" | \"state\" }` and `reticle_observe { action: \"network\" | \"console\" }`.\n- **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** `reticle_act` and everything else move or read the app and prove nothing, so a session ending without one of those two has no result however many tools it used.\n- Covered flows: `npx @reticlehq/server gate` reports which recorded flows the changed files affect and whether they still pass.\n\n**Setting Reticle up? You are mid-sequence \u2014 do not stop until a verdict exists.** The whole of it\nis: instrument the app \u2192 get a dev server running \u2192 open the app in a browser \u2192 drive one flow \u2192\nreport the verdict. Every step is yours to do, and none of them needs the user. Stopping short leaves an app that\nlooks installed and can verify nothing, which is the commonest way this goes wrong. `/reticle`\ncarries the recovery ladder; never report the install as finished without a verdict to point at.\n\n**Nothing connected? Get the app running.**\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_session { action: \"list\" }` 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\nA dev server that is already running does not pick up an edited build config or a newly created plugin file \u2014 restart it and hard-reload the tab. And if a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.\n\n**Finish `src/reticle-dev.ts` before you claim setup is done.** `init` writes it and cannot always fill it in: a store that needs an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack `queryClient`) is left as a commented `registerStore` line. A file that registers nothing looks exactly like a finished one, and `reticle_look { action: \"state\" }` then returns empty forever \u2014 which is indistinguishable from an app that has nothing to report, so it reads as success. Uncomment the line, complete it, and prove it by driving one flow and seeing your keys come back. If `init` told you to restart your client, this is the job waiting for you on the other side of that restart.\n\n**Verify each feature as you finish it, not all of them at the end.** Asked for four, build one, drive it, get a verdict, then start the second. A red verdict after four builds has four suspects; after one it has none.\n\n**Capture what a change is FOR while you are building it, not afterwards.** The business outcome a change is meant to produce is known only while the change is being made. Pass `intent` when a flow is saved, so the saved flow carries the reason it exists. A flow without one replays for months and then reports \"step 3 failed\" instead of what stopped being true for a user.\n\n**Honesty, which is the whole point:**\n\n- **`verified: \"unknown\"` is not a pass.** It means Reticle drove the app and could not tell what happened; `verifiedReason` says which clause decided that. Report it as unknown, never as working.\n- **`verified: \"no-fault\"` is not a pass either.** It means nothing was DECLARED to prove: the page settled and no channel complained, but you asserted nothing, so there is no verification. You get it whenever `until` is omitted. Name a consequence the action changes \u2014 a signal, a request, a route, or store state \u2014 and call again.\n- **Never weaken a check to make it green.** Downgrading, skipping or deleting an assertion is a finding, not a fix.\n- **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.\n- **Setup is not finished until one real flow has been driven and produced a verdict.** `init` exiting 0, the tools appearing, and a session being listed are all things that happen before anything has been verified.\n\n**The `/reticle` skill runs this whole loop for you** \u2014 detect, connect, drive one flow, report. If your client does not have it, install it once: `/plugin marketplace add reticlehq/reticle` then `/plugin install reticle@reticlehq` in Claude Code, or `npx skills add reticlehq/reticle` anywhere the skills CLI works.\n\n**A tool you need is missing?** Call `reticle_tools` before assuming it: this surface merges several families behind an `action`, so what looks absent is usually one argument away. It is the verify loop and nothing else on purpose, and a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises the wider set \u2014 it reads that at startup, so it takes effect on the next one.\n\n**Report Reticle's own defects with `reticle_session { action: \"feedback\" }` the moment you notice**, then carry on with your task. You are the user Reticle is built for and the only one who can say what it cost you, and that knowledge is gone when your context is.\n\n\uD83D\uDCC4 **The rest is in [RETICLE.md](./RETICLE.md): what to do when the tools are missing, when a result carries `version_skew` or `update_available`, when `reticle_look { action: \"state\" }` comes back empty, and how to write a feedback report that can be acted on. Read it when you hit one of those, not before.**";
+export declare const RULE_BODY = "## Verifying with Reticle\n\nThis app is instrumented by **Reticle**, an in-app verification layer exposed as `reticle_*` MCP tools and the `npx @reticlehq/server` CLI (always through npx: Reticle's server is not installed into this project). Verifying is part of \"done\", not an optional extra.\n\n**Verify when you have changed something a user can see or do.** A component, a form, a route, a request, a piece of state that reaches the screen. Do it BEFORE telling the user it is complete. Reading the diff proves nothing and unit tests do not run the app.\n\n**Do not reach for Reticle when the change cannot show up in the running app.** It costs tool calls and the user's patience, and a verdict over an unrelated flow proves nothing about what you changed. Skip it for: documentation, comments, tests, build config, CI, dependency bumps with no user-facing effect, backend or CLI work with no UI surface, and any change to a project that is not a running web app. Say in one line that you skipped verification and why, rather than silently not doing it.\n\n**How to verify \u2014 the rules to keep in mind on every call:**\n\n1. **Only `verified: \"yes\"` is a pass.** `\"no-fault\"` (nothing was declared \u2014 you omitted `until`) and `\"unknown\"` (Reticle could not tell; `verifiedReason` says why) are not a pass: report them as not proved, never as working.\n2. **Name the consequence BEFORE acting:** `reticle_act_and_wait({ target, action, until })` (add `durable: true` if it must survive a reload). Only it, `reticle_assert` and `reticle_act { steps }` produce a verdict; everything else proves nothing.\n3. **A journey is one call:** `reticle_act { steps: [{ target, action, expect }] }` runs every step and stops at the first `expect` that fails. The last step's `expect` is the end state you were asked to deliver.\n4. **Text checks are exact-case.** Add `ignoreCase: true` only when case truly does not matter.\n5. **Target by `{ testid }` or `{ role, name }`.** An ambiguous target is refused, never guessed.\n6. **On a failure, read `expected` / `observed` / the nearest candidates before retrying.** Never weaken a check to make it green.\n7. **Open `screenshot.path` only when the look matters;** `reticle_observe { since }` has the rest.\n8. **Predicates:** `{ kind: \"signal\", name }` \u00B7 `{ kind: \"net\", method, urlContains, status }` \u00B7 `{ kind: \"route\", pathname }` \u00B7 `{ kind: \"state\", path, equals }` \u00B7 `{ kind: \"element\", query: { role, name } }` \u00B7 `{ kind: \"text\", contains }` \u00B7 `allOf` / `anyOf` / `not`.\n9. **No session?** `reticle_session { action: \"list\" }` and do its `next_action`. **No app connected at all?** Run `npx @reticlehq/server init` in the app's own folder yourself. **A version-skew warning?** `npx @reticlehq/server stop`, then retry.\n10. **End with the Reticle result block the server gives you**, verbatim.\n11. **If your context was compacted or you lost track, run `npx @reticlehq/server context --compact` first.** It is the daemon's own record of what was proved, what failed and what is still owed.\n\nCovered flows: `npx @reticlehq/server gate` reports which recorded flows the changed files affect and whether they still pass.\n\n**Setting Reticle up? You are mid-sequence \u2014 do not stop until a verdict exists.** The whole of it\nis: instrument the app \u2192 get a dev server running \u2192 open the app in a browser \u2192 drive one flow \u2192\nreport the verdict. Every step is yours to do, and none of them needs the user. Stopping short leaves an app that\nlooks installed and can verify nothing, which is the commonest way this goes wrong. `/reticle`\ncarries the recovery ladder; never report the install as finished without a verdict to point at.\n\n**Nothing connected? Get the app running.**\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_session { action: \"list\" }` 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\nIf a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.\n\n**Finish `src/reticle-dev.ts` before you claim setup is done.** `init` writes it and cannot always fill it in: a store that needs an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack `queryClient`) is left as a commented `registerStore` line. A file that registers nothing looks exactly like a finished one, and `reticle_look { action: \"state\" }` then returns empty forever \u2014 which is indistinguishable from an app that has nothing to report, so it reads as success. Uncomment the line, complete it, and prove it by driving one flow and seeing your keys come back. If `init` told you to restart your client, this is the job waiting for you on the other side of that restart.\n\n**Verify each feature as you finish it, not all of them at the end.** Asked for four, build one, drive it, get a verdict, then start the second. A red verdict after four builds has four suspects; after one it has none.\n\n**Capture what a change is FOR while you are building it, not afterwards.** The business outcome a change is meant to produce is known only while the change is being made. Pass `intent` when a flow is saved, so the saved flow carries the reason it exists. A flow without one replays for months and then reports \"step 3 failed\" instead of what stopped being true for a user.\n\n**Honesty, which is the whole point:**\n\n- **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.\n- **Setup is not finished until one real flow has been driven and produced a verdict.** `init` exiting 0, the tools appearing, and a session being listed are all things that happen before anything has been verified.\n\n**The `/reticle` skill runs this whole loop for you** \u2014 detect, connect, drive one flow, report. If your client does not have it, install it once: `/plugin marketplace add reticlehq/reticle` then `/plugin install reticle@reticlehq` in Claude Code, or `npx skills add reticlehq/reticle` anywhere the skills CLI works.\n\n**A tool you need is missing?** Call `reticle_tools` before assuming it: this surface merges several families behind an `action`, so what looks absent is usually one argument away. It is the verify loop and nothing else on purpose, and a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises the wider set \u2014 it reads that at startup, so it takes effect on the next one.\n\n**Report Reticle's own defects with `reticle_session { action: \"feedback\" }` the moment you notice**, then carry on with your task. You are the user Reticle is built for and the only one who can say what it cost you, and that knowledge is gone when your context is.\n\n\uD83D\uDCC4 **The rest is in [RETICLE.md](./RETICLE.md): what to do when the tools are missing, when a result carries `version_skew` or `update_available`, when `reticle_look { action: \"state\" }` comes back empty, and how to write a feedback report that can be acted on. Read it when you hit one of those, not before.**";
 /** The full-rules file, written verbatim (no markers: `init` owns this file entirely). */
 export declare function reticleMdFile(): string;
 export declare const AgentRuleStatus: {