@reticlehq/server 2.14.0 → 3.2.0

package/docs/autodrive.md

@@ -0,0 +1,99 @@
+---
+title: Let Reticle drive
+description: Hand the whole drive to a model inside the daemon, and get the flows it recorded back, so every run after the first one replays with no model in the loop.
+icon: steering-wheel
+---
+
+Driving an app is the expensive part of verifying one. Every snapshot, every act result and every observation lands in your agent's context and is re-read on every turn after, and none of it is kept: the next run starts from nothing and pays again.
+
+`reticle_verify { action: "explore" }` moves the driving into the daemon. A model there drives your app through the same tool surface your agent uses, records what it drove as saved flows, and hands back a few lines.
+
+```jsonc
+reticle_verify {
+  action: "explore",
+  persona: "a returning customer checking out with a saved card"
+}
+// → { stopReason, steps, savedFlows: ["checkout"], summary, usage }
+```
+
+From the command line, on a project with nothing recorded yet:
+
+```bash
+npx @reticlehq/server verify http://localhost:3000 --persona "an admin revoking a teammate's seat"
+```
+
+## The flows are the point
+
+A drive costs a model. A **saved flow costs nothing to run again**: `reticle_verify { action: "flows" }` replays every one of them deterministically, with no model anywhere in the loop, and re-resolves each step's anchor and asserts its recorded consequence.
+
+So the drive is a one-off: pay for it once, and the journeys it recorded become the regression suite every later run replays. That is why the harness is told to record as it goes, and why a drive that saved nothing is reported as having proved nothing, however long it ran.
+
+## It replays before it drives
+
+A drive reads `.reticle` first: every saved flow with the consequence that must still hold, and every signal and testid your app declares that no flow has ever asserted. It builds a plan from that before it opens its eyes on a page.
+
+Anything already recorded is **replayed**, deterministically, with no model call at all. Only the gaps are driven. So a second run over the same app is mostly free, and the model budget is spent on the part nobody has proved yet rather than on rediscovering what is already on disk. A replay that goes red is reported as a regression; one that DRIFTS is reported separately, because the app moved under the recording and that needs re-anchoring rather than a code change.
+
+Every journey a drive walks is saved, whatever happens to the drive, including one that broke, ran out of budget, or whose model simply stopped asking for tools.
+
+## What it needs
+
+**A model in the daemon's environment.** Any one of three, and the choice is reported back so a comparison can never mislabel its own arms:
+
+| Variable | Driver |
+| --- | --- |
+| `RETICLE_API_KEY` | `jev`, against the platform's own proxy, using the key `reticle link` already wrote. No model API key of your own, and the cheap path: it answers typed questions about the page rather than generating tool calls as text. |
+| `ANTHROPIC_API_KEY` | `anthropic`, which generates its calls as text. |
+| `OPENAI_API_KEY` | `openai`, the same, on OpenAI. |
+| `JEV_API_KEY` | `jev`, against TypeSafe directly, for anyone who holds their own key. |
+
+With several configured, `anthropic` is the default and `RETICLE_HARNESS_DRIVER` moves off it; with only a platform key, `jev` is not the cheaper option, it is the only one. Naming a driver that is not configured is an error, never a silent substitution.
+
+A driver can also be chosen per call, as `reticle_verify { action: "explore", driver: "jev" }`. The question people actually have is comparative, and answering it with an environment variable means restarting the daemon between arms.
+
+Three other dials, all optional:
+
+| Variable | What it does |
+| --- | --- |
+| `RETICLE_HARNESS_MODEL` | The Anthropic model that drives. Defaults to a mid-tier one on purpose, for the reason below. |
+| `RETICLE_HARNESS_MAX_STEPS` | Ceiling on model turns in one drive. Bounds cost, not value. |
+| `RETICLE_HARNESS_BASE_URL` | A proxy or gateway instead of the default API host. |
+
+## Two models, and what each one is for
+
+The `jev` driver decides; it cannot write. Every choice a drive makes is a selection from candidates Reticle enumerated off the page: which element, which tool, what consequence to claim. That is why it costs a fraction of a generating model and answers in a few hundred milliseconds.
+
+One thing in a drive is not a selection. A text field is a composition: "a business name", "a statement descriptor", "a search term that returns results" cannot be enumerated from the page. Where the field's label is enough to guess, a small table answers it. Where it is not, and a generating model is configured, that model writes the value, and nothing else.
+
+Typing is a small minority of what a drive does: clicks and navigations are the overwhelming majority. So this is escalation rather than a second model in the loop, and a drive with no text fields never calls it at all.
+
+What it writes is a FIXTURE, not an opinion. Generated values are saved to `.reticle/fill-values.json` and reused forever: the second drive pays nothing, a replay sends exactly what the recording sent, and a value you dislike is a line in a git-checked file you can edit rather than an argument with a model.
+
+## Turning it off, and who pays for it
+
+A project linked to a Reticle workspace reads two things from it before a drive starts, and honours both:
+
+- **The switch.** Autonomous driving can be turned off per project in the dashboard, under Settings → Verification model. A drive then refuses and says where to turn it back on. Everything else is unaffected, including the tools your own agent drives with.
+- **Who is paying.** Driving through the platform spends Reticle's model budget, which is free for three months once claimed and included on a paid plan. Outside both, a drive is refused with the claim link rather than run on somebody else's money.
+
+Neither applies to a drive on a model key of your own: that costs us nothing, so it is not ours to gate. A daemon that cannot reach the platform at all drives normally: an unreachable settings endpoint is not a reason to lose a feature you were never told to stop using.
+
+## What it will not do
+
+**It does not decide whether your app is correct.** The model chooses what to _try_; the engine decides what _happened_, from what it recorded. A model that graded its own driving would be scoring its own homework, and its verdict would be unfalsifiable. So the summary it writes is an account of what it drove, and nothing downstream grades from it.
+
+That split is also why the default model is not the largest one available. The harness is exploring an interface and stating expectations, not reasoning about your business logic. If finding defects needed a frontier model _there_, the engine would not be doing its job.
+
+**It really clicks.** A drive navigates, submits forms and mutates state, exactly like the crawl does. Point it at a preview or a dev environment, not production.
+
+**It is never automatic.** `reticle verify` will not drive your app unless you ask with `--explore` or `--persona`, and it never drives a project that already has saved flows. Replaying those is the cheap path, and spending a model budget to re-discover what is already recorded would be the wrong trade.
+
+## Give it a persona
+
+A drive with no focus clicks around. A drive with a persona completes a journey, and a journey is what turns into a flow worth replaying:
+
+- `"a first-time user signing up and inviting a teammate"`
+- `"an admin revoking a seat, then checking the seat count"`
+- `"a returning customer applying an expired discount code"`
+
+Name the outcome, not the buttons. What breaks in real products is a chain: sign up, verify, invite, join. A chain fails at whichever link nobody walked.

