@reticlehq/server 2.8.0 → 2.10.0

package/docs/best-practices.mdx

@@ -1,10 +1,12 @@
 ---
-title: Best practices: how to earn a green
+title: 'Best practices: how to earn a green'
 sidebarTitle: Best practices
 description: The habits that make a verdict worth trusting, and the specific mistakes that produce a confident, wrong pass.
 icon: star
 ---
 
+A green is worth trusting when you named the consequence **before** you acted, ended the run on `reticle_act_and_wait` or `reticle_assert` (nothing else produces a verdict), scoped the assertion with `since`, and read `verified` rather than `pass`. Everything below is one of those habits, or the specific mistake that breaks it.
+
 Everything here comes from driving Reticle against real apps and getting it wrong first. None of it is theoretical, and several entries exist because they bit us while writing these docs.
 
 ## Name the consequence before you act
@@ -87,11 +89,14 @@ Every `act` response returns a `since`. Use it.
 
 Every verdict reports `honesty.grade`. Aim for `signal`.
 
-| Grade      | What it means                | How much it proves       |
-| ---------- | ---------------------------- | ------------------------ |
-| `presence` | Something appeared           | A mock does this too     |
-| `state`    | A registered store changed   | The app accepted it      |
-| `signal`   | The app fired a named signal | The app declared success |
+| Grade      | What it means                 | How much it proves          |
+| ---------- | ----------------------------- | --------------------------- |
+| `presence` | Something appeared            | A mock does this too        |
+| `state`    | A registered store changed    | The app accepted it         |
+| `net`      | A request fired and came back | The app talked to the world |
+| `signal`   | The app fired a named signal  | The app declared success    |
+
+Ranked weakest to strongest, that is `presence` < `state` < `net` < `signal`. A predicate with no consequence at all grades `none`.
 
 Getting from `presence` to `signal` is roughly ten minutes of [instrumentation](/instrumentation) per flow, and it is the highest-leverage work available.
 

package/docs/capabilities.mdx

@@ -4,9 +4,9 @@ description: Coverage, storage, fake clocks, autonomous crawling, visual diffing
 icon: sparkles
 ---
 
-Most of the time you want the verify loop. Look, act, observe, assert.
+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 tools for the times you want something else, and they are the ones people are most surprised exist. All of them live in the cold tail, reachable through [`reticle_run`](/tools-tools-and-run).
+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.
 
 ## Available anywhere
 
@@ -15,21 +15,24 @@ These work through the always-on SDK, in any connected session.
 ### Coverage: what you have not driven yet
 
 ```json
-{ "tool": "reticle_coverage" }
+{ "tool": "reticle_verify", "args": { "action": "coverage" } }
 ```
 
 ```json
 {
-  "total": 3,
-  "exercised": 0,
+  "total": 43,
+  "exercised": 2,
   "untouched": [
-    { "ref": "e3", "label": "textbox \"Email\"" },
-    { "ref": "e4", "label": "textbox \"Password\"" },
-    { "ref": "e5", "label": "button \"Sign in\"" }
+    { "ref": "e619", "label": "button \"Overview\"" },
+    { "ref": "e627", "label": "button \"Compose\"" },
+    { "ref": "e632", "label": "textbox \"Filter by service…\"" },
+    { "ref": "e635", "label": "button \"Row actions\"" }
   ]
 }
 ```
 
+That is a real capture with 39 of the 41 untouched entries trimmed out. Two controls driven out of forty-three.
+
 Not code coverage. Control coverage: which interactive elements this session has actually touched.
 
 Useful at the end of a drive, when the agent is about to report success. "I verified the page" reads differently next to `exercised: 0`.
