@reticlehq/server 3.6.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
 

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
 
@@ -66,7 +66,7 @@ attached to the Reticle daemon on :4497 ... it is driving http://localhost:5177/
 
 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.

package/docs/cli/init.mdx

@@ -7,7 +7,10 @@ icon: wand-magic-sparkles
 `reticle init` is the one command a person runs before anything else. It inspects the directory it is standing in, works out the framework, and writes every piece of wiring Reticle needs: the MCP server registration, the agent rule files, the dev dependencies, `.reticle.json`, and the bundler plugin.
 
 ```bash
-npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>] [--yes]
+npx @reticlehq/server init [--env KEY=VALUE]... [--app <dir>] [--license <key>] [--json]
+                           [--files-only] [--relaunch] [--no-open] [--no-agents] [--url <app url>]
+                           [--timeout S] [--dry-run] [--hooks] [--port N] [--no-mcp] [--no-install]
+                           [--start] [--capture-bodies] [--no-first-run]
 ```
 
 ## Flags
@@ -17,9 +20,21 @@ npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--a
 | `--dry-run` | boolean | `false` | Print the full plan and write nothing |
 | `--port N` | number | unset (resolves to `4400`) | Bridge port to write into the config |
 | `--no-mcp` | boolean | `false` (MCP is registered) | Skip the MCP registration **and** the agent rule files (`CLAUDE.md`, `AGENTS.md`, `.cursor`) and the `/reticle` command |
-| `--no-install` | boolean | `false` (deps are installed) | Do not run the install. The step becomes `[⚠]` and prints the `add -D` command for you to run by hand, rather than vanishing from the plan |
-| `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory |
+| `--no-install` | boolean | `false` (deps are installed) | Do not run the install. The step becomes `[–]` ("skipped (--no-install); install them yourself: …") with the install command for you to run by hand, rather than vanishing from the plan |
+| `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory. On its own it implies `--files-only` |
+| `--start` | boolean | `false` | With `--app`, also boot the app the way a plain `init` does |
+| `--capture-bodies` | boolean | `false` | Write `captureNetworkBodies: true` into the Vite plugin call, so request and response bodies are captured |
+| `--no-first-run` | boolean | `false` | Connect and stop, without the coverage summary |
 | `--hooks` | boolean | `false` | Also add a print-only Stop hook to `.claude/settings.json`, merged into what is there. When the agent stops without a claim that held, it prints one line; it never blocks. See [`reticle report`](/cli/report) |
+| `--env KEY=VALUE` | string, repeatable | none | What the app needs to reach a usable state: a key from `.env.example`, a mock backend, a variable that skips an auth wall. A value may contain spaces and `=` |
+| `--license <key>` | string | unset | Write an enterprise license key to `.env` and keep `.env` out of git |
+| `--json` | boolean | `false` | Put the result on stdout as one object, for an agent to read |
+| `--files-only` | boolean | `false` | Write the files, register the MCP server and pre-approve the tools, then stop: no dev server, no browser. Also the upgrade path for an existing install |
+| `--relaunch` | boolean | `false` | Print the exact command that restarts this agent conversation with the `reticle_*` tools loaded. Refuses when the session has no transcript behind it. Works with `--files-only` |
+| `--no-open` | boolean | `false` | Do not open a browser window. The connect is checked in a hidden tab instead |
+| `--no-agents` | boolean | `false` | Do not register the MCP server with the other agents on this machine |
+| `--url <app url>` | string | unset | The app is already running at this URL: use it instead of starting a dev server |
+| `--timeout S` | seconds | the framework's own budget | How long to wait for the dev server and for a session to connect |
 | `--yes` | boolean | `false` | Accepted for scripting. `init` has no interactive prompts today, so it is a no-op |
 
 <Warning>
@@ -29,7 +44,7 @@ npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--a
 
 ## What it prints
 
