@reticlehq/server 3.5.0 → 3.7.0

package/docs/cli/cloud.mdx

@@ -4,13 +4,15 @@ description: Connect a project in one command, then read runs and regressions fr
 icon: cloud
 ---
 
-From your app directory, `reticle connect --project "My App"` wires the app, opens browser sign-in approval if needed, links the named cloud project, and syncs the local history already on this machine. Run the [installer](/quickstart) once on the machine first. The commands below remain available when you need to sign in or link separately.
+From your app directory, `reticle connect --project "My App"` wires the app, opens browser sign-in approval if needed, links the named cloud project, and syncs the local history already on this machine. Run the [installer](/quickstart) once on the machine first. `connect` is the one command for signing in, linking and choosing a project.
 
 ```bash
 npx @reticlehq/server connect --project "My App"
 ```
 
-Use `--url https://your-cloud-origin` for a self-hosted cloud. `connect` checks a saved sign-in against that exact host before reuse; if it has expired, the browser approval opens again. It mints or reuses a project-scoped key, so there is no key to paste. A newly wired app may have no run to sync yet: ask your agent to verify one flow and the linked daemon will sync the result. Run `reticle whoami` to check the binding and `reticle push` to send anything still pending.
+If your daemon is not on the default port 4400, run `npx @reticlehq/server init --port <N>` first: `connect` takes no `--port`, and the `init` it runs for an unwired app uses the default.
+
+Use `--url https://your-cloud-origin` for a self-hosted cloud. `connect` checks a saved sign-in against that exact host before reuse; if it has expired, the browser approval opens again. It mints or reuses a project-scoped key, so there is no key to paste. The browser asks you to sign in, or to create a free account at app.reticle.sh. A new account gets 10 free credits to try Harness; adding a card starts a 14-day trial with 500 credits, and the paid plan includes 1,000 credits per seat each month. Harness drives and chat checks spend credits; storing and syncing runs is free. What syncs, and how to switch each part off, is in [What is recorded](/what-is-recorded). A newly wired app may have no run to sync yet: ask your agent to verify one flow and the linked daemon will sync the result. Run `reticle status` to check who is signed in and whether this folder is linked, and `reticle sync` to send anything still pending.
 
 The other cloud commands are thin clients over the `/v1` API. Their logic is server-side.
 
@@ -18,82 +20,41 @@ The other cloud commands are thin clients over the `/v1` API. Their logic is ser
 
 | Path | Contents | Secret |
 | --- | --- | --- |
-| `~/.reticle/session.json` | `{ url, token, orgName }` from `reticle login` | Yes |
-| `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes |
+| `~/.reticle/session.json` | `{ url, token, orgName }` from `reticle connect` | Yes |
+| `~/.reticle/credentials.json` | Project-scoped API keys from `reticle connect`, 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_API_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` (or its short form `RETICLE_URL`) overrides the endpoint; without it, a command uses the saved session's host, and otherwise the hosted service, `https://app.reticle.sh`.
 
 ## In CI
 
-CI needs `RETICLE_API_KEY` and nothing else: no `login`, no `link`. Commit `.reticle/cloud.json`, store the key as a secret, and the daemon and `reticle push` sync to the project the binding names. A key stored in `credentials.json` wins over the environment when both exist.
+CI needs `RETICLE_API_KEY` and nothing else: no `connect`. Commit `.reticle/cloud.json`, store the key as a secret, and the daemon and `reticle sync` sync to the project the binding names. A key stored in `credentials.json` wins over the environment when both exist.
 
 The environment key is only sent to the host it belongs to: `RETICLE_CLOUD_URL` when set, otherwise the hosted service. A repo linked to a self-hosted install therefore also needs `RETICLE_CLOUD_URL` set to that install in CI. A repo with no `cloud.json` and a key in the environment syncs to the hosted service, or to `RETICLE_CLOUD_URL`.
 
 ## The commands
 
