@reticlehq/server 2.7.0 → 2.9.0

package/dist/index.js

@@ -11,9 +11,11 @@ import { resolveBridgeSecurityWithAutoToken } from './bridge/bridge-security.js'
 import { Bridge } from './bridge/bridge.js';
 import { BaselineStore } from './project/baselines.js';
 import { RecordingStore } from './flows/recordings.js';
+import { initImpact } from './impact/impact-recorder.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';
@@ -22,6 +24,8 @@ import { createRunnerPort } from './runs/runner-port.js';
 import { RunStore } from './runs/run-store.js';
 import { startVerifyServer } from './runs/verify-server.js';
 import { createMcpServer } from './mcp/mcp.js';
+import { LEASE_ACQUIRE_TOOL } from './tools/lease-tools.js';
+import { runTool } from './tools/invoke-tool.js';
 import { SessionReaper, endAllSessions, MCP_DISCONNECT_SUMMARY } from './session/session-reaper.js';
 import { wireSessionScope } from './session/no-session-watch.js';
 import { buildIdlePredicate } from './daemon/daemon-usefulness.js';
@@ -33,9 +37,13 @@ import { BrowserPool } from './pool/browser-pool.js';
 import { playwrightLauncher, resolveMaxContexts } from './pool/playwright-launcher.js';
 import { LeaseReaper } from './pool/lease-reaper.js';
 import { readJournalEnabled, readProjectId } from './cli/cli-port.js';
+import { hasProjectConnectedBefore } from './session/connection-memory.js';
+import { reticleStateHome } from './daemon/daemon.js';
+import { probeChromium } from './cli/chromium-hint.js';
 import { makeJournalAttach } from './journal/attach-journal.js';
 import { makeSessionEnd } from './journal/session-end.js';
 import { AmbientStore } from './journal/ambient-store.js';
+import { ensureWorkspaceGitignore } from './journal/workspace-gitignore.js';
 import { pruneSessions } from './journal/retention.js';
 import { log } from './log.js';
 /** A human-facing one-liner for a panel replay verdict — ✓ passed / ⚠ drifted / ✗ errored. */
@@ -171,8 +179,14 @@ function attachJournal(bridge, deps) {
     });
     // Teardown: flush the journal tail to disk + persist what this session learned.
     bridge.attachSessionEnd(makeSessionEnd(deps));
-    if (deps.enabled)
+    if (deps.enabled) {
         void pruneSessions(deps.fs, deps.reticleRoot);
+        // Here rather than in `init`, because this is the moment we are actually about to write into
+        // somebody's repository — and the paths that reach it without ever running `init` (a plugin
+        // install, a hand-added client config) are exactly the ones that would otherwise leave an
+        // unexplained pile of untracked files behind. Best-effort and write-once; see the helper.
+        void ensureWorkspaceGitignore(deps.fs, deps.reticleRoot);
+    }
 }
 /**
  * Resolve the drive/real-input provider from options — shared by start and startDaemon so the
@@ -223,6 +237,10 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
 /** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
 export async function start(options = {}) {
     const port = options.port ?? RETICLE_DEFAULT_PORT;
+    // Open the user's impact record before anything can connect. Not inside the MCP branch: a daemon
+    // serving a browser with no agent attached still has a HUD to answer, and a report that reads
+    // "nothing recorded yet" over a month of history on disk is the worst version of this feature.
+    initImpact({ reticleRoot: options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT) });
     const security = await resolveBridgeSecurityWithAutoToken(options);
     const bridge = new Bridge({ port, ...security });
     // Server-authoritative liveness: a Node-side reaper (immune to browser throttling) ends sessions
@@ -253,6 +271,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);
@@ -269,12 +288,13 @@ export async function start(options = {}) {
             reticleRoot,
             now,
             bridgePort: port,
+            browserProbe: probeChromium,
             // The daemon's OWN project, so a tool can tell "this session is mine" from "this session
             // belongs to a sibling app under the same daemon". contract_save refuses on the second.
             ...(activeProjectId === undefined ? {} : { projectId: activeProjectId }),
         };
         const profile = resolveToolSurface(options.toolProfile);
-        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile);
+        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile, hasProjectConnectedBefore(reticleStateHome(), port, activeProjectId));
         // When the agent (the MCP client) disconnects cleanly, end every active session at once so the
         // HUD doesn't linger. (If the agent instead KILLS this process, the WS dies and the browser
         // self-ends via SESSION_LIFECYCLE.BRIDGE_LOST_MS — see transport.ts.)
@@ -306,6 +326,12 @@ export async function start(options = {}) {
  */
 export async function startDaemon(options = {}) {
     const port = options.port ?? RETICLE_DEFAULT_PORT;
+    // The SAME line as in `start`, because these are two entry points that each wire their own world
+    // and the daemon is the one that actually serves people. Wired only in `start`, the impact record
+    // was never opened in the process the HUD talks to: tool calls still recorded (the dispatch
+    // chokepoint opens it lazily), but a tab that connected before the first tool call was pushed
+    // nothing, so the report read "nothing recorded yet" over a file with history in it.
+    initImpact({ reticleRoot: options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT) });
     const security = await resolveBridgeSecurityWithAutoToken(options);
     const shared = createSharedServer(security.token === undefined ? {} : { token: security.token });
     const bridge = new Bridge({ port, server: shared.httpServer, ...security });