-A plan, one line per step, each with a status mark: `✓` written, `·` already in place or left alone, `⚠` needs a hand, `–` deliberately skipped by a flag. Captured from a real `--dry-run` inside `apps/bench-app`:
+A plan, one line per step, each with a status mark: `✓` written, `·` already in place or left alone, `⚠` needs a hand, `–` deliberately skipped by a flag, `ℹ` done, but incomplete in a way that matters. Captured from a real `--dry-run` inside `apps/bench-app`:
 
 ```
 reticle init (dry run, no files written)
@@ -37,8 +52,8 @@ reticle init (dry run, no files written)
 
   [·] MCP server (Claude, global) → global (claude user scope)
       reticle already registered (install once, used by every project)
-  [·] MCP server (Cursor, global) → /Users/you/.cursor/mcp.json
-      reticle already in Cursor global config
+  [·] MCP server (Cursor) → /Users/you/.cursor/mcp.json
+      reticle already registered with Cursor
   [⚠] MCP server (Codex CLI) → /Users/you/.codex/config.toml
       add this to /Users/you/.codex/config.toml by hand:
       [mcp_servers.reticle]
@@ -54,7 +69,7 @@ reticle init (dry run, no files written)
   [✓] The /reticle command → .claude/commands/reticle.md
       type /reticle to verify one flow in the browser
   [✓] Install dependencies → package.json
-      pnpm add -D @reticlehq/react@2.8.0 @reticlehq/vite-plugin@2.8.0
+      pnpm add -D @reticlehq/react@3.7.0 @reticlehq/vite-plugin@3.7.0
   [✓] Reticle config → .reticle.json
       write project config (framework + port)
   [✓] Vite plugin → vite.config.ts
@@ -62,9 +77,11 @@ reticle init (dry run, no files written)
   [·] Capabilities + store → src/reticle-dev.ts
       file exists, left alone, it is yours to edit
 
-Restart `vite`.
+Restart your dev server (`vite`).
 ```
 
+The install line pins the packages to the version of Reticle you are running. When the `codex` binary is on your PATH, the Codex row is not a hand edit: it reads `[✓] MCP server (Codex CLI)` and registers through `codex mcp add reticle -- npx @reticlehq/server mcp`.
+
 Below the plan it also prints the two things that actually finish the install: restart your agent so it re-reads its MCP server list, then run `npx @reticlehq/server status` to confirm the app connected.
 
 With `--no-mcp`, the whole MCP and rules group collapses into one skipped line:
@@ -89,7 +106,7 @@ Several apps found in this workspace. Re-run `reticle init` for the one you want
   reticle init --app apps/vibe-builder-demo
 ```
 
-Given `--app`, it says which directory it moved to before printing the plan:
+Given `--app`, it writes that app's files and starts nothing: no daemon and no dev server, since a monorepo app's dev server is often run from the root. Add `--start` to boot it the way a plain `init` does. It says which directory it moved to before printing the plan:
 
 ```
 No app in this directory ... wiring apps/bench-app instead.
@@ -99,12 +116,12 @@ In the two captures above, the punctuation that separates the two halves of the
 
 ## Exit codes
 
-| Code | Meaning                                                                                 |
-| ---- | --------------------------------------------------------------------------------------- |
-| `0`  | The plan ran. Steps marked `⚠` still need a hand, and do not change the code            |
-| `1`  | Init failed, an unknown flag was passed, or several apps were found and none was chosen |
+| Code | Meaning |
+| --- | --- |
+| `0` | The app connected. Steps marked `⚠` still need a hand, and do not change the code |
+| `1` | No session connected, init failed, an unknown flag was passed, or several apps were found and none was chosen |
 
-An unknown flag is rejected by name: `reticle init --bogus` prints `unknown argument '--bogus'`, then the full usage block, and exits `1`.
+An unknown flag is rejected by name: `reticle init --bogus` prints `unknown argument '--bogus'`, then the short usage (`reticle --help`), and exits `1`.
 
 ## Worked example
 
@@ -116,5 +133,5 @@ npx @reticlehq/server status             # confirm the app actually connected
 ```
 
 <Card title="The install, step by step" icon="wand-magic-sparkles" href="/install-agentic">
-  What each step writes and how to read the four status marks.
+  What each step writes and how to read the five status marks.
 </Card>