-### `reticle login`
+### `reticle connect`
 
 ```bash
-npx @reticlehq/server login                                    # browser device flow (the default)
-npx @reticlehq/server login --email you@acme.com               # headless: requests a code
-npx @reticlehq/server login --email you@acme.com --code 123456 # headless: exchanges it
-npx @reticlehq/server login --email you@acme.com --org "Acme"  # --org is consulted only for a brand new account
-```
-
-With no `--email`, it runs a browser device flow like `gh auth login`: fetch a device and user code, open the browser to approve, poll until confirmed. With `--email` it keeps the two-step code path for CI and servers, because it proves you own the inbox before handing out a session. A local cloud whose dev mailer cannot deliver echoes the code back and completes in one command.
-
-### `reticle logout`
-
-Empties `session.json`. Per-project keys in `credentials.json` stay. Prints `{ "loggedOut": true }`.
-
-### `reticle whoami`
-
-The one call to make when you do not know your state. Real capture:
-
-```json
-{
-  "loggedInAs": "acme",
-  "repo": {
-    "attached": false,
-    "projectId": null,
-    "url": null,
-    "sync": { "runs": true, "memory": true, "flows": true },
-    "verify": "local"
-  }
-}
+npx @reticlehq/server connect [--project <name|id>] [--workspace <name|id>] [--url <cloud origin>] [--no-install]
 ```
 
-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`
-```
+Signs in if needed (a browser device flow like `gh auth login`: approve in the browser, the CLI polls until confirmed), then binds this repository to a cloud project and sends local history. 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, and creates the project when no project has that name. Omitted, the project is named after the `projectId` in `.reticle.json`, else after this folder. `--workspace` picks the workspace to link in when you belong to more than one. `--no-install` is passed to the `init` it runs for an unwired app. Writes `cloud.json` and the key.
 
-`whoami` exits `0` either way. Throughout this page, the punctuation joining the two halves of a message is shown as `...`.
+`reticle login`, `reticle link` and `reticle project` are the old spellings. They still work for one release and print one line naming `connect`. To sign in without a browser (an agent, a server), `login` keeps a two-step email path: `reticle login --email <e> [--org <name>]` mails a 6-digit code, then `reticle login --email <e> --code <123456>` signs in and links this repo. For CI, use `RETICLE_API_KEY` rather than any sign-in.
 
-### `reticle link`
+### `reticle logout`
 
 ```bash
-npx @reticlehq/server link [--project <name|id>]
+npx @reticlehq/server logout [--url <cloud origin>]
 ```
 
-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`
+Signs out of ONE host. Which host: `--url`, else `RETICLE_CLOUD_URL`, else the active session. Every other host stays signed in, and per-project keys in `credentials.json` stay. Prints `{ "loggedOut": true, "url": "…" }`, naming the host it signed out of.
 
-```bash
-npx @reticlehq/server project ls
-npx @reticlehq/server project create "My App"
-npx @reticlehq/server project rename <projectId> "New name"
-npx @reticlehq/server project rm <projectId>
-```
+### Who am I: `reticle status`
 
-`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 status`](/cli/status) says who you are signed in as and whether this folder is linked to a cloud project, beside the daemon and session facts. The account half reads local files only and makes no call to the cloud. `reticle whoami` is the old spelling; it still works for one release and prints one line naming `status`.
 
 ### `reticle config`
 
@@ -104,45 +65,64 @@ npx @reticlehq/server config [--runs on|off] [--memory on|off] [--flows on|off]
 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: no .reticle/cloud.json here ... run `reticle connect` first
 ```
 
-### `reticle push`
+### `reticle sync`
 
-Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ ok, project, sent, pulled }`, where `sent` carries the accepted counts and, when the server refused anything, a `rejected` array naming each run's index and reason and a `refused` array for flows, capsules and derived records. `sent.records` lists only the records the server accepted.
+Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy, and collects decisions made on the dashboard. Each switch removes only its own part: with `sync.runs` off no runs are sent, but flows and records still go unless they are off too. Prints `{ ok, project, sent, pulled }`, where `sent` carries the accepted counts and, when the server refused anything, a `rejected` array naming each run's index and reason and a `refused` array for flows, capsules and derived records. `sent.records` lists only the records the server accepted.
 
 Runs go up in batches, so a large backlog is never one oversized request.
 
+`reticle push` is the old name; it still works for one release and prints one line naming `sync`. Add `--watch` to keep syncing: it runs one cycle, waits, and runs the next, until you stop it with `Ctrl+C`. The wait is 60 seconds by default; set `RETICLE_SYNC_INTERVAL_MS` to change it. Add `--move-history` to also send the runs, flows and records made under this folder's previous link, after it was linked to another workspace.
+
+```bash
+npx @reticlehq/server sync --watch
+```
+
 What the platform cannot read is not sent at all, and a `notSent` array says why: a record kind an older platform does not know yet (this one alone leaves `ok` true), or a flow or run in a file version it does not read. Sending those would only be refused again on every cycle.
 
-**A rejection is a failed push.** If the server refuses any artifact, `ok` is `false` and the command exits `1`, even when other artifacts in the same bundle landed. The reason is kept as `sync.lastError` in `reticle whoami`, and the background daemon logs it once, until a cycle refuses nothing. A refused run is not offered again until its file changes or the platform reports that it reads more: until then it is listed under `notRetried`, and the summary reads `refused, not retried: N run(s) (reason)`. A refused artifact never reaches the dashboard and is re-offered on every cycle, so partial loss is still loss. `ok: true` and exit `0` mean everything offered was accepted, which includes the common case of a repo that was already up to date. The accepted counts still report what did land, so a partial push is visible as one.
+**A rejection is a failed sync.** If the server refuses any artifact, `ok` is `false` and the command exits `1`, even when other artifacts in the same bundle landed. The reason is kept as the last sync error, which `reticle status` reports, and the background daemon logs it once, until a cycle refuses nothing. A refused run is not offered again until its file changes or the platform reports that it reads more: until then it is listed under `notRetried`, and the summary reads `refused, not retried: N run(s) (reason)`. A refused artifact never reaches the dashboard and is re-offered on every cycle, so partial loss is still loss. `ok: true` and exit `0` mean everything offered was accepted, which includes the common case of a repo that was already up to date. The accepted counts still report what did land, so a partial sync is visible as one.
 
 ### `reticle runs`
 
 The linked project's recent run artifacts. The key scopes the query server-side.
 
-### `reticle regression`
+`reticle runs <runId>` reads one run, which is how to get back a Harness drive whose local `.reticle/runs/<runId>.drive.json` is gone. It exits `1` with "not synced yet, or not found" when the platform does not have it.
+
+### `reticle runs regression`
 
-The CI gate: which flows broke relative to before. **Exits `3`** when any flow regressed, which is the whole point of it being a separate command.
+Which flows broke relative to before. **Exits `3`** when any flow regressed. [`reticle gate`](/cli/gate) checks the same thing in a linked repo and exits `3` too, so CI needs only the gate.
 
-### `reticle share`
+### `reticle runs share`
 
 ```bash
-npx @reticlehq/server share <runId>
+npx @reticlehq/server runs 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 runs issues`
+
+```bash
+npx @reticlehq/server runs issues
+npx @reticlehq/server runs issues --fix <fingerprint>
 ```
-reticle: usage: reticle share <runId>
-```
+
+The triage queue from the dashboard. `--fix <fingerprint>` prints that one issue's fix prompt as bare text on stdout, so it can be piped straight into an agent. An unknown fingerprint exits `2`; an issue with no suggested fix prints nothing on stdout and exits `4`.
+
+### `reticle runs memory`
+
+What the linked project has learned, scoped to the project this folder is linked to. `--subject <name>` narrows it to one area. If the response cannot be shown to be about this project, it prints nothing on stdout and exits `1`.
+
+`reticle regression`, `reticle share`, `reticle issues` and `reticle memory` are the old spellings. They still work for one release, with the same exit codes, and print one line naming the `runs` form.
 
 ## 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:
+`sync` and every `runs` command 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_API_KEY)
+reticle: cloud not attached here: run `reticle connect`, or set RETICLE_API_KEY
 ```
 
 ## Exit codes
@@ -150,18 +130,17 @@ reticle: cloud not attached here ... run `reticle link` (or set RETICLE_API_KEY)
 | Code | Meaning |
 | --- | --- |
 | `0` | Success |
-| `1` | The API call failed, the repository is not attached where attachment is required, or `push` had an artifact refused |
+| `1` | The API call failed, the repository is not attached where attachment is required, or `sync` had an artifact refused |
 | `2` | Usage error, or not signed in and no `RETICLE_API_KEY` |
-| `3` | `regression` only: at least one flow broke |
+| `3` | `runs regression` only: at least one flow broke |
+| `4` | `runs issues --fix` only: that issue carries no suggested fix |
 
 Output is pretty-printed JSON on stdout. Errors and next-step nudges go to stderr, so an agent parsing stdout is unaffected.
 
 ## Worked example
 
 ```bash