package/docs/benchmarks.md

@@ -71,7 +71,7 @@ Why not compare to traditional test frameworks (Playwright the library, Cypress,
 
 There **is** a comparison against a Playwright script, and it answers a different question: not "what does it cost an agent to look" but "what can each tool structurally SEE, at all." That one is in Part 5a. It runs no model, so nothing about it depends on how well an agent drives, which is what makes it the more durable of the two results.
 
-Tool versions are pinned in `bench/raw/run-meta.json` so any run is reproducible.
+Tool versions are recorded by hand in `bench/README.md`, not generated: the file that used to pin them is no longer produced. Treat that table as the expiry date on every cross-tool number here, and re-derive before quoting rather than assuming a run from months ago still describes today's tools.
 
 ---
 

package/docs/best-practices.mdx

@@ -23,7 +23,7 @@ Not this:
 
 ...followed by looking around for something that seems fine.
 
-An agent that acts first and then decides what counts as success will always find something that counts. Stating the expectation up front is the entire difference between a check and a rationalisation, and it costs no extra calls: [`reticle_act_and_wait`](/tools-act-and-wait) does both in one hop.
+An agent that acts first and then decides what counts as success will always find something that counts. Stating the expectation up front is the entire difference between a check and a rationalisation, and it costs no extra calls: [`reticle_act_and_wait`](/tools/act-and-wait) does both in one hop.
 
 ## A drive that ends on `reticle_act` proved nothing
 
@@ -49,7 +49,7 @@ We hit one writing the instrumentation page: a login that genuinely succeeded, s
 { "verified": "unknown", "verifiedReason": "unsettled", "verdict": { "pass": true } }
 ```
 
-Report it as unknown. If you believe it is wrong, [say so](/tools-session-and-feedback). Reticle calls an unknown verdict its own defect, and the response literally invites the report.
+Report it as unknown. If you believe it is wrong, [say so](/tools/session-and-feedback). Reticle calls an unknown verdict its own defect, and the response literally invites the report.
 
 ## Focus the tab
 
@@ -196,7 +196,7 @@ Sessions accumulate. Four stale ones pointing at dev servers you restarted an ho
 
 ## Confirm a navigation landed
 
-`reticle_navigate` returns `confirmed: false` by design. A navigation destroys the document the SDK lives in, so it can only report dispatch. Check [`reticle_sessions`](/tools-sessions) for a session at the new URL before acting, and re-snapshot: refs do not survive a new document.
+`reticle_navigate` returns `confirmed: false` by design. A navigation destroys the document the SDK lives in, so it can only report dispatch. Check [`reticle_sessions`](/tools/sessions) for a session at the new URL before acting, and re-snapshot: refs do not survive a new document.
 
 ## Start with what the app says about itself
 

package/docs/capabilities.mdx

@@ -4,7 +4,7 @@ description: Coverage, storage, fake clocks, autonomous crawling, visual diffing
 icon: sparkles
 ---
 
-These are the Reticle tools that do something other than look, act, observe and assert: control coverage, client storage, a fake clock, autonomous crawling, semantic and visual baselines, network mocking, flow recording and replay, and the CI artifact. Reach for them when the verify loop is not the shape of the question. None of them live in the default advertised surface, so all of them are called through [`reticle_run`](/tools-tools-and-run).
+These are the Reticle tools that do something other than look, act, observe and assert: control coverage, client storage, a fake clock, autonomous crawling, semantic and visual baselines, network mocking, flow recording and replay, and the CI artifact. Reach for them when the verify loop is not the shape of the question. They are **not advertised on the default tool surface, but they are reachable from it**: `reticle_run({ tool, args })` dispatches to any registered tool by name, advertised or not, which is the spelling used on this page. To have them advertised outright instead, with their output schemas, start the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read once at startup, so restart it) and call them by name.
 
 Most of the time you want the verify loop. Look, act, observe, assert. These are the tools for the times you want something else, and they are the ones people are most surprised exist.
 
@@ -55,7 +55,7 @@ Useful at the end of a drive, when the agent is about to report success. "I veri
 }
 ```
 
-Note the token redaction. Credential-shaped values are stripped here exactly as they are in [`reticle_network`](/tools-network), so reading storage never puts a session token in your context.
+Note the token redaction. Credential-shaped values are stripped here exactly as they are in [`reticle_network`](/tools/network), so reading storage never puts a session token in your context.
 
 localStorage, sessionStorage and readable cookies.
 
@@ -358,7 +358,7 @@ Stopping a recording used to return a very large payload, almost all of it the r
 }
 ```
 
-Each step's `args` is elided above because a recorded step is an anchor, not a call you make by hand: it resolves a testid at replay time rather than a `ref`, so copying it into [`reticle_act`](/tools-act) would not work.
+Each step's `args` is elided above because a recorded step is an anchor, not a call you make by hand: it resolves a testid at replay time rather than a `ref`, so copying it into [`reticle_act`](/tools/act) would not work.
 
 Nine hundred and fifty-three bytes for 445 recorded events. `timeline_omitted` hands you the exact `reticle_observe` call to make if you want them, so nothing is lost, it is only not charged for by default.
 
@@ -419,7 +419,7 @@ A replay against a drifted app names what moved and where. This is `reticle_veri
 
 Passing flows are counted, not described. Only failures carry detail, because the detail is the actionable part. `flaky` lists flows seen to both pass and fail on unchanged code, which is a bug in the flow rather than in the app.
 
