@reticlehq/init 3.5.0 → 3.7.0

package/dist/index.d.ts

@@ -29,8 +29,9 @@ export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from '
 export { configWithInstallSource } from './project/install-source-config.js';
 export { projectIdOf, rememberProjectOnDisk, type RegistryIo } from './project/remember-project.js';
 export { detectPackageManager, Framework, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
-export { findWorkspaceApps } from './detect/workspace-apps.js';
+export { enclosingWorkspaceRoot, findWorkspaceApps, isWebApp, workspacePackageDirs, } from './detect/workspace-apps.js';
 export { desktopLaunch, type DesktopLaunch } from './detect/dev-script.js';
+export { detectNonJsEcosystem, noPackageJsonMessage } from './detect/non-js-project.js';
 export { deriveProjectId, packageName } from './project/project-id.js';
 export { refreshAgentRules } from './project/refresh-rules.js';
 export { diagnoseDesktop, isDesktopProject } from './diagnose/desktop-doctor.js';
@@ -46,5 +47,6 @@ export { reticleConfigContent } from './patch/snippets.js';
  * here", and the two would disagree the first time a client was added to one of them.
  */
 export { McpClient, ConfigScope, MCP_CLIENTS, ClientMergeStatus, clientSpec, mergeClientConfig, } from './register/mcp-clients.js';
-export { claudeAddCommand, claudeAvailableProbe, claudeHasReticle, } from './register/mcp.js';
+export { claudeAddCommand, claudeAvailableProbe, claudeHasReticle, codexAddCommand, codexAvailableProbe, } from './register/mcp.js';
+export { codexNamesOurServer } from './register/codex-toml.js';
 export { detectMcpClients, type DetectedClient } from './register/detect-clients.js';

package/dist/index.js

@@ -29,8 +29,9 @@ export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from '
 export { configWithInstallSource } from './project/install-source-config.js';
 export { projectIdOf, rememberProjectOnDisk } from './project/remember-project.js';
 export { detectPackageManager, Framework, installCommandParts, parseMajor, PackageManager, } from './detect/detect.js';
-export { findWorkspaceApps } from './detect/workspace-apps.js';
+export { enclosingWorkspaceRoot, findWorkspaceApps, isWebApp, workspacePackageDirs, } from './detect/workspace-apps.js';
 export { desktopLaunch } from './detect/dev-script.js';
+export { detectNonJsEcosystem, noPackageJsonMessage } from './detect/non-js-project.js';
 export { deriveProjectId, packageName } from './project/project-id.js';
 export { refreshAgentRules } from './project/refresh-rules.js';
 export { diagnoseDesktop, isDesktopProject } from './diagnose/desktop-doctor.js';
@@ -50,5 +51,9 @@ export { claudeAddCommand,
 // The two probes `run.ts` uses to decide about Claude Code. Exported because `reticle setup mcp`
 // asks the same question and had no way to ask it: Claude Code keeps no config file, so the
 // file-reading detector cannot see it, and the installer silently skipped the commonest client.
-claudeAvailableProbe, claudeHasReticle, } from './register/mcp.js';
+claudeAvailableProbe, claudeHasReticle, 
+// Codex keeps its registration behind `codex mcp add`, like Claude. `reticle setup mcp` needs the
+// command, the probe and the "is the entry already there, in any shape" check to do the same.
+codexAddCommand, codexAvailableProbe, } from './register/mcp.js';
+export { codexNamesOurServer } from './register/codex-toml.js';
 export { detectMcpClients } from './register/detect-clients.js';

package/dist/no-package-json.js

@@ -6,9 +6,8 @@
  * static page it can see whole, or prints the snippet for the stack it recognised (Streamlit,
  * Django, several pages) and stops.
  */
-import { join } from 'node:path';
 import { PackageManager, Framework } from './detect/detect.js';