-npx @reticlehq/server login
-npx @reticlehq/server project create "Checkout"
-npx @reticlehq/server link --project "Checkout"
-npx @reticlehq/server verify http://localhost:4173   # runs auto-push once linked
-npx @reticlehq/server regression                      # exit 3 fails the pipeline
+npx @reticlehq/server connect --project "Checkout"    # signs in, creates the project if needed, links
+npx @reticlehq/server verify http://localhost:4173   # runs sync automatically once linked
+npx @reticlehq/server runs regression                 # exit 3 fails the pipeline
 ```

package/docs/cli/doctor.mdx

@@ -14,19 +14,21 @@ npx @reticlehq/server doctor [--port N]
 
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which bridge port to diagnose |
+| `--port N` | number | `RETICLE_PORT`, else the port in `.reticle.json`, else the daemon already serving this project, else `4400` | Which bridge port to diagnose |
 
 ## What it prints
 
-Human-readable lines on stdout, not the JSON log. Real capture:
+Human-readable lines on stdout, not the JSON log. A healthy setup (rows that print only on a condition are absent):
 
 ```
 reticle doctor
   node         v22.14.0
   chromium     ✓ installed (chromium-1234)
-  daemon       ✓ running on :4400 (pid 72698, v2.8.0)
+  daemon       ✓ running on :4400 (pid 72698, v3.7.0)
   sessions     ✓ 1 page connected
   bridge port  4400  (your app must dial THIS port, not your dev-server port)
+  agent link   ✓ an MCP client attached here and called tools before (a record, not a live check)
+  project      ✓ wired here (my-app)
   daemon log   /Users/you/.reticle/daemon-4400.log
   tracing      RETICLE_TRACE=1 on the daemon for per-stage timings in that log
 ```
@@ -56,9 +58,12 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | `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 |
+| `project` | Whether the app in this folder is wired: a `.reticle.json` with a readable `projectId`, or an app that has connected here before. Everything above can be green in a project that never ran `init` |
 | `daemon log` | Where the structured daemon log lives |
 | `tracing` | How to turn that log into a per-stage trace |
 | `desktop` | Only on a desktop project. Every Electron and Tauri misconfiguration here fails silently, so it is diagnosed explicitly |
+| `coverage` | Only with a connected app. What Reticle sees in it, out of eight capabilities: what is missing, what is not seen yet, and, once a verdict recorded a gap, a prompt to paste into your coding agent |
+| `unsynced` | Only when a project folder holds runs the platform never got. Names the folder and the command that sends them, usually `reticle connect` run there |
 
 ## The chromium line
 
@@ -74,6 +79,12 @@ All three captures below are real, taken by pointing `PLAYWRIGHT_BROWSERS_PATH`
 
 **`✓ using the installed Google Chrome`** (or Microsoft Edge) means the pinned build is absent and Reticle drives the browser you already have instead, through Playwright's channel. Nothing to do: the line also names the command that adds Playwright's own build, if you want it.
 
+**`✓ using <path> (RETICLE_CHROMIUM_PATH)`** means you named the browser with [`RETICLE_CHROMIUM_PATH`](/environment), so the bundled revision is not checked at all. If the path does not exist, is not a file (a directory, say), or is not executable, the line says which instead, and offers no install command, because installing would not fix a wrong path:
+
+```
+  chromium     ✗ RETICLE_CHROMIUM_PATH points at /opt/nope/chrome, which does not exist; fix the path, or unset it to use Playwright's own Chromium
+```
+
 When neither is there, Reticle does not refuse. The first command that needs a browser (a lease, `verify`, a drive) runs the bundled Playwright's own pinned install for you, announced on stderr so `reticle mcp`'s stdout stays clean. The two `✗` lines below are what you see when that has not happened yet, or failed.
 
 **`✗ wrong revision`** means builds are installed and none of them is the wanted one. One pinned download away. The line names the revision Playwright wants, then every revision the root actually holds, then the exact command:

package/docs/cli/drive.mdx

@@ -12,13 +12,13 @@ npx @reticlehq/server drive <url> [--headless] [--headed]
 
 ## Arguments and flags
 
