@reticlehq/init 2.14.0 → 3.2.0

package/dist/plan/notices.js

@@ -0,0 +1,94 @@
+/**
+ * Steps that TELL the user something rather than change anything.
+ *
+ * `StepStatus.NOTICE` exists because reporting these as `manual` made "steps left to do" a
+ * number that could never reach zero. They are one category by that test: a dev server in a
+ * container, an MCP registration Windows will not take, a UI library no gate covers. Reticle is
+ * not going to fix any of them and the user is better off knowing.
+ *
+ * They live together because that shared test is a real seam.
+ */
+import { CONTAINERISED_TITLE, containerisedDevServerNote } from '../diagnose/containerised-dev-server.js';
+import { mcpWindowsNote } from '../register/mcp.js';
+import { unverifiedUiLibraryNote, WEBGL_CANVAS_LIMIT_NOTE } from '../patch/snippets.js';
+import { FRAMEWORK_ADAPTERS } from './framework-adapter.js';
+import { NodePlatform } from '../detect/platform.js';
+import { UiLibrary } from '../detect/detect.js';
+// `Step` and `PlanInput` are TYPES, so importing them back from `plan.ts` is erased at build
+// time and creates no cycle. `StepStatus` and `MCP_TARGET` are values, and both are read inside
+// function bodies rather than at module scope, which is what keeps the pair safe to import in
+// both directions. If a third value is ever needed here, move the vocabulary to its own module
+// rather than widening this.
+import { MCP_TARGET, StepStatus } from './plan-types.js';
+const WINDOWS_MCP_TITLE = 'Windows MCP spawn';
+/**
+ * The two things a containerised dev server does differently, said before they go wrong.
+ *
+ * Null for every project with no container marker near it, which is almost all of them — so this
+ * adds nothing to the ordinary plan and does not move the install baseline.
+ */
+export function containerisedStep(input) {
+    const marker = input.containerMarker;
+    if (marker === undefined || 0 === marker.length)
+        return null;
+    return {
+        title: CONTAINERISED_TITLE,
+        target: marker,
+        status: StepStatus.NOTICE,
+        detail: containerisedDevServerNote(marker),
+    };
+}
+/** Windows only. The reported install never reached mcpManual because `claude mcp add` succeeded. */
+export function windowsMcpNoteStep(input) {
+    if (input.platform !== NodePlatform.WINDOWS)
+        return null;
+    return {
+        title: WINDOWS_MCP_TITLE,
+        target: MCP_TARGET,
+        status: StepStatus.NOTICE,
+        detail: mcpWindowsNote(),
+    };
+}
+/**
+ * A step that says out loud when the app isn't React. SvelteKit already carries its own unverified
+ * note, so it isn't doubled up here.
+ */
+export function uiLibraryStep(input) {
+    const lib = input.detection.uiLibrary;
+    // A framework whose own recipe already says it is unverified must not be argued with by a second,
+    // more generic notice. Asked of the registry rather than of a remembered `SVELTEKIT || NUXT` pair:
+    // the pair was the answer, not the question, and a third framework joining it was a silent edit.
+    if (lib === UiLibrary.REACT)
+        return [];
+    if (FRAMEWORK_ADAPTERS[input.detection.framework].carriesOwnUnverifiedNote)
+        return [];
+    if (lib === UiLibrary.UNKNOWN)
+        return [];
+    return [
+        {
+            title: `${lib} is UNVERIFIED`,
+            target: 'package.json',
+            status: StepStatus.NOTICE,
+            detail: unverifiedUiLibraryNote(lib),
+        },
+    ];
+}
+/**
+ * A WebGL subtree is pixels, and Reticle reads the DOM.
+ *
+ * react-three-fiber and its relatives render into a canvas, so the tools that find and drive
+ * elements have nothing to find. Disclosed rather than blocked: the rest of the app is still
+ * verifiable and a NOTICE says which part is not.
+ */
+export function webGlCanvasStep(input) {
+    if (true !== input.detection.webGlSubtree)
+        return [];
+    return [
+        {
+            title: 'WebGL canvas is not observable',
+            target: 'package.json',
+            status: StepStatus.NOTICE,
+            detail: WEBGL_CANVAS_LIMIT_NOTE,
+        },
+    ];
+}

package/dist/{plan-electron-vite.d.ts → plan/plan-electron-vite.d.ts}

