@reticlehq/init 2.14.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Reticle Labs
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Reticle
+Copyright 2026 Reticle Labs
+
+This product includes software developed at Reticle Labs.
+Licensed under the Apache License, Version 2.0.

package/README.md

@@ -0,0 +1,29 @@
+# @reticlehq/init
+
+The project scaffolder behind `reticle init`. Detects the framework and package manager, writes `.reticle.json`, patches the build config, generates the connect snippet and the agent rules, and registers the Reticle MCP server with whichever clients are on the machine.
+
+Split out of [`@reticlehq/server`](https://www.npmjs.com/package/@reticlehq/server) because nothing in here observes a running app: it is a build-time codemod that runs once. Keeping it inside the daemon meant a typo in a generated snippet forced a republish of the MCP server, and every MCP user downloaded a scaffolder they run once or never.
+
+You do not install this directly — `@reticlehq/server` depends on it and the `reticle` CLI drives it:
+
+```bash
+npx @reticlehq/server init
+```
+
+## Using it as a library
+
+```ts
+import { buildNodeIo, runInit, type InitHost } from '@reticlehq/init';
+
+const io = buildNodeIo(process.cwd(), host); // host: version, tracing, telemetry, pairing token
+const result = runInit(
+  { cwd: process.cwd(), port: undefined, mcp: true, dryRun: false, install: true },
+  io,
+);
+```
+
+`InitHost` is the seam: everything the scaffolder cannot know for itself — the release version, a tracing hook, where to report the outcome, the bridge pairing token, the declared install channel — is supplied by the caller. That is what keeps this package free of any dependency on the daemon.
+
+## License
+
+FSL-1.1-ALv2 — free for any Permitted Purpose, converts to Apache-2.0 two years after release. See [LICENSE](./LICENSE).

package/dist/agent-rules.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `reticle init` writes a behavioral rule into the coding agent's instruction file so the agent
+ * VERIFIES a feature with Reticle after building it — not only when the user remembers to say "test
+ * it with reticle". Registering the MCP server (mcp.ts / mcp-clients.ts) only makes the tools AVAILABLE;
+ * this is the piece that makes the agent reach for them, every session, unprompted.
+ *
+ * It carries a SECOND standing instruction, and that one is not about this project at all: send
+ * feedback to the Reticle maintainers, from the moment instrumentation starts. The agent is the party
+ * that experiences Reticle, and the only one who can say what it cost — and by the time anyone would
+ * think to ask, the context that knew is gone. Written into the same block, because the moment the
+ * rule lands (init, before any framework wiring) is the moment the setup itself is being lived
+ * through, which is when the reports we hear least about are actually generated.
+ *
+ * The rule is framed as a definition-of-done (WHEN to verify, HOW, and the anti-reward-hacking guard),
+ * written into whichever instruction file the detected agent reads: `CLAUDE.md` (Claude Code),
+ * `.cursor/rules/reticle.mdc` (Cursor, `alwaysApply` so it stays in context), or `AGENTS.md` as the
+ * cross-agent fallback. Idempotent via a marker block — safe to append to an existing file and a
+ * re-run is a no-op. Mirrors the apply/already result shape used across init (see mcp-clients.ts).
+ */
+/** 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";
+/**
+ * Does this file already carry the managed block?
+ *
+ * Exported so callers cannot invent their own looser test. The begin marker carries explanatory
+ * text inside the comment, so a substring check for `reticle:begin` matches files that
+ * `mergeMarkedInstruction` would treat as having NO block — and the two disagreeing means a refresh
+ * silently appends a second copy instead of updating the first.
+ */
+export declare function hasManagedBlock(text: string): boolean;
+/**
+ * How the agent must INVOKE the CLI.
+ *
+ * `reticle init` installs the SDK packages, never the server — so there is no `reticle` on the
+ * agent's PATH, and every bare `reticle <cmd>` this rule named was an instruction that could not be
+ * followed. Reported from a field sweep: three of them, in the file the agent re-reads every session.
+ *
+ * `npx @reticlehq/server` is the same invocation the MCP registration uses, and it is derived from
+ * the package's own name so the two can never drift apart.
+ */
+export declare const CLI = "npx @reticlehq/server";
+/**
+ * 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: one server at a time,
+ * read the command rather than invent one, never kill anything you did not start, and leave the
+ * permission prompt to the host. "Background it and say so" is no longer among them because the
+ * branch above now states it at the point of action, and this text is read every turn — a rule
+ * stated twice costs every agent tokens forever and is the first thing to drift.
+ *
+ * The RESTART branch outranks the rest and is stated first. It used to be an aside, while "if a dev
+ * server is already listening, use it" was a numbered guard — so an agent resolving the two
+ * reasonably reused a server started before `init` edited the build config, served a bundle with no
+ * SDK in it, and landed on an empty session list with every other step done correctly.
+ *
+ * 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.";
+/**
+ * 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.
+ */
+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.**";
+/** 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";
+};
+export type AgentRuleStatus = (typeof AgentRuleStatus)[keyof typeof AgentRuleStatus];
+interface AgentRuleResult {
+    status: AgentRuleStatus;
+    /** Full file content to write when status is APPLY; the unchanged input otherwise. */
+    content: string;
+}
+/** The marker-wrapped block appended to a CLAUDE.md / AGENTS.md instruction file. */
+export declare function markedBlock(): string;
+/**
+ * Merge the managed block into a marker-delimited instruction file. Already present ⇒ no change
+ * (idempotent re-run). Absent/empty ⇒ the block alone. Otherwise append the block, preserving the
+ * existing content and a clean separating blank line.
+ */
+export declare function mergeMarkedInstruction(existing: string | null | undefined): AgentRuleResult;
+/** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
+export declare function cursorRuleFile(): string;
+export {};

package/dist/agent-rules.js

@@ -0,0 +1,279 @@
+/**
+ * `reticle init` writes a behavioral rule into the coding agent's instruction file so the agent
+ * VERIFIES a feature with Reticle after building it — not only when the user remembers to say "test
+ * it with reticle". Registering the MCP server (mcp.ts / mcp-clients.ts) only makes the tools AVAILABLE;
+ * this is the piece that makes the agent reach for them, every session, unprompted.
+ *
+ * It carries a SECOND standing instruction, and that one is not about this project at all: send
+ * feedback to the Reticle maintainers, from the moment instrumentation starts. The agent is the party
+ * that experiences Reticle, and the only one who can say what it cost — and by the time anyone would
+ * think to ask, the context that knew is gone. Written into the same block, because the moment the
+ * rule lands (init, before any framework wiring) is the moment the setup itself is being lived
+ * through, which is when the reports we hear least about are actually generated.
+ *
+ * The rule is framed as a definition-of-done (WHEN to verify, HOW, and the anti-reward-hacking guard),
+ * written into whichever instruction file the detected agent reads: `CLAUDE.md` (Claude Code),
+ * `.cursor/rules/reticle.mdc` (Cursor, `alwaysApply` so it stays in context), or `AGENTS.md` as the
+ * cross-agent fallback. Idempotent via a marker block — safe to append to an existing file and a
+ * re-run is a no-op. Mirrors the apply/already result shape used across init (see mcp-clients.ts).
+ */
+import { NPX } from './mcp.js';
+import { RETICLE_NPM_PACKAGE } from './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. */
+const RULE_BEGIN = '<!-- reticle:begin (managed by `reticle init` — edit outside these markers) -->';
+const RULE_END = '<!-- reticle:end -->';
+/**
+ * Does this file already carry the managed block?
+ *
+ * Exported so callers cannot invent their own looser test. The begin marker carries explanatory
+ * text inside the comment, so a substring check for `reticle:begin` matches files that
+ * `mergeMarkedInstruction` would treat as having NO block — and the two disagreeing means a refresh
+ * silently appends a second copy instead of updating the first.
+ */
+export function hasManagedBlock(text) {
+    return text.includes(RULE_BEGIN);
+}
+/**
+ * How the agent must INVOKE the CLI.
+ *
+ * `reticle init` installs the SDK packages, never the server — so there is no `reticle` on the
+ * agent's PATH, and every bare `reticle <cmd>` this rule named was an instruction that could not be
+ * followed. Reported from a field sweep: three of them, in the file the agent re-reads every session.
+ *
+ * `npx @reticlehq/server` is the same invocation the MCP registration uses, and it is derived from
+ * the package's own name so the two can never drift apart.
+ */
+export const CLI = `${NPX} ${RETICLE_NPM_PACKAGE}`;
+/**
+ * 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: one server at a time,
+ * read the command rather than invent one, never kill anything you did not start, and leave the
+ * permission prompt to the host. "Background it and say so" is no longer among them because the
+ * branch above now states it at the point of action, and this text is read every turn — a rule
+ * stated twice costs every agent tokens forever and is the first thing to drift.
+ *
+ * The RESTART branch outranks the rest and is stated first. It used to be an aside, while "if a dev
+ * server is already listening, use it" was a numbered guard — so an agent resolving the two
+ * reasonably reused a server started before `init` edited the build config, served a bundle with no
+ * SDK in it, and landed on an empty session list with every other step done correctly.
+ *
+ * Exported because slash-command.ts renders the same rule; there must not be two versions of it.
+ */
+export 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:
+
+1. **A dev server was already running?** Restart it, then hard-reload the tab. "Something is listening" does not mean the right bundle is served.
+2. **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.
+
+Stopping to ask is how a verification turn ends with nothing verified.
+
+Four guards, none optional:
+
+1. **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.
+2. **Never guess the command.** It comes from \`package.json\` scripts. No recognisable dev script means say so and stop, not invent one.
+3. **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.
+4. **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.
+ *
+ * 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.
+ */
+export 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 (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.
+
+**Setting Reticle up, or just restarted? You are mid-sequence — do not stop until a verdict exists.**
+The whole of it is: instrument the app → get a dev server running → open the app in a browser →
+drive one flow → report the verdict. Every step is yours to do, and none of them needs the user.
+The ONE legitimate pause is a client restart, because a client reads its server list at startup;
+when you come back, you are not finished, you are on the next step — resume it without being asked.
+Stopping anywhere else leaves an app that looks installed and can verify nothing, which is the
+single commonest way this goes wrong. \`/reticle\` carries the full recovery ladder when a step
+does not work; use it rather than guessing, and never report the install as finished without a
+verdict to point at.
+
+**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.
+
+**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 — 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.
+
+**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.
+
+**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.
+
+**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.
+- **\`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 — a signal, a request, a route, or store state — and call again.
+- **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.
+
+**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.
+
+**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 — what is established, what is proven, what is still unverified — 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.
+
+**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.
+
+## 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.
+- **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 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',
+};
+/** The marker-wrapped block appended to a CLAUDE.md / AGENTS.md instruction file. */
+export function markedBlock() {
+    return `${RULE_BEGIN}\n${RULE_BODY}\n${RULE_END}\n`;
+}
+/**
+ * Merge the managed block into a marker-delimited instruction file. Already present ⇒ no change
+ * (idempotent re-run). Absent/empty ⇒ the block alone. Otherwise append the block, preserving the
+ * existing content and a clean separating blank line.
+ */
+export function mergeMarkedInstruction(existing) {
+    if (existing !== null && existing !== undefined && existing.includes(RULE_BEGIN)) {
+        // A block that can never be updated is not managed. Returning ALREADY on sight of the marker
+        // meant a project that ran init once kept that release's rule text forever, so every improvement
+        // reached only new projects — and a rule about a field introduced later (`version_skew`) could
+        // never arrive at all. The markers promise the inside is ours; idempotence comes from comparing
+        // CONTENT instead of presence.
+        return refreshMarkedBlock(existing);
+    }
+    const block = markedBlock();
+    if (null === existing || existing === undefined || 0 === existing.trim().length) {
+        return { status: AgentRuleStatus.APPLY, content: block };
+    }
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    return { status: AgentRuleStatus.APPLY, content: `${existing}${separator}${block}` };
+}
+/**
+ * Swap the managed block for the current one, leaving every character outside the markers alone.
+ *
+ * A malformed file — a begin marker with no end — is left untouched and reported ALREADY. Rewriting
+ * from a marker to end-of-file would eat whatever the human wrote after it, and silently destroying
+ * someone's instruction file is far worse than a stale rule.
+ */
+function refreshMarkedBlock(existing) {
+    const start = existing.indexOf(RULE_BEGIN);
+    const endAt = existing.indexOf(RULE_END, start);
+    if (-1 === endAt)
+        return { status: AgentRuleStatus.ALREADY, content: existing };
+    const current = existing.slice(start, endAt + RULE_END.length);
+    const wanted = markedBlock().trimEnd();
+    if (current === wanted)
+        return { status: AgentRuleStatus.ALREADY, content: existing };
+    const content = `${existing.slice(0, start)}${wanted}${existing.slice(endAt + RULE_END.length)}`;
+    return { status: AgentRuleStatus.APPLY, content };
+}
+/** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
+export function cursorRuleFile() {
+    return `---
+description: Verify web features with Reticle after building them, and report Reticle problems back to its maintainers
+alwaysApply: true
+---
+
+${RULE_BODY}
+`;
+}

package/dist/app-choice.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Which app in a workspace `reticle init` should wire, when the caller says.
+ *
+ * Refusing to guess between several apps is right — instrumenting one silently would leave the rest
+ * unverified while reporting success. But "re-run inside the one you want" is not an answer a
+ * script, a CI step, or an agent that cannot change directory can act on, so the refusal was a dead
+ * end for exactly the callers most likely to hit it.
+ *
+ * A name that is not one of the discovered apps is refused rather than trusted: it is almost always
+ * a typo or a stale path, and wiring a directory that is not an app writes files nothing compiles.
+ */
+type AppChoice = {
+    ok: true;
+    app: string | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Trim the trailing slashes tab-completion adds, without a regex.
+ *
+ * `/\/+$/` is quadratic on a long run of slashes: the engine retries the match from every start
+ * position. Nobody is attacking their own `--app` flag, so the risk here is theoretical — but the
+ * loop is the same two lines, is linear, and keeps a real ReDoS finding out of the scanner's
+ * results, where a theoretical one costs the attention that a genuine one needs.
+ */
+export declare function withoutTrailingSlashes(path: string): string;
+export declare function chooseWorkspaceApp(requested: string | undefined, apps: readonly string[]): AppChoice;
+export {};

package/dist/app-choice.js

@@ -0,0 +1,39 @@
+/**
+ * Which app in a workspace `reticle init` should wire, when the caller says.
+ *
+ * Refusing to guess between several apps is right — instrumenting one silently would leave the rest
+ * unverified while reporting success. But "re-run inside the one you want" is not an answer a
+ * script, a CI step, or an agent that cannot change directory can act on, so the refusal was a dead
+ * end for exactly the callers most likely to hit it.
+ *
+ * A name that is not one of the discovered apps is refused rather than trusted: it is almost always
+ * a typo or a stale path, and wiring a directory that is not an app writes files nothing compiles.
+ */
+/**
+ * Trim the trailing slashes tab-completion adds, without a regex.
+ *
+ * `/\/+$/` is quadratic on a long run of slashes: the engine retries the match from every start
+ * position. Nobody is attacking their own `--app` flag, so the risk here is theoretical — but the
+ * loop is the same two lines, is linear, and keeps a real ReDoS finding out of the scanner's
+ * results, where a theoretical one costs the attention that a genuine one needs.
+ */
+export function withoutTrailingSlashes(path) {
+    let end = path.length;
+    while (0 < end && '/' === path[end - 1])
+        end -= 1;
+    return path.slice(0, end);
+}
+export function chooseWorkspaceApp(requested, apps) {
+    if (requested === undefined || '' === requested)
+        return { ok: true, app: undefined };
+    // Tab-completion adds a trailing slash; the discovered names never carry one.
+    const wanted = withoutTrailingSlashes(requested);
+    if (apps.includes(wanted))
+        return { ok: true, app: wanted };
+    return {
+        ok: false,
+        message: 0 === apps.length
+            ? `--app ${requested} was given, but no app was found in this workspace`
+            : `--app ${requested} is not one of the apps found here: ${apps.join(', ')}`,
+    };
+}