-`reticle_flow_heal` proposes the rebind. It refuses when it is not confident:
+`reticle_verify { action: "heal" }` proposes the rebind. It refuses when it is not confident:
 
 ```json
 {

package/docs/cli/cloud.mdx

@@ -10,7 +10,7 @@ Ten subcommands bind this repository to Reticle Cloud so runs and flows land on
 npx @reticlehq/server <login|logout|whoami|link|project|config|push|runs|regression|share>
 ```
 
-These are thin clients over the `/v1` API. The moat is the server, not the verbs.
+These are thin clients over the `/v1` API. The logic is server-side; these verbs surface it.
 
 ## Where credentials live
 
@@ -20,7 +20,7 @@ These are thin clients over the `/v1` API. The moat is the server, not the verbs
 | `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes |
 | `<repo>/.reticle/cloud.json` | `{ projectId, projectName, url, sync, verify }`. The non-secret binding | No, commit it |
 
-Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`. When a command falls back to that default without `RETICLE_CLOUD_URL` (or a saved session URL), it prints a one-line notice on stderr; stdout stays pure JSON for agents.
+Auth for any command is `RETICLE_API_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`. When a command falls back to that default without `RETICLE_CLOUD_URL` (or a saved session URL), it prints a one-line notice on stderr; stdout stays pure JSON for agents.
 
 ## The commands
 
@@ -70,7 +70,7 @@ An unattached repo also gets a next-step nudge on stderr, telling you to run `re
 npx @reticlehq/server link [--project <name|id>]
 ```
 