@@ -1,11 +1,10 @@
 /**
  * The plan's electron-vite half: the renderer plugin, capabilities, and the two Electron steps.
  *
- * Its own module rather than more of `plan-framework.ts`, which was at the 1000-line backstop.
- * Cohesive on its own terms: this is the only framework whose wiring reaches outside the renderer,
- * into a preload and a main process that the web frameworks have no equivalent of.
+ * Its own module because this is the only framework whose wiring reaches outside the renderer, into
+ * a preload and a main process the web frameworks have no equivalent of.
  */
-import { type PlanInput, type Step } from './plan.js';
+import { type PlanInput, type Step } from './plan-types.js';
 /**
  * electron-vite: the renderer plugin, then capabilities, then the two Electron halves.
  *

package/dist/{plan-electron-vite.js → plan/plan-electron-vite.js}

@@ -1,17 +1,16 @@
 /**
  * The plan's electron-vite half: the renderer plugin, capabilities, and the two Electron steps.
  *
- * Its own module rather than more of `plan-framework.ts`, which was at the 1000-line backstop.
- * Cohesive on its own terms: this is the only framework whose wiring reaches outside the renderer,
- * into a preload and a main process that the web frameworks have no equivalent of.
+ * Its own module because this is the only framework whose wiring reaches outside the renderer, into
+ * a preload and a main process the web frameworks have no equivalent of.
  */
-import { StepStatus } from './plan.js';
+import { StepStatus } from './plan-types.js';
 import { StepTitle } from './connect-steps.js';
 import { capabilitiesStep, patchStep } from './plan-framework.js';
-import { patchElectronViteConfig } from './electron-vite-patch.js';
-import { patchElectronMain, patchElectronPreload } from './electron-patch.js';
-import { ELECTRON_CAPTURE_FIX, ELECTRON_PRELOAD_FIX } from './desktop-doctor.js';
-import { electronViteManual, ELECTRON_VITE_DEV_MODULE_PATH } from './snippets.js';
+import { patchElectronViteConfig } from '../patch/electron-vite-patch.js';
+import { patchElectronMain, patchElectronPreload } from '../patch/electron-patch.js';
+import { ELECTRON_CAPTURE_FIX, ELECTRON_PRELOAD_FIX } from '../diagnose/desktop-doctor.js';
+import { electronViteManual, ELECTRON_VITE_DEV_MODULE_PATH } from '../patch/snippets.js';
 /**
  * electron-vite: the renderer plugin, then capabilities, then the two Electron halves.
  *

package/dist/{plan-framework.d.ts → plan/plan-framework.d.ts}

@@ -1,10 +1,10 @@
 /**
  * How each framework gets wired: the Vite plugin, the three Next files, the SvelteKit client hook.
- * Split out of `plan.ts` — that file is the plan's SHAPE (statuses, ordering, the agent/MCP steps),
- * this one is the per-framework detail, and they grow for different reasons.
+ * `plan.ts` is the plan's SHAPE (statuses, ordering, the agent/MCP steps); this is the per-framework
+ * detail, and they grow for different reasons.
  */