@@ -42,12 +45,18 @@ Useful at the end of a drive, when the agent is about to report success. "I veri
 
 ```json
 {
-  "local": {},
-  "session": { "__reticle_ref_base": "100", "__reticle_session": "lease-0cee1313…" },
-  "cookies": {}
+  "local": { "reticle.bench.authToken": "[REDACTED]" },
+  "session": {
+    "__reticle_ref_base": "700",
+    "__reticle_session": "s223e0fad-e012-43f9-a23d-6d585470c90d",
+    "reticle.bench.sessionId": "[REDACTED]"
+  },
+  "cookies": { "bench_session": "724fa5c2-d913-4d19-8a90-3a4d85dc09a0" }
 }
 ```
 
+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.
 
 This is where the "logged in but nothing persisted" bug lives. A login can fire its success signal, mutate state, and write nothing. Reload, and you are back at the login screen.
@@ -72,6 +81,8 @@ This is where the "logged in but nothing persisted" bug lives. A login can fire
 { "tool": "reticle_clock", "args": { "reset": true } }
 ```
 
+`advanceMs` answers `{ "frozen": true }`, because advancing keeps the clock frozen at the new time. `reset` answers `{ "frozen": false }` and hands time back to the browser.
+
 Toasts that auto-dismiss, debounced search, polling, session timeouts, retry backoff. All of these are normally verified by sleeping, which is slow and flaky in equal measure.
 
 Freeze the clock, advance it by exactly the interval, assert the consequence. No sleeping, no guessing, and the same result on a fast laptop and a loaded CI runner.
@@ -79,20 +90,30 @@ Freeze the clock, advance it by exactly the interval, assert the consequence. No
 ### Crawl: click everything, report anomalies
 
 ```json
-{ "tool": "reticle_crawl", "args": { "maxSteps": 6 } }
+{ "tool": "reticle_verify", "args": { "action": "crawl", "maxSteps": 6 } }
 ```
 
 ```json
 {
-  "interactiveFound": 3,
-  "stepsRun": 3,
+  "interactiveFound": 43,
+  "stepsRun": 6,
   "anomalies": [],
   "counts": { "consoleErrors": 0, "failedRequests": 0, "deadControls": 0, "contradictions": 0 },
-  "visited": ["- textbox \"Email\"", "- textbox \"Password\"", "- button \"Sign in\""],
-  "truncated": false
+  "visited": [
+    "- button \"Overview\"",
+    "- button \"Deployments40\"",
+    "- button \"Compose\"",
+    "- button \"Diagnostics\"",
+    "- button \"Hostile\"",
+    "- button \"Search or jump to…⌘K\""
+  ],
+  "truncated": true,
+  "coverageNote": "the page changed as you clicked: 7 control(s) that did not exist when this crawl started were never visited, interactiveFound is a floor, not a total; re-run the crawl from the state you are now in to cover them"
 }
 ```
 
+Read `coverageNote` before you read the counts. `interactiveFound` is measured when the crawl starts, so on any app where clicking reveals new controls it is a floor rather than a total, and the tool says so rather than letting `43` read as complete.
+
 Autonomously clicks every reachable control and reports what went wrong. No script, no plan. The counts are the useful part: `deadControls` and `contradictions` are the two that indicate a real problem rather than a busy page.
 
 This is the tool for an app you did not write and do not understand yet.
@@ -108,7 +129,15 @@ This is the tool for an app you did not write and do not understand yet.
 { "tool": "reticle_reconcile" }
 ```
 
-Compares the data an endpoint returned against what the page actually displays.
+```json
+{
+  "mismatches": [],
+  "compared": 2,
+  "note": "compared 2 response(s); nothing on screen contradicts them"
+}
+```
+
+Compares the data an endpoint returned against what the page actually displays. `compared` is the field that makes the empty `mismatches` meaningful: `compared: 0` would mean it had nothing to check, not that everything agreed.
 
 The bug it catches is specific and common: the API returned ten rows, the table shows nine, and nothing errored. Neither the network log nor the DOM is wrong on its own. Only the comparison is.
 
@@ -134,7 +163,7 @@ The most useful tool nobody knows about.
     ],
     "declaredUntestedTestids": ["deploy-submit", "drawer", "palette", "…"]
   },