-import { detectDjangoProject, detectStreamlitProject, djangoSetupMessage, noPackageJsonMessage, streamlitSetupMessage, } from './detect/non-js-project.js';
+import { detectDjangoProject, detectStreamlitProject, djangoSetupMessage, NoPackageJsonCase, noPackageJsonAnswer, streamlitSetupMessage, } from './detect/non-js-project.js';
 import { InitFailure } from './diagnose/init-failure.js';
 import { HTML_INDEX_PATH, STATIC_TOKEN_MODULE, staticTokenFiles, withStaticSnippet, } from './patch/static-page.js';
 import { connectArg, connectArgWithToken, djangoMiddlewareSnippet, reticleConfigContent, staticPageSnippet, streamlitPageSnippet, } from './patch/snippets.js';
@@ -60,9 +59,23 @@ function wireStaticPage(options, io, connect) {
     };
 }
 export function initWithoutPackageJson(options, io) {
+    // Relative to the IO's own root, like every other read here (`readFile` below, `HTML_INDEX_PATH`).
+    // The real IO resolves it to the same file; joining `options.cwd` onto it only made these checks
+    // miss in the in-memory IO the tests use, so no test could tell the branches below apart.
+    const existsHere = (file) => io.exists(file);
     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());
+    const django = !streamlit && detectDjangoProject(existsHere, io.rootFiles());
+    // "Run init from your app's directory" is the whole answer, so stop at it. This used to fall
+    // through to the shared tail below: it wrote `.reticle.json` into the directory it had just called
+    // wrong, then printed a script-tag snippet under a message that asks for none (#1366).
+    const answer = noPackageJsonAnswer(existsHere, io.rootFiles());
+    if (!streamlit && !django && answer.kind === NoPackageJsonCase.WRONG_DIRECTORY) {
+        io.print(answer.message);
+        if (!options.dryRun)
+            io.host.reportOutcome({ ok: false, reason: InitFailure.NO_PACKAGE_JSON });
+        return { ok: false, applied: 0, manual: 0 };
+    }
     // Scope the project on disk before anything else, so the daemon can serve this page.
     //
     // This path used to print and exit, leaving no `.reticle.json` at all — and the reporter who
@@ -110,11 +123,7 @@ export function initWithoutPackageJson(options, io) {
     // 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)), io.rootFiles()));
+    streamlit ? streamlitSetupMessage() : django ? djangoSetupMessage() : answer.message);
     writeConfig();
     // The message says "add the snippet below". Print the snippet, or the message is the same broken
     // promise in the other direction.

package/dist/node-io.d.ts

