@reticlehq/server 2.7.0 → 2.9.0

package/docs/cli/identify.mdx

@@ -0,0 +1,76 @@
+---
+title: reticle identify
+description: Opt in to telling the Reticle maintainers who you are, and undo it at any time.
+icon: id-card
+---
+
+`reticle identify` attaches a name, a company, an email and a usage context to this machine's Reticle install and sends them to the maintainers, so support or an enterprise trial has someone to talk to. It is off unless you run it, and `reticle identify --forget` undoes it.
+
+It is opt-in and deliberately not interactive. A prompt in the middle of someone's work is pressure, and this is the one command where the choice has to be free. You type what you want to share, or you never run it at all.
+
+```bash
+npx @reticlehq/server identify --context <company|side_project|open_source|learning> [--company "Acme"] [--email you@acme.com] [--forget]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--context K` | one of `company`, `side_project`, `open_source`, `learning` | none. Required unless `--forget` | What Reticle is being used for |
+| `--company N` | string | unset | Your company name. Optional |
+| `--email E` | string | unset | An address to reach you on. Optional |
+| `--forget` | boolean | `false` | Delete the local identity file and stop sending it |
+
+Every field except the context is optional, so you can say "this is a company" without saying which, or name the company without leaving an address.
+
+## What it prints
+
+The consent notice, then the exact payload, then the result:
+
+```
+sending      {"context":"company","company":"Acme","email":"you@acme.com"}
+thanks       saved and sent. we may reach out; `reticle identify --forget` undoes this.
+```
+
+`not sent` replaces the last line when telemetry is disabled on the machine, in which case the identity is saved locally only.
+
+With `--forget`:
+
+```
+forgotten    the local identity file is deleted; nothing further is sent.
+             to have what was already sent removed, email support@reticlehq.com
+```
+
+Run with no valid `--context`, it prints the current identity (if any), the usage, and the full consent notice, and exits `1`. Real capture on a machine with no identity on file:
+
+```
+usage: reticle identify --context <company|side_project|open_source|learning>
+       [--company "Acme"] [--email you@acme.com] [--forget]
+
+This sends the details you type here to the Reticle maintainers, so we can contact you and
+understand how teams use Reticle. It is linked to this machine's anonymous id, which means it
+also connects the anonymous usage already recorded from this machine to what you enter now.
+Nothing about your app, your code, or your repository is included, and nothing else changes.
+Undo it any time with `reticle identify --forget` (that stops future sends and deletes the local file;
+email support@reticlehq.com to have what was already sent removed).
+```
+
+<Warning>
+  Identifying links this machine's anonymous id to what you type, which also connects the anonymous
+  usage already recorded from this machine to that identity. The command says so before it sends
+  anything. Nothing about your app, your code, or your repository is ever included.
+</Warning>
+
+## Exit codes
+
+| Code | Meaning                                                                        |
+| ---- | ------------------------------------------------------------------------------ |
+| `0`  | Identity saved, or forgotten, or usage printed when an identity already exists |
+| `1`  | No valid `--context` and no identity on file                                   |
+
+## Worked example
+
+```bash
+npx @reticlehq/server identify --context open_source --email maintainer@example.com
+npx @reticlehq/server identify --forget
+```

package/docs/cli/init.mdx