-  "summary": "47 flows: 14 asserted, 2 presence-only, 31 assertion-free. 13 declared signal(s) no flow asserts. 33 flow(s) assert no consequence."
+  "summary": "47 flows: 14 asserted, 2 presence-only, 31 assertion-free. test first: asserted-demo2 (last run drifted). 13 declared signal(s) no flow asserts. 33 flow(s) assert no consequence."
 }
 ```
 
@@ -159,7 +188,7 @@ Each flow comes back graded, with the consequence that must hold and a risk leve
 }
 ```
 
-`declaredUntestedSignals` is the other half: signals your app emits that no flow ever checks. It is a to-do list for your test suite, generated from what the app says about itself.
+`declaredUntestedSignals` is the other half: signals your app emits that no flow ever checks. It is a to-do list for your test suite, generated from what the app says about itself. The full response also carries `declared` (the app's registered testids, signals and stores), `riskRanked` (every flow ordered worst first) and `unassertedFlows`.
 
 <Tip>
   Run this before writing a new flow. It tells you what is already covered, what is covered badly,
@@ -171,20 +200,47 @@ Each flow comes back graded, with the consequence that must hold and a risk leve
 
 ```json
 { "tool": "reticle_baseline", "args": { "action": "save", "name": "checkout-empty" } }
+```
+
+```json
+{ "baseline": "checkout-empty", "lineCount": 174 }
+```
+
+```json
 { "tool": "reticle_baseline", "args": { "action": "diff", "name": "checkout-empty" } }
 ```
 
-Records the meaningful state of a page and compares later. Structure and content rather than pixels, so a font change does not fail your check and a missing row does.
+```json
+{
+  "baseline": "checkout-empty",
+  "removed": [],
+  "added": [],
+  "consoleErrors": 0,
+  "routeChanged": false
+}
+```
+
+Records the meaningful state of a page and compares later. Structure and content rather than pixels, so a font change does not fail your check and a missing row does. `action: "list"` returns the saved names.
 
 ## Needs a driven browser
 
 Four tools apply their effects through the Chrome DevTools Protocol. The always-on SDK cannot do that, so they need a browser Reticle is driving.
 
 <Warning>
-**A pooled lease is not enough.** Verified: acquiring one with `reticle_lease` and calling these
-still returns `{ "ok": false, "reason": "no-cdp-provider" }` and `"no-visual-provider"`.
+**A pooled lease is not enough.** Re-verified on 2026-08-16: acquire one with `reticle_lease` and
+`reticle_screenshot` answers
+
+```json
+{
+  "ok": false,
+  "reason": "no-visual-provider",
+  "recommendation": "visual capture needs a driven browser, start with `reticle drive <url>` or set RETICLE_CDP_URL; the always-on SDK does not ship a screenshotter"
+}
+```
+
+while `reticle_network_mock` answers `{ "applied": false, "count": 0, "ok": false, "reason": "no-cdp-provider" }`. Under a driven browser, all four work: the captures below were taken that way.
 
-Point `RETICLE_CDP_URL` at a Chrome started with `--remote-debugging-port`. That is currently the reliable route.
+Run `reticle drive <url>`, or point `RETICLE_CDP_URL` at a Chrome started with `--remote-debugging-port`.
 
 </Warning>
 
@@ -192,16 +248,45 @@ Point `RETICLE_CDP_URL` at a Chrome started with `--remote-debugging-port`. That
 
 ```json
 { "tool": "reticle_screenshot", "args": { "name": "login-baseline" } }
+```
+
+```json
+{
+  "ok": true,
+  "saved": true,
+  "name": "login-baseline",
+  "path": ".reticle/visual/login-baseline.png",
+  "bytes": 191150
+}
+```
+
+```json
 { "tool": "reticle_visual_diff", "args": { "baseline": "login-baseline" } }
 ```
 
+```json
+{
+  "ok": true,
+  "matched": true,
+  "changedPixels": 0,
+  "totalPixels": 921600,
+  "ratio": 0,
+  "dimensionMismatch": false,
+  "baseline": { "width": 1280, "height": 720 },
+  "current": { "width": 1280, "height": 720 },
+  "diffPath": ".reticle/visual/login-baseline.diff.png"
+}
+```
+
+`dimensionMismatch` is the field that saves an afternoon. A diff between two different viewport sizes is meaningless, and this says so rather than reporting a huge `ratio`.
+
 <Warning>
   Note the asymmetry. `reticle_screenshot` names the baseline with **`name`**; `reticle_visual_diff`
   refers to it with **`baseline`**. Passing `name` to the diff is rejected, and it is an easy
   mistake to make twice.
 </Warning>
 
-`fullPage` captures the whole scroll height. `ref` or `clip` scopes to one element or region. `threshold` sets the pixel-difference tolerance, defaulting to `0.01`, and `masks` excludes regions that are expected to change.
+`fullPage` captures the whole scroll height. `ref` or `clip` scopes to one element or region. `threshold` sets the pixel-difference tolerance, defaulting to `0.01`, `maxRatio` caps the acceptable changed fraction, and `masks` excludes regions that are expected to change.
 
 Reticle reads program truth, not pixels, so this is the deliberate exception: a font that failed to load or a compositing glitch is only visible in the actual frame.
 
@@ -211,6 +296,10 @@ Reticle reads program truth, not pixels, so this is the deliberate exception: a
 { "tool": "reticle_viewport", "args": { "width": 1280, "height": 800 } }
 ```
 
+```json
+{ "applied": true, "width": 1280, "height": 800 }
+```
+
 Fixes the viewport so a visual baseline is reproducible across machines. Without it, a diff taken on a laptop and re-run in CI compares two different layouts and fails for a reason nobody wants to debug.
 
 ### Network mocking
@@ -222,7 +311,11 @@ Fixes the viewport so a visual baseline is reproducible across machines. Without
 }
 ```
 
-Return a 500, force offline, or delay a response. First matching rule wins. `clear: true` turns it off.
+```json
+{ "applied": true, "count": 1 }
+```
+
+Return a 500, force offline, or delay a response. First matching rule wins. `clear: true` turns it off and answers `{ "applied": true, "count": 0 }`.
 
 Most error states have never actually run. This is how you find out whether yours works, without touching the backend or waiting for a real outage to tell you.
 
@@ -234,7 +327,7 @@ The loop closer, and the reason Reticle is not only an interactive tool.
 { "tool": "reticle_record", "args": { "action": "start", "recordingName": "ship-a-deploy" } }
 { "tool": "reticle_record", "args": { "action": "stop", "recordingName": "ship-a-deploy" } }
 { "tool": "reticle_flow_save", "args": { "flowName": "ship-a-deploy" } }
-{ "tool": "reticle_flow_verify" }
+{ "tool": "reticle_verify", "args": { "action": "flows" } }
 ```
 
 <Warning>
@@ -243,22 +336,37 @@ The loop closer, and the reason Reticle is not only an interactive tool.
   rather than guessing, which is the right call and still costs you a turn.
 </Warning>
 
-Stopping a recording returns a **large** payload. A one-click recording came back at roughly 63,000 characters, and 69,000 of the 70,000 were the raw `events` array. There is currently no way to cap it: `max_events` and `filters` are rejected, even though the response's own `cost.recommendation` suggests them.
-
-The parts you actually want are tiny. Read these and ignore the rest:
+Stopping a recording used to return a very large payload, almost all of it the raw `events` array. It no longer does. The timeline is omitted and replaced with a pointer, so a stop is under a kilobyte. This is a real capture of a one-click recording, complete rather than trimmed:
 
 ```json
 {
-  "program": { "name": "ship-a-deploy", "steps": [{ "tool": "reticle_act", "stable": true, "args": { … } }] },
+  "recordingName": "docs-check",
+  "program": {
+    "name": "docs-check",
+    "version": 1,
+    "steps": [{ "tool": "reticle_act", "stable": true, "args": { … } }]
+  },
+  "timeline_omitted": "445 event(s) were recorded and are not included here. Call reticle_observe { since: 11445 } for the raw timeline.",
   "proposedConsequences": [
-    { "predicate": { "kind": "signal", "name": "auth:granted" }, "tier": 0, "label": "signal \"auth:granted\" fires" },
-    { "predicate": { "kind": "state", "store": "app", "path": "auth" }, "tier": 1, "label": "state \"app\" changes" },
-    { "predicate": { "kind": "net", "method": "POST", "urlContains": "/api/login", "status": 200 }, "tier": 1, "label": "POST /api/login responds" }
+    { "predicate": { "kind": "signal", "name": "auth:granted" }, "tier": 0, "label": "signal \"auth:granted\" fires", "weak": false },
+    { "predicate": { "kind": "state", "store": "app", "path": "auth" }, "tier": 1, "label": "state \"app\" changes", "weak": false },
+    { "predicate": { "kind": "net", "method": "POST", "urlContains": "/api/login", "status": 200 }, "tier": 1, "label": "POST /api/login responds", "weak": false }
   ],
-  "summary": { "total": 440, "network": 1, "consoleErrors": 0, "signals": 1 }
+  "window_ms": 17387,
+  "summary": { "total": 445, "network": 1, "domChanged": 304, "consoleErrors": 0, "animations": 12, "signals": 1 },
+  "cost": { "events": 445, "bytes": 953 }
 }
 ```
 
+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.
+
+<Note>
+  `reticle_record` takes `action`, `recordingName` and `sessionId` and nothing else. `max_events`
+  and `filters` are rejected, which no longer matters now that the timeline is omitted anyway.
+</Note>
+
 `proposedConsequences` is the useful part and the reason to record at all. Reticle watched the interaction and worked out what would have proved it, ranked by strength. Tier 0 is the app's own signal. You do not have to invent the assertion; you pick one.
 
 ### Saving and replaying
@@ -271,28 +379,46 @@ The parts you actually want are tiny. Read these and ignore the rest:
 {
   "name": "ship-a-deploy",
   "stepCount": 1,
+  "degraded": 0,
+  "empty": false,
   "assertions": {
     "grade": "assertion-free",
-    "warning": "This flow performs actions but asserts no observable consequence, so it will pass even if the feature is broken."
+    "hasConsequenceAssertion": false,
+    "totalSteps": 1,
+    "consequenceSteps": 0,
+    "weakSteps": 0,
+    "successIsConsequence": false,
+    "intentVerified": false,
+    "warning": "This flow performs actions but asserts no observable consequence, so it will pass even if the feature is broken. Add a consequence assertion with reticle_annotate (assert-signal / assert-net) or a success-state."
   }
 }
 ```
 
 Reticle grades the flow as you save it, and tells you when you have just created a test that cannot fail. Take the warning seriously: an assertion-free flow replays green whatever the app does.
 
-A replay against a drifted app names what moved and where:
+A replay against a drifted app names what moved and where. This is `reticle_verify {action:"flows"}` reporting the same flow after the app changed underneath it:
 
 ```json
 {
-  "status": "drift",
-  "decision": {
-    "whatChanged": "testid \"login-submit\" not found",
-    "whereInSource": "src/components/Login.tsx:81",
-    "suggestedFix": "rebind the anchor to \"sign-out\" (closest survivor)"
-  }
+  "status": "fail",
+  "total": 1,
+  "passed": 0,
+  "failed": 1,
+  "failures": [
+    {
+      "flow": "docs-check",
+      "verdict": "drift",
+      "whatChanged": "testid \"login-submit\" not found",
+      "whereInSource": "src/components/Login.tsx:81",
+      "nextAction": "rebind the anchor to \"sign-out\" (closest survivor), or update the flow if the change was intended."
+    }
+  ],
+  "flaky": ["suite-500", "suite-route", "drift-demo", "stitch-probe"]
 }
 ```
 
+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:
 
 ```json
@@ -319,27 +445,46 @@ Flows live in `.reticle/` as human-readable files, so they are reviewed in pull
 
 ```json
 {
-  "schemaVersion": 1,
-  "runId": "11fd8ee9-2820-4bfa-bfe3-e4eeb111af26",
-  "durationMs": 41968,
-  "project": { "name": "reticle", "framework": "other" },
-  "agent": { "id": "reticle-mcp", "kind": "coding-agent" },
-  "flows": [
-    { "name": "suite-404", "status": "pass", "steps": 3, "oracle": "fault:injected" },
-    {
-      "name": "deploy-journey",
+  "run": {
+    "schemaVersion": 1,
+    "runId": "1f49b2d8-e402-4629-b202-819566fcace5",
+    "createdAt": 1786817831460,
+    "durationMs": 4,
+    "profile": "dev",
+    "project": { "name": "reticle", "framework": "other" },
+    "agent": { "id": "reticle-mcp", "kind": "coding-agent" },
+    "trigger": { "kind": "manual" },
+    "changedFiles": [],
+    "flows": [
+      {
+        "name": "sweep-flow",
+        "status": "fail",
+        "steps": 0,
+        "durationMs": 4,
+        "failureReason": "no such flow on disk, run reticle_flow{action:\"list\"} to see saved flows"
+      }
+    ],
+    "checks": [],
+    "risks": [],
+    "evidence": {
+      "consoleErrors": [],
+      "networkAnomalies": [],
+      "stateAssertions": [],
+      "timeline": []
+    },
+    "verdict": {
       "status": "fail",
-      "steps": 1,
-      "failureReason": "testid \"login-submit\" not found"
+      "reasons": ["flow sweep-flow: no such flow on disk"],
+      "confidence": "medium",
+      "blockingRisks": 0
     }
-  ],
-  "verdict": { "status": "partial", "confidence": "high", "blockingRisks": 0 }
+  }
 }
 ```
 
-A versioned, machine-readable record of a verification run. This is what you hand to CI, a dashboard, or a platform embedding Reticle in its pipeline.
+Note the `run` wrapper. The artifact is nested one level down, which matters if you are parsing it in CI.
 
-`oracle` on a passing flow names the consequence that made it a pass, so a green row says what it proved rather than only that it was green.
+A versioned, machine-readable record of a verification run. This is what you hand to CI, a dashboard, or a platform embedding Reticle in its pipeline. A passing flow additionally carries `oracle`, the consequence that made it a pass, so a green row says what it proved rather than only that it was green.
 
 ### The capability contract
 
@@ -351,6 +496,8 @@ A versioned, machine-readable record of a verification run. This is what you han
 { "saved": true, "path": ".reticle/contract.json", "testidCount": 49, "signalCount": 16 }
 ```
 
+Read it back with `reticle_capabilities { "fromDisk": true }`, which needs no browser at all.
+
 Persists the app's live capability registry to a git-checked file. A fresh agent can read it without booting the app, and a diff shows when someone removes a signal something depended on.
 
 ### Talking to the human

package/docs/cli/affected.mdx

@@ -25,14 +25,16 @@ One `reticle_affected` line. Real capture from this repository, with the file an
 
 ```json
 {
-  "t": "2026-08-14T19:38:46.407Z",
+  "t": "2026-08-15T18:42:58.072Z",
   "event": "reticle_affected",
-  "changedFiles": ["docs/cli.mdx", "packages/server/src/tools/e2e-surface-drift.test.ts"],
-  "affected": ["deploy-journey", "verify-route", "console-compose"],
-  "unknownProvenance": ["deploy-journey", "verify-route", "console-compose"]
+  "changedFiles": ["docs/cli.mdx"],
+  "affected": ["WEB-flow", "console-compose", "deploy-journey", "verify-route"],
+  "unknownProvenance": ["WEB-flow", "console-compose", "deploy-journey", "verify-route"]
 }
 ```
 
+The real run named 47 flows in each list. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
+
 | Field | Meaning |
 | --- | --- |
 | `changedFiles` | The resolved file set: your positional arguments plus whatever `--since` added |

package/docs/cli/capsules.mdx

@@ -14,25 +14,26 @@ No flags.
 
 ## What it prints
 
-One `reticle_capsules` line: a `count` and an array. Real capture from this repository, trimmed to three of the sixty-three entries:
+One `reticle_capsules` line: a `count` and an array. Real capture from this repository, trimmed to three of the seventy-nine entries and pretty-printed (the CLI prints it as a single line):
 
 ```json
 {
+  "t": "2026-08-15T18:42:48.790Z",
   "event": "reticle_capsules",
-  "count": 63,
+  "count": 79,
   "capsules": [
     {
-      "id": "1786713193695-e23",
+      "id": "1786793143459-e5",
       "origin": "failed-assert",
-      "expected": "declared consequence",
-      "observed": "no element matched {\"role\":\"dialog\"} in state 'visible'",
+      "expected": "signal auth:granted",
+      "observed": "signal \"auth:granted\" never fired",
       "steps": 1
     },
     {
-      "id": "1786696531874-e103",
+      "id": "1786791565180-e12",
       "origin": "failed-assert",
-      "expected": "signal auth:granted",
-      "observed": "signal \"auth:granted\" never fired",
+      "expected": "declared consequence",
+      "observed": "route is '/actions', expected '/server-actions'",
       "steps": 1
     },
     {

package/docs/cli/cloud.mdx

@@ -56,7 +56,13 @@ The one call to make when you do not know your state. Real capture:
 }
 ```
 
-An unattached repo also gets a next-step nudge on stderr, telling you to run `reticle link`.
+An unattached repo also gets a next-step nudge on stderr, telling you to run `reticle link`:
+
+```
+→ this repo is not attached ... run `reticle link`
+```
+
+`whoami` exits `0` either way. Throughout this page, the punctuation joining the two halves of a message is shown as `...`.
 
 ### `reticle link`
 
@@ -75,7 +81,11 @@ npx @reticlehq/server project rename <projectId> "New name"
 npx @reticlehq/server project rm <projectId>
 ```
 
-`rename` and `rm` work but are not in the usage block. Missing or malformed arguments exit `2`.
+`rename` and `rm` work but are missing from the top-level `reticle help` block, which lists only `<ls|create <name>>`. The command's own usage error names all four. Missing or malformed arguments exit `2`:
+
+```
+reticle: usage: reticle project <ls|create <name>|rename <id> <name>|rm <id>>
+```
 
 ### `reticle config`
 
@@ -83,7 +93,11 @@ npx @reticlehq/server project rm <projectId>
 npx @reticlehq/server config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
 ```
 
-Edits `.reticle/cloud.json` in place. Any value other than `on` or `off` (or `local` or `server` for `--verify`) exits `2`. Requires the repo to be linked.
+Edits `.reticle/cloud.json` in place. Any value other than `on` or `off` (or `local` or `server` for `--verify`) exits `2`. Requires the repo to be linked; run in an unlinked repo it exits `2` before it looks at the flags at all:
+
+```
+reticle: no .reticle/cloud.json here ... run `reticle link` first
+```
 
 ### `reticle push`
 
@@ -103,7 +117,19 @@ The CI gate: which flows broke relative to before. **Exits `3`** when any flow r
 npx @reticlehq/server share <runId>
 ```
 
-Mints a public proof link for one run. A missing `runId` exits `2`.
+Mints a public proof link for one run. A missing `runId` exits `2`:
+
+```
+reticle: usage: reticle share <runId>
+```
+
+## When the repo is not attached
+
+`push`, `runs` and `regression` all need a project to talk to. Without one they exit `1` with the same line on stderr, measured:
+
+```
+reticle: cloud not attached here ... run `reticle link` (or set RETICLE_CLOUD_URL/KEY)
+```
 
 ## Exit codes