-| Argument     | Type                             | Default                  | What it does      |
-| ------------ | -------------------------------- | ------------------------ | ----------------- |
-| `url`        | string, positional, **required** | none                     | The page to drive |
-| `--headed`   | boolean                          | on by default outside CI | Show the browser  |
-| `--headless` | boolean                          | on when `CI` is set      | Hide it           |
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `url` | string, positional, **required** | none | The page to drive |
+| `--headed` | boolean | on by default outside CI | Show the browser |
+| `--headless` | boolean | on when `CI` or `RETICLE_HEADLESS` is set, or on Linux with no display | Hide it |
 
-`drive` is the one interactive command in the family, so it is the one that shows the browser by default. `serve`, `mcp` and the internal daemon own the pooled browser behind leases, which is batch work, and hide theirs.
+`serve` and `mcp` show their browser by default too, so you can watch your agent's run; `--headless` hides it. `restart` always starts its daemon headless.
 
 ## What it prints
 
@@ -30,7 +30,7 @@ Omitting the URL is a usage error. Real capture, with the usage block that follo
 {"t":"2026-08-15T18:43:06.977Z","event":"reticle_usage_error","message":"drive needs a url"}
 drive needs a url
 
-usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)
+usage:  reticle <command>   (or npx @reticlehq/server <command>)
   ...
 ```
 
@@ -42,10 +42,10 @@ usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin i
 
 ## Exit codes
 
-| Code | Meaning                                                               |
-| ---- | --------------------------------------------------------------------- |
-| `0`  | Running in the foreground, or attached with a connected session       |
-| `1`  | No URL, an unknown flag, the engine failed to start, or attach failed |
+| Code | Meaning |
+| --- | --- |
+| `0` | Running in the foreground, or attached with a connected session |
+| `1` | No URL, an unknown flag, the engine failed to start, attach failed, or the attached tab never connected |
 
 ## When a daemon already has the port
 
@@ -53,14 +53,20 @@ A daemon on `:4400` is the normal state the moment any agent connects, and `driv
 
 ```bash
 $ npx @reticlehq/server drive http://localhost:5173
-{"event":"reticle_drive_attached","port":4400,"url":"http://localhost:5173","sessionId":"lease-9f2b…","ready":true}
+{"event":"reticle_drive_attached","port":4400,"url":"http://localhost:5173","sessionId":"lease-9f2b…","ready":true,"projectId":"web","title":"Web"}
 ```
 
-A plain-text line follows it naming the same session, how long it survives untouched (any tool call against it resets that), and, if the page never dialled the bridge, why.
+A plain-text line follows it naming the same session, the app it belongs to (the `projectId` and title the page reported), how long it survives untouched (any tool call against it resets that), and, if the page never dialled the bridge, why.
+
+In a monorepo the port you meant for one app can be held by another. When the current directory's `.reticle.json` names a different project from the one the page reported, the line ends with a warning saying so, and the JSON carries both as `projectId` and `expectedProjectId`. Real capture, with app `admin` on the port, `drive` run from app `web`, and the sentence break shown as `...`:
+
+```
+attached to the Reticle daemon on :4497 ... it is driving http://localhost:5177/?__reticle_project=admin (project "admin", "Admin console") as session lease-74bf5522-8eee-4ea2-b66d-4c056c7dad3a, which every Reticle tool can address. It is released after 300s untouched; any tool call against it resets that. Warning: this directory's .reticle.json is project "web", but the page at http://localhost:5177/?__reticle_project=admin is project "admin", so another app is probably serving that port. Check which dev server is on it before trusting anything this session reports.
+```
 
 That session lives in the daemon, so the tools your agent already has open can address it by id. You do **not** need `reticle stop` first, and should not use it: the MCP proxy respawns a daemon as soon as the next tool call arrives, which is a race a manual `stop` loses.
 
-Attaching means the browser is the daemon's pooled, headless one, so `--headed` cannot apply. To watch a browser instead, drive on a port no daemon owns (`RETICLE_PORT=4460`).
+Attaching means the browser is the daemon's pooled one, shown or hidden as that daemon was started, so `--headed` cannot apply. To watch a browser instead, drive on a port no daemon owns (`RETICLE_PORT=4460`).
 
 <Note>
   If the port is held by something that is **not** a Reticle daemon, `drive` refuses and names the

package/docs/cli/feedback.mdx