-Binds this repository to a cloud project. With a login token it **mints** a project-scoped key, so there is nothing to paste. With `RETICLE_CLOUD_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name; omitted, it uses the `default` project. Writes `cloud.json` and the key.
+Binds this repository to a cloud project. With a login token it **mints** a project-scoped key, so there is nothing to paste. With `RETICLE_API_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name; omitted, it uses the `default` project. Writes `cloud.json` and the key.
 
 ### `reticle project`
 
@@ -137,7 +137,7 @@ reticle: cloud not attached here ... run `reticle link` (or set RETICLE_CLOUD_UR
 | ---- | ----------------------------------------------------------------------------------- |
 | `0`  | Success                                                                             |
 | `1`  | The API call failed, or the repository is not attached where attachment is required |
-| `2`  | Usage error, or not signed in and no `RETICLE_CLOUD_KEY`                            |
+| `2`  | Usage error, or not signed in and no `RETICLE_API_KEY`                              |
 | `3`  | `regression` only: at least one flow broke                                          |
 
 Output is pretty-printed JSON on stdout. Errors and next-step nudges go to stderr, so an agent parsing stdout is unaffected.

package/docs/cli/doctor.mdx

@@ -52,6 +52,7 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | `daemon` | Whether the port holds a Reticle daemon, a foreign process (named where possible), or nothing. Adds a `version` line when the daemon's version or contract fingerprint disagrees with the CLI's |
 | `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
 | `agent link` | Whether an MCP client has listed Reticle's tools on this port **and actually called one**. Every other row here checks a component; this one checks the hop between your agent and the daemon. It is possible for the SDK to be injected, a session to be live, and your client to show every tool enabled, while no request has ever crossed from the agent. That state passes every other check and is the one people lose hours to |
+| `loopback` | Which of `localhost`'s two answers reaches the bridge. Printed **only when they disagree**. The daemon binds `127.0.0.1`, and a best-effort alias forwards `[::1]` to it so the name works everywhere. When that alias cannot open (IPv6 disabled, or something already holding `[::1]` on the port) the daemon serves IPv4 perfectly and a page told to dial `localhost` still cannot reach it, because Windows Chrome tries the IPv6 answer first. Every other row here goes green in that state |
 | `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
 | `port check` | Only when your project's configured port disagrees with the one the daemon is on. Prints the mismatch rather than leaving you to spot it across two lines |
 | `sibling` | Only when a well-known Reticle port other than this daemon's has a listener. An observation, not a diagnosis: that listener may or may not be related |

package/docs/cli/feedback.mdx

@@ -61,7 +61,7 @@ npx @reticlehq/server feedback --agent --kind gap \
 <Card
   title="The same channel from inside a session"
   icon="comments"
-  href="/tools-session-and-feedback"
+  href="/tools/session-and-feedback"
 >
   `reticle_feedback` when the tools are reachable.
 </Card>

package/docs/cli/init.mdx

@@ -77,8 +77,8 @@ Run from a workspace root with several apps, it refuses to guess, names them, an
 
 ```
 Several apps found in this workspace. Re-run `reticle init` inside the one you want:
-  packages/next
-  packages/vite-plugin
+  adapters/build/next
+  adapters/build/vite
   apps/atlas
   apps/bench-app
   apps/electron-smoke
@@ -87,7 +87,7 @@ Several apps found in this workspace. Re-run `reticle init` inside the one you w
   apps/tauri-smoke
   apps/vibe-builder-demo
 
-Or name one without changing directory:  reticle init --app packages/next
+Or name one without changing directory:  reticle init --app apps/next-smoke
 ```
 
 Given `--app`, it says which directory it moved to before printing the plan:

package/docs/cli/mcp.mdx

@@ -58,6 +58,6 @@ Runs for the life of an active editor session. A fully quiet, abandoned link exi
 }
 ```
 
-<Card title="The tools this exposes" icon="screwdriver-wrench" href="/tools-overview">
+<Card title="The tools this exposes" icon="screwdriver-wrench" href="/tools/overview">
   The full surface your agent gets once this is registered.
 </Card>

package/docs/cli/status.mdx

@@ -7,7 +7,7 @@ icon: heart-pulse
 `reticle status` is the command that tells you whether the install actually finished. Not a tick in a checklist: a connected app.
 
 ```bash