-import { type SourcePatch } from './patch-kind.js';
-import { type PlanInput, type Step } from './plan.js';
+import { type SourcePatch } from '../patch/patch-kind.js';
+import { type PlanInput, type Step } from './plan-types.js';
 import { StepTitle } from './connect-steps.js';
 /** What adding `reticle()` to a Vite config buys, which differs by framework. */
 export declare const VITE_PLUGIN_DETAIL: {
@@ -111,12 +111,3 @@ export declare function cspStep(input: PlanInput): Step[];
  * where the if/else chain this replaced used to hand it these instructions silently.
  */
 export declare function htmlSteps(input: PlanInput): Step[];
-/**
- * The per-framework half of the plan, looked up rather than switched.
- *
- * `FRAMEWORK_ADAPTERS` is a `Record<Framework, FrameworkAdapter>`, so a member added to `Framework`
- * is a compile error in that one table instead of a framework the plan quietly does not serve. The
- * exhaustive switch this replaced gave the same guarantee for the steps alone; the record gives it
- * for the packages, the connect-step titles and the unverified-note flag in the same edit.
- */
-export declare function frameworkSteps(input: PlanInput): Step[];

package/dist/{plan-framework.js → plan/plan-framework.js}

@@ -1,24 +1,23 @@
 /**
  * How each framework gets wired: the Vite plugin, the three Next files, the SvelteKit client hook.
- * Split out of `plan.ts` — that file is the plan's SHAPE (statuses, ordering, the agent/MCP steps),
- * this one is the per-framework detail, and they grow for different reasons.
+ * `plan.ts` is the plan's SHAPE (statuses, ordering, the agent/MCP steps); this is the per-framework
+ * detail, and they grow for different reasons.
  */
 import { bridgeWsUrl } from '@reticlehq/core';
-import { patchViteConfig, VitePatchKind, VITE_IMPORT } from './vite-config.js';
-import { patchNextConfig, patchRootLayout, patchPagesApp } from './next-patch.js';
-import { ASTRO_ENV_DTS_PATH, patchAstroConfig, patchAstroEnvDts, patchAstroLayout, } from './astro-patch.js';
-import { CRA_DEV_MODULE_IMPORT, CRA_ENV_PATH, CRA_TOKEN_PER_MACHINE_NOTICE, TOKEN_VAR, craDevModuleFile, craDevModulePath, craEnvPatch, craImportPatch, } from './cra.js';
-import { PatchKind } from './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 './snippets.js';
-import { hasOptOut, OPT_OUT_MARKER } from './init-opt-out.js';
-import { StepStatus } from './plan.js';
+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 { 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';
+import { hasOptOut, OPT_OUT_MARKER } from '../detect/declared/init-opt-out.js';
+import { StepStatus } from './plan-types.js';
 import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { CSP_STEP_TITLE } from './csp-check.js';
+import { CSP_STEP_TITLE } from '../diagnose/csp-check.js';
 import { StepTitle } from './connect-steps.js';
-import { tanstackStartManual, TANSTACK_START_ROOT_PATH } from './tanstack-start.js';
-import { FRAMEWORK_ADAPTERS } from './framework-adapter.js';
-import { diagnoseWebCsp } from './csp-doctor.js';
-import { patchNuxtConfig } from './nuxt-patch.js';
+import { tanstackStartManual, TANSTACK_START_ROOT_PATH } from '../patch/tanstack-start.js';
+import { diagnoseWebCsp } from '../diagnose/csp-doctor.js';
+import { patchNuxtConfig } from '../patch/nuxt-patch.js';
 /** What adding `reticle()` to a Vite config buys, which differs by framework. */
 export const VITE_PLUGIN_DETAIL = {
     /** A plain Vite app gets both halves from the plugin. */
@@ -352,14 +351,6 @@ export function nextSteps(input) {
         patchStep(StepTitle.MOUNT_RETICLE_DEV, layout?.path ?? NEXT_LAYOUT_PATH, layoutPatch, 'mount <ReticleDev /> in the root layout (dev-only)', NEXT_LAYOUT_MANUAL),
     ];
 }
-/**
- * SvelteKit is WIRED but not SUPPORTED, and the plan says so out loud.
- *
- * There is no SvelteKit app in `apps/` and no CI gate for one, so nothing proves this hook still
- * registers a session — every other framework init offers (React, Next, Remix, Astro) has both. The
- * wiring is real and may well work; what is missing is anything that would tell us when it stops.
- * Silently emitting it reads as a support claim, which is the thing this project exists to not do.
- */
 /**
  * The one failure `init` cannot otherwise see: the bundler will not parse our SDK.
  *
@@ -760,14 +751,3 @@ export function htmlSteps(input) {
         },
     ];
 }
-/**
- * The per-framework half of the plan, looked up rather than switched.
- *
- * `FRAMEWORK_ADAPTERS` is a `Record<Framework, FrameworkAdapter>`, so a member added to `Framework`
- * is a compile error in that one table instead of a framework the plan quietly does not serve. The
- * exhaustive switch this replaced gave the same guarantee for the steps alone; the record gives it
- * for the packages, the connect-step titles and the unverified-note flag in the same edit.
- */
-export function frameworkSteps(input) {
-    return FRAMEWORK_ADAPTERS[input.detection.framework].steps(input);
-}

package/dist/{plan.d.ts → plan/plan-types.d.ts}

@@ -1,22 +1,13 @@
 /**
- * Pure assembly of the `reticle init` action plan. Given the detection result and the relevant file
- * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
- * runner performs the `write` side-effects; this module decides *what* should happen.
- */
-import { Framework, UiLibrary, type Detection } from './detect.js';
-import type { FoundStore } from './capabilities.js';
-import { McpClient } from './mcp-clients.js';
-import { RETICLE_CONFIG_FILE } from './existing-config.js';
-export { RETICLE_CONFIG_FILE };
-/**
- * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
+ * The plan's vocabulary: what a step IS, what status it can be in, and what a plan is built from.
  *
- * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
- * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
- * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
- * right after `init` had detected the real UI library and said so on screen.
+ * A leaf. Four modules that `plan.ts` calls — the framework adapters, the electron-vite steps, the
+ * per-framework steps and the notices — each named these to declare their own signatures, and all
+ * four had to import them back out of the module that calls them.
  */
-export declare function frameworkPackages(framework: Framework, uiLibrary?: UiLibrary): readonly string[];
+import type { Detection, Framework, UiLibrary } from '../detect/detect.js';
+import type { FoundStore } from '../detect/capabilities.js';
+import type { McpClient } from '../register/mcp-clients.js';
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
 export declare const MCP_TARGET = "global (claude user scope)";
 /** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
@@ -260,6 +251,13 @@ export interface PlanInput {
     pairingToken?: string;
     /** Whether .reticle.json already exists in the project root (idempotency). */
     reticleConfigExists?: boolean;
+    /**
+     * The container marker found near the app (`Dockerfile`, `docker-compose.yml`, …), or undefined.
+     *
+     * Not proof the dev server runs in one — see containerised-dev-server.ts for why over-eager is the
+     * right direction here, and for what goes wrong when it does.
+     */
+    containerMarker?: string | undefined;
     /**
      * Its CONTENT, so an existing config can be checked instead of trusted.
      *
@@ -309,4 +307,3 @@ export interface PlanInput {
         sdkVersion?: string;
     };
 }
-export declare function buildPlan(input: PlanInput): Plan;

package/dist/plan/plan-types.js

@@ -0,0 +1,24 @@
+/**
+ * The plan's vocabulary: what a step IS, what status it can be in, and what a plan is built from.
+ *
+ * A leaf. Four modules that `plan.ts` calls — the framework adapters, the electron-vite steps, the
+ * per-framework steps and the notices — each named these to declare their own signatures, and all
+ * four had to import them back out of the module that calls them.
+ */
+/** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
+export const MCP_TARGET = 'global (claude user scope)';
+/** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
+export const DEPS_TARGET = 'package.json';
+export const StepStatus = {
+    APPLY: 'apply',
+    MANUAL: 'manual',
+    ALREADY: 'already',
+    SKIP: 'skip',
+    /**
+     * Something the user should KNOW, not something they must DO. The UNVERIFIED lines are the case:
+     * a Preact or SvelteKit app is wired and working, it just isn't covered by a gate. Reporting those
+     * as `manual` made "steps left to do" a number that could never reach zero, and made a release gate
+     * read two regressions that were not regressions.
+     */
+    NOTICE: 'notice',
+};

package/dist/plan/plan.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure assembly of the `reticle init` action plan. Given the detection result and the relevant file
+ * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
+ * runner performs the `write` side-effects; this module decides *what* should happen.
+ */
+import { Framework, UiLibrary } from '../detect/detect.js';
+import { type Plan, type PlanInput } from './plan-types.js';
+export { DEPS_TARGET, MCP_TARGET, StepStatus, type Step, type Plan, type PlanInput, } from './plan-types.js';
+import { RETICLE_CONFIG_FILE } from '../detect/existing-config.js';
+export { RETICLE_CONFIG_FILE };
+/**
+ * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
+ *
+ * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
+ * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
+ * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
+ * right after `init` had detected the real UI library and said so on screen.
+ */
+export declare function frameworkPackages(framework: Framework, uiLibrary?: UiLibrary): readonly string[];
+export declare function buildPlan(input: PlanInput): Plan;

package/dist/{plan.js → plan/plan.js}

@@ -3,30 +3,33 @@
  * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
-import { Framework, UiLibrary, installCommand, installCommandParts, } from './detect.js';
-import { installFailureHint } from './install-hint.js';
-import { installRetries } from './install-retries.js';
-import { claudeAddCommand, mcpManual, mcpWindowsNote } from './mcp.js';
-import { NodePlatform } from './platform.js';
-import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, McpClient, } from './mcp-clients.js';
-import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from './slash-command.js';
-import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, markedBlock, AGENTS_MD_PATH, RETICLE_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
-import { cspStep, frameworkSteps } from './plan-framework.js';
+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 { 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';
+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';
+export { DEPS_TARGET, MCP_TARGET, StepStatus, } from './plan-types.js';
 import { join } from 'node:path';
-import { reticleConfigContent, unverifiedUiLibraryNote, WEBGL_CANVAS_LIMIT_NOTE, } from './snippets.js';
-import { configWithInstallSource } from './install-source-config.js';
-import { existingConfigProblem, projectIdOf, RETICLE_CONFIG_FILE } from './existing-config.js';
+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';
 // Re-exported: it moved to the module that reads it, and every existing importer says `plan.js`.
 export { RETICLE_CONFIG_FILE };
 /**
  * Pin the SDK to the CLI's own version.
  *
- * `pnpm add -D @reticlehq/react` installed **2.2.1** in one project while npm and yarn took 2.3.0 in
- * the next — a stale registry metadata cache, invisible to the user and to us. A version-skewed SDK
- * talking to a newer daemon is the `-32000` failure path: the app connects, the protocol disagrees,
- * and nothing on either side names a version. Asking for the CLI's exact version makes the cache
- * irrelevant, and a skewed pair impossible to install by accident.
+ * `pnpm add -D @reticlehq/react` once installed an older release in one project while npm and yarn
+ * took the current one in the next — a stale registry metadata cache, invisible to everyone. A
+ * version-skewed SDK talking to a newer daemon is the `-32000` failure path: the app connects, the
+ * protocol disagrees, and nothing on either side names a version. Asking for the CLI's exact version
+ * makes the cache irrelevant, and a skewed pair impossible to install by accident.
  */
 function pinnedPackages(packages, version) {
     if (version === undefined || 0 === version.length)
@@ -59,23 +62,6 @@ export function frameworkPackages(framework, uiLibrary = UiLibrary.UNKNOWN) {
     const kit = wantsReactKit(uiLibrary) ? RETICLE_REACT_KIT : RETICLE_BROWSER_SDK;
     return FRAMEWORK_ADAPTERS[framework].packages(kit);
 }
-/** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
-export const MCP_TARGET = 'global (claude user scope)';
-/** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
-export const DEPS_TARGET = 'package.json';
-export const StepStatus = {
-    APPLY: 'apply',
-    MANUAL: 'manual',
-    ALREADY: 'already',
-    SKIP: 'skip',
-    /**
-     * Something the user should KNOW, not something they must DO. The UNVERIFIED lines are the case:
-     * a Preact or SvelteKit app is wired and working, it just isn't covered by a gate. Reporting those
-     * as `manual` made "steps left to do" a number that could never reach zero, and made a release gate
-     * read two regressions that were not regressions.
-     */
-    NOTICE: 'notice',
-};
 /**
  * Where the agent-facing files go, which is not always where the app is.
  *
@@ -188,18 +174,6 @@ function mcpSteps(input) {
         steps.push(windowsNote);
     return steps;
 }
-const WINDOWS_MCP_TITLE = 'Windows MCP spawn';
-/** Windows only. The reported install never reached mcpManual because `claude mcp add` succeeded. */
-function windowsMcpNoteStep(input) {
-    if (input.platform !== NodePlatform.WINDOWS)
-        return null;
-    return {
-        title: WINDOWS_MCP_TITLE,
-        target: MCP_TARGET,
-        status: StepStatus.NOTICE,
-        detail: mcpWindowsNote(),
-    };
-}
 const SLASH_COMMAND_TITLE = 'The /reticle command';
 /**
  * Nothing to do for this command file: it already holds the CURRENT body, or it is not ours at all.
@@ -436,8 +410,8 @@ function agentRuleSteps(input) {
  *
  * pnpm's `minimumReleaseAge` refuses any release younger than the configured window — a deliberate
  * supply-chain policy, not a bug — with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`. Unpinned it silently
- * resolves to an OLDER version instead, which is how an app ends up running a 2.2.1 SDK against a
- * 2.3.0 daemon: the connection succeeds, the protocol disagrees, and the failure surfaces as -32000
+ * resolves to an OLDER version instead, which is how an app ends up running a stale SDK against a
+ * newer daemon: the connection succeeds, the protocol disagrees, and the failure surfaces as -32000
  * 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.
  */
@@ -594,46 +568,6 @@ function reticleConfigSteps(input) {
         input.installSource);
     return [reticleConfigStep(input, content), ...agentRootConfigStep(input, content)];
 }