@@ -8,7 +8,7 @@ icon: comment
 
 ```bash
 npx @reticlehq/server feedback [--rating 1-5] [--bug] "what worked, what didn't"
-npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"
+npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "what happened"
 ```
 
 The `--agent` form is for an agent that cannot reach the `reticle_session { action: "feedback" }` tool: during `init`, while instrumentation is half wired, or when the daemon will not start. Those are the reports that are hardest to hear and most needed, because every other path requires the tool surface to already work.
@@ -29,12 +29,12 @@ Everything that is not a flag or a flag's value becomes the message, joined with
 The payload is printed **before** it is sent, every time. A channel that carries free text and does not show you what it sends is asking for trust it has not earned.
 
 ```
-sending      {"source":"human","kind":"experience","stack":"vite","runtime":"web"}
+sending      {"stack":"vite","version":"3.7.0","os":"darwin","ci":false}
 redacted     email (removed before sending)
 thanks       your feedback is in. it genuinely changes what gets built next.
 ```
 
-`not sent` replaces the last line when the send failed or telemetry is off, and names the reason. Humans who have never identified also get an offer of a reply route, printed after the receipt rather than as a prompt.
+`not sent` replaces the last line when the send failed or telemetry is off, and names the reason. Nothing is lost either way: a failed send is kept on disk and retried, and with telemetry off the report is written to disk instead.
 
 Run with no message and no rating, it prints usage and exits `1`. Real capture:
 

package/docs/cli/gate.mdx

@@ -7,7 +7,7 @@ icon: shield-halved
 `reticle gate` is what makes verification unavoidable. It computes the [affected](/cli/affected) flows, looks for a passing artifact for each, and fails the command if any is missing. An agent that edits a covered file cannot call itself finished without re-verifying.
 
 ```bash
-npx @reticlehq/server gate [--since <ref>] [--accept-coverage] [file...]
+npx @reticlehq/server gate [--since <ref>] [--accept-coverage] [--hook] [file...]
 ```
 
 ## Arguments and flags
@@ -17,6 +17,9 @@ npx @reticlehq/server gate [--since <ref>] [--accept-coverage] [file...]
 | `file...` | strings, positional | none | Explicit changed files |
 | `--since <ref>` | string | `HEAD` when no files are given | Also include files git reports as changed since this ref |
 | `--accept-coverage` | boolean | off | Accept today's coverage levels as the new best before judging. Use it when a drop was intended, such as a control you removed on purpose. The run reports what it accepted as `coverageAccepted` |
+| `--hook` | boolean | off | For an agent's Stop hook. A failure or a known regression also prints a short prose summary for a human; exit `2` (no saved flows) prints nothing extra. A refused platform credential does not fail the gate in this mode |
+
+In hook mode only, setting `RETICLE_SKIP_GATE` turns a failing gate into exit `0` and prints that the change is unverified.
 
 ## What blocks and what does not
 
@@ -53,7 +56,9 @@ One `reticle_gate` line. Real capture from this repository, with the flow lists
 | Code | Meaning |
 | --- | --- |
 | `0` | Every affected, non-flaky flow has a passing artifact, nothing was weakened or deleted, and coverage held |
-| `1` | Something is uncovered, downgraded, deleted, unflowed, unexecuted, or coverage fell. Also `1` on any internal fault: the gate fails closed |
+| `1` | Something is uncovered, downgraded, deleted, unflowed, unexecuted, or coverage fell. Also `1` on any internal fault, and, outside `--hook`, when the linked platform refused the project's credential: the gate fails closed |
+| `2` | No saved flows, so nothing was checked. This is not a failure of the change: the gate says how to record one |
+| `3` | The linked project's dashboard knows a flow that passed before and is broken now, the same code `reticle runs regression` exits with. Checked only when the repo is linked; offline, it changes nothing |
 
 Measured on this repository, `npx @reticlehq/server gate --since HEAD~1` exited `1` with the output above: 0 of 47 flows covered, 39 uncovered and 8 quarantined.
 

package/docs/cli/help.mdx

@@ -1,10 +1,10 @@
 ---
 title: reticle help
-description: Print the complete Reticle command grammar, every command and every flag, on one screen.
+description: Print the short, grouped list of Reticle commands; every command with help all; one command in detail with --help.
 icon: circle-question
 ---
 