-npx @reticlehq/server status [--port N]
+npx @reticlehq/server status [--port N] [--json]
 ```
 
 ## Flags
@@ -15,10 +15,37 @@ npx @reticlehq/server status [--port N]
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which daemon to ask |
+| `--json` | flag | off | Print the machine-readable event instead of the block below |
 
 ## What it prints
 
-One JSON line on stdout. Real capture, daemon up and no app connected:
+A short block, for whoever is reading the terminal. Real capture, daemon up with two apps connected:
+
+```text
+reticle status
+  daemon       ✓ running on :4400 (pid 90790)
+  sessions     ✓ 2 pages connected
+               http://localhost:5173/  (throttled, hidden)
+               http://localhost:7699/  (throttled, hidden)
+  agent link   enumerated
+```
+
+And with no daemon on the port:
+
+```text
+reticle status
+  daemon       ✗ not running on :4999
+  agent link   never-attached
+  next         no daemon is running on this port, which is normal. An agent starts it when it
+               first calls a Reticle tool, and it exits again when idle. Ask your agent to verify
+               something, then run status again.
+```
+
+A session's parenthesised notes are the ones that explain an answer you would otherwise call a bug: `throttled` and `hidden` mean a background tab answering slowly, `stale` means the page has moved on from what the daemon last saw, and `unresponsive` means it is not answering at all.
+
+### `--json`
+
+The same facts as one event line on stderr, for a caller that parses rather than reads:
 
 ```json
 {
@@ -33,30 +60,18 @@ One JSON line on stdout. Real capture, daemon up and no app connected:
 }
 ```
 
-With an app connected, `why` is absent and each session carries its own fields:
+It is one line in the terminal, pretty-printed here, with `why` trimmed at the ellipses. With an app connected `why` is absent and each session carries its own fields:
 
 ```json
 {
-  "t": "2026-08-15T18:45:58.190Z",
-  "event": "reticle_status",
-  "port": 4400,
-  "running": true,
-  "pid": 72698,
-  "sessionCount": 1,
-  "sessions": [
-    {
-      "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
-      "url": "http://localhost:4310/",
-      "throttled": false,
-      "stale": false,
-      "pendingMarks": 0
-    }
-  ]
+  "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
+  "url": "http://localhost:4310/",
+  "throttled": false,
+  "stale": false,
+  "pendingMarks": 0
 }
 ```
 
-Both are one line of JSON in the terminal, pretty-printed here, with `why` trimmed at the ellipses.
-
 | Field | Meaning |
 | --- | --- |
 | `running` | Whether a usable daemon owns the port |

package/docs/cli/watch.mdx

@@ -34,7 +34,7 @@ Real capture, the first two lines of a run in this repository:
 A save then produces a `reticle_watch_affected` line naming the changed files and the flows they put at risk, followed by a refreshed buddy line. Real capture, with both lists trimmed:
 
 ```json
-{"t":"2026-08-15T18:44:09.317Z","event":"reticle_watch_affected","changed":["packages/init/src/mcp-clients.ts"],"affected":["WEB-flow","deploy-journey","verify-route"]}
+{"t":"2026-08-15T18:44:09.317Z","event":"reticle_watch_affected","changed":["init/src/mcp-clients.ts"],"affected":["WEB-flow","deploy-journey","verify-route"]}
 {"t":"2026-08-15T18:44:09.355Z","event":"reticle_buddy","status":"✗ 39 deviations: ELECTRON-1LINE-flow, ELECTRON-COLD-flow +37 more · 0 nominal · 9 flaky quarantined"}
 ```
 

package/docs/cli.mdx

@@ -32,15 +32,15 @@ npx @reticlehq/server <command>
 
 ### `reticle init`
 
-Wires Reticle into the project in the current directory, then boots the app, proves a session connected and drives one flow to a verdict. It exits non-zero if no verdict was produced, and prints what is left to do.
+Wires Reticle into the project in the current directory, then boots the app and proves a session connected. It exits non-zero if nothing connected, and prints what is left to do. It does not drive: proving a flow is the FIRST RUN, `reticle verify <url> --explore --persona "<who does what>"`.
 
 ```
