@reticlehq/server 2.7.0 → 2.8.0

package/dist/index.js

@@ -14,6 +14,7 @@ import { RecordingStore } from './flows/recordings.js';
 import { FlowStore } from './flows/flows.js';
 import { buildFlowChips } from './flows/flow-scope.js';
 import { ProjectStore } from './project/project-store.js';
+import { attachRouteLearning } from './project/learned-routes.js';
 import { AnnotationStore } from './flows/annotation-store.js';
 import { createNodeFileSystem } from './project/fs-port.js';
 import { cleanupCaptureDirectories } from './visual/capture-cleanup.js';
@@ -253,6 +254,7 @@ export async function start(options = {}) {
         attachJournal(bridge, { fs, reticleRoot, enabled: journalEnabled });
         const flows = new FlowStore(fs, reticleRoot, { now });
         const project = new ProjectStore(fs, reticleRoot, { now });
+        attachRouteLearning(bridge, project);
         const annotations = new AnnotationStore();
         pool = createBrowserPool(options.headless ?? true);
         leaseReaper = new LeaseReaper(pool);
@@ -345,6 +347,7 @@ export async function startDaemon(options = {}) {
     attachJournal(bridge, { fs, reticleRoot, enabled: journalEnabled });
     const flows = new FlowStore(fs, reticleRoot, { now });
     const project = new ProjectStore(fs, reticleRoot, { now });
+    attachRouteLearning(bridge, project);
     const annotations = new AnnotationStore();
     const pool = createBrowserPool(options.headless ?? true);
     const leaseReaper = new LeaseReaper(pool);

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

@@ -20,6 +20,20 @@
 /** Project-root instruction files the agent re-reads every session. */
 export declare const CLAUDE_MD_PATH = "CLAUDE.md";
 export declare const AGENTS_MD_PATH = "AGENTS.md";
+/**
+ * The full rules, written once and pointed at from every always-loaded file.
+ *
+ * Two problems it solves at the same time. The rule text is dense and most of it is REFERENCE (what
+ * to do when the tools are missing, what a `version_skew` field means, how to file feedback), which
+ * an agent needs on the turn it hits that situation and never before — so carrying all of it in
+ * `CLAUDE.md` taxed every session for text almost every session did not read. And `AGENTS.md` was
+ * only written when NO agent was detected, so a repo set up on a Claude Code machine told Codex,
+ * Copilot, Amp and every other agent nothing at all.
+ *
+ * So: the operative rules (when to verify, WHEN NOT TO, how, and the honesty guards) go in the files
+ * that load every turn, and this file holds the rest, one hop away and named in that block.
+ */
+export declare const RETICLE_MD_PATH = "RETICLE.md";
 /** Cursor project rule; the frontmatter `alwaysApply` keeps it in context on every turn. */
 export declare const CURSOR_RULE_PATH = ".cursor/rules/reticle.mdc";
 /**
@@ -33,6 +47,8 @@ export declare const CURSOR_RULE_PATH = ".cursor/rules/reticle.mdc";
  * the package's own name so the two can never drift apart.
  */
 export declare const CLI: string;
+/** The full-rules file, written verbatim (no markers: `init` owns this file entirely). */
+export declare function reticleMdFile(): string;
 export declare const AgentRuleStatus: {
     readonly APPLY: "apply";
     readonly ALREADY: "already";

package/dist/init/agent-rules.js

@@ -22,6 +22,20 @@ import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
 /** Project-root instruction files the agent re-reads every session. */
 export const CLAUDE_MD_PATH = 'CLAUDE.md';
 export const AGENTS_MD_PATH = 'AGENTS.md';
+/**
+ * The full rules, written once and pointed at from every always-loaded file.
+ *
+ * Two problems it solves at the same time. The rule text is dense and most of it is REFERENCE (what
+ * to do when the tools are missing, what a `version_skew` field means, how to file feedback), which
+ * an agent needs on the turn it hits that situation and never before — so carrying all of it in
+ * `CLAUDE.md` taxed every session for text almost every session did not read. And `AGENTS.md` was
+ * only written when NO agent was detected, so a repo set up on a Claude Code machine told Codex,
+ * Copilot, Amp and every other agent nothing at all.
+ *
+ * So: the operative rules (when to verify, WHEN NOT TO, how, and the honesty guards) go in the files
+ * that load every turn, and this file holds the rest, one hop away and named in that block.
+ */
+export const RETICLE_MD_PATH = 'RETICLE.md';
 /** Cursor project rule; the frontmatter `alwaysApply` keeps it in context on every turn. */
 export const CURSOR_RULE_PATH = '.cursor/rules/reticle.mdc';
 /** Markers delimiting the managed block so a re-run is idempotent and the block stays updatable. */
@@ -38,36 +52,96 @@ const RULE_END = '<!-- reticle:end -->';
  * the package's own name so the two can never drift apart.
  */
 export const CLI = `${NPX} ${RETICLE_NPM_PACKAGE}`;
-/** The rule body (markdown). States WHEN to verify, HOW, and never-weaken-a-check. */
+/**
+ * The operative rules, carried by every file that loads on every turn.
+ *
+ * Short on purpose. This is the text that has to CHANGE BEHAVIOUR, so it states when to verify, when
+ * 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.
+ */
 const RULE_BODY = `## Verifying with Reticle
 
-This app is instrumented by **Reticle** — an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`${CLI}\` CLI (run it through npx — Reticle's server is not installed into this project). Verifying is part of "done", not an optional extra.
+This app is instrumented by **Reticle**, an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`${CLI}\` CLI (always through npx: Reticle's server is not installed into this project). Verifying is part of "done", not an optional extra.
+
+**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.
+
+**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.
+
+**How to verify:**
+
+- 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.
+- Batch a multi-step journey (a login, a form) into one \`reticle_act_sequence\` rather than one round trip per field.
+- Read the surrounding evidence with \`reticle_snapshot\`, \`reticle_state\`, \`reticle_network\`, \`reticle_console\`.
+- **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.
+- Covered flows: \`${CLI} gate\` reports which recorded flows the changed files affect and whether they still pass.
+
+**Honesty, which is the whole point:**
+
+- **\`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.
+- **Never weaken a check to make it green.** Downgrading, skipping or deleting an assertion is a finding, not a fix.
+- **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.
+- **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.
+
+**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.
+
+📄 **The rest is in [RETICLE.md](./${RETICLE_MD_PATH}): 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.**`;
+/**
+ * The reference half. Fetched when a situation calls for it rather than carried every turn.
+ *
+ * Every section here answers a question an agent only has once it is already stuck, and each one was
+ * written because the absence of it cost somebody a session: tools that were never loaded read as a
+ * broken install, a `version_skew` field went unread while its green verdicts were trusted, an empty
+ * `reticle_state` was reported as a clean setup, and a defect in Reticle was worked around in silence.
+ */
+const RETICLE_MD_BODY = `# Reticle: the full rules
+
+The short version lives in your agent instruction file (\`CLAUDE.md\` / \`AGENTS.md\` / \`.cursor/rules/reticle.mdc\`) and loads every turn. This file is the reference: read the section that matches the situation you are in.
+
+## The tools are missing entirely
+
+They have not been loaded yet, which is not the same as broken. \`init\` registers the MCP server, but a client reads its server list at startup and does not re-read it, and no slash command reloads it (\`/mcp\` only manages servers already loaded).
+
+Ask the human to RESTART their client: restart Claude Code, reload the window in Cursor, or hit Start in \`.vscode/mcp.json\` in VS Code. Then wait and carry on. This is once per machine, because Reticle is registered globally and later projects already have the tools. \`${CLI} status\` works meanwhile and says whether the daemon is up and whether the app has connected.
+
+## A result carries \`verify_next\`
+
+You have driven this page several times without asking for a verdict, so nothing you have done so far is proven. Do what the field says next.
+
+## A result carries \`version_skew\`
+
+Act on it before trusting anything else. Two pieces of Reticle are on different wire contracts, so tools can misbehave in ways neither side reports, and a green is not evidence. The field names the pair that disagrees and the exact fix: run \`${CLI} stop\` and retry when the DAEMON is stale, or tell the human to install the matching SDK and restart their dev server when the PAGE is. Then redo whatever you were verifying.
 
-- **When:** after you build or change any user-facing feature, flow, or UI, verify it with Reticle **before** telling the user it is complete. Reading the code or passing unit tests is not enough — drive the real running app.
-- **How:** 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. Batch a multi-step flow (a login, a form) into one \`reticle_act_sequence\` rather than one round trip per field. Read the surrounding evidence with \`reticle_snapshot\`, \`reticle_state\`, \`reticle_network\`, \`reticle_console\`.
-- **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 that ends without one of those two has no result however many tools it used. In practice \`reticle_act\` is reached for far more often and proves nothing; \`act_and_wait\` is where the defects actually get caught.
-- **\`verified: "unknown"\` is not a pass.** It means Reticle drove the app and could not tell what happened; \`verifiedReason\` says which of eleven clauses decided that and what to do about it. Report it as unknown — never as working.
-- **If a tool result carries \`verify_next\`, do what it says next.** It means you have driven this page several times without asking for a verdict, so nothing you have done so far is proven.
-- **Covered flows:** run \`${CLI} gate\` — it reports which recorded flows the changed files affect and whether they still pass.
-- **Never weaken a check to make it green.** Downgrading, skipping, or deleting an assertion is a finding, not a fix.
-- **If Reticle can't run** (no daemon, or this is not a running web app), say so — do not skip verification silently.
-- **If the \`reticle_*\` tools are missing entirely, they have not been loaded yet — not broken.** \`init\` registers the MCP server, but a client reads its tool list at startup and does not re-read it. Ask the human to reload their MCP tools (\`/mcp\` in Claude Code, or reload the window in Cursor/VS Code), wait, then carry on. \`npx ${RETICLE_NPM_PACKAGE} status\` works meanwhile and says whether the daemon is up and whether the app has connected.
-- **Setup is not finished until one real flow has been driven and produced a verdict.** \`init\` exiting 0 means files were written; the tools appearing means your client can reach a daemon; a listed session means the app dialled in. None of those is evidence that anything works. If you are blocked before a verdict, say which step and what you tried — never report a clean install you did not verify.
-- **If a tool result carries \`version_skew\`, act on it before trusting anything else.** Two pieces of Reticle are on different wire contracts, so tools can misbehave in ways neither side reports — a green here is not evidence. The field says which pair disagrees and names the exact fix: run \`${CLI} stop\` and retry when the DAEMON is stale, or tell the human to install the matching SDK and restart their dev server when the PAGE is. Do that first, then redo whatever you were verifying.
-- **If a tool result carries \`update_available\`, say so.** Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`${CLI} update\` — between tasks, never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
+## A result carries \`update_available\`
 
-## Sending feedback to the Reticle team (first-class)
+Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`${CLI} update\`, between tasks and never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
 
-**Reporting your experience with Reticle is part of using Reticle, from the moment you start wiring it in — not something to do at the end if anything went wrong.** Reticle is built FOR agents, which makes you its actual user and the only one who can see what it costs you. That knowledge is gone when your context is, so it has to leave the turn it happened in.
+## \`reticle_state\` comes back empty
 
-- **Send it with \`reticle_feedback\`, the moment you notice.** One call, then carry straight on with your task. Do not batch reports, do not wait until the task is done, and do not decide something is too minor — the small awkward things are what nobody ever reports, so they never get fixed.
-- **Everything counts, in both directions.** A tool that returned something wrong (\`bug\`), something Reticle could not observe at all (\`gap\`), a verdict you could not act on (\`ambiguity\`), something you wished existed (\`feature_request\`), something that works but costs too many calls or has an awkward shape (\`improvement\`).
-- **Setup and installation count too, and are the easiest to lose.** Anything that went wrong while installing, wiring, or starting Reticle — a step in the docs that did not match reality, a plugin that had to be added by hand, a daemon that would not start, an OS-specific detour. You hit these before any verification runs, which is exactly why they usually go unreported.
+The generated \`reticle-dev\` file registers nothing. Say so. \`init\` registers every store it could prove from your source; the ones needing an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack \`queryClient\`) are left commented, and a file that registers nothing is indistinguishable from a working one until you read the state back.
+
+Finish that file when you see it. It is what lets you check what the app BELIEVES, not only what it rendered, which is the class of bug a screenshot cannot show. Never report a clean setup over an empty state read. It blocks nothing else: DOM, network, console and source pointers all work without it.
+
+## Sending feedback to the Reticle team
+
+**Reporting your experience is part of using Reticle, from the moment you start wiring it in.** Reticle is built FOR agents, which makes you its actual user and the only one who can see what it costs you.
+
+- **Send it with \`reticle_feedback\` the moment you notice.** One call, then carry straight on. Do not batch reports, do not wait until the task is done, and do not decide something is too minor. The small awkward things are what nobody ever reports, so they never get fixed.
+- **Everything counts, in both directions.** A tool that returned something wrong (\`bug\`), something Reticle could not observe at all (\`gap\`), a verdict you could not act on (\`ambiguity\`), something you wished existed (\`feature_request\`), something that works but costs too many calls (\`improvement\`).
+- **Setup and installation count too, and are the easiest to lose.** Anything that went wrong while installing, wiring, or starting Reticle: a step in the docs that did not match reality, a plugin that had to be added by hand, a daemon that would not start, an OS-specific detour. You hit these before any verification runs, which is exactly why they go unreported.
 - **When the tools are not reachable yet**, file the same report from the shell: \`${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. It needs no daemon and no working install, so a Reticle that broke before it started can still be reported.
-- **Write it so it can be acted on.** For a failure: what you called, what you expected, what you got, and the call trail in \`trace\`. For a request: the GOAL in \`need\` (not your guess at the solution), what improves in \`impact\`, and how you work around it today in \`currentApproach\` — that workaround is usually the most useful line in the report. Set \`model\` to the model you are running.
+- **Write it so it can be acted on.** For a failure: what you called, what you expected, what you got, and the call trail in \`trace\`. For a request: the GOAL in \`need\` (not your guess at the solution), what improves in \`impact\`, and how you work around it today in \`currentApproach\`. That workaround is usually the most useful line in the report. Set \`model\` to the model you are running.
 - **Working around a Reticle defect in silence is the one thing not to do.** A silent workaround is how the same defect survives to the next user.
-- **Report defects in *Reticle*, not in the app under test.** A bug you find in this app is Reticle working as intended; that belongs in your report to the user.
-- **Never include app source, secrets, user data, or customer records** in a report.`;
+- **Report defects in *Reticle*, not in the app under test.** A bug you find in this app is Reticle working as intended; that one belongs in your report to the user.
+- **Never include app source, secrets, user data, or customer records** in a report.
+
+## More
+
+The docs are built to be fetched rather than browsed: \`https://docs.reticle.sh/llms.txt\` lists every page, and appending \`.md\` to any page URL returns its source with no site chrome.
+`;
+/** The full-rules file, written verbatim (no markers: `init` owns this file entirely). */
+export function reticleMdFile() {
+    return RETICLE_MD_BODY;
+}
 export const AgentRuleStatus = {
     APPLY: 'apply',
     ALREADY: 'already',

package/dist/init/astro-patch.d.ts

@@ -12,5 +12,6 @@
  * Half-editing a build config is worse than a documented manual step.
  */
 import { type SourcePatch } from './patch-kind.js';
+import { UiLibrary } from './detect.js';
 export declare function patchAstroConfig(source: string): SourcePatch;
-export declare function patchAstroLayout(source: string, port: number | undefined, projectId: string | undefined): SourcePatch;
+export declare function patchAstroLayout(source: string, port: number | undefined, projectId: string | undefined, uiLibrary?: UiLibrary): SourcePatch;

package/dist/init/astro-patch.js

@@ -13,6 +13,8 @@
  */
 import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
 import { PatchKind } from './patch-kind.js';
+import { UiLibrary } from './detect.js';
+import { sdkImport } from './snippets.js';
 /** Present in a patched config AND in a hand-followed recipe — so both count as already wired. */
 const CONFIG_MARKER = '__RETICLE_TOKEN__';
 /** Present in a patched layout and in the printed recipe's script. */
@@ -204,7 +206,11 @@ export function patchAstroConfig(source) {
     };
 }
 /** The dev-only connect that goes inside the layout's `<body>`. */
-function astroConnectScript(port, projectId) {
+function astroConnectScript(port, projectId, uiLibrary) {
+    // Must match what `frameworkPackages` installed. Astro hosts islands from any framework, so an
+    // Astro app whose islands are Vue or Svelte gets the sensor, and a script importing the React
+    // adapter would load a package that is not in node_modules. See sdkImport.
+    const sdk = sdkImport(uiLibrary);
     const url = port !== undefined && port !== RETICLE_DEFAULT_PORT
         ? `\n          url: '${bridgeWsUrl(port)}',`
         : '';
@@ -213,8 +219,8 @@ function astroConnectScript(port, projectId) {
       if (import.meta.env.DEV) {
         const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
         const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
-        const { reticle, install } = await import('@reticlehq/react');
-        install();
+        const { reticle${sdk.usesInstall ? ', install' : ''} } = await import('${sdk.specifier}');
+        ${sdk.usesInstall ? 'install();' : '// The sensor has no install(); that is the React adapter.'}
         reticle.connect({${id}${url}
           ...(token.length > 0 ? { token } : {}),
           ...(root.length > 0 ? { root } : {}),
@@ -223,7 +229,7 @@ function astroConnectScript(port, projectId) {
     </script>
 `;
 }
-export function patchAstroLayout(source, port, projectId) {
+export function patchAstroLayout(source, port, projectId, uiLibrary = UiLibrary.REACT) {
     if (source.includes(LAYOUT_MARKER))
         return { kind: PatchKind.ALREADY };
     const at = source.lastIndexOf(BODY_CLOSE);
@@ -235,6 +241,6 @@ export function patchAstroLayout(source, port, projectId) {
     }
     return {
         kind: PatchKind.APPLY,
-        code: `${source.slice(0, at)}${astroConnectScript(port, projectId)}${source.slice(at)}`,
+        code: `${source.slice(0, at)}${astroConnectScript(port, projectId, uiLibrary)}${source.slice(at)}`,
     };
 }

package/dist/init/capabilities.d.ts

@@ -15,3 +15,25 @@ export declare const MAX_TESTIDS = 60;
 export declare function scanTestids(sources: readonly string[]): string[];
 /** The store libraries this app depends on, as ready-to-uncomment registration lines. */
 export declare function storeHints(deps: ReadonlySet<string>): string[];
+/** A store instance we found in the app's own source, with everything needed to import and register it. */
+export interface FoundStore {
+    /** The name it registers under — what `reticle_state` keys its output by. */
+    key: string;
+    /** The exported identifier. */
+    ident: string;
+    /** Module specifier relative to `src/reticle-dev.ts`. */
+    importPath: string;
+}
+/** Where the generated dev module lives, for Vite. Next passes its own. */
+export declare const DEFAULT_DEV_MODULE_DIR = "src";
+/**
+ * Store instances declared in the app's own source, ready to import and register.
+ *
+ * Only exported declarations of a factory the app actually depends on: anything less certain would
+ * generate an import that breaks the dev module everything else hangs off, and a broken module is
+ * worse than the commented hint it replaces.
+ */
+export declare function scanStores(files: readonly {
+    path: string;
+    source: string;
+}[], deps: ReadonlySet<string>, fromDir?: string): FoundStore[];

package/dist/init/capabilities.js

@@ -9,6 +9,7 @@
  * depends on zustand is easy, knowing which module exports the store instance is not, and generating
  * a wrong import would break the dev module that everything else now hangs off.
  */
+import { posix } from 'node:path';
 /** `data-testid="foo"` / `data-testid='foo'` / `data-testid={"foo"}` — the forms people actually write. */
 const TESTID_ATTR = /data-testid\s*=\s*[{]?\s*["'`]([^"'`]+)["'`]/g;
 /** Cap the generated list. A capabilities block is a hint for an agent, not an inventory. */
@@ -52,3 +53,78 @@ const STORE_LIBRARIES = [
 export function storeHints(deps) {
     return STORE_LIBRARIES.filter(([dep]) => deps.has(dep)).map(([, hint]) => hint);
 }
+/**
+ * Store factories whose EXPORTED result is the store instance itself — the form `registerStore`
+ * takes directly. Each is gated on the app actually depending on that library, so a local helper
+ * called `create` in an app with no store library is never mistaken for one.
+ *
+ * Deliberately short. The adapter-wrapped libraries (Jotai, XState, Valtio, MobX, TanStack Query)
+ * need an argument we cannot infer — which atoms, which actor, which queryClient — so they keep the
+ * commented hint. Guessing there produces a module that throws on import, which is strictly worse
+ * than a comment.
+ */
+const STORE_FACTORIES = [
+    ['zustand', 'create'],
+    ['@reduxjs/toolkit', 'configureStore'],
+    ['redux', 'createStore'],
+];
+/** `export const useCart = create<S>()(...)` / `export const store = configureStore({...})`. */
+function storeDeclaration(factory) {
+    return new RegExp(`export\\s+const\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*${factory}\\s*[<(]`, 'g');
+}
+/**
+ * `src/cart-store.ts` → `cart`; `src/store.ts` → `app`. The key is what the agent reads state under,
+ * so it has to be stable and distinct — two stores sharing one key would silently overwrite.
+ */
+function storeKey(path, taken) {
+    const file = (path.split('/').pop() ?? '').replace(/\.[^.]+$/, '');
+    const base = file.replace(/[-_.]?stores?$/i, '').replace(/[^a-z0-9]+/gi, '-') || 'app';
+    const key = base.toLowerCase();
+    if (!taken.has(key))
+        return key;
+    for (let n = 2;; n += 1) {
+        const candidate = `${key}-${String(n)}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}
+/**
+ * Module specifier for `store.ts` as seen FROM the generated dev module.
+ *
+ * The dev module is not always a sibling: Vite puts it at `src/reticle-dev.ts`, Next at
+ * `app/reticle-dev.tsx` or `src/app/reticle-dev.tsx`. A specifier computed for one is dead in the
+ * other, and a dead import in this file breaks the module every other capability hangs off — so the
+ * relative path is computed, not assumed.
+ */
+function importPathFor(storePath, fromDir) {
+    const noExt = storePath.replace(/\.[^./]+$/, '');
+    const rel = posix.relative(fromDir, noExt);
+    return rel.startsWith('.') ? rel : `./${rel}`;
+}
+/** Where the generated dev module lives, for Vite. Next passes its own. */
+export const DEFAULT_DEV_MODULE_DIR = 'src';
+/**
+ * Store instances declared in the app's own source, ready to import and register.
+ *
+ * Only exported declarations of a factory the app actually depends on: anything less certain would
+ * generate an import that breaks the dev module everything else hangs off, and a broken module is
+ * worse than the commented hint it replaces.
+ */
+export function scanStores(files, deps, fromDir = DEFAULT_DEV_MODULE_DIR) {
+    const factories = STORE_FACTORIES.filter(([dep]) => deps.has(dep)).map(([, f]) => f);
+    const found = [];
+    const keys = new Set();
+    for (const { path, source } of files) {
+        for (const factory of factories) {
+            for (const m of source.matchAll(storeDeclaration(factory))) {
+                const ident = m[1];
+                if (ident === undefined)
+                    continue;
+                const key = storeKey(path, keys);
+                keys.add(key);
+                found.push({ key, ident, importPath: importPathFor(path, fromDir) });
+            }
+        }
+    }
+    return found;
+}

package/dist/init/confirm.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The step `init` never took: stay and watch for an app to connect.
+ *
+ * The install has two halves. Registering the MCP server gives the agent the tools; getting the SDK
+ * into a running page gives it something to look at. Almost everyone finishes the first, and nothing
+ * joined "init finished" to "an app connected" — so `init` exited 0 having written files, and the
+ * person left with a config file and no instrumented page was never told (#269).
+ *
+ * The capability existed in three places and was used together by none of them: the poll behind
+ * `reticle open`, the install gate (which calls this exact check "the only step that proves the
+ * install works"), and the event that measures whether it ever happened.
+ *
+ * WHY NO FLAG, and no dev-server management:
+ *
+ *  - No flag, because the people this is for are the ones who do not know to ask. `--verify` would
+ *    be typed by the users who already run `status` afterwards, which is exactly the cohort that is
+ *    not being lost. The gate instead is whether a HUMAN IS AT THE TERMINAL: `init` waits when
+ *    stdout is a TTY and skips the wait entirely otherwise, so a scripted or agent-driven `init`
+ *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
+ *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
+ *    also keeps `init`'s documented flag surface where it is.
+ *  - It never starts anything. Reticle attaches to what is already running and does not manage a
+ *    dev server; that rule holds here too. So the honest shape is: confirm the app if it connects,
+ *    otherwise name the ONE command that is outstanding and the one that proves it worked.
+ */
+import { InitConfirmation } from '@reticlehq/core';
+import type { InitOutcome } from '@reticlehq/core';
+/**
+ * How long a human is asked to wait.
+ *
+ * Long enough for a page that is already loading to finish dialling, short enough that somebody who
+ * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
+ * have not typed the command that would make it succeed, and the message tells them which one.
+ */
+export declare const CONFIRM_WINDOW_MS = 12000;
+export declare const CONFIRM_POLL_MS = 500;
+export interface ConfirmDeps {
+    /** Session ids connected right now, or null when nothing is listening on the bridge port. */
+    listSessionIds: () => Promise<readonly string[] | null>;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    windowMs?: number;
+    pollMs?: number;
+}
+/** The narrow slice of the init IO this needs — it prints, and nothing else. */
+interface PrintIo {
+    print: (line: string) => void;
+}
+/** What `runInit` hands back; `outcome` is present only on a real (non-dry) run. */
+interface ConfirmableResult {
+    ok: boolean;
+    applied: number;
+    manual: number;
+    outcome?: InitOutcome;
+}
+/**
+ * Poll until an app connects or the window runs out.
+ *
+ * A session that was ALREADY there when the wait began does not count, and this is the whole reason
+ * the check reads ids rather than a count. A daemon is shared across every project on the machine,
+ * so "a session exists" is satisfied by another app, by a stray tab, by yesterday's work — and
+ * confirming this install on somebody else's session is a false green in the one message a user
+ * reads to decide whether they are done. `reticle open` refuses the same way, for the same reason.
+ *
+ * The conservative direction is deliberate: an app that reconnects under an id it already held is
+ * reported as not-yet-connected, and the message it gets sends them to `status`, which shows it. A
+ * missed confirmation costs one command; a false one costs the whole point of confirming.
+ */
+export declare function confirmAppConnected(deps: ConfirmDeps): Promise<InitConfirmation>;
+/**
+ * What the user reads, in the marks the rest of the report already uses: `⚠` means work left to do
+ * and nothing else, `ℹ` is worth reading but is not work, `✓` happened.
+ *
+ * Only NO_SESSION earns a `⚠`, and it earns it honestly: the app is wired and has not connected, so
+ * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
+ * up when the agent loads the tools — so it is a notice.
+ */
+export declare function confirmationMessage(confirmation: InitConfirmation, port: number): string;
+/**
+ * Finish `init` on evidence rather than on a write.
+ *
+ * The telemetry report happens HERE rather than inside `runInit`, so the one `init_completed` event
+ * carries what was seen. Emitting inside `runInit` and again after the wait would double-count the
+ * funnel it exists to measure, and a second event kind for the same command would need joining back
+ * to the first before anybody could read either.
+ */
+export declare function confirmInstall(result: ConfirmableResult, io: PrintIo, deps: ConfirmDeps & {
+    interactive: boolean;
+    port: number;
+}, report?: (outcome: InitOutcome) => void): Promise<void>;
+/** The real deps: the daemon's own status endpoint, and whether a human is watching. */
+export declare function nodeConfirmDeps(port?: number): ConfirmDeps & {
+    interactive: boolean;
+    port: number;
+};
+export {};

package/dist/init/confirm.js

@@ -0,0 +1,138 @@
+/**
+ * The step `init` never took: stay and watch for an app to connect.
+ *
+ * The install has two halves. Registering the MCP server gives the agent the tools; getting the SDK
+ * into a running page gives it something to look at. Almost everyone finishes the first, and nothing
+ * joined "init finished" to "an app connected" — so `init` exited 0 having written files, and the
+ * person left with a config file and no instrumented page was never told (#269).
+ *
+ * The capability existed in three places and was used together by none of them: the poll behind
+ * `reticle open`, the install gate (which calls this exact check "the only step that proves the
+ * install works"), and the event that measures whether it ever happened.
+ *
+ * WHY NO FLAG, and no dev-server management:
+ *
+ *  - No flag, because the people this is for are the ones who do not know to ask. `--verify` would
+ *    be typed by the users who already run `status` afterwards, which is exactly the cohort that is
+ *    not being lost. The gate instead is whether a HUMAN IS AT THE TERMINAL: `init` waits when
+ *    stdout is a TTY and skips the wait entirely otherwise, so a scripted or agent-driven `init`
+ *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
+ *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
+ *    also keeps `init`'s documented flag surface where it is.
+ *  - It never starts anything. Reticle attaches to what is already running and does not manage a
+ *    dev server; that rule holds here too. So the honest shape is: confirm the app if it connects,
+ *    otherwise name the ONE command that is outstanding and the one that proves it worked.
+ */
+import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { fetchStatus, summarizeStatus } from '../cli/cli-launch.js';
+import { reportInitOutcome } from '../telemetry/init-telemetry.js';
+/**
+ * How long a human is asked to wait.
+ *
+ * Long enough for a page that is already loading to finish dialling, short enough that somebody who
+ * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
+ * have not typed the command that would make it succeed, and the message tells them which one.
+ */
+export const CONFIRM_WINDOW_MS = 12_000;
+export const CONFIRM_POLL_MS = 500;
+/**
+ * Poll until an app connects or the window runs out.
+ *
+ * A session that was ALREADY there when the wait began does not count, and this is the whole reason
+ * the check reads ids rather than a count. A daemon is shared across every project on the machine,
+ * so "a session exists" is satisfied by another app, by a stray tab, by yesterday's work — and
+ * confirming this install on somebody else's session is a false green in the one message a user
+ * reads to decide whether they are done. `reticle open` refuses the same way, for the same reason.
+ *
+ * The conservative direction is deliberate: an app that reconnects under an id it already held is
+ * reported as not-yet-connected, and the message it gets sends them to `status`, which shows it. A
+ * missed confirmation costs one command; a false one costs the whole point of confirming.
+ */
+export async function confirmAppConnected(deps) {
+    const deadline = deps.now() + (deps.windowMs ?? CONFIRM_WINDOW_MS);
+    let before;
+    for (;;) {
+        const ids = await deps.listSessionIds();
+        // A port nobody is listening on cannot receive a session, and no amount of waiting changes that.
+        // One look settles it; polling on would spend the whole window to re-learn the first answer.
+        if (null === ids)
+            return InitConfirmation.NO_DAEMON;
+        const baseline = before;
+        if (baseline === undefined)
+            before = new Set(ids);
+        else if (ids.some((id) => !baseline.has(id)))
+            return InitConfirmation.CONNECTED;
+        if (deadline <= deps.now())
+            return InitConfirmation.NO_SESSION;
+        await deps.sleep(deps.pollMs ?? CONFIRM_POLL_MS);
+    }
+}
+const PROVE_COMMAND = '`npx @reticlehq/server status`';
+/**
+ * What the user reads, in the marks the rest of the report already uses: `⚠` means work left to do
+ * and nothing else, `ℹ` is worth reading but is not work, `✓` happened.
+ *
+ * Only NO_SESSION earns a `⚠`, and it earns it honestly: the app is wired and has not connected, so
+ * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
+ * up when the agent loads the tools — so it is a notice.
+ */
+export function confirmationMessage(confirmation, port) {
+    if (confirmation === InitConfirmation.CONNECTED) {
+        return ('  [✓] an app is connected — that is the install finished, not just written.\n' +
+            '      Ask your agent to drive a flow.');
+    }
+    if (confirmation === InitConfirmation.NO_DAEMON) {
+        return (`  [ℹ] nothing is listening on port ${String(port)} yet, so no app could have connected and ` +
+            'this run did not wait for one.\n' +
+            '      The daemon starts on its own when your agent loads the Reticle tools. After that, ' +
+            `${PROVE_COMMAND} confirms the app.`);
+    }
+    return ('  [⚠] no app has connected yet — the files are written, the page half of the install is not ' +
+        'done.\n' +
+        '      Restart your dev server (Reticle attaches to it, it never starts it for you) and load ' +
+        'the app in a browser.\n' +
+        `      ${PROVE_COMMAND} then confirms it, or says exactly why it has not connected.`);
+}
+const WATCHING = (windowMs) => `  watching for an app to connect (up to ${String(Math.round(windowMs / 1000))}s) — Ctrl-C is safe, ` +
+    'everything above is already written.';
+/**
+ * Finish `init` on evidence rather than on a write.
+ *
+ * The telemetry report happens HERE rather than inside `runInit`, so the one `init_completed` event
+ * carries what was seen. Emitting inside `runInit` and again after the wait would double-count the
+ * funnel it exists to measure, and a second event kind for the same command would need joining back
+ * to the first before anybody could read either.
+ */
+export async function confirmInstall(result, io, deps, report = reportInitOutcome) {
+    const outcome = result.outcome;
+    // No outcome means a dry run or an exit that already reported for itself (no package.json). A
+    // preview is not an install and must not land in the funnel as either a success or a failure.
+    if (outcome === undefined)
+        return;
+    if (!deps.interactive) {
+        report(outcome);
+        return;
+    }
+    io.print('');
+    io.print(WATCHING(deps.windowMs ?? CONFIRM_WINDOW_MS));
+    const confirmation = await confirmAppConnected(deps);
+    io.print(confirmationMessage(confirmation, deps.port));
+    report({ ...outcome, confirmation });
+}
+/** The real deps: the daemon's own status endpoint, and whether a human is watching. */
+export function nodeConfirmDeps(port = RETICLE_DEFAULT_PORT) {
+    return {
+        listSessionIds: async () => {
+            const payload = await fetchStatus(port);
+            // `fetchStatus` resolves undefined when nothing answered, which is precisely the "no daemon"
+            // case — a zero-session daemon and an absent one need opposite messages.
+            if (payload === undefined)
+                return null;
+            return summarizeStatus(payload).sessions.map((s) => s.sessionId);
+        },
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        interactive: true === process.stdout.isTTY,
+        port,
+    };
+}

package/dist/init/cra.js

@@ -12,6 +12,7 @@
  * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
  * mechanism and is gitignored by CRA's own template.
  */
+import { CLI } from './agent-rules.js';
 /** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
 export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
 export const CRA_DEV_MODULE_PATH = 'src/reticle-dev.ts';
@@ -30,7 +31,7 @@ export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
  */
 export const CRA_TOKEN_MISSING_NOTE = `${TOKEN_VAR} is not set, so Reticle cannot pair with the daemon. ` +
     `The pairing token is per-machine and ${CRA_ENV_PATH} is gitignored by CRA's template, ` +
-    'so it does not survive a clone. Run `npx reticle init` in this project to write it for this machine.';
+    `so it does not survive a clone. Run \`${CLI} init\` in this project to write it for this machine.`;
 /**
  * Said as its own NOTICE line, beside the write — not inside it.
  *
@@ -46,7 +47,7 @@ export const CRA_TOKEN_MISSING_NOTE = `${TOKEN_VAR} is not set, so Reticle canno
 export const CRA_TOKEN_PER_MACHINE_NOTICE = `${CRA_ENV_PATH} is in CRA's own .gitignore, so the token just written does not travel. ` +
     'It works on THIS machine and nowhere else: a teammate cloning the repo, CI, or a container ' +
     'gets an app that boots, never pairs, and reports it only in the browser console. ' +
-    'Each developer runs `npx reticle init` once locally.';
+    `Each developer runs \`${CLI} init\` once locally.`;
 /** Add the import after the last existing one, or null when it is already present. */
 export function craImportPatch(source) {
     if (source.includes(CRA_DEV_MODULE_IMPORT))