@@ -330,13 +356,6 @@ export async function startDaemon(options = {}) {
     });
     const reaper = new SessionReaper(bridge.sessions);
     reaper.start();
-    // Scope auto-selection to the active project (from .reticle.json) so a stray tab from another app is
-    // never picked when the agent omits a sessionId. Explicit per-call scope/sessionId still overrides.
-    // Scope + the no-session diagnosis: "no browser session connected" is the error that ends most
-    // sessions, and the agent is told to check two things it cannot see. See no-session-diagnosis.ts.
-    // The pool reader is passed lazily: `pool` is assigned above but may be undefined when this
-    // daemon runs without one, and the diagnosis must degrade to the tab message rather than lie.
-    wireSessionScope(bridge.sessions, readProjectId(process.cwd()), port, () => pool?.reapedLeaseCount() ?? 0);
     const { realInput, owned } = await resolveRealInput(options, () => shared.close(), makeNetworkDetailRouter(bridge, options.driveUrl));
     const fs = createNodeFileSystem();
     const reticleRoot = options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT);
@@ -345,10 +364,19 @@ 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);
     leaseReaper.start();
+    // Scope auto-selection to the active project (from .reticle.json) so a stray tab from another app is
+    // never picked when the agent omits a sessionId. Explicit per-call scope/sessionId still overrides.
+    // Scope + the no-session diagnosis: "no browser session connected" is the error that ends most
+    // sessions, and the agent is told to check two things it cannot see. See no-session-diagnosis.ts.
+    // Ordered AFTER the pool: the watch may open a browser itself the moment it finds a listening dev
+    // server for a wired project (see no-session-watch.ts), and it opens it through the pool — the same
+    // path reticle_lease takes, in this process, binding nothing.
+    wireSessionScope(bridge.sessions, readProjectId(process.cwd()), port, () => pool.reapedLeaseCount(), (url) => pool.acquire(url));
     const deps = {
         sessions: bridge.sessions,
         pool,
@@ -361,10 +389,18 @@ export async function startDaemon(options = {}) {
         reticleRoot,
         now,
         bridgePort: port,
+        browserProbe: probeChromium,
     };
     const profile = resolveToolSurface(options.toolProfile);
     const effectiveDeps = realInput !== undefined ? { ...deps, realInput } : deps;
-    shared.attachMcp(() => createMcpServer(effectiveDeps, profile));
+    // Read per attach, not once: a project that gets wired while this daemon is alive should stop
+    // being told to wire itself on the next agent that connects.
+    shared.attachMcp(() => createMcpServer(effectiveDeps, profile, hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(process.cwd()))));
+    // `reticle drive <url>` when this daemon already owns the port: it asks HERE instead of trying to
+    // bind a port we are holding, and gets the same pooled context an agent's reticle_lease returns —
+    // through runTool, so it is counted and reported like any other call rather than being a second,
+    // invisible dispatch path. See cli/drive-attach.ts for why attaching beats refereeing the race.
+    shared.attachDrive((url) => runTool(LEASE_ACQUIRE_TOOL, effectiveDeps, { url }));
     // Optional OEM/CI verify endpoint: a host platform POSTs to /verify and gets an ReticleVerificationRun,
     // driving the same flow-replay machinery the agent uses — no MCP stdio, no human. Each verdict is
     // persisted via RunStore. Localhost-bound + token-guarded. Off unless `reticle serve --http`.