-reticle init  [--flow "<what to drive>"] [--env KEY=VALUE]... [--app <dir>] [--license <key>]
-              [--json] [--files-only] [--no-open] [--no-drive] [--dry-run]
-              [--port N] [--no-mcp] [--no-install] [--timeout S] [--drive-model M]
+reticle init  [--env KEY=VALUE]... [--app <dir>] [--license <key>]
+              [--json] [--files-only] [--no-open] [--dry-run]
+              [--port N] [--no-mcp] [--no-install] [--timeout S]
 ```
 
-`--flow`, `--env` and `--app` are the answers the command cannot work out for itself: which journey proves what you care about, what the app needs to reach a usable state, and which app in a monorepo. `--files-only` is what `init` did before it learned to boot the app: it still registers the MCP server and pre-approves Reticle's tools, so it doubles as the upgrade path for an existing install.
+`--env` and `--app` are the answers the command cannot work out for itself: what the app needs to reach a usable state, and which app in a monorepo. Which journey proves what you care about is asked on the first run, as `--persona`. `--files-only` is what `init` did before it learned to boot the app: it still registers the MCP server and pre-approves Reticle's tools, so it doubles as the upgrade path for an existing install.
 
 <Card title="Full walkthrough with real output" icon="wand-magic-sparkles" href="/install-agentic">
   What it writes, and how to read its four status marks.
@@ -71,26 +71,16 @@ Exits `0`. That parenthetical about the bridge port is doing a lot of work. Mixi
 
 Whether the daemon is up and which apps have connected.
 
-```json
-{
-  "t": "2026-08-15T18:45:58.190Z",
-  "event": "reticle_status",
-  "port": 4400,
-  "running": true,
-  "pid": 72698,
-  "sessionCount": 1,
-  "sessions": [
-    {
-      "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
-      "url": "http://localhost:4310/",
-      "throttled": false,
-      "stale": false,
-      "pendingMarks": 0
-    }
-  ]
-}
+```text
+reticle status
+  daemon       ✓ running on :4400 (pid 90790)
+  sessions     ✓ 1 page connected
+               http://localhost:4310/
+  agent link   enumerated
 ```
 
+Add `--json` for the same facts as one machine-readable event line. See [`reticle status`](/cli/status) for the fields.
+
 Exits `0`. A session in the list is the install genuinely finished. Not a tick in a checklist, a connected app.
 
 ### `reticle telemetry [status|enable|disable]`
@@ -153,7 +143,7 @@ npx @reticlehq/server affected --since HEAD~1
 {
   "t": "2026-08-15T18:42:57.431Z",
   "event": "reticle_affected",
-  "changedFiles": ["SKILL.md", "docs/cli/doctor.mdx", "packages/init/src/agent-rules.ts"],
+  "changedFiles": ["SKILL.md", "docs/cli/doctor.mdx", "init/src/agent-rules.ts"],
   "affected": ["WEB-flow", "deploy-journey", "verify-modal", "verify-route"],
   "unknownProvenance": ["WEB-flow", "deploy-journey", "verify-modal", "verify-route"]
 }
@@ -230,7 +220,7 @@ npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request
 
 The `--agent` form matters more than it looks: the setup that failed halfway is exactly the setup worth hearing about, and in that state the MCP tools do not exist yet.
 
-<Card title="How feedback is handled" icon="comments" href="/tools-session-and-feedback">
+<Card title="How feedback is handled" icon="comments" href="/tools/session-and-feedback">
   What each kind means, and what happens when a report cannot be delivered.
 </Card>
 

package/docs/desktop.mdx

@@ -214,7 +214,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "2.14"
+reticle-tauri = "3.2"
 ```
 
 ```rust

package/docs/enterprise.md

@@ -67,8 +67,9 @@ The honest one-pager a security review needs. Reticle is built so the answer to
 
 | Scope | License | Why |
 | --- | --- | --- |
-| Embeddable SDK (`browser`, `protocol`, `react`, `babel-plugin`, `next`, `vite-plugin`, `eslint-plugin`) | **Apache-2.0** | safe to ship inside your customers' apps; explicit patent grant |
+| The protocol and the rules (`open-verification`, `core`, `engine`) | **Apache-2.0** | the part that DECIDES a verdict, auditable and reimplementable by anyone |
+| Embeddable SDK (`browser`, `react`, `babel-plugin`, `next`, `vite-plugin`, `electron`, `eslint-plugin`) | **Apache-2.0** | safe to ship inside your customers' apps; explicit patent grant |
 | Server / CLI / MCP (`server`, `test`, umbrella) | **FSL-1.1-ALv2** | free for any use except reselling Reticle itself; converts to Apache after 2 years |
-| Enterprise features (`packages/server/src/ee/`) | **Reticle Enterprise License** | source-available; free for dev/eval, license key required in production |
+| Enterprise features (`server/src/features/ee/`) | **Reticle Enterprise License** | source-available; free for dev/eval, license key required in production |
 
 Embedding / OEM / enterprise: **[hey@reticle.sh](mailto:hey@reticle.sh)**.

package/docs/faq.mdx

@@ -38,7 +38,7 @@ Support beyond that is uneven, and we would rather say so than let you find out:
 <Accordion title="Can it tell me whether my UI looks good?">
   No. Reticle verifies behaviour, not aesthetics. Visual correctness and "does this feel right" remain a human job, or a visual-diff tool's.
 
-It does read design tokens. [`reticle_inspect`](/tools-inspect) reports whether a colour came from your theme or from someone's clipboard. But that is a consistency check, not taste.
+It does read design tokens. [`reticle_inspect`](/tools/inspect) reports whether a colour came from your theme or from someone's clipboard. But that is a consistency check, not taste.
 
 </Accordion>
 