-/**
- * A step that says out loud when the app isn't React. SvelteKit already carries its own unverified
- * note, so it isn't doubled up here.
- */
-function uiLibraryStep(input) {
-    const lib = input.detection.uiLibrary;
-    // A framework whose own recipe already says it is unverified must not be argued with by a second,
-    // more generic notice. Asked of the registry rather than of a remembered `SVELTEKIT || NUXT` pair:
-    // the pair was the answer, not the question, and a third framework joining it was a silent edit.
-    if (lib === UiLibrary.REACT)
-        return [];
-    if (FRAMEWORK_ADAPTERS[input.detection.framework].carriesOwnUnverifiedNote)
-        return [];
-    if (lib === UiLibrary.UNKNOWN)
-        return [];
-    return [
-        {
-            title: `${lib} is UNVERIFIED`,
-            target: 'package.json',
-            status: StepStatus.NOTICE,
-            detail: unverifiedUiLibraryNote(lib),
-        },
-    ];
-}
-/**
- * Say the WebGL gap out loud at install time. Without it, init looks fully green on an R3F app
- * while the canvas — often the product — stays a blank rectangle to every look and act tool (#880).
- */
-function webGlCanvasStep(input) {
-    if (true !== input.detection.webGlSubtree)
-        return [];
-    return [
-        {
-            title: 'WebGL canvas is not observable',
-            target: 'package.json',
-            status: StepStatus.NOTICE,
-            detail: WEBGL_CANVAS_LIMIT_NOTE,
-        },
-    ];
-}
 export function buildPlan(input) {
     const steps = [
         ...cspStep(input),
@@ -646,5 +580,10 @@ export function buildPlan(input) {
         ...reticleConfigSteps(input),
     ];
     steps.push(...frameworkSteps(input));
+    // 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);
+    if (container !== null)
+        steps.push(container);
     return { framework: input.detection.framework, uiLibrary: input.detection.uiLibrary, steps };
 }

package/dist/{agent-rules.d.ts → project/agent-rules.d.ts}

@@ -82,7 +82,7 @@ export declare const CLI = "npx @reticlehq/server";
  *
  * Exported because slash-command.ts renders the same rule; there must not be two versions of it.
  */
-export declare const DEV_SERVER_POLICY = "**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_sessions` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.";
+export declare const DEV_SERVER_POLICY = "**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.";
 /**
  * The operative rules, carried by every file that loads on every turn.
  *
@@ -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_sequence` rather than one round trip per field.\n- Read the surrounding evidence with `reticle_snapshot`, `reticle_state`, `reticle_network`, `reticle_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, or just restarted? You are mid-sequence \u2014 do not stop until a verdict exists.**\nThe whole of it is: instrument the app \u2192 get a dev server running \u2192 open the app in a browser \u2192\ndrive one flow \u2192 report the verdict. Every step is yours to do, and none of them needs the user.\nThe ONE legitimate pause is a client restart, because a client reads its server list at startup;\nwhen you come back, you are not finished, you are on the next step \u2014 resume it without being asked.\nStopping anywhere else leaves an app that looks installed and can verify nothing, which is the\nsingle commonest way this goes wrong. `/reticle` carries the full recovery ladder when a step\ndoes not work; use it rather than guessing, and never report the install as finished without a\nverdict 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_sessions` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.\n\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_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.** `reticle_intent` records the business outcome a change is meant to produce, and the only moment anybody knows it is while the change is being made. Pass `intent` when you save a flow, 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? It exists.** The default surface advertises a subset; reach any other by name with `reticle_run { tool, args }`, and list them with `reticle_tools`. Two worth knowing: `reticle_context` returns this run's own memory \u2014 what is established, what is proven, what is still unverified \u2014 which is what you want after a compaction or when picking up work you did not start; `reticle_intent` records what a change was MEANT to do, while somebody still knows.\n\n**Report Reticle's own defects with `reticle_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_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:**\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.**";
 /** The full-rules file, written verbatim (no markers: `init` owns this file entirely). */
 export declare function reticleMdFile(): string;
 export declare const AgentRuleStatus: {