@reticlehq/server 3.5.0 → 3.7.0

package/docs/quickstart.mdx

@@ -5,7 +5,7 @@ description: Install Reticle, connect your coding agent, and get a real verdict
 icon: rocket
 ---
 
-**Run the installer once, then run `reticle connect --project "My App"` in your project.** Reticle embeds a dev-only SDK in your running app, signs you in through browser approval when needed, and syncs your checks to the project you name.
+**Four steps: run the installer once per machine, run `reticle init` once per project, then optionally `reticle connect` for the dashboard and `reticle sync` to send runs.** Skip `init` and your agent's first `reticle_session` call wires the app instead. Reticle embeds a dev-only SDK in your running app and proves a browser session connected. No account needed for steps 1 and 2.
 
 By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
 
@@ -16,7 +16,7 @@ By the end of this page your agent will click a button in your app and prove wha
 
 ## Prerequisites
 
-- Node 20 or newer
+- Node 20.11 or newer
 - A web app you can run locally, and its dev server
 - A coding agent that speaks MCP (Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code)
 
@@ -36,9 +36,9 @@ irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1
 
 </CodeGroup>
 
-This puts `reticle` on your PATH and registers the MCP server with every coding agent it can reach: Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Warp, Kiro, Amazon Q, Cline, Amp, Continue and Factory Droid. Nothing is asked.
+This puts `reticle` on your PATH and registers the MCP server with every coding agent it can reach: Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Antigravity, Warp, Kiro, Amazon Q, Cline, Roo Code, Amp, Continue and Factory Droid. Nothing is asked. It does not wire your app, and says so: that is step 2. Want a verdict first? Signed in, `reticle try <url>` drives a URL once in a window you watch.
 
-Codex CLI keeps a TOML config that Reticle will not rewrite, so the installer prints the lines to paste and the file to paste them into.
+Codex CLI keeps a TOML config that Reticle will not rewrite itself, so with the `codex` command installed the installer registers Reticle through `codex mcp add`. Without it, the installer prints the lines to paste and the file to paste them into.
 
 <Note>
   **Run this before opening your agent, and there is nothing to restart.** A coding agent reads its
@@ -46,26 +46,32 @@ Codex CLI keeps a TOML config that Reticle will not rewrite, so the installer pr
   you open it. If it was already open, quit and reopen it once.
 </Note>
 
-Prefer not to pipe a script into a shell? The two commands it runs are:
+Prefer not to pipe a script into a shell? The same result by hand:
 
 ```bash
 npm install -g @reticlehq/server
 npx @reticlehq/server setup mcp
 ```
 
-## Step 2. Connect this project
+## Step 2. Wire this project
 
 In your project directory, before opening your coding agent:
 
 ```bash
-npx @reticlehq/server connect --project "My App"
+RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server init
 ```
 
-This installs the SDK, wires your app, starts the dev server, and checks that a browser session connected. It then opens browser sign-in approval if needed, links this folder to the named cloud project, and sends existing local history. Approve the short code shown in the browser and terminal; the command resumes by itself. A saved sign-in is reused after the cloud accepts it. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools.
+This installs the dev-only SDK, wires your build config, starts the dev server, and checks that a browser session connected. Nothing from your project leaves your machine. If your dev server was already running, restart it once and hard-reload the tab: it read your build config before `init` edited it. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools. The `RETICLE_INSTALL_SOURCE` prefix is optional and only tells us which page you installed from. It is idempotent: run it twice and the second run reports what was already done rather than doing it again.
 
-Step 1 is once per machine. This step is once per project.
+Step 1 is once per machine. This step is once per project. **Skipping it is a common reason Reticle "does nothing":** the agent has the tools, but there is no app on the other end for them to see.
 
-Want local-only verification without an account? Run `reticle init` in this step instead. You can run `reticle connect` later to sync your history.
+<Note>
+  **Skipped this step?** Ask your agent to verify something in the app. Its first `reticle_session`
+  call finds a project that has never connected, runs `init` there itself, and lists every file it
+  changed under `wired`. Asked about something unrelated, it offers to wire the app instead of doing
+  it. This works in Claude Code, Codex, Cursor and other MCP agents, including a second project
+  while Reticle is already running for another one.
+</Note>
 
 Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
 