@@ -58,7 +58,7 @@ Measured on the same app: Reticle caught 10 of 10 injected bugs, Playwright MCP
 </Accordion>
 
 <Accordion title="Can I run several apps or tabs at once?">
-  Yes. Each is a session. Pass `sessionId` to any tool when more than one is connected, and [`reticle_sessions`](/tools-sessions) lists them.
+  Yes. Each is a session. Pass `sessionId` to any tool when more than one is connected, and [`reticle_sessions`](/tools/sessions) lists them.
 
 Reticle scopes to your project and prefers the active tab, and it **refuses rather than guesses** when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab.
 
@@ -102,9 +102,9 @@ What is measured is detection: 10 of 10 injected regressions caught, with zero f
 <Accordion title="Why does my agent only see some of Reticle's tools?">
   Because MCP re-sends every advertised tool definition on **every turn**, so the tool list is rent, not a one-time cost. Reticle advertises the verify loop directly and keeps the cold tail one call away.
 
-Nothing is unreachable. `reticle_tools` lists every tool (pass `names: [...]` for full parameters) and `reticle_run({ tool, args })` invokes any of them by name. If you want the whole surface advertised directly, set `RETICLE_ADVERTISE_ALL_TOOLS=1` in the **daemon's** environment and restart it, which costs roughly seven times the per-turn schema tax and is meant for suites that call by name rather than for running agents.
+`reticle_tools` lists every registered tool (pass `names: [...]` for full parameters), and `reticle_run { tool, args }` calls any of them by name, whether or not it is advertised. That hatch is what makes a trimmed surface honest: a tool it does not show is one hop away rather than out of reach. If you want the whole surface advertised directly, set `RETICLE_ADVERTISE_ALL_TOOLS=1` in the **daemon's** environment and restart it, which costs roughly seven times the per-turn schema tax and is meant for suites that call by name rather than for running agents.
 
-  <Card title="The surface, explained" icon="wrench" href="/tools-overview">
+  <Card title="The surface, explained" icon="wrench" href="/tools/overview">
     Which tools are advertised directly, and why each earned its slot.
   </Card>
 </Accordion>

package/docs/first-drive.md

@@ -21,7 +21,7 @@ pnpm install
 pnpm build       # required: the specs and the CLI run from dist/, not src/
 ```
 
-`pnpm build` is not optional. Several things below load `packages/server/dist`, and a stale or absent `dist` produces errors that read as code faults rather than as a missing build.
+`pnpm build` is not optional. Several things below load `server/dist`, and a stale or absent `dist` produces errors that read as code faults rather than as a missing build.
 
 ## 1. Boot something to look at
 
@@ -57,7 +57,7 @@ node -e "require('playwright').chromium.launch({headless:true})
 Then ask for a verdict:
 
 ```bash
-node packages/server/dist/cli.js verify "" --port 4400 \
+node server/dist/command/cli.js verify "" --port 4400 \
   --expect '{"kind":"text","contains":"Reticle"}'
 ```
 
@@ -72,7 +72,7 @@ That is the whole product in one line: a claim, checked against a running page,
 Try making it fail, because a tool that only ever says yes is not telling you anything:
 
 ```bash