@@ -451,6 +487,7 @@ export async function startDaemon(options = {}) {
         // Exposed so the shutdown watcher can give an ATTACHED daemon a longer grace. The predicate above
         // says WHETHER it is idle; this says how long that quiet should be tolerated — see idle-grace.
         agentAttached: () => agentConnected,
+        announceShutdown: () => shared.announceShutdown(),
         close: async () => {
             reaper.stop();
             await cleanupCaptureDirectories();

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,28 @@ 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;
+/**
+ * Who starts the dev server, stated once and rendered everywhere it is needed.
+ *
+ * The old rule was "Reticle never starts the dev server for you — that's your job", and agents obeyed
+ * it exactly: they read it, declined to start anything, and ended the turn with nothing verified. An
+ * instruction that reliably produces no verification is a defect in the instruction.
+ *
+ * The AGENT starts it, not the daemon. A daemon that spawns a build process is invisible to the
+ * person whose machine it is running on, was never consented to, and orphans when the daemon exits.
+ * The agent already has shell access in this repo, already runs install and build commands, and runs
+ * inside a host that asks the human for permission — so a dev server it starts is visible in the
+ * transcript, attributable, and stoppable.
+ *
+ * The guards are the whole reason this is safe, so no renderer may drop them: adopt what is already
+ * listening, read the command rather than invent one, never kill, background it and SAY so, and leave
+ * the permission prompt to the host.
+ *
+ * Exported because slash-command.ts renders the same rule; there must not be two versions of it.
+ */
+export declare const DEV_SERVER_POLICY = "**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.";
+/** 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,132 @@ 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. */
+/**
+ * Who starts the dev server, stated once and rendered everywhere it is needed.
+ *
+ * The old rule was "Reticle never starts the dev server for you — that's your job", and agents obeyed
+ * it exactly: they read it, declined to start anything, and ended the turn with nothing verified. An
+ * instruction that reliably produces no verification is a defect in the instruction.
+ *
+ * The AGENT starts it, not the daemon. A daemon that spawns a build process is invisible to the
+ * person whose machine it is running on, was never consented to, and orphans when the daemon exits.
+ * The agent already has shell access in this repo, already runs install and build commands, and runs
+ * inside a host that asks the human for permission — so a dev server it starts is visible in the
+ * transcript, attributable, and stoppable.
+ *
+ * The guards are the whole reason this is safe, so no renderer may drop them: adopt what is already
+ * listening, read the command rather than invent one, never kill, background it and SAY so, and leave
+ * the permission prompt to the host.
+ *
+ * Exported because slash-command.ts renders the same rule; there must not be two versions of it.
+ */
+export const DEV_SERVER_POLICY = `**If no dev server is listening, start one yourself.** Read the project's own dev script out of \`package.json\` (\`dev\`, \`start\`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.
+
+Five guards, none optional:
+
+1. **Never start a second one.** If something is already listening on the app's port, use it.
+2. **Never guess the command.** It comes from \`package.json\` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.
+3. **Never kill anything.** Not a dev server, not a daemon, not a port holder — including one you started.
+4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.
+5. **The permission prompt belongs to your host.** Never try to 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.
+ *
+ * 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.
+
+**Nothing connected? Get the app running.**
+
+${DEV_SERVER_POLICY}
+
+A dev server that is already running does not pick up an edited build config or a newly created plugin file — 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.
+
+**Honesty, which is the whole point:**
 
-- **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.
+- **\`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.
 
-## Sending feedback to the Reticle team (first-class)
+**The \`/reticle\` skill runs this whole loop for you** — 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.
 
-**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.
+**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.
 
-- **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 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.
+
+## A result carries \`update_available\`
+
+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.
+
+## \`reticle_state\` comes back empty
+
+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

@@ -11,8 +11,10 @@
  * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
  * Half-editing a build config is worse than a documented manual step.
  */
-import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, ReticleDir, 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. */
@@ -29,6 +31,26 @@ const LAYOUT_MARKER = 'reticle.connect';
  * never got it.
  */
 const SDK_INCLUDE_LITERAL = `'@reticlehq/react'`;
+/**
+ * The daemon's journal directory, kept out of the dev server's watcher.
+ *
+ * The daemon writes `.reticle/` into the project root and rewrites `ambient.json` atomically
+ * (`.tmp` + rename) for as long as a session is live. Astro dev is a Vite dev server watching that
+ * root, and `.reticle/` is not in Vite's default ignore list — so every journal write read as a
+ * project file changing and Vite answered with a full page reload. That closes a loop with no exit:
+ * the page loads, the SDK connects and streams events, the daemon journals them, Vite reloads the
+ * page, the SDK reconnects. It ran several times a second for as long as the dev server was up,
+ * and the symptom looked nothing like the cause — stale refs, actions dying mid-flight, and a log
+ * full of connect/disconnect pairs that read as a flapping SDK.
+ *
+ * The Vite plugin sets the same ignore in its `config` hook. Astro is hand-patched and never loads
+ * that plugin, so it needs its own.
+ *
+ * A RegExp, not a glob. chokidar dropped glob support in v4 and Vite 7+ ships v4/v5, where a
+ * double-star pattern is accepted and matches nothing — the ignore would be visibly present in the
+ * config and do nothing at all. Measured against the chokidar this repo resolves.
+ */
+const WATCH_IGNORE_LITERAL = `/(^|[\\\\/])\\.${ReticleDir.ROOT.slice(1)}([\\\\/]|$)/`;
 /**
  * An `include:` the app already declared — ours joins that array instead of adding a second key.
  * Deliberately not anchored to a newline: `optimizeDeps: { include: ['x'] }` on one line is the
@@ -70,12 +92,17 @@ const VITE_KEYS = [
         key: 'define',
         inner: `\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),`,
     },
+    // Merged in first, so a `server: { port }` the app already set keeps its port. An app that
+    // already sets `server.watch` itself is the one shape this loses to — the inner `watch` key would
+    // be duplicated and the app's would win — which is the same nested-merge ceiling `build` has.
+    { key: 'server', inner: `\n      watch: { ignored: [${WATCH_IGNORE_LITERAL}] },` },
 ];
 /** Whole-key form, for a `vite:` block that does not have the key at all. */
 const WHOLE = {
     build: `\n    build: { target: 'es2022' },`,
     optimizeDeps: `\n    optimizeDeps: { include: [${SDK_INCLUDE_LITERAL}], esbuildOptions: { target: 'es2022' } },`,
     define: `\n    define: {\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),\n    },`,
+    server: `\n    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },`,
 };
 /**
  * Add our keys to an existing `vite: { ... }` block, merging into any the app already set.
@@ -155,6 +182,7 @@ const VITE_BLOCK = `  vite: {
       __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
       __RETICLE_ROOT__: JSON.stringify(process.cwd()),
     },
+    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },
   },
 `;
 export function patchAstroConfig(source) {
@@ -204,7 +232,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 +245,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 +255,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 +267,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;
+}