@@ -86,6 +92,7 @@ Useful flags for the local-only `reticle init` path:
 
 ```
 reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+              [--env KEY=VALUE]... [--files-only] [--json] [--relaunch]
               --app picks WHICH app in a monorepo, when several are found
               --no-mcp skips MORE than the server registration: also the agent rule files
               (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
@@ -95,13 +102,38 @@ reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
 Start with `reticle init --dry-run` if you want to see the app changes before anything is written.
 
 <Tip>
-  In a monorepo, `init` will find several apps and ask which one you mean. `--app packages/web`
-  skips the question.
+  In a monorepo, `init` run at the root lists every app it found, each with its own
+  `reticle init --app <dir>` line, and stops. Run the line for the app you want: it writes that
+  app's files and starts nothing (add `--start` to boot it). With only one app, it wires that one
+  without asking.
 </Tip>
 
 Prefer to wire it yourself? See [Manual install](/install-manual). It is about ten lines, and worth reading once even if you let the agent do it, because it explains what the agent actually changed.
 
-## Step 3. Check the setup
+## Step 3. Connect the dashboard (optional)
+
+Skip this if you only want local verdicts. Everything above works without an account.
+
+```bash
+npx @reticlehq/server connect --project "My App"
+```
+
+`connect` runs Step 2 first if this project isn't wired yet, so you can use it in place of `init`. Then it:
+
+1. Opens a browser so you can sign in, or create a free account at app.reticle.sh. Approve the short code shown in the browser and in the terminal, and the command carries on by itself.
+2. Links this folder to the cloud project you named, creating it if it doesn't exist. `npx @reticlehq/server status` shows the link.
+3. Sends the runs and flows already on this machine.
+
+After that, every verified run syncs on its own. To sync right now, for example before showing a teammate:
+
+```bash
+npx @reticlehq/server sync            # one sync
+npx @reticlehq/server sync --watch    # keep syncing while you work
+```
+
+A new account gets 10 free credits to try the Harness. What syncs, and how to switch each part off (`reticle config --runs/--memory/--flows on|off`), is in [What is recorded](/what-is-recorded). In CI, set `RETICLE_API_KEY` instead of signing in.
+
+## Step 4. Check the setup
 
 ```bash
 npx @reticlehq/server doctor
@@ -109,9 +141,9 @@ npx @reticlehq/server doctor
 
 `doctor` diagnoses the whole setup in one command: Chromium, the daemon, the port. If something is wrong this is the page you want before you start debugging your app instead.
 
-## Step 4. Open your app again when you need it
+## Step 5. Open your app again when you need it
 