-node packages/server/dist/cli.js verify "" --port 4400 \
+node server/dist/command/cli.js verify "" --port 4400 \
   --expect '{"kind":"text","contains":"definitely not on this page"}'
 ```
 
@@ -110,9 +110,9 @@ node -e "import('./apps/e2e/gate-harness.mjs').then(m=>m.freePortSafely(4400,{on
 
 **The bench app shows a login first, and views are reached from the nav.** A query parameter does not select a view. Log in, click the nav item, then drive.
 
-**Fixtures are in a second repo.** The apps in `apps/` are all already instrumented, so none of them can tell you whether a fresh install still works. That question lives in [`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures), which keeps a pristine `clean` branch of real third-party apps plus `main` and `reticle/<version>`. See [`fixtures.md`](fixtures.md).
+**Fixtures are in a second repo.** The apps in `apps/` are all already instrumented, so none of them can tell you whether a fresh install still works. That question lives in [`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures), which keeps a pristine `clean` branch of real third-party apps plus `main` and `reticle/<version>`. See [`fixtures.md`](https://github.com/reticlehq/reticle/blob/main/docs/fixtures.md).
 
-**Telemetry fails silently.** Nothing throws, no test reddens, the data is just permanently gone. Read [`telemetry-contract.md`](telemetry-contract.md) before touching anything that emits.
+**Telemetry fails silently.** Nothing throws, no test reddens, the data is just permanently gone. Read [`telemetry-contract.md`](https://github.com/reticlehq/reticle/blob/main/docs/telemetry-contract.md) before touching anything that emits.
 
 **`core` is the contract and may not gain dependencies.** Anything crossing browser ↔ bridge ↔ agent is defined there as a constant plus a zod schema. Never inline a wire string elsewhere.
 

package/docs/flows.md

@@ -4,7 +4,7 @@ description: 'Record an interactive run once and replay it forever as a git-chec
 icon: repeat
 ---
 
-A **flow** is a recorded interactive run that Reticle stores as JSON under `.reticle/flows/` and replays forever with no AI model in the loop. Steps are anchored on **meaning** (a testid, a signal, or an auto-derived component + source location), never on a `eXX` ref or a coordinate, so they survive refactors; when an anchor does drift, `reticle_flow_replay` names what changed and `reticle_flow_heal` can rebind it.
+A **flow** is a recorded interactive run that Reticle stores as JSON under `.reticle/flows/` and replays forever with no AI model in the loop. Steps are anchored on **meaning** (a testid, a signal, or an auto-derived component + source location), never on a `eXX` ref or a coordinate, so they survive refactors; when an anchor does drift, `reticle_flow_replay` names what changed and `reticle_verify { action: "heal" }` can rebind it.
 
 Reticle turns an interactive run into a **git-checked, replayable program** stored under `.reticle/`. Flows are anchored on **meaning** (testid + signal), not volatile element refs or coordinates, so they survive refactors, and when an anchor does drift, Reticle tells you _why_ and can repair it. This is what makes Reticle "the project's living test suite a human seeds and an agent maintains."
 
@@ -129,14 +129,14 @@ Passing flows are counted; only failures carry detail (token-cheap). Build → `
 
 ## Self-healing: the agent maintains the flow
 
-When a testid is renamed, the flow drifts. `reticle_flow_heal` proposes (and optionally applies) the nearest-match rebind, so flows don't rot:
+When a testid is renamed, the flow drifts. `reticle_verify { action: "heal" }` proposes (and optionally applies) the nearest-match rebind, so flows don't rot:
 
 ```jsonc
-reticle_flow_heal({ flowName: "create-task" })               // PROPOSE only, never writes
+reticle_verify({ action: "heal", flowName: "create-task" })               // PROPOSE only, never writes
 // → { status: "drift", applied: false,
 //     proposals: [{ step: 0, from: "add-tassk", to: "add-task", confidence: 0.8 }] }
 
-reticle_flow_heal({ flowName: "create-task", apply: true })  // rewrite the anchor on disk
+reticle_verify({ action: "heal", flowName: "create-task", apply: true })  // rewrite the anchor on disk
 // → { status: "healed", applied: true, proposals: [...] }
 ```
 
@@ -166,7 +166,7 @@ With `apply: false` the flow file is **never modified**; you get the proposed di
 | `reticle_flow {action:"load"}` | `{ flowName }` | the flow JSON |
 | `reticle_flow_replay` | `{ flowName }` | `{ status, steps, decision? }` (decision on drift/fail) |
 | `reticle_verify {action:"flows"}` | `{ names?, sessionId? }` | suite verdict `{ status, passed, failed, failures[] }` |
-| `reticle_flow_heal` | `{ flowName, apply? }` | propose / apply nearest-match rebind |
+| `reticle_verify { action: "heal" }` | `{ flowName, apply? }` | propose / apply nearest-match rebind |
 | `reticle_annotate` | `{ kind, … }` | compile a structured annotation into the flow |
 
 > Flow `name` must be a single safe path segment (no `/`, `\`, `..`, or leading dot).

package/docs/for-agents.md

@@ -67,5 +67,6 @@ You rarely need more than one.
 | Look up a specific tool, flag, or workflow | [Complete usage guide](/usage) |
 | Understand what Reticle is doing under the hood | [Architecture](/architecture) |
 | Wire it into a desktop app | [Desktop apps](/desktop) |
-| Make the checks repeatable in CI | [Specs for CI](/testing) |
+| Write my own checks in code, no agent involved | [Write verification in code](/testing) |
+| Make the checks repeatable in CI | [Write verification in code](/testing) |
 | Work on Reticle itself | [Gates](/gates), then [System map](/system-map) |

package/docs/frameworks.mdx

@@ -255,6 +255,6 @@ Angular and Solid appear in dependency detection but have no wiring, no adapter
   </Accordion>
 </AccordionGroup>
 
-<Card title="Something missing?" icon="comments" href="/tools-session-and-feedback">
+<Card title="Something missing?" icon="comments" href="/tools/session-and-feedback">
   A framework you need is a `gap` report. It is the signal that decides what gets built.
 </Card>