@@ -0,0 +1,121 @@
+---
+title: reticle init
+description: Wire Reticle into the project in the current directory, registering the MCP server and installing the SDK.
+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]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--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 |
+| `--yes` | boolean | `false` | Accepted for scripting. `init` has no interactive prompts today, so it is a no-op |
+
+<Warning>
+  `--no-mcp` skips more than the server registration. The agent rule files and the `/reticle`
+  command go with it, because all three only make sense once the tools are reachable.
+</Warning>
+
+## 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`:
+
+```
+reticle init (dry run, no files written)
+  in /Users/you/reticle/apps/bench-app
+
+  [·] 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 (Codex CLI) → /Users/you/.codex/config.toml
+      add this to /Users/you/.codex/config.toml by hand:
+      [mcp_servers.reticle]
+      command = "npx"
+      args = ["@reticlehq/server", "mcp"]
+
+  [✓] Agent verification rule → CLAUDE.md
+      teach the agent to verify features with Reticle after building them
+  [✓] Agent verification rule → AGENTS.md
+      teach the agent to verify features with Reticle after building them
+  [✓] Full agent rules → RETICLE.md
+      the reference the always-loaded rule points at (when NOT to verify, recovery, feedback)
+  [✓] 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
+  [✓] Reticle config → .reticle.json
+      write project config (framework + port)
+  [✓] Vite plugin → vite.config.ts
+      add reticle() to plugins (also injects connect())
+  [·] Capabilities + store → src/reticle-dev.ts
+      file exists, left alone, it is yours to edit
+
+Restart `vite`.
+```
+
+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:
+
+```
+  [–] MCP server (global) → global (claude user scope)
+      --no-mcp ... also skips the agent rule files (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command
+```
+
+Run from a workspace root with several apps, it refuses to guess, names them, and exits `1`:
+
+```
+Several apps found in this workspace. Re-run `reticle init` inside the one you want:
+  packages/next
+  packages/vite-plugin
+  apps/atlas
+  apps/bench-app
+  apps/electron-smoke
+  apps/large-dom-bench
+  apps/next-smoke
+  apps/tauri-smoke
+  apps/vibe-builder-demo
+
+Or name one without changing directory:  reticle init --app packages/next
+```
+
+Given `--app`, it says which directory it moved to before printing the plan:
+
+```
+No app in this directory ... wiring apps/bench-app instead.
+```
+
+In the two captures above, the punctuation that separates the two halves of the sentence is shown as `...`.
+
+## 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 |
+
+An unknown flag is rejected by name: `reticle init --bogus` prints `unknown argument '--bogus'`, then the full usage block, and exits `1`.
+
+## Worked example
+
+```bash
+cd apps/web
+npx @reticlehq/server init --dry-run     # read the plan first
+npx @reticlehq/server init               # then run it
+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.
+</Card>

package/docs/cli/kill.mdx

@@ -0,0 +1,91 @@
+---
+title: reticle kill
+description: Free the bridge port by killing its listener, without touching the agent's own MCP proxy.
+icon: skull
+---
+
+`reticle kill` frees the bridge port. It asks **who is listening** on the port and signals that one process, which is the whole difference between this command and the shell pipeline everybody reaches for.
+
+```bash
+npx @reticlehq/server kill [--port N] [--force]
+```
+
+<Warning>
+  Never free the port with `lsof -ti tcp:4400 | xargs kill -9`. `reticle mcp` holds a **client**
+  socket on that port, so `-ti` lists the proxy right beside the daemon and the pipeline kills both.
+  When the proxy dies, the agent's next tool calls get no reply at all: not an error, not a timeout.
+  Nothing is written to the proxy log either, because the process that writes it is the one that
+  died. That is the mechanism behind most "my MCP disconnected" reports.
+</Warning>
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which port to free |
+| `--force` | boolean | `false` | Kill the listener even when it is not a Reticle daemon |
+
+## kill or stop?
+
+They target different things, and the distinction matters exactly when you are stuck.
+
+|  | `reticle stop` | `reticle kill` |
+| --- | --- | --- |
+| Finds the process by | the pid recorded in Reticle's own state | the **listener** on the port |
+| Works when the pid file is stale or was never written | no | yes |
+| Works on a daemon from another checkout | no | yes |
+| Works without `lsof` (Windows, slim containers) | yes | yes, falling back to the recorded pid and saying so |
+
+Reach for `stop` in a script that shuts down a daemon it started. Reach for `kill` when the port is held and you want it back.
+
+## How it decides
+
+1. Look up the listener with `lsof -nP -iTCP:<port> -sTCP:LISTEN`. Client sockets are excluded by construction, so the proxy is never a candidate.
+2. It is Reticle's if it answers `/status`, **or** if it is the pid Reticle recorded for the port. `/status` outranks the pid file, so a daemon started from another checkout is still recognised as ours.
+3. Anything else is refused, by name, unless `--force`.
+4. `SIGTERM`, then `SIGKILL` after 5 seconds, then report that it survived and exit `1`.
+
+## What it prints
+
+Real captures, taken against a daemon started on a scratch port. The long `note` and `reason` strings are trimmed at the ellipsis. Measured exit codes: `0` for killed and nothing-to-do, `1` for refused.
+
+Killed:
+
+```
+{"t":"2026-08-15T18:43:43.590Z","event":"reticle_killed","port":4499,"pid":78621,"escalated":false,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone ..."}
+```
+
+Refused, because the listener is not ours. This one was captured with `python3 -m http.server 4498` holding the port:
+
+```
+{"t":"2026-08-15T18:43:57.128Z","event":"reticle_kill_refused","port":4498,"reason":"pid 78795 (\"Python\") is listening, and it is not a Reticle daemon ... it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}
+```
+
+Nothing to free:
+
+```
+{"t":"2026-08-15T18:43:43.784Z","event":"reticle_kill_nothing_to_do","port":4499,"presence":"free"}
+```
+
+| Event | When |
+| --- | --- |
+| `reticle_killed` | The listener is gone. `escalated: true` means it took a `SIGKILL`; `forced: true` means `--force` overrode a refusal |
+| `reticle_kill_refused` | The listener is not a Reticle daemon and `--force` was not given. Exits `1` |
+| `reticle_kill_survived` | It survived `SIGKILL`. The port is still held. Exits `1` |
+| `reticle_kill_nothing_to_do` | No listener, and no live recorded pid |
+
+`listenerIdentified: false` means `lsof` could not run and the pid came from Reticle's records rather than from an observed listener. Those are different claims, so the field says which one you got.
+
+## Exit codes
+
+| Code | Meaning                                                            |
+| ---- | ------------------------------------------------------------------ |
+| `0`  | The port is free                                                   |
+| `1`  | The port is still held: refused, or the process survived `SIGKILL` |
+
+## Worked example
+
+```bash
+npx @reticlehq/server kill            # free 4400
+npx @reticlehq/server status          # confirm
+```

package/docs/cli/license.mdx

@@ -0,0 +1,48 @@
+---
+title: reticle license
+description: Show the enterprise license status resolved from the environment, offline.
+icon: key
+---
+
+`reticle license` reports whether an enterprise license is active. It resolves entirely from the environment. Nothing leaves the machine.
+
+```bash
+npx @reticlehq/server license
+```
+
+No flags.
+
+## What it prints
+
+One `reticle_license` line. Real capture on a checkout with no issuer key configured:
+
+```json
+{
+  "t": "2026-08-15T18:42:26.758Z",
+  "event": "reticle_license",
+  "status": "eval",
+  "detail": "evaluation mode: enterprise features run free (no issuer key configured)"
+}
+```
+
+| `status`  | Meaning                                       |
+| --------- | --------------------------------------------- |
+| `active`  | A valid license is present                    |
+| `eval`    | Evaluation mode. Enterprise features run free |
+| `missing` | No license, and the build expects one         |
+
+`detail` is a sentence explaining the status.
+
+## Exit codes
+
+Always `0`.
+
+## Worked example
+
+```bash
+npx @reticlehq/server license | jq -r .status
+```
+
+<Card title="What enterprise covers" icon="building" href="/enterprise">
+  The licensed surface, and what stays Apache 2.0.
+</Card>

package/docs/cli/mcp.mdx

@@ -0,0 +1,61 @@
+---
+title: reticle mcp
+description: Run the MCP stdio proxy your agent talks to, starting a daemon if one is not already up.
+icon: plug
+---
+
+`reticle mcp` is the command your agent runs. It is the MCP server the editor launches: a stdio proxy that bridges the client to the daemon's SSE endpoint, starting a daemon first if the port is empty.
+
+```bash
+npx @reticlehq/server mcp [--port N] [--drive <url>] [--headless] [--headed] [--http] [--http-port N] [--http-token T]
+```
+
+This is what `reticle init` registers, so you rarely type it yourself.
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port |
+| `--drive <url>` | string | unset | Have the daemon launch its own browser at this URL, so the agent has autonomous control without relying on your tab |
+| `--headless` | boolean | `true` for `mcp` | Hide that browser |
+| `--headed` | boolean | `false` | Show it |
+| `--http` | boolean | `false` | Forward the HTTP verify endpoint flags to the daemon it spawns |
+| `--http-port N` | number | unset | Port for that endpoint |
+| `--http-token T` | string | unset | Bearer token for it |
+
+## The rule this command lives by
+
+The proxy **is** the MCP server the editor launched. Nothing respawns it, so an uncaught throw here is what a user experiences as "the MCP server disconnected". Three behaviours follow from that:
+
+- Crash handlers write to the proxy's own log file, not just stderr, because the editor swallows stderr.
+- A daemon that is not there is not fatal. The proxy answers `initialize` itself, serves the cached tool catalog, and retries a daemon on every client request. Present and complaining beats absent, because absent needs a human.
+- Reconnect is self-healing: if the daemon exited, crashed, was stopped, or shut itself down as idle, the reconnect path spawns a new one rather than retrying a dead port until the budget runs out.
+
+## What it prints
+
+Structured lines to the proxy log (`~/.reticle/`), not to your terminal, since stdout is the MCP transport.
+
+| Event | Meaning |
+| --- | --- |
+| `reticle_mcp_daemon_started` | It spawned a daemon |
+| `reticle_mcp_daemon_unavailable` | It could not, and is serving anyway |
+| `reticle_mcp_proxy_first_connect_failed` | The first connect was refused. Expected when the daemon is still coming up |
+
+## Exit codes
+
+Runs for the life of the editor session.
+
+## Worked example
+
+```json
+{
+  "mcpServers": {
+    "reticle": { "command": "npx", "args": ["@reticlehq/server", "mcp"] }
+  }
+}
+```
+
+<Card title="The tools this exposes" icon="screwdriver-wrench" href="/tools-overview">
+  The full surface your agent gets once this is registered.
+</Card>

package/docs/cli/open.mdx

@@ -0,0 +1,74 @@
+---
+title: reticle open
+description: Show the app in a browser, reusing the already-connected tab when there is one.
+icon: window-maximize
+---
+
+`reticle open` is the one-command "show me the app". It resolves the port, makes sure a daemon is up, and then either reuses the tab that is already connected or opens a new one.
+
+```bash
+npx @reticlehq/server open [url] [--port N]
+```
+
+## Arguments and flags
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `url` | string, positional, optional | unset | The URL to open. Omit it to reuse a connected tab |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port. If nothing is on it, `open` discovers a running daemon rather than making you hunt |
+
+It is idempotent. Re-running never piles up duplicate tabs.
+
+## What it prints
+
+One `reticle_open` line, whose fields say which of four things happened.
+
+| Fields | Meaning |
+| --- | --- |
+| `reusing` | A connected tab was already on the right page. Nothing was opened |
+| `reusing` + `requested` + `note` | A tab is connected on that origin but sitting on a different page. It was **left there**, not navigated. Drive it with `reticle_navigate` or open the URL yourself |
+| `opened` + `connected: true` | A browser was launched and a Reticle session appeared |
+| `opened` + `connected: false` + `note` | The URL went to the system default browser and no session showed up within 8 seconds. Almost always means the app carries no SDK, or dials a different port |
+| `error` | No app connected and no URL given, or the browser could not be launched |
+
+<Note>
+  `connected` is measured, not assumed. This command polls for a **new** session rather than printing
+  `{"opened": url}` unconditionally, so a run where nothing opened no longer looks like one where it did.
+  When the launcher itself cannot run, there is no `opened` field at all. Real capture:
+
+```
+{"event":"reticle_open","port":4499,"error":"could not launch a browser: spawn open ENOENT","recovery":"Nothing was opened. This command asks the OS to open a url in your default browser (`open` on this platform) and that failed, so the fix is on the OS side: open the url yourself, or set a default browser."}
+```
+
+Calling it with no URL when nothing has connected is the other `error` shape. It exits `0`, because reporting "there is nothing to show you" is a complete answer. Real capture, with the sentence break shown as `...`:
+
+```
+{"t":"2026-08-15T18:43:41.651Z","event":"reticle_open","port":4499,"error":"no app connected ... pass a url: reticle open <url>. Desktop app (Electron/Tauri)? There is no url to open: start it as you normally would and it connects to this bridge itself."}
+```
+
+</Note>
+
+<Warning>
+  This command does **not** use Reticle's own Chromium. It hands the URL to your system default
+  browser, so a `chromium` warning from `reticle doctor` has nothing to do with an `open` that came
+  back `connected: false`. That misread cost a reporter an afternoon in their bridge config.
+</Warning>
+
+<Warning>
+  For an Electron or Tauri app there is no URL to open. Start the app the way you normally would; it
+  dials the bridge itself.
+</Warning>
+
+## Exit codes
+
+| Code | Meaning                                                             |
+| ---- | ------------------------------------------------------------------- |
+| `0`  | Reused, opened, or reported that no app is connected                |
+| `1`  | A browser could not be launched, or the daemon could not be reached |
+
+## Worked example
+
+```bash
+npx @reticlehq/server open http://localhost:5173
+npx @reticlehq/server status    # confirm the session is really there
+```

package/docs/cli/restart.mdx

@@ -0,0 +1,60 @@
+---
+title: reticle restart
+description: Free the bridge port and put a daemon back on it, reporting each half separately.
+icon: rotate
+---
+
+`reticle restart` is [`reticle kill`](/cli/kill) followed by a daemon start that waits for a real bind.
+
+```bash
+npx @reticlehq/server restart [--port N] [--force]
+```
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which port to restart on |
+| `--force` | boolean | `false` | Passed to the kill half: clear a listener that is not a Reticle daemon |
+
+## The two halves are reported separately
+
+A restart that killed the old daemon and then could not start a new one leaves you somewhere quite different from one that could not kill anything at all, and a single `ok: false` cannot tell you which happened. So each half prints its own line.
+
+Real capture, restarting over a running daemon (exit `0`), with the long `note` trimmed at the ellipsis:
+
+```
+{"t":"2026-08-15T18:43:41.949Z","event":"reticle_killed","port":4499,"pid":78137,"escalated":false,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone ..."}
+{"t":"2026-08-15T18:43:42.258Z","event":"reticle_daemon_spawned","port":4499}
+```
+
+Real capture, when the port is held by something that is not ours (exit `1`). Both `reason` strings are trimmed at the ellipsis:
+
+```
+{"t":"2026-08-15T18:43:57.317Z","event":"reticle_kill_refused","port":4498,"reason":"pid 78795 (\"Python\") is listening, and it is not a Reticle daemon ... it never answered /status and it is not the pid Reticle recorded. Killing it would be killing someone else's process. Run it again with --force if that is what you meant, or start Reticle on another port.","holder":"Python"}
+{"t":"2026-08-15T18:43:57.318Z","event":"reticle_restart_aborted","port":4498,"reason":"the port was not freed, so nothing was started ... the old holder is still there"}
+```
+
+<Note>
+  The start half is `serve`'s, which waits for the daemon to **answer** before claiming it started
+  and exits non-zero when it does not. A restart never reports success for a daemon that never
+  bound.
+</Note>
+
+## Exit codes
+
+| Code | Meaning                                                   |
+| ---- | --------------------------------------------------------- |
+| `0`  | The port was freed and a daemon is answering on it        |
+| `1`  | The port was not freed, or the new daemon did not come up |
+
+## Worked example
+
+```bash
+npx @reticlehq/server restart         # after an upgrade, so the new version is the one serving
+npx @reticlehq/server status
+```
+
+<Card title="Why not lsof" icon="skull" href="/cli/kill">
+  The pipeline everyone reaches for kills the agent's own MCP proxy along with the daemon.
+</Card>

package/docs/cli/rollback.mdx

@@ -0,0 +1,35 @@
+---
+title: reticle rollback
+description: Restore the previously installed Reticle server version and restart.
+icon: arrow-rotate-left
+---
+
+`reticle rollback` is the undo for [`reticle update`](/cli/update). It restores the previous server version and restarts.
+
+```bash
+npx @reticlehq/server rollback
+```
+
+No flags.
+
+## What it prints
+
+Nothing on the happy path: `rollback()` replaces the process. A failure logs `reticle_rollback_failed` with the error message.
+
+Telemetry records the move as a `version_changed` event with `direction: "rollback"`, which is treated as a release-quality alarm rather than a routine version move.
+
+## Exit codes
+
+| Code | Meaning                                                     |
+| ---- | ----------------------------------------------------------- |
+| `0`  | The previous version was restored (the process is replaced) |
+| `1`  | There was nothing to roll back to, or the restore threw     |
+
+## Worked example
+
+```bash
+npx @reticlehq/server update
+# the new build misbehaves:
+npx @reticlehq/server rollback
+npx @reticlehq/server version
+```

package/docs/cli/serve.mdx

@@ -0,0 +1,69 @@
+---
+title: reticle serve
+description: Start the Reticle daemon on the bridge port and wait until it has actually bound.
+icon: play
+---
+
+`reticle serve` starts the daemon: the WebSocket bridge your app dials into, plus the tool engine behind it. It spawns a detached child and then waits for that child to answer `/status` before reporting success.
+
+```bash
+npx @reticlehq/server serve [--port N] [--drive <url>] [--headless] [--headed] [--http] [--http-port N] [--http-token T]
+```
+
+Most people never type this. Your agent runs [`reticle mcp`](/cli/mcp), which starts a daemon itself if one is not already up.
+
+## Flags
+
+| Flag | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Bridge port to bind |
+| `--drive <url>` | string | unset | Launch Reticle's own browser at this URL instead of waiting for your tab |
+| `--headless` | boolean | `true` for `serve` | Hide the browser |
+| `--headed` | boolean | `false` | Show it. `serve` owns the pooled browser behind leases, which is batch work, so it hides by default |
+| `--http` | boolean | `false` | Also expose the HTTP verify endpoint |
+| `--http-port N` | number | unset | Port for that endpoint |
+| `--http-token T` | string | unset | Bearer token the endpoint requires |
+
+## What it prints
+
+One structured line. When a daemon already owns the port, it says so and does nothing:
+
+```json
+{ "t": "2026-08-15T18:43:33.065Z", "event": "reticle_daemon_already_running", "port": 4499 }
+```
+
+A successful spawn logs `reticle_daemon_spawned` with the port:
+
+```json
+{ "t": "2026-08-15T18:43:32.604Z", "event": "reticle_daemon_spawned", "port": 4499 }
+```
+
+A port held by something that is not a Reticle daemon is refused up front rather than spawned into. The reason is repeated as plain text on stderr for the person who typed the command. Real capture, with `python3 -m http.server 4498` holding the port and the punctuation between the two halves of the reason shown as `...`:
+
+```
+{"t":"2026-08-15T18:43:57.478Z","event":"reticle_daemon_start_refused","port":4498,"presence":"foreign","reason":"port 4498 is held by another process that is not a Reticle daemon ... a daemon cannot bind it. Stop that process, or run Reticle on a different port (`--port`), then retry."}
+port 4498 is held by another process that is not a Reticle daemon ... a daemon cannot bind it. Stop that process, or run Reticle on a different port (`--port`), then retry.
+```
+
+## Exit codes
+
+| Code | Meaning                                                                           |
+| ---- | --------------------------------------------------------------------------------- |
+| `0`  | A daemon is up on the port, whether this run started it or found it               |
+| `1`  | The port is held by a foreign process, or the child never bound within 15 seconds |
+
+<Note>
+  `serve` reports the **bind**, not the spawn. It used to exit `0` the moment it forked, while the
+  child died on an `EADDRINUSE` nobody joined back up. It now waits for the daemon to answer.
+</Note>
+
+## Worked example
+
+```bash
+npx @reticlehq/server serve --port 4400
+npx @reticlehq/server status
+```
+
+<Card title="What the daemon is" icon="sitemap" href="/architecture">
+  The bridge, the tool engine, and where `.reticle/` lives.
+</Card>