-`connect` already started the dev server and opened the app. On a later day, start your dev server as usual, then:
+`init` (or `connect`) already started the dev server and opened the app. On a later day, start your dev server as usual, then:
 
 ```bash
 npx @reticlehq/server open
@@ -121,12 +153,13 @@ This reuses the tab you already have open, or opens one if you don't. The SDK co
 
 <Warning>
   If the browser console says `[Reticle] this page could not open a websocket to …`, your app and
-  the daemon disagree about the port. Set it explicitly:
-  `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` for Vite, or `reticle.connect({url})`. This is
-  the single most common setup problem, and the console message names the exact address it tried.
+  the daemon disagree about the port. Set it explicitly: `RETICLE_PORT=4400 pnpm dev` (Vite
+  plugin), `reticle({ port: 4400 })` in `vite.config`, or
+  `reticle.connect({ url: 'ws://localhost:4400/reticle' })` by hand. The console
+  message names the exact address it tried.
 </Warning>
 
-## Step 5. Look at the page
+## Step 6. Look at the page
 
 Ask your agent to take a snapshot. This is what came back from a real app:
 
@@ -148,7 +181,7 @@ The whole snapshot cost **61 tokens**. This is `mode: "interactive"`, which retu
 
 Each control has a `ref` like `e5`. That's the handle for the next step, and it stays valid until the element leaves the DOM, so you don't re-snapshot between actions.
 
-## Step 6. Act, and prove it
+## Step 7. Act, and prove it
 
 Here is the whole idea of Reticle in one call. Your agent names the expected consequence **before** it acts:
 
@@ -218,7 +251,7 @@ Read what that actually proves:
 
 ## What "verified" can say
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
   <Card title="yes" icon="circle-check">
     The consequence you named actually happened, and the evidence is attached.
   </Card>
@@ -228,6 +261,9 @@ Read what that actually proves:
   <Card title="unknown" icon="circle-question">
     Reticle drove the app and could not tell. **This is not a pass.** Report it as unknown.
   </Card>
+  <Card title="no-fault" icon="circle-minus">
+    Nothing was declared to prove, so nothing was checked. **Not a pass either:** add an `until`.
+  </Card>
 </CardGroup>
 
 That third state is the one that matters. Most tools have two outcomes and quietly file "I couldn't tell" under "fine". A verification layer that cannot admit uncertainty is just a very confident random number generator.
@@ -249,17 +285,19 @@ That third state is the one that matters. Most tools have two outcomes and quiet
 </Accordion>
 
 <Accordion title="Will any of this end up in my production build?">
-  No. The SDK is dev-only. The Vite plugin declares `apply: 'serve'`, so it is dropped from `vite
-  build` entirely, and `connect()` self-disables when the build reports `NODE_ENV=production`. The
-  recommended wiring also guards the call behind `import.meta.env.DEV`, so there are two independent
-  locks.
+  No. The SDK is dev-only. A production `vite build` with the Vite plugin injects nothing and
+  replaces the SDK with an inert stub, and `connect()` self-disables when the build reports
+  `NODE_ENV=production`. The recommended wiring also guards the call behind `import.meta.env.DEV`,
+  so there are two independent locks.
 </Accordion>
 
 <Accordion title="Does my code or my app's data leave my machine?">
-  No. The daemon runs on your machine and the SDK runs in your browser. No application code, DOM,
-  network traffic or console output leaves it. Anonymous product analytics are sent unless you opt
-  out with `npx @reticlehq/server telemetry disable`, and they never include your code or your app's
-  data.
+  Not unless you link a project. The daemon runs on your machine and the SDK runs in your browser.
+  Nothing from your app leaves the machine until you link a project (`reticle connect`, or
+  `RETICLE_API_KEY` in CI). After that, what syncs is set by `reticle config`, and when the Harness
+  drives, the platform sees the steps it drives. Secret values never leave. Anonymous product
+  analytics are sent unless you opt out with `npx @reticlehq/server telemetry disable`, and they
+  never include your code or your app's data.
 </Accordion>
 
 <Accordion title="What if my framework is not React or Next.js?">
@@ -283,7 +321,8 @@ That third state is the one that matters. Most tools have two outcomes and quiet
     Emit signals like `auth:granted` so your verdicts get stronger than "the DOM changed".
   </Card>
   <Card title="Every tool" icon="list" href="/tools/overview">
-    The 18 tools your agent sees by default, and the 30 more it can reach on demand.
+    The 10 tools your agent sees by default, and the rest it reaches through `reticle_tools` and
+    `reticle_run`.
   </Card>
   <Card title="Run it in CI" icon="circle-check" href="/testing">
     Turn this session into a suite that blocks a bad merge.

package/docs/required-checks.md

@@ -9,9 +9,9 @@ That gap is the difference between a gate and a decoration. A decoration still c
 
 ## How it works here
 
-`ci.yml` ends in a single job called **`gate`**. It waits on every other job in that file and passes only when each one either succeeded or was legitimately skipped. So one required check, `gate`, covers all fifteen jobs in `ci.yml`.
+`ci.yml` ends in a single job called **`gate`**. It waits on every other job in that file and passes only when each one either succeeded or was legitimately skipped. So one required check, `gate`, covers every other job in `ci.yml` except `fixtures-dispatch`, which notifies another repository and never runs on a pull request.
 
-That trick only reaches so far. A job can only wait on jobs in **its own workflow file**, so the five workflows below cannot be folded into `gate`. Each has to be named in branch protection separately, or it blocks nothing.
+That trick only reaches so far. A job can only wait on jobs in **its own workflow file**, so the other workflows below cannot be folded into `gate`. Each has to be named in branch protection separately, or it blocks nothing.
 
 `server/src/ci-aggregate-covers-jobs.test.ts` fails if a new workflow starts running on pull requests without being accounted for, and if a job in `ci.yml` is not watched by `gate`.
 
@@ -21,13 +21,14 @@ Set these as required status checks on the default branch:
 
 | check | what it is | what merges without it |
 | --- | --- | --- |
-| `gate` | every job in `ci.yml`: build, tests, e2e, desktop, install, Rust, Windows, macOS, bench | a red build of any kind |
-| `package-quality` | the published packages: exports and types correctness, and the browser SDK's size budget | a package that installs but cannot be imported, or a silently growing SDK |
-| `break-gates` | onboarding | a broken first-run experience |
-| `codeql` | security scan | a flagged vulnerability |
+| `gate` | every job in `ci.yml`: build, tests, e2e, desktop, install, Rust, Windows, macOS, bench, package quality, the break gates | a red build of any kind (bench and the Windows install cells run only after merge) |
 | `dco` | contributions are signed off | an unsigned contribution |
 
-`labeler` is deliberately absent. It adds labels to a pull request; there is no result to block on.
+package-quality and the break gates (`launchers`, `early-gates`, `break-matrix`) run as jobs inside `ci.yml` and are covered by `gate`. They used to be separate workflows with no `merge_group` trigger, so requiring them by name would have stalled the queue.
+
+CodeQL (`analyze (javascript-typescript)`) runs on pull requests and in the merge queue, but the ruleset does not require it, so a flagged vulnerability is reported rather than blocked.
+
+`labeler`, `welcome` and `dependabot-auto-merge` are deliberately absent. They label a pull request, greet a first contribution, and turn on auto-merge for Dependabot updates the queue still gates; there is no result to block on.
 
 ## Adding a workflow
 

package/docs/reticle-manual.md

@@ -10,7 +10,9 @@ Every row below is a call that was made against a running app and the answer tha
 
 `refused (names the fix)` means the error told you what to call instead, so you can correct without reading anything else. `refused (no fix named)` means it did not.
 
-## reticle_snapshot
+## reticle_look { action: "page" }
+
+Probed as `reticle_snapshot`, its name before the merge, which still answers. Call it as `reticle_look { action: "page" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |
@@ -18,7 +20,9 @@ Every row below is a call that was made against a running app and the answer tha
 | the documented call: `{"mode":"interactive"}` | ran | 434 |
 | a value outside the allowed set: `{"mode":"not-a-mode"}` | refused (names the fix) | 236 |
 
-## reticle_query
+## reticle_look { action: "find" }
+
+Probed as `reticle_query`, its name before the merge, which still answers. Call it as `reticle_look { action: "find" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |
@@ -26,7 +30,9 @@ Every row below is a call that was made against a running app and the answer tha
 | the documented call: `{"by":"role","value":"button"}` | ran | 200 |
 | a value outside the allowed set: `{"by":"telepathy","value":"x"}` | refused (names the fix) | 290 |
 
-## reticle_network
+## reticle_observe { action: "network" }
+
+Probed as `reticle_network`, its name before the merge, which still answers. Call it as `reticle_observe { action: "network" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |
@@ -34,13 +40,17 @@ Every row below is a call that was made against a running app and the answer tha
 | the documented call: `{"limit":5}` | ran | 1175 |
 | a number outside its range: `{"limit":-1}` | refused (names the fix) | 222 |
 
-## reticle_console
+## reticle_observe { action: "console" }
+
+Probed as `reticle_console`, its name before the merge, which still answers. Call it as `reticle_observe { action: "console" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |
 | an argument the tool does not declare: `{"thisArgDoesNotExist":1}` | refused (names the fix) | 293 |
 
-## reticle_state
+## reticle_look { action: "state" }
+
+Probed as `reticle_state`, its name before the merge, which still answers. Call it as `reticle_look { action: "state" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |

package/docs/skill-file.mdx

@@ -1,107 +1,45 @@
 ---
 title: 'The SKILL file: paste and go'
 sidebarTitle: SKILL file
-description: One URL you paste into any coding agent to teach it Reticle. How it works, what it contains, and when you need it at all.
+description: One URL you paste into any coding agent to teach it Reticle. Where it lives and what it tells the agent.
 icon: graduation-cap
 ---
 
-Paste `https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` into any coding agent and say "read this and set up Reticle". The document tells the agent to run `npx @reticlehq/server init`, which wires the project and gets the app connected, then to do the first run with `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`, and gives it the rules for verifying afterwards. You often do not need the file at all: that one command configures Claude Code, Cursor and nine other agents directly, and the file mostly exists to tell an agent which journey to prove and how to read what comes back.
+`SKILL.md` is one short document written for a coding agent. Its home is this docs site:
 
-`SKILL.md` is a single document you hand to a coding agent. It teaches the agent to install Reticle, wire it into your app, and then drive a verification loop properly. Without you explaining any of it.
-
-```
-https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md
-```
-
-That URL is live and returns the current version. Paste it into your agent and say "read this and set up Reticle".
-
-<Note>
-  You often do not need it. `npx @reticlehq/server init` writes a `/reticle` slash command for
-  Claude Code automatically, and installs agent rule files for Claude and Cursor. The SKILL file is
-  for agents that `init` cannot configure, for a from-scratch install, or when you want the agent to
-  have the full protocol in context rather than a summary.
-</Note>
-
-## It has two modes, and it picks one itself
-
-The first thing the document tells an agent to do is check which situation it is in:
-
-```bash
-cat .reticle.json 2>/dev/null || echo "NOT_FOUND"
 ```
-
-- **Not found** → run **Setup mode**: register the MCP server, install the SDK, wire the entry point, validate the connection, and prove it on one flow while the user watches.
-- **Found** → run **Test mode**: connect, orient, decide what to test, drive it, report.
-
-One document, two jobs, no flag for you to remember. The second time you invoke it, it skips straight to the useful part.
-
-## What Setup mode actually does
-
-| Phase | What the agent does |
-| --- | --- |
-| Save the skill | Store it as `/reticle` so the loop is one word away from then on |
-| Run `init`, then the first run | Without asking you questions it can answer itself, naming the journey worth proving as the `persona` |
-| Manual fallbacks | Only when `init` could not run: an older CLI that stops after writing files, or the same failure twice |
-| Validate | Confirm a session actually connected. Not that a checklist went green |
-| Prove it | Drive one real flow while you watch, so the install ends in evidence |
-
-That last row is the one that matters. Plenty of installs "succeed" and then nothing works. The skill does not consider itself finished until a real flow has produced a real verdict.
-
-## What Test mode actually does
-
-Five phases: connect, orient, decide what to test, run the tests, report. The reporting format is specified, which matters more than it sounds. An agent left to summarise freely will summarise optimistically.
-
-The rules it operates under are the same ones these docs keep repeating:
-
-- Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.
-- `verified: "unknown"` is not a pass.
-- Never weaken a check to make it pass.
-
-## Feedback is the first section, on purpose
-
-Before setup, before anything, the document tells the agent that reporting problems is part of the job. And that this applies **during** setup, which is where Reticle is most likely to break and least likely to hear about it.
-
-It even covers the case where nothing is installed yet:
-
-```bash
-npx @reticlehq/server feedback --agent --kind gap "init finished but no session ever connected"
+https://docs.reticle.sh/skill.md
 ```
 
-That works with no daemon running, which is the entire point. The install that failed halfway is the one worth hearing about, and in that state the MCP tools do not exist.
-
-<Tip>
-  It also draws a line that saves everyone time: report defects in **Reticle**. A bug found in the
-  app under test is Reticle working correctly, and belongs in the answer to the user.
-</Tip>
-
-## It ships inside the package too
-
-`SKILL.md` is bundled into `@reticlehq/server` at publish time, alongside a copy of this entire documentation site. So an agent that has already installed Reticle can read it from disk without a network round trip:
+Paste that URL into the agent and say "read this and set up Reticle". It is the canonical file with [Agent Skill](https://agentskills.io) frontmatter (`name`, `description`) added. The repository copy, `https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md`, has the same body without the frontmatter, and a test fails if the two ever differ. To install the rules as a skill instead, `npx skills add reticlehq/reticle` installs `reticle` (the Claude Code plugin's shorter restructure of this file, held to the same rules by that test) and the task skills beside it. The same file ships inside the package, so an agent with no network can read it from disk:
 
 ```
 node_modules/@reticlehq/server/SKILL.md
 node_modules/@reticlehq/server/docs/
 ```
 
-Handy in a sandbox with no outbound network, which is an increasingly common place for an agent to live.
+The `docs/` folder beside it is a copy of this site.
+
+## What it tells the agent
 
-## Should you read it?
+It is the critical path and nothing else. Read [SKILL.md](https://github.com/reticlehq/reticle/blob/main/SKILL.md) itself to get the rules exactly right; in short:
 
-Probably not, unless you are curious. It is roughly 60 KB and written for an agent, which means it is exhaustive in the way a runbook is exhaustive. Every fallback, every framework, every failure mode spelled out rather than summarised.
+- **First move:** if the `reticle_*` tools are visible, call `reticle_session { action: "list" }`. If they are not, hand the user the installer line and stop.
+- **Setup is `init`, then the first run.** `init` wires the app and waits for a session. It never drives. A dev server that was already running must be restarted once.
+- **Done means a verdict.** A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
+- **Only `verified: "yes"` is a pass.** `unknown` means Reticle could not tell. Never weaken a check to make it pass.
+- **Replay before you drive.** `reticle_verify { action: "change" }` or `{ action: "flows" }` re-verifies saved journeys in one call.
+- **Report problems with Reticle** through `reticle_session { action: "feedback" }`, or `reticle feedback --agent` from the shell.
 
-If you want the human version of the same material, you are already in it:
+## Do you need it?
+
+Often not. The installer registers the MCP server with your agents, and `reticle init` writes agent rule files and a `/reticle` command for Claude Code. The SKILL file is for agents `init` cannot configure, for a from-scratch install, or for an agent you want to hold the rules in context.
 
 <CardGroup cols={2}>
   <Card title="Agentic install" icon="wand-magic-sparkles" href="/install-agentic">
     What `reticle init` does, with real output.
   </Card>
-  <Card title="Manual install" icon="screwdriver-wrench" href="/install-manual">
-    Every step `init` cannot automate.
-  </Card>
   <Card title="Agent cheat sheet" icon="bolt" href="/agent-cheatsheet">
     The one-screen version of the drive loop.
   </Card>
-  <Card title="Best practices" icon="star" href="/best-practices">
-    The habits that make verdicts worth trusting.
-  </Card>
 </CardGroup>

package/docs/skill-setup.md

@@ -6,7 +6,7 @@ icon: wrench
 
 You only need this page while you are setting Reticle up, which happens once per project. Once an app is connected, the everyday loop lives in `SKILL.md` and you never need to come back here.
 
-**One command. It does all of it, and it ends with a verdict.**
+**One command. It wires the app and proves a session connected. The verdict is the first run, after it.**
 
 ```bash
 RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
@@ -14,7 +14,7 @@ RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
 
 `@latest` is deliberate: `npx` caches, and a stale cached CLI is the most common silent setup failure. Never pin a version here.
 
-That single command detects the framework and package manager, wires the build config, installs the SDK, registers the MCP server, starts the dev server, opens the app, and waits for a session to connect from inside it. It exits non-zero if nothing connected, and prints exactly what is left to do. Then prove a flow. That is the FIRST RUN, and it is a separate call: `reticle_verify { action: "explore", persona: "<who does what>" }`. It drives with a model inside the daemon and records what it drove, so later checks replay it with no model in the loop.
+That single command detects the framework and package manager, wires the build config, installs the SDK, registers the MCP server, starts the dev server, opens the app, and waits for a session to connect from inside it. It exits non-zero if nothing connected, and prints exactly what is left to do. Then prove a flow. That is the FIRST RUN, and it is a separate call: drive one journey with `reticle_act_and_wait` and an `until` on its last step. On a project linked with `reticle connect`, `reticle_verify { action: "explore", persona: "<who does what>" }` lets the Reticle Harness drive it on the platform instead. Either way what was driven is saved as a flow, so later checks replay it with no model in the loop.
 
 ## What YOU decide, and pass in
 
@@ -22,7 +22,7 @@ The command reads the repository. It cannot read the request, and three things l
 
 | flag | what only you know |
 | --- | --- |
-| `persona: "<what>"` | Not an `init` flag. It belongs to the FIRST RUN, `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`. Which journey proves the thing the user asked for: code can list the buttons; it cannot know checkout matters and the theme toggle does not. Naming it took one real app from a ten-minute timeout to 138 seconds, because the turns go into FINDING a flow. |
+| `persona: "<what>"` | Not an `init` flag. It belongs to the FIRST RUN, `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`. Which journey proves the thing the user asked for: code can list the buttons; it cannot know checkout matters and the theme toggle does not. Without one, the turns go into FINDING a flow. |
 | `--env KEY=VALUE` | what the app needs to reach a usable state: the key from `.env.example`, the mock backend in the README, the variable that skips an auth wall. Repeatable. Without it a real app sits on a login screen and there is no flow to drive at all. |
 | `--app <dir>` | which app in a monorepo. It can list the ones that are servable; only the request says which one is being worked on. |
 
@@ -34,7 +34,7 @@ The command reads the repository. It cannot read the request, and three things l
 
 `⚠` lines and a non-zero exit are a to-do list, not a failed install. The command names the cause and prints the REMAINING steps from wherever it stopped, and it will not tell you to redo a phase that already worked. Do those, and re-run; re-running is safe.
 
-**It is not finished until a verdict exists.** Writing files is not an install, and neither is a connected session. If it exits non-zero, the app is wired and something is still outstanding; say so plainly rather than reporting success.
+**It is not finished until a verdict exists.** A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict. Writing files is not an install. If it exits non-zero, the app is wired and something is still outstanding; say so plainly rather than reporting success.
 
 **If the user gave you a license key**, see [License key](#license-key) below.
 
@@ -42,13 +42,13 @@ The command reads the repository. It cannot read the request, and three things l
 
 ## If that command could not run it
 
-**Do not choose this path.** It is not the thorough version of the one above; it is what you fall back to when the command physically could not do the work, and taking it by preference is how an install costs 176 turns instead of one. That is a measured figure, not a way of speaking.
+**Do not choose this path.** It is not the thorough version of the one above; it is what you fall back to when the command physically could not do the work, and taking it by preference turns a one-command install into a long manual one.
 
 Use it only when ONE of these is true, and you can say which:
 
-- `init` exited without ever printing `starting:` or `▸ WATCH`, which means the CLI on this machine predates the runtime phases and stopped after writing files.
+- `init` exited without ever printing `starting:` or `watching for an app to connect`, which means the CLI on this machine predates the runtime phases and stopped after writing files.
 - `init` printed a to-do list, you did those things, re-ran it, and it stopped in the same place twice.
-- There is no Node 18 or newer on this machine, so nothing can run.
+- There is no Node 20.11 or newer on this machine, so nothing can run.
 
 Anything else is not a reason: not a `⚠` in the report, not a step you would rather do yourself, not a feeling that you should check its work. Re-run the command. It is idempotent, it reports what is already wired, and it names what is still outstanding.
 
@@ -69,7 +69,7 @@ Do not reconstruct it from memory. Three things decide whether it works, and all
 
 ## The dev server, whoever starts it
 
-**A dev server already running when `init` ran does not have Reticle in its bundle.** It read `vite.config.ts` / `next.config.js` at boot; `init` edited that file afterwards. The process keeps serving the old bundle, the page loads without the SDK, no session appears, and every symptom points at the wiring you just correctly did. This is a 100% failure, not an intermittent one, and it is the single largest cause of an install that gets to step 4 and finds an empty list.
+**A dev server already running when `init` ran does not have Reticle in its bundle.** It read `vite.config.ts` / `next.config.js` at boot; `init` edited that file afterwards. The process keeps serving the old bundle, the page loads without the SDK, no session appears, and every symptom points at the wiring you just correctly did. This fails every time, not intermittently, and it is a common reason an install finds an empty session list.
 
 So, in this order:
 
@@ -97,7 +97,7 @@ Enterprise features are unlocked by a signed key, verified locally with Ed25519
 npx @reticlehq/server@latest init --license <key>
 ```
 
-That writes `RETICLE_LICENSE_KEY` to the project's `.env` and adds `.env` to `.gitignore` if nothing there covers it. Do not do those two by hand: a key committed to git is a leaked credential, and it stays leaked after the file is removed. Confirm with `npx @reticlehq/server license`, which prints `active`, `eval`, `missing` or `expired`.
+That writes `RETICLE_LICENSE_KEY` to the project's `.env` and adds `.env` to `.gitignore` if nothing there covers it. Do not do those two by hand: a key committed to git is a leaked credential, and it stays leaked after the file is removed. Confirm with `npx @reticlehq/server license`, which prints `active`, `eval`, `missing`, `invalid` or `expired`.
 
 Never echo the key back in your reply, and never put it in a commit, a code comment, or a feedback report. The rest: `curl https://docs.reticle.sh/enterprise.md`.