-`reticle help` prints the whole usage block to stdout and exits `0`.
+`reticle help` prints a short list of the commands most people need, grouped, one line each, to stdout and exits `0`.
 
 ```bash
 npx @reticlehq/server help
@@ -14,70 +14,65 @@ npx @reticlehq/server -h
 
 All three are the same command.
 
-<Warning>
-  There is no per-command help. `reticle init --help` is not a help request, it is an unknown
-  argument: the parser rejects it, prints `unknown argument '--help'` followed by this same block,
-  and exits `1`. This page and the rest of this section are the per-command reference.
-</Warning>
+| You type | You get |
+| --- | --- |
+| `reticle help` | The short list, grouped |
+| `reticle help all` (or `--help all`) | Every command, one line each, including the ones the short list leaves out |
+| `reticle <command> --help` (or `reticle help <command>`) | That command's flags and detail |
 
-## What it prints
+`--help` works anywhere on the line, so `reticle init --help` is a help request, never an unknown argument, and never runs the command.
 
-Real capture, in full:
+## The short list
 
+```text
+usage:  reticle <command>   (or npx @reticlehq/server <command>)
+
+Get started
+  init        Wire Reticle into the app in this folder
+  connect     Sign in and link this project to the dashboard
+  try         Watch Reticle drive a URL once and say which journeys work
+
+Check your app
+  verify      Check the saved flows against the running app; exit 0 means pass
+  gate        Fail unless passing checks cover the flows your changes touch
+
+Reticle on this machine
+  status      Is Reticle running, is your app connected, are you signed in
+  doctor      Find what is wrong with the setup, and what is missing from coverage
+  open        Open the app in your browser, or reuse a tab that is already connected
+  stop        Stop Reticle; --force frees its port even without a recorded pid
+  restart     Stop Reticle, then start it and wait until it is listening
+  update      Install the latest version and restart
+
+Account
+  logout      Sign out (of one host; others stay signed in)
+  feedback    Tell us what worked and what didn't; prints exactly what it sends
+  telemetry   Show or change anonymous usage metrics
+
+All commands: reticle help all     One command: reticle <command> --help
 ```
-usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)
-
-  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
-                --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
-                only make sense once the tools are reachable.
-  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
-  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)
-  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)
-  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)
-  reticle status [--port N]
-  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
-  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
-  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
-  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
-  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
-  reticle watch [url]                                  (on save, report which saved flows must re-verify)
-  reticle drive <url> [--headless]                     (foreground mode, for debugging)
-  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)
-  reticle update                                       (install the latest server version and restart)
-  reticle rollback                                     (restore the previous server version and restart)
-  reticle license                                      (show enterprise license status: active | eval | missing)
-  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)
-  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't; prints exactly what it sends)
-  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "message"
-                                                       (agents: file from anywhere, including a setup that never finished)
-  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
-                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
-
-Cloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):
-  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)
-  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
-  reticle whoami                                        (who am I signed in as, and is this repo attached?)
-  reticle project <ls|create <name>>                   (list or create cloud projects)
-  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
-  reticle push                                          (send local run artifacts to the dashboard)
-  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
-
-'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
-and the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.
-```
+
+| Group                   | Commands                                                |
+| ----------------------- | ------------------------------------------------------- |
+| Get started             | `init`, `connect`, `try`                                |
+| Check your app          | `verify`, `gate`                                        |
+| Reticle on this machine | `status`, `doctor`, `open`, `stop`, `restart`, `update` |
+| Account                 | `logout`, `feedback`, `telemetry`                       |
+
+## Only in `help all`
+
+`sync`, `runs`, `config`, `affected`, `report`, `context`, `mcp`, `serve`, `drive`, `setup`, `license`, `rollback` and `version`. They all work the same as always; they are left out of the short list because most people never type them. See the [CLI reference](/cli) for one row per command, including the renamed and removed ones.
 
 ## Errors print it too
 
-Any usage error prints the offending thing first, then this same block on stderr, and exits `1`:
+Any usage error prints the offending thing first, then the short list on stderr, and exits `1`:
 
-```
+```text
 {"t":"2026-08-15T18:42:48.476Z","event":"reticle_usage_error","message":"unknown command 'nonsense-cmd'"}
 unknown command 'nonsense-cmd'
 
-usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)
-  ... the whole block above ...
+usage:  reticle <command>   (or npx @reticlehq/server <command>)
+... the short list ...
 ```
 
 Two audiences, two channels: the structured line for logs and scripts, the plain text for the person who just typed the command.