@@ -8,7 +8,7 @@ import type { InitHost } from './host.js';
 /**
  * Every program `init` is ever allowed to run.
  *
- * The set is closed and tiny — the four package managers, `npx`, `corepack`, and the Claude CLI —
+ * The set is closed and tiny — the four package managers, `npx`, `corepack`, and the Claude and Codex CLIs —
  * because those are the only things the plan can ask for. It is a named constant for the same reason
  * every other wire string here is one, and it is CHECKED because of the shell: on Windows these spawn
  * through a shell, and a shell turns the command name into something the shell parses rather than a

package/dist/node-io.js

@@ -4,7 +4,7 @@
  * command, not the MCP stdio transport.
  */
 import { terminalWidth, wrapForTerminal } from './diagnose/terminal-wrap.js';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, accessSync, constants, } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, accessSync, constants, lstatSync, } from 'node:fs';
 import { NodePlatform } from './detect/platform.js';
 import { join, dirname, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
@@ -24,7 +24,7 @@ function shellSafe(args) {
 /**
  * Every program `init` is ever allowed to run.
  *
- * The set is closed and tiny — the four package managers, `npx`, `corepack`, and the Claude CLI —
+ * The set is closed and tiny — the four package managers, `npx`, `corepack`, and the Claude and Codex CLIs —
  * because those are the only things the plan can ask for. It is a named constant for the same reason
  * every other wire string here is one, and it is CHECKED because of the shell: on Windows these spawn
  * through a shell, and a shell turns the command name into something the shell parses rather than a
@@ -46,6 +46,7 @@ export const RUNNABLE_COMMANDS = [
     'npx',
     'corepack',
     'claude',
+    'codex',
 ];
 /** The command, proven to be one of `RUNNABLE_COMMANDS` — never the caller's string. */
 function runnable(command) {
@@ -158,6 +159,14 @@ export function buildNodeIo(cwd, host, output = {}) {
                 return [];
             }
         },
+        isSymlink(rel) {
+            try {
+                return lstatSync(abs(rel)).isSymbolicLink();
+            }
+            catch {
+                return false;
+            }
+        },
         scoped(rel) {
             // The host travels with the re-rooted IO: a monorepo redirect re-enters `runInit` through
             // this, and an untraced, unreported inner run is the half of init that actually did the work.

package/dist/patch/next-patch.d.ts

@@ -5,6 +5,7 @@
  * half-edit. These must not be left manual: both edits fail silently when skipped, and one of them
  * is JSX.
  */
+import type { InitIo } from '../run-types.js';
 import { type SourcePatch } from './patch-kind.js';
 /** Where the generated connect component goes, and how the mount file should import it. */
 interface ReticleDevLocation {
@@ -41,9 +42,36 @@ export declare function patchRootLayout(source: string): SourcePatch;
  * ReticleDev component has to land NEXT TO the layout or the relative import it generates is dead.
  */
 export declare const NEXT_LAYOUT_CANDIDATES: string[];
+/** What `findRouteGroupRootLayout` found: the layout to mount into, or the ones it could not choose between. */
+export type RouteGroupLayouts = {
+    path: string;
+} | {
+    candidates: string[];
+};
+type ListingIo = Pick<InitIo, 'listDirs' | 'listFiles' | 'readFile'>;
+/**
+ * The root layout of an App Router app with no top-level `app/layout.*`: its root layouts then live
+ * in route groups (`app/(site)/layout.tsx`), one per group, which Next documents as "multiple root
+ * layouts" (#1538). `null` when the app has none, so the Pages Router candidates are still asked.
+ *
+ * One layout is chosen, because a step patches one file: a group layout that already mounts
+ * `<ReticleDev />` (so the patch reports it already wired), else the one group that renders `/`,
+ * else the only group layout there is. Several and none of those is returned as candidates, so the
+ * manual step can name them rather than say there is no root layout.
+ */
+export declare function findRouteGroupRootLayout(io: ListingIo): RouteGroupLayouts | null;
 /**
  * Pages Router mount points, checked only when there is no App Router layout. A Pages app has no
  * `app/` directory at all, so writing the component there produced a file nothing imported.
  */
 export declare const NEXT_PAGES_APP_CANDIDATES: string[];
+/**
+ * The file `<ReticleDev />` is mounted in: the App Router's root layout, then a route-group root
+ * layout (#1538), then the Pages Router's `_app`. `candidates` is set when route groups hold several
+ * root layouts and none could be chosen, so the manual step can name them.
+ */
+export declare function findNextMountFile(io: ListingIo & Pick<InitIo, 'exists'>): {
+    path: string | null;
+    candidates?: string[];
+};
 export {};

package/dist/patch/next-patch.js

@@ -223,6 +223,57 @@ export const NEXT_LAYOUT_CANDIDATES = [
     'src/app/layout.jsx',
     'src/app/layout.js',
 ];
+/** The App Router roots, in the order `NEXT_LAYOUT_CANDIDATES` checks them. */
+const NEXT_APP_DIRS = ['app', 'src/app'];
+const LAYOUT_BASENAMES = ['layout.tsx', 'layout.jsx', 'layout.js'];
+const PAGE_FILE = /^page\.(tsx|ts|jsx|js|mdx)$/;
+/** `(marketing)`: a route group, which organises routes without adding a URL segment. */
+const ROUTE_GROUP = /^\(.+\)$/;
+/** Whether `dir` renders `/`: a page of its own, or one in a route group nested under it. */
+function servesRoot(io, dir) {
+    if (io.listFiles(dir).some((name) => PAGE_FILE.test(name)))
+        return true;
+    return io
+        .listDirs(dir)
+        .filter((name) => ROUTE_GROUP.test(name))
+        .some((name) => servesRoot(io, `${dir}/${name}`));
+}
+/**
+ * The root layout of an App Router app with no top-level `app/layout.*`: its root layouts then live
+ * in route groups (`app/(site)/layout.tsx`), one per group, which Next documents as "multiple root
+ * layouts" (#1538). `null` when the app has none, so the Pages Router candidates are still asked.
+ *
+ * One layout is chosen, because a step patches one file: a group layout that already mounts
+ * `<ReticleDev />` (so the patch reports it already wired), else the one group that renders `/`,
+ * else the only group layout there is. Several and none of those is returned as candidates, so the
+ * manual step can name them rather than say there is no root layout.
+ */
+export function findRouteGroupRootLayout(io) {
+    for (const appDir of NEXT_APP_DIRS) {
+        const layouts = io
+            .listDirs(appDir)
+            .filter((name) => ROUTE_GROUP.test(name))
+            .sort()
+            .flatMap((group) => {
+            const dir = `${appDir}/${group}`;
+            const files = io.listFiles(dir);
+            const layout = LAYOUT_BASENAMES.find((name) => files.includes(name));
+            return layout === undefined ? [] : [{ dir, path: `${dir}/${layout}` }];
+        });
+        if (0 === layouts.length)
+            continue;
+        const wired = layouts.find((l) => true === io.readFile(l.path)?.includes(RETICLE_DEV_COMPONENT));
+        if (wired !== undefined)
+            return { path: wired.path };
+        const root = layouts.filter((l) => servesRoot(io, l.dir));
+        if (1 === root.length && root[0] !== undefined)
+            return { path: root[0].path };
+        if (1 === layouts.length && layouts[0] !== undefined)
+            return { path: layouts[0].path };
+        return { candidates: layouts.map((l) => l.path) };
+    }
+    return null;
+}
 /**
  * Pages Router mount points, checked only when there is no App Router layout. A Pages app has no
  * `app/` directory at all, so writing the component there produced a file nothing imported.
@@ -235,3 +286,18 @@ export const NEXT_PAGES_APP_CANDIDATES = [
     'src/pages/_app.jsx',
     'src/pages/_app.js',
 ];
+/**
+ * The file `<ReticleDev />` is mounted in: the App Router's root layout, then a route-group root
+ * layout (#1538), then the Pages Router's `_app`. `candidates` is set when route groups hold several
+ * root layouts and none could be chosen, so the manual step can name them.
+ */
+export function findNextMountFile(io) {
+    const top = NEXT_LAYOUT_CANDIDATES.find((p) => io.exists(p));
+    if (top !== undefined)
+        return { path: top };
+    const groups = findRouteGroupRootLayout(io);
+    if (groups !== null && 'path' in groups)
+        return { path: groups.path };
+    const pagesApp = NEXT_PAGES_APP_CANDIDATES.find((p) => io.exists(p)) ?? null;
+    return null === groups ? { path: pagesApp } : { path: pagesApp, candidates: groups.candidates };
+}

package/dist/patch/nuxt-snippets.js

@@ -130,6 +130,6 @@ and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which i
 
 The package is @reticlehq/browser — the framework-neutral sensor. DOM, network, console, routing and
 source file:line all work in Vue. What you do not get is React component identity, which is the only
-thing the React adapter adds. The install gate scaffolds a Nuxt app on every release and requires a session, so this wiring
+thing the React adapter adds. The install gate scaffolds a Nuxt app whenever the install path changes and requires a session, so this wiring
 is proven; if something does not work, please open an issue.`;
 }

package/dist/patch/snippets.d.ts

@@ -182,7 +182,7 @@ export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
  * reporting all-green.
  */
 export declare function unverifiedUiLibraryNote(library: string, installGated?: boolean): string;
-export declare 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 declare 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 declare const UNVERIFIED_TANSTACK_START_NOTE = "Reticle has no TanStack Start app and no CI gate for one, so this wiring is untested \u2014 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/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 [
                 {