diff --git a/docs/caddy.md b/docs/caddy.md
index 49ec82e..2aa63b8 100644
--- a/docs/caddy.md
+++ b/docs/caddy.md
@@ -1,18 +1,37 @@
 # Caddy and HAProxy in front of berth
 
-Recommended public deployments use HAProxy on external `:443` as a TCP
-SNI router:
+This is how I run a public berth leader. The goal is to put the public site
+and the cluster endpoint behind the same `:443`, on one VPS, without losing
+the agent's mTLS client certificate on the way in.
 
-- `leader.example.com:443` is passed through to Caddy on
-  `127.0.0.1:8443`; Caddy terminates public TLS and reverse-proxies to
+The trick is that HAProxy owns `:443` and routes by SNI at the TCP layer.
+It never terminates TLS. Caddy sits behind it on loopback and terminates
+public TLS only for the public site. The cluster traffic goes straight
+through to berth so the daemon still sees the agent cert.
+
+`scripts/setup-leader-vps.sh <base-domain>` writes all of the config below
+for you. If you'd rather wire it up by hand, the pieces are here. See
+[../README.md](../README.md) for the project itself and
+[deploy.md](deploy.md) for the broader deployment story.
+
+## How traffic flows
+
+Two names point at the same box, both on `:443`:
+
+- `leader.example.com:443` — HAProxy passes the TCP stream to Caddy on
+  `127.0.0.1:8443`. Caddy terminates public TLS and reverse-proxies to
   berth's plain-HTTP public listener on `127.0.0.1:11500`.
-- `cluster.example.com:443` is passed through directly to berth's
-  cluster listener on `127.0.0.1:11501`; HAProxy does not terminate TLS,
-  so berth still sees the agent's mTLS client certificate.
+- `cluster.example.com:443` — HAProxy passes the stream straight to berth's
+  cluster listener on `127.0.0.1:11501`. No TLS termination in the middle,
+  so berth still gets the agent's mTLS client certificate.
+
+Anything that arrives with neither SNI is dropped at HAProxy.
 
 ## Caddyfile
 
-Recommended 443/SNI example:
+This is `/etc/caddy/Caddyfile`. Replace `leader.example.com` and
+`cluster.example.com` with your own names; `8443`, `11500` and `11501` are
+the loopback ports.
 
 ```caddyfile
 {
@@ -30,8 +49,8 @@ http://cluster.example.com {
 https://leader.example.com:8443 {
     bind 127.0.0.1
     header {
-        # Caddy is behind HAProxy on :443; do not advertise loopback :8443
-        # as an external HTTP/3 endpoint.
+        # Caddy is behind HAProxy on :443; do not advertise loopback
+        # :8443 as an external HTTP/3 endpoint.
         -Alt-Svc
         Strict-Transport-Security "max-age=31536000"
     }
@@ -39,18 +58,63 @@ https://leader.example.com:8443 {
         header_up X-Forwarded-Proto https
     }
 }
+
+# Catch-all on the same loopback listener: any request whose Host header does
+# not match the public site above gets 421 Misdirected Request instead of
+# Caddy's empty 200. tls internal uses Caddy's local CA, which is fine here —
+# this site only sees connections that HAProxy already routed via the leader
+# SNI but with a wrong Host header.
+https://:8443 {
+    bind 127.0.0.1
+    tls internal
+    respond 421
+}
 ```
 
+A few things worth knowing:
+
+- `auto_https disable_redirects` keeps Caddy from standing up its own `:443`
+  redirector. HAProxy owns `:443`, not Caddy.
+- The `http://cluster.example.com` site answers `404`. Plain HTTP to the
+  cluster name shouldn't reach berth's mTLS listener, so Caddy just turns it
+  away.
+- `-Alt-Svc` strips the header that would otherwise tell clients to come back
+  on `:8443` over HTTP/3. That port is loopback-only; nothing external should
+  ever see it.
+
 ## HAProxy
 
+This is `/etc/haproxy/haproxy.cfg`. It's a pure TCP/SNI router — `mode tcp`
+everywhere, no `mode http`.
+
 ```haproxy
+global
+    log /dev/log local0
+    log /dev/log local1 notice
+    chroot /var/lib/haproxy
+    stats socket /run/haproxy/admin.sock mode 660 level admin
+    stats timeout 30s
+    user haproxy
+    group haproxy
+    daemon
+
+defaults
+    log global
+    mode tcp
+    option tcplog
+    timeout connect 5s
+    timeout client  1h
+    timeout server  1h
+
 frontend berth_https
     bind *:443
     tcp-request inspect-delay 5s
     tcp-request content accept if { req.ssl_hello_type 1 }
+    # Drop connections that don't carry one of our two expected SNI values.
+    # No default_backend: anything not matched here has already been rejected.
+    tcp-request content reject if !{ req.ssl_sni -i cluster.example.com leader.example.com }
     use_backend berth_cluster if { req.ssl_sni -i cluster.example.com }
     use_backend berth_public if { req.ssl_sni -i leader.example.com }
-    default_backend berth_public
 
 backend berth_public
     server caddy_public 127.0.0.1:8443 check
@@ -59,9 +123,17 @@ backend berth_cluster
     server berth_cluster 127.0.0.1:11501 check
 ```
 
+The `reject if !{...}` line is the important one. There's no `default_backend`:
+a connection has to present `cluster.example.com` or `leader.example.com` in
+its SNI, or HAProxy closes it. The long `timeout client`/`timeout server` of
+`1h` is for the cluster's long-lived mTLS WebSocket — agents hold that
+connection open.
+
 ## On the daemon side
 
-Set the corresponding `~/.berth/config.toml`:
+berth has to know it's behind a proxy: bind on loopback, speak plain HTTP on
+the public listener, and trust the forwarded headers Caddy adds. Put this in
+`~/.berth/config.toml`:
 
 ```toml
 [server]
@@ -81,9 +153,23 @@ port = 11501
 bind = "127.0.0.1"
 ```
 
-Set `BERTH_LEADER_URL=https://cluster.example.com` in the berth
-systemd unit so enrollment URIs advertise the external 443 endpoint
-instead of the loopback cluster port.
+What these do:
+
+- `[server] leader_only` runs the leader as control-plane only — no local
+  Docker or NVIDIA required, every deploy targets a remote agent. Drop it if
+  the leader box also has GPUs.
+- `[public] scheme = "http"` plus `trust_proxy_headers` makes berth bind plain
+  HTTP and honour the `X-Forwarded-Proto` Caddy sends. `forwarded_allow_ips`
+  restricts that trust to the loopback proxy, so a client can't spoof the
+  header.
+- Both listeners bind `127.0.0.1` because HAProxy is the only thing that
+  should reach them.
+
+Then set `BERTH_LEADER_URL=https://cluster.example.com` in berth's systemd
+unit. That's the URL berth puts in the enrollment URIs it hands out. Without
+it, agents would be told to connect to the loopback cluster port instead of
+the external `:443` endpoint. The leader installer and `berth deploy bootstrap
+--sni-443` both set this for you.
 
 ## Verifying the path
 
@@ -98,3 +184,9 @@ curl -i https://leader.example.com/healthz
 curl -k https://cluster.example.com/admin/ca.pem
 # → the CA PEM the daemon serves on the cluster listener
 ```
+
+The first request proves the public path: HAProxy → Caddy → berth on
+`:11500`. The second proves the cluster path goes straight through to berth on
+`:11501` — `-k` because you don't have the CA yet, which is exactly what that
+endpoint hands you. If either one hangs, check that the SNI name you're
+hitting matches one of the two HAProxy `use_backend` rules.
diff --git a/docs/deploy.md b/docs/deploy.md
index e2520c1..d38becd 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -1,38 +1,50 @@
 # Deploying berth on a public VPS
 
-Operator guide for standing up a leader-only control plane on a small
-Linux VPS with public DNS, Caddy for the public UI/API, HAProxy for
-443/TLS passthrough routing, and one or more remote GPU hosts joining
-as agents.
-
-The `berth deploy bootstrap` command (see [Bootstrap](#bootstrap) below)
-automates most of this. This page documents the underlying recipe so
-you can run it manually or audit what the bootstrap does.
-
-## Requirements
-
-**VPS**:
-- 2 vCPU / 2 GB RAM is plenty (the leader doesn't run inference).
-- ~5 GB disk for db / ca / logs.
-- Public IPv4 (or IPv6).
-- Ports 80 and 443 open inbound. Agents use 443, which works through
-  most corporate egress firewalls. The berth cluster listener stays on
-  loopback (`127.0.0.1:11501`) behind HAProxy TLS passthrough.
-- Outbound to the agents' GPU hosts is *not* required — agents always
-  dial the leader.
-
-**DNS**:
-- Two A records (or AAAA) pointing at the VPS:
-  - `leader.example.com` for the public UI/API.
-  - `cluster.example.com` for agent enrollment and the mTLS WebSocket.
-
-**Agents** (the GPU hosts):
-- Outbound reachability to `cluster.example.com:443`. No inbound
-  needed — useful behind corporate VPNs that block client-to-client
-  traffic and non-standard outbound ports.
+This is the operator guide for the leader: a small public VPS that serves
+the OpenAI-compatible API and the UI, and that GPU agents dial back into
+over mTLS. The leader is control-plane-only. No models run on it. The
+weights live on the enrolled agent hosts, and the leader routes to them.
+
+If you just want it done, run [the one-command setup](#one-command-vps-setup)
+and skip the rest. The manual recipe below documents what that script does,
+so you can run the steps by hand or audit them. For the agent side and how
+the WebSocket tunnel works, see [multi-node.md](multi-node.md).
+
+## What you need
+
+The leader does no inference, so it's cheap.
+
+- 2 vCPU / 2 GB RAM is plenty.
+- ~5 GB disk for the DB, CA, and logs.
+- A public IPv4 or IPv6.
+- Ports 80 and 443 open inbound, nothing else. Agents connect on 443,
+  which gets through most corporate egress firewalls. The berth cluster
+  listener stays on loopback (`127.0.0.1:11501`) behind HAProxy doing TLS
+  passthrough.
+- No outbound to the GPU hosts. Agents always dial the leader, never the
+  other way around.
+
+You need two DNS records, both pointing at the VPS (A or AAAA):
+
+- `leader.example.com` — the public UI and API.
+- `cluster.example.com` — agent enrollment and the mTLS WebSocket.
+
+Set these up *before* you run the installer. The setup script checks the
+domain is well-formed but it can't make DNS resolve for you, and HAProxy
+routes by the SNI hostname.
+
+On the GPU hosts you only need outbound reachability to
+`cluster.example.com:443`. Nothing listens for inbound. That's the whole
+point: agents work fine behind corporate VPNs that block client-to-client
+traffic and non-standard outbound ports.
 
 ## Topology
 
+HAProxy owns external `:443` and routes by SNI. The public hostname goes
+to Caddy, which terminates TLS and proxies to the daemon's loopback port.
+The cluster hostname is passed straight through so the agent's client
+certificate survives — Caddy never sees it.
+
 ```
 [ public internet ]
         ↓ :443
@@ -43,144 +55,259 @@ you can run it manually or audit what the bootstrap does.
                                 (TLS passthrough; agent mTLS preserved)
 ```
 
+The ports:
+
+| Port | Bind | What |
+| --- | --- | --- |
+| 443 | public | HAProxy, SNI router |
+| 80 | public | Caddy, redirects to HTTPS |
+| 8443 | `127.0.0.1` | Caddy public HTTPS, behind HAProxy |
+| 11500 | `127.0.0.1` | berth public API/UI, behind Caddy |
+| 11501 | `127.0.0.1` | berth cluster mTLS listener, behind HAProxy passthrough |
+
+Do not expose 11501 publicly in this setup. Only HAProxy should reach
+`127.0.0.1:11501`.
+
 ## One-command VPS setup
 
-Clone berth on a fresh Ubuntu/Debian VPS, make sure DNS already points
-at the box, then run:
+Clone berth on a fresh Ubuntu or Debian box, confirm DNS already points at
+it, then run:
 
 ```bash
 sudo ./scripts/setup-leader-vps.sh example.com
 ```
 
-This derives:
+It derives the two hostnames from the base domain:
+
+```text
+leader.example.com    public UI/API on external 443
+cluster.example.com   agent enrollment + mTLS WebSocket on external 443
+```
+
+The script runs twelve steps and prints one status line each. Full output
+of every step goes to `/var/log/berth-install.log`; the terminal stays
+quiet unless something fails. It looks like this:
 
 ```text
-leader.example.com   public UI/API
-cluster.example.com  agent enrollment + mTLS WebSocket
+  berth leader installer    example.com
+  ────────────────────────────────────────────────────────────
+  [ 1/12] Installing OS packages ························· ok  14s
+  [ 2/12] Creating berth user and directories ·········· ok
+  [ 3/12] Copying checkout to /opt/berth/src ··········· ok
+  [ 4/12] Installing berth (hash-pinned deps) ·········· ok  39s
+  [ 5/12] Installing operator wrapper ·················· ok
+  [ 6/12] Bootstrapping config, CA, DB, key ············ ok
+  [ 7/12] Writing systemd unit ························· ok
+  [ 8/12] Writing Caddy + HAProxy config ··············· ok
+  [ 9/12] Validating service configs ··················· ok
+  [10/12] Firewall + unattended upgrades ··············· ok
+  [11/12] Kernel + SSH hardening + fail2ban ············ ok
+  [12/12] Starting services ···························· ok
 ```
 
-The script installs Caddy + HAProxy, creates the `berth` system user,
-installs berth into `/opt/berth/venv`, writes a leader-only
-`/var/lib/berth/config.toml`, bootstraps the DB/CA/key pepper/admin key,
-writes systemd/Caddy/HAProxy configs, installs `/usr/local/bin/berth` as the
-operator command, opens only `80/tcp` and `443/tcp` in UFW, and starts the
-services.
+If a step fails, the script stops, prints the last 20 lines of the install
+log inline, and points you at the full log. Pass `-v` / `--verbose` to
+stream every command live instead of logging it quietly. Pass `--force` to
+overwrite an existing `config.toml`.
+
+At the end it prints a framed summary with the first admin key (shown once),
+the two URLs, and the log path:
+
+```text
+  ────────────────────────────────────────────────────────────
+  ✓ berth leader is up
+
+    Admin key  (shown once — save it now)
+        sk-...
 
-After setup, use short commands:
+    Public UI/API     https://leader.example.com
+    Agent endpoint    https://cluster.example.com
+
+    Verify            berth status
+    Enroll an agent   berth nodes enroll <label>
+    Reset state       berth wipe
+    Install log       /var/log/berth-install.log
+```
+
+Save the admin key now. It isn't shown again. If keys already exist (a
+re-run), the summary says so and doesn't mint a new one.
+
+### What the script actually does
+
+In order, the twelve steps:
+
+1. Installs OS packages: `ca-certificates`, `caddy`, `curl`, `fail2ban`,
+   `git`, `haproxy`, `python3-venv`, `ufw`, `unattended-upgrades`.
+2. Creates the `berth` system user (nologin, home `/var/lib/berth`, mode
+   0700) and `/opt/berth`.
+3. Copies your checkout to `/opt/berth/src`, excluding VCS state, caches,
+   and anything that looks like a local secret (`.env*`, `*.pem`, `*.key`,
+   `id_rsa*`, `*.kdbx`, editor configs).
+4. Builds the venv at `/opt/berth/venv` and installs berth with hash-pinned
+   deps. It uses `uv export --frozen` from `uv.lock` to produce a
+   requirements file with hashes, installs it with `--require-hashes`, then
+   installs the project itself with `--no-deps`. The VPS gets exactly what
+   CI tested. (The script refuses to run if `uv.lock` is missing — run
+   `uv lock` before deploying.)
+5. Writes `/etc/berth/operator.env` and installs the `berth` wrapper to
+   `/usr/local/bin/berth` so you run short commands as yourself.
+6. Runs `berth deploy bootstrap --quiet` to write `config.toml`, generate
+   the CA, init the DB, and mint the first admin key. (See
+   [Bootstrap](#bootstrap).)
+7. Writes the systemd unit at `/etc/systemd/system/berth.service`.
+8. Writes `/etc/caddy/Caddyfile` and `/etc/haproxy/haproxy.cfg`.
+9. Validates both with `caddy validate` and `haproxy -c` before starting
+   anything.
+10. Opens 22, 80, and 443 in UFW (enables UFW), and turns on unattended
+    security upgrades.
+11. Hardens the box: sysctl (`/etc/sysctl.d/99-berth.conf`), SSH (root login
+    off, password auth off, validated with `sshd -t` before reload), and a
+    fail2ban jail for sshd.
+12. Starts and enables `berth`, `caddy`, and `haproxy`.
+
+After it finishes, use the short commands. The wrapper runs berth as the
+`berth` user against `/var/lib/berth` and defaults the leader URL to your
+cluster host:
 
 ```bash
-berth status
-berth nodes enroll gpu-host-1
+berth status                          # is the leader up
+berth nodes enroll gpu-host-1         # mint an enrollment URI for an agent
 berth key create teammate --tier admin
-berth wipe   # reset local berth state and start over
-```
-
-## Bring-up (manual)
-
-1. **VPS bootstrap** — fresh Ubuntu/Debian, as a non-root user with sudo:
-
-   ```bash
-   # System prep
-   sudo useradd -r -m -d /var/lib/berth berth
-   sudo apt-get install -y python3-venv caddy haproxy ufw
-   ```
-
-2. **Install Caddy**:
-
-   ```bash
-   sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
-   curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
-   curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
-   sudo apt update && sudo apt install -y caddy
-   ```
-
-3. **Drop the Caddy + HAProxy configs** (see [caddy.md](caddy.md)).
-   HAProxy owns external `:443` and routes by SNI. Caddy handles
-   `leader.example.com`; berth handles `cluster.example.com` directly
-   on loopback so agent client certificates are preserved.
-
-4. **Install berth and the operator command**:
-
-   ```bash
-   sudo install -d -o berth -g berth -m 0755 /opt/berth
-   sudo -u berth python3 -m venv /opt/berth/venv
-   sudo -u berth /opt/berth/venv/bin/pip install /path/to/berth
-   sudo install -d -m 0755 /etc/berth
-   sudo tee /etc/berth/operator.env >/dev/null <<'EOF'
-   BERTH_REAL=/opt/berth/venv/bin/berth
-   BERTH_HOME=/var/lib/berth
-   BERTH_USER=berth
-   BERTH_LEADER_URL_DEFAULT=https://cluster.example.com
-   EOF
-   sudo install -m 0755 packaging/berth-wrapper /usr/local/bin/berth
-   ```
-
-5. **Configure** `/var/lib/berth/config.toml`:
-
-   ```toml
-   [server]
-   leader_only = true
-
-   [public]
-   host = "leader.example.com"
-   port = 11500
-   bind = "127.0.0.1"                # Caddy is on the same box
-   scheme = "http"                   # Caddy terminates TLS
-   trust_proxy_headers = true
-   forwarded_allow_ips = "127.0.0.1"
-
-   [cluster]
-   host = "cluster.example.com"
-   bind = "127.0.0.1"                # HAProxy passes TLS through
-   port = 11501                      # internal loopback port
-   ```
-
-   Set the advertised agent URL in the systemd unit:
-
-   ```ini
-   Environment=BERTH_LEADER_URL=https://cluster.example.com
-   ```
-
-6. **Install the systemd unit** (`packaging/berth.service` in
-   this repo):
-
-   ```bash
-   sudo cp packaging/berth.service /etc/systemd/system/
-   sudo systemctl daemon-reload
-   sudo systemctl enable --now berth
-   sudo systemctl status berth    # confirm active (running)
-   ```
-
-7. **Mint the first admin key** over the UDS (auth-bypassed for the
-   first key only):
-
-   ```bash
-   berth key create root --tier admin
-   # ← prints sk-… once. Save it somewhere safe.
-   ```
-
-8. **Enroll a GPU agent**:
-
-   ```bash
-   # On the leader:
-   berth nodes enroll gpu-host-1
-   # → emits a berth://enroll?leader=…&token=…&ca_fp=… URI
-
-   # On the GPU host:
-   berth agent register --uri '<paste>'
-   berth agent start                # compact foreground status
-   berth agent logs --follow        # full agent log, if needed
-   ```
+berth wipe                            # reset local berth state and start over
+```
+
+## Manual bring-up
+
+The recipe the script automates, step by step. Run these on a fresh Ubuntu
+or Debian box as a non-root user with sudo.
+
+### 1. System prep
+
+```bash
+sudo useradd -r -m -d /var/lib/berth berth
+sudo apt-get install -y python3-venv caddy haproxy ufw
+```
+
+### 2. Install Caddy
+
+If `caddy` isn't already packaged for your release, add the Cloudsmith repo:
+
+```bash
+sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+sudo apt update && sudo apt install -y caddy
+```
+
+### 3. Caddy + HAProxy config
+
+HAProxy owns external `:443` and routes by SNI. Caddy handles
+`leader.example.com`. berth handles `cluster.example.com` directly on
+loopback so agent client certificates are preserved through the
+passthrough. The full Caddyfile and `haproxy.cfg` are in
+[caddy.md](caddy.md); `berth deploy bootstrap --sni-443` also prints
+ready-to-paste versions of both.
+
+### 4. Install berth and the operator command
+
+```bash
+sudo install -d -o berth -g berth -m 0755 /opt/berth
+sudo -u berth python3 -m venv /opt/berth/venv
+sudo -u berth /opt/berth/venv/bin/pip install /path/to/berth
+sudo install -d -m 0755 /etc/berth
+sudo tee /etc/berth/operator.env >/dev/null <<'EOF'
+BERTH_REAL=/opt/berth/venv/bin/berth
+BERTH_HOME=/var/lib/berth
+BERTH_USER=berth
+BERTH_LEADER_URL_DEFAULT=https://cluster.example.com
+EOF
+sudo install -m 0755 packaging/berth-wrapper /usr/local/bin/berth
+```
+
+### 5. Configure `/var/lib/berth/config.toml`
+
+```toml
+[server]
+leader_only = true
+
+[public]
+host = "leader.example.com"
+port = 11500
+bind = "127.0.0.1"                # Caddy is on the same box
+scheme = "http"                   # Caddy terminates TLS
+trust_proxy_headers = true
+forwarded_allow_ips = "127.0.0.1"
+
+[cluster]
+host = "cluster.example.com"
+bind = "127.0.0.1"                # HAProxy passes TLS through
+port = 11501                      # internal loopback port
+```
+
+Set the advertised agent URL in the systemd unit so agents know where to
+dial back:
+
+```ini
+Environment=BERTH_LEADER_URL=https://cluster.example.com
+```
+
+### 6. Install the systemd unit
+
+The unit ships as `packaging/berth.service`:
+
+```bash
+sudo cp packaging/berth.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now berth
+sudo systemctl status berth    # confirm active (running)
+```
+
+### 7. Mint the first admin key
+
+The first key is minted over the local UDS with auth bypassed (first key
+only):
+
+```bash
+berth key create root --tier admin
+# prints sk-... once. Save it somewhere safe.
+```
+
+If you ran bootstrap, this already happened — skip it.
+
+### 8. Enroll a GPU agent
+
+```bash
+# On the leader:
+berth nodes enroll gpu-host-1
+# emits a berth://enroll?leader=…&token=…&ca_fp=… URI (single-use, 10 min)
+
+# On the GPU host:
+berth agent register --uri '<paste>'
+berth agent start                # compact foreground status
+berth agent logs --follow        # full agent log, if needed
+```
+
+The enrollment URI bundles the leader URL, a single-use token, and the CA
+fingerprint. The fingerprint pin is what stops a swapped CA from
+man-in-the-middling the bootstrap. More on the agent side in
+[multi-node.md](multi-node.md).
 
 ## Bootstrap
 
-`berth deploy bootstrap --domain <fqdn>` wraps steps 5 and 7 (write
-config.toml + mint first admin key) plus the DB/CA/pepper init that
-the daemon would otherwise do on first start. Idempotent: re-running
-preserves the existing config and skips the key mint when keys
+`berth deploy bootstrap` does the daemon-side setup the installer's step 6
+runs, and that you'd otherwise leave to the daemon's first start: write
+`config.toml`, generate the CA, init the DB (so migrations run once, under
+the lock, with you at the keyboard), create the key pepper, and mint the
+first admin key. It's idempotent except for the first key — a re-run keeps
+the existing config (unless you pass `--force`) and skips the mint when keys
 already exist.
 
-Typical first-run on the VPS:
+It deliberately does *not* touch `/etc`, install packages, or write systemd
+units. Those are sudo-territory and OS-specific, so bootstrap prints the
+exact commands and lets you run them. Use `scripts/setup-leader-vps.sh`
+when you want all of that automated too.
+
+The typical SNI-on-443 first run:
 
 ```bash
 berth deploy bootstrap \
@@ -190,62 +317,90 @@ berth deploy bootstrap \
     --leader-only
 ```
 
-Output includes:
-
-- Ready-to-paste Caddy and HAProxy snippets.
-- The first admin API key (shown once — save it).
-- The exact systemd commands to enable + start the service.
-
-For a direct-TLS deployment (no Caddy in front), pass `--direct-tls`.
-The daemon's TLS will use the cluster-CA-signed server cert by default;
-override with `[public_tls]` in `config.toml` if you want a custom
-chain (Let's Encrypt minted out-of-band, an internal CA, etc.).
-
-To reset a local leader and start over without uninstalling packages or proxy
-configs:
+Flags worth knowing:
+
+- `--domain` — public FQDN clients use (required).
+- `--cluster-domain` — FQDN agents dial. Required with `--sni-443`.
+- `--sni-443` — generate HAProxy + Caddy config so both hostnames share
+  external 443 by SNI, keeping the cluster listener on loopback with TLS
+  passthrough.
+- `--leader-only` — write `[server] leader_only = true` for a
+  control-plane-only VPS. This is what you want here.
+- `--public-port` (default 11500), `--cluster-port` (default 11501),
+  `--public-tls-port` (default 8443) — override the ports.
+- `--berth-home` — override the daemon home (default `~/.berth`).
+- `--force` — overwrite an existing `config.toml`.
+- `--direct-tls` — bind the public listener with TLS directly, no Caddy in
+  front. Useful when you already manage certs elsewhere. Can't be combined
+  with `--sni-443`.
+- `--quiet` / `-q` — print only the status block and admin key, skip the
+  "Next steps" runbook. This is what the installer uses.
+
+Without `--quiet`, the output includes ready-to-paste Caddy and HAProxy
+snippets, the first admin key (once), and the exact systemd commands to
+enable and start the service.
+
+For `--direct-tls`, the daemon's TLS uses the cluster-CA-signed server cert
+by default. Override it with `[public_tls]` in `config.toml` if you want a
+different chain — Let's Encrypt minted out of band, an internal CA, whatever.
+
+### Resetting
+
+To wipe a local leader and start over without uninstalling packages or
+touching the proxy configs:
 
 ```bash
 berth wipe
 ```
 
-`berth wipe` prompts before deleting state. Use `berth wipe --yes` only for
+It prompts before deleting state. Use `berth wipe --yes` (or `-y`) only in
 automation.
 
-Operator-controlled sudo steps (install systemd unit, install Caddy and
-HAProxy) stay manual on purpose — bootstrap doesn't write to /etc or run
-package managers. Use `scripts/setup-leader-vps.sh` when you want those
-steps automated.
-
 ## Backup and DR
 
-`berth backup create /var/backups/berth-$(date +%F).tar.gz` snapshots
-the recoverable state:
+This is the part that bites people. The CA private key is the
+keys-to-the-kingdom: lose it and every agent certificate is dead. Treat the
+backup tarball like a credential.
+
+```bash
+berth backup create /var/backups/berth-$(date +%F).tar.gz
+```
+
+That snapshots the recoverable state:
+
+- `db.sqlite` — taken via SQLite's `.backup` so it's consistent even under
+  load.
+- `ca/` — the CA cert and private key. Losing this invalidates every agent
+  cert.
+- `key_pepper` — losing this invalidates every API key.
+- `config.toml`.
 
-- `db.sqlite` (consistent via SQLite `.backup`)
-- `ca/` (CA cert + private key — losing this invalidates every agent
-  cert)
-- `key_pepper` (losing this invalidates every API key)
-- `config.toml`
+Not in the backup, on purpose:
 
-**Not in the backup** (deliberately):
-- Model weights (`models/`) — large; re-downloadable from HF.
+- Model weights (`models/`) — large, and re-downloadable from Hugging Face.
 - Logs.
 
-Run on a cron and copy off-host. The CA private key is the
-keys-to-the-kingdom — treat the tarball like a credential.
+Run it on a cron and copy the tarball off-host. If your backup tool doesn't
+encrypt at rest, exclude the CA directory from it and handle that one
+separately.
 
 ## Operational tips
 
-- Use `/readyz` (not `/healthz`) for load-balancer health probes —
-  `/healthz` returns 200 unconditionally; `/readyz` blocks until
-  startup is complete and the DB is reachable.
-- `/metrics` requires a non-revoked API key (any tier), including during
-  first-run bootstrap before any key exists.
-- In the recommended 443/SNI setup, do not expose `11501/tcp` publicly.
-  Only HAProxy should reach `127.0.0.1:11501`.
-- Per-IP rate limiting respects `X-Forwarded-For` when
-  `trust_proxy_headers = true` — make sure Caddy strips spoofed
-  inbound XFF headers before forwarding (`request_header -X-Forwarded-For`
-  in the Caddyfile if you want full control).
-- The CA directory should be excluded from any backup tool that
-  doesn't already encrypt at rest.
+- For load-balancer health probes use `/readyz`, not `/healthz`. `/healthz`
+  returns 200 unconditionally (it only proves the process is up). `/readyz`
+  returns 503 until the lifespan has finished and the DB answers `SELECT 1`,
+  then 200.
+- `/metrics` requires a non-revoked API key of any tier — including during
+  first-run bootstrap, before any key exists. Mint a key first.
+- In the 443/SNI setup, never expose `11501/tcp` publicly. Only HAProxy
+  reaches `127.0.0.1:11501`.
+- Per-IP rate limiting honours `X-Forwarded-For` when
+  `trust_proxy_headers = true`. Make sure Caddy strips spoofed inbound XFF
+  before forwarding — add `request_header -X-Forwarded-For` to the Caddyfile
+  if you want to be strict about it.
+- `berth status` is the quick "is the leader healthy" check.
+
+For the agent side, enrollment internals, and routing, see
+[multi-node.md](multi-node.md). For the full proxy configs, see
+[caddy.md](caddy.md). When something misbehaves, start with
+[troubleshooting.md](troubleshooting.md).
diff --git a/docs/multi-node.md b/docs/multi-node.md
index be7b80e..d391aa8 100644
--- a/docs/multi-node.md
+++ b/docs/multi-node.md
@@ -1,42 +1,30 @@
-# Multi-Node berth
+# Multi-node berth
 
-This page is the operator's guide to running a leader plus one or more
-agent hosts. It sticks to setup, verification, and troubleshooting.
+This is the operator's guide to running a leader plus one or more GPU agents. It covers setup, verification, and the things that go wrong. If you only have one box, you don't need any of this — start with the [README](../README.md) and come back when the second box shows up.
 
-> **Current status.** The cluster fabric, enrollment, remote start/stop,
-> tunneled proxying, health probes, and remote log streaming are wired and
-> tested. Direct-LAN data-plane mode, replicas, automatic public ACME, and
-> fine-grained per-agent request metrics are still follow-up work.
+The short version: one leader serves the API. Each extra GPU host runs a thin agent that dials home to the leader over an mTLS WebSocket. Start, stop, health checks, logs, and `/v1/*` traffic all flow over that one link. The agent needs nothing but outbound HTTPS to the leader's cluster port — no inbound ports, no VPN, no NAT punching.
+
+> **Status.** The cluster fabric, enrollment, remote start/stop, tunneled proxying, health probes, and remote log streaming are wired up and tested. Direct-LAN data-plane mode, replicas, automatic public ACME, and fine-grained per-agent request metrics are still on the list. See [Status: what works today](#status-what-works-today) for the honest line on each.
 
 ## Concepts
 
-- **Leader.** The existing `berth daemon`. Owns SQLite state, the
-  OpenAI-compatible API, the admin API, the router, and the lifecycle
-  manager. There is exactly one leader.
-- **Agent.** A thin daemon (`berth agent start`) that runs on each
-  additional GPU host. It dials home to the leader over an mTLS
-  WebSocket and exposes the host's local Docker through that channel.
-- **Public listener.** The leader's external-facing HTTPS port
-  (default `:11500`). Serves `/v1/*`, `/admin/*` (bearer-auth),
-  `/healthz`, `/metrics`. Operator supplies a publicly-trusted cert
-  for browser/SDK clients; falls back to a self-signed cluster-CA
-  cert in dev.
-- **Cluster listener.** A second HTTPS port (default `:11501`) with
-  mTLS and its own cert chain. Serves `/cluster/agent` (WS),
-  `/admin/nodes/register` (token-gated), `/admin/ca.pem`
-  (fingerprint-pinned). This is the only port agents ever touch.
-- **Cluster CA.** A self-signed root that lives only on the leader at
-  `~/.berth/ca/`. Used to mint both the leader's cluster-listener
-  server cert and each agent's mTLS client cert. Agents pin its
-  SHA-256 fingerprint at enrollment.
-- **Node.** A row in the leader's `nodes` table. The leader's own host
-  is always present as `label=local`; each enrolled agent gets one
-  more row.
+There are six words you need before the rest of this makes sense.
+
+**Leader.** The plain `berth daemon` you already know. It owns the SQLite state, the OpenAI-compatible API, the admin API, the router, and the lifecycle manager. There is exactly one leader.
+
+**Agent.** A thin daemon (`berth agent start`) on each extra GPU host. It dials home to the leader over an mTLS WebSocket and exposes that host's local Docker through the channel. No API of its own.
+
+**Public listener.** The leader's external HTTPS port, default `:11500`. Serves `/v1/*`, `/admin/*` (bearer auth), `/healthz`, `/metrics`. You supply a publicly-trusted cert for browser and SDK clients; in dev it falls back to a self-signed cluster-CA cert.
+
+**Cluster listener.** A second HTTPS port, default `:11501`, with mTLS and its own cert chain. Serves `/cluster/agent` (the WebSocket), `/admin/nodes/register` (token-gated), and `/admin/ca.pem` (fingerprint-pinned). This is the only port an agent ever touches.
+
+**Cluster CA.** A self-signed root that lives only on the leader, at `~/.berth/ca/`. It mints the leader's cluster-listener server cert and every agent's mTLS client cert. Agents pin its SHA-256 fingerprint at enrollment, so a swapped CA during bootstrap fails loudly.
+
+**Node.** A row in the leader's `nodes` table. The leader's own host is always there as `label=local`. Each enrolled agent adds one more row.
 
 ## Install
 
-Both the leader and each agent install the same package. There is no
-separate "agent" build — the role is chosen at runtime.
+Leader and agent install the same package. There is no separate agent build — the role is decided at runtime.
 
 ```bash
 git clone https://github.com/Mapika/berth
@@ -45,23 +33,19 @@ uv tool install --editable .
 berth doctor
 ```
 
-Linux + NVIDIA + Docker 24+ requirements apply to every agent host. The leader
-still needs Docker because it owns lifecycle orchestration and can run local
-deployments, but it can act mostly as a control plane when workloads target
-remote node labels.
+Linux, NVIDIA, and Docker 24+ apply to every agent host, because that's where the engines actually run. The leader needs Docker too — it owns lifecycle orchestration and can run local deployments — but it can sit mostly as a control plane when all the workloads target remote node labels. If that's your plan, run `berth doctor --leader-only` on the leader to skip the GPU checks, and set `[server] leader_only = true` (or `berth deploy bootstrap --leader-only`) so the daemon doesn't expect local GPUs.
 
-## Quick start (LAN, single afternoon)
+## Quick start: LAN, one afternoon
 
-The leader autodetects its LAN IP and serves TLS on both ports
-directly from uvicorn — no reverse proxy.
+On a LAN you don't need a reverse proxy or a real cert. The leader autodetects its LAN IP and serves TLS on both ports straight from uvicorn.
 
-### Leader
+### 1. Start the leader
 
 ```bash
 berth daemon start
 ```
 
-The startup banner prints both URLs and the CA fingerprint:
+The banner prints both URLs and the CA fingerprint:
 
 ```
 daemon started (pid …)
@@ -72,13 +56,11 @@ cluster : https://192.168.0.164:11501  (cert: berth cluster CA)
             ca fingerprint: sha256:7f3a…
 ```
 
-The "using cluster-CA cert" warning is expected on a LAN — you don't
-need a publicly-trusted cert for traffic that never leaves your
-network. Browser/SDK clients hitting the public URL will have to trust
-the cluster CA (or you can ignore the warning if you only call from
-the loopback / local CLI / a trusting `httpx` client).
+The "using cluster-CA cert" warning is expected on a LAN. You don't need a publicly-trusted cert for traffic that never leaves your network. Browser and SDK clients hitting the public URL will have to trust the cluster CA — or you just ignore the warning if you only call from loopback, the local CLI, or a trusting `httpx` client.
+
+### 2. Mint an enrollment URI
 
-Mint an enrollment URI for the new GPU host:
+On the leader, name the new GPU host:
 
 ```bash
 $ berth nodes enroll gpu-rig-2
@@ -90,9 +72,9 @@ On the agent host, run:
   berth agent register --uri 'berth://enroll?leader=…&token=…&ca_fp=…'
 ```
 
-Copy the entire `berth agent register --uri '…'` line.
+Copy the whole `berth agent register --uri '…'` line. The token is single-use and expires in 10 minutes.
 
-### Agent
+### 3. Register and start the agent
 
 On the new GPU host:
 
@@ -102,71 +84,61 @@ git clone https://github.com/Mapika/berth
 cd berth
 uv tool install --editable .
 
-# Paste the line you copied.
+# Paste the line you copied from the leader.
 berth agent register --uri 'berth://enroll?leader=…&token=…&ca_fp=…'
 berth agent start
 ```
 
-What `--uri` does under the hood:
+Here's what `register --uri` actually does:
 
-1. Parses leader URL + token + CA fingerprint out of the URI.
-2. Fetches `https://<leader>/admin/ca.pem` with TLS verification
-   disabled for this one request.
-3. Verifies `sha256(downloaded ca.pem)` equals the pinned fingerprint.
-   This closes the standard MITM-during-CA-bootstrap hole — an
-   attacker who substitutes their own CA fails this check.
+1. Parses the leader URL, token, and CA fingerprint out of the URI.
+2. Fetches `https://<leader>/admin/ca.pem` with TLS verification off — just for this one request, because the agent doesn't trust the CA yet.
+3. Checks that `sha256(downloaded ca.pem)` equals the pinned fingerprint. This closes the MITM-during-CA-bootstrap hole: an attacker who substitutes their own CA fails the check and registration aborts.
 4. Writes the verified CA to `~/.berth/ca.crt`.
-5. POSTs the token to `/admin/nodes/register`, gets back a per-host
-   mTLS client cert, writes `agent.crt`, `agent.key`, and
-   `agent.yaml`.
+5. POSTs the token to `/admin/nodes/register`, gets back a per-host mTLS client cert, and writes `agent.crt`, `agent.key`, and `agent.yaml`.
 
-After that, `berth agent start` runs the agent loop and connects to
-`wss://<cluster URL>/cluster/agent` with mTLS. In an interactive
-terminal it shows a compact live status panel; full reconnect,
-download, Docker, and warning details go to `~/.berth/logs/agent.log`.
-Use `berth agent logs --follow` to tail that file, or
-`berth agent start --verbose` when you want raw logs and progress bars
-in the foreground.
+After that, `berth agent start` runs the agent loop and connects to `wss://<cluster URL>/cluster/agent` over mTLS. In an interactive terminal it shows a compact live status panel — status, leader, node, uptime, current operation, last error, recent activity. The full reconnect, download, Docker, and warning detail goes to `~/.berth/logs/agent.log`. Tail it with `berth agent logs --follow`, or run `berth agent start --verbose` when you want the raw logs and progress bars in the foreground instead of the panel.
 
-### Verify (from the leader)
+To keep the agent running across reboots, install it as a service:
 
 ```bash
-berth nodes ls            # new node should appear `ready`
-berth nodes show <id>     # GPU inventory, agent_version, last heartbeat
+berth agent install-service            # a --user unit (default)
+berth agent install-service --system   # a system unit; run via sudo
 ```
 
-### Run on an agent
+The `--user` unit lands in `~/.config/systemd/user/berth-agent.service`. Run `loginctl enable-linger $USER` so it survives logout. The `--system` unit goes to `/etc/systemd/system/` and needs a non-root account for `User=` (it picks up `$SUDO_USER`). Both enable and start the unit immediately if `systemctl` is present.
 
-Target the node label when launching directly:
+### 4. Verify, from the leader
+
+```bash
+berth nodes ls            # the new node should show up `ready`
+berth nodes show <id>     # GPU inventory, agent version, last heartbeat
+```
+
+`nodes ls` prints ID, label, status, GPU count, total VRAM, and agent version. `nodes show <id>` adds CPU/RAM and the per-GPU list.
+
+### 5. Run a model on the agent
+
+Target the node label when you launch:
 
 ```bash
 berth run qwen-0_5b --node gpu-rig-2 --gpu 0 --engine vllm
 ```
 
-Or set `node_label` on a service profile. The leader sends the start request
-through the agent tunnel, the agent downloads/mounts the model on its own host,
-and `/v1/*` traffic is proxied back through the same mTLS WebSocket.
+Or set `node_label` on a service profile. Either way the leader sends the start request through the agent tunnel, the agent downloads and mounts the model on its own host, and `/v1/*` traffic gets proxied back through the same mTLS WebSocket. The default for `--node` is the leader host; any other value has to match an enrolled, currently-ready agent.
 
 ## Configuring the leader
 
-Resolution order for every address-shaped setting (flag wins, then env,
-then file, then autodetect, then literal default):
+Every address-shaped setting resolves in this order, flag winning over everything:
 
-1. `--public-host` / `--public-port` / `--public-bind` /
-   `--cluster-host` / `--cluster-port` / `--cluster-bind` on
-   `berth daemon start`.
-2. `BERTH_PUBLIC_HOST`, `BERTH_PUBLIC_PORT`, `BERTH_PUBLIC_BIND`,
-   `BERTH_CLUSTER_HOST`, `BERTH_CLUSTER_PORT`, `BERTH_CLUSTER_BIND`
-   env vars.
+1. Flags on `berth daemon start`: `--public-host`, `--public-port`, `--public-bind`, `--public-cert`, `--public-key`, `--cluster-host`, `--cluster-port`, `--cluster-bind`.
+2. Env vars: `BERTH_PUBLIC_HOST`, `BERTH_PUBLIC_PORT`, `BERTH_PUBLIC_BIND`, `BERTH_CLUSTER_HOST`, `BERTH_CLUSTER_PORT`, `BERTH_CLUSTER_BIND`.
 3. `~/.berth/config.toml`.
-4. Autodetect (UDP-connect trick + `gethostbyname`) for the host;
-   `127.0.0.1` for the bind; `11500` / `11501` for ports.
+4. Autodetect for the host (a UDP-connect trick plus `gethostbyname`), `127.0.0.1` for the bind, `11500` / `11501` for the ports.
 
-`BERTH_LEADER_URL` is an explicit override of the
-**advertised** cluster URL only (i.e. what enrollment URIs contain).
-It does not change bind addresses.
+`BERTH_LEADER_URL` is a separate thing: it overrides only the *advertised* cluster URL, i.e. what goes into enrollment URIs. It does not change what the daemon binds to.
 
-Inspect:
+### Inspect
 
 ```bash
 berth config show
@@ -181,12 +153,17 @@ public_tls.key       /etc/le/.../privkey.pem           (file)
 cluster.host         cluster.example.com               (file)
 cluster.port         11501                             (default)
 cluster.bind         10.0.0.1                          (file)
+server.leader_only   False                             (default)
+leader_url_override  -                                 (default)
 
 resolved public_url : https://api.example.com:11500
 resolved cluster_url: https://cluster.example.com:11501
+config file         : /home/you/.berth/config.toml
 ```
 
-Edit:
+Each value shows where it came from, so you can tell a flag from a file from a default.
+
+### Edit
 
 ```bash
 berth config set-public host=api.example.com port=11500
@@ -195,7 +172,9 @@ berth config set-public-tls cert=/etc/le/.../fullchain.pem \
                             key=/etc/le/.../privkey.pem
 ```
 
-The config file is `~/.berth/config.toml`:
+`set-public` and `set-cluster` accept `host`, `port`, `bind`. `set-public-tls` accepts `cert`, `key` and warns if the paths don't exist yet. Anything else is rejected.
+
+The file is `~/.berth/config.toml`:
 
 ```toml
 [public]
@@ -210,23 +189,23 @@ key  = "/etc/letsencrypt/live/api.example.com/privkey.pem"
 [cluster]
 host = "cluster.example.com"
 port = 11501
-bind = "10.0.0.1"   # bind cluster listener to a VPN iface
+bind = "10.0.0.1"   # bind the cluster listener to a VPN interface
+
+[server]
+leader_only = false  # true on a control-plane-only VPS with no local GPUs
 ```
 
-All sections optional; missing keys fall through to env / autodetect.
+Every section is optional. Missing keys fall through to env, then autodetect.
 
-## Cross-network setup (different networks, VPN, NAT)
+## Cross-network setup: different networks, VPN, NAT
 
-The tunnel-by-default design was built for this case. **The agent only
-needs outbound reach to the leader's cluster port.** No port forwarding
-on the agent side, no NAT punching, no VPN required.
+This is the case the tunnel-by-default design was built for. The agent only needs outbound reach to the leader's cluster port. No port forwarding on the agent side, no NAT punching, no VPN.
 
-Requirements:
+What you need:
 
-- The leader has a stable, routable address from the agent's network
-  (public DNS + public IP, a Tailscale / WireGuard peer, anything).
+- The leader has a stable, routable address from the agent's network — public DNS plus a public IP, a Tailscale or WireGuard peer, whatever.
 - The leader's cluster port is reachable from the agent.
-- The agent's firewall allows outbound HTTPS to the cluster port.
+- The agent's firewall allows outbound HTTPS to that port.
 
 Topology:
 
@@ -245,198 +224,132 @@ Topology:
                   +-- SDK clients call /v1/*
 ```
 
-Flow is identical to the LAN setup. The enrollment URI carries the
-cluster URL, so the agent ends up dialing the right port automatically:
+The flow is identical to the LAN setup. The enrollment URI carries the cluster URL, so the agent dials the right port on its own:
 
 ```bash
 # On the leader:
 berth nodes enroll home-rig
 
-# On the agent (anywhere with outbound HTTPS to the cluster port):
+# On the agent, anywhere with outbound HTTPS to the cluster port:
 berth agent register --uri 'berth://enroll?…'
 berth agent start
 ```
 
-### Latency / throughput honesty
+### About latency and throughput
 
-Every prompt byte and every generated token traverses the leader↔agent
-WebSocket. For one LLM streaming 30 tok/s at ~80 B/token that's
-~2.4 KB/s per request — negligible. At 50 concurrent streams it's a
-few hundred KB/s through one persistent socket on the leader process.
-The leader's uplink is the bottleneck. Fine for moderate scale; not
-what you want for serving hundreds of concurrent users from a
-residential leader. The direct-LAN mode (agent advertises a reachable
-address; leader probes; uses direct path when available) is on the
-follow-up list precisely to avoid this hop when both ends actually can
-reach each other.
+I'll be straight about the cost. Every prompt byte and every generated token traverses the leader↔agent WebSocket. For one stream at 30 tok/s and ~80 B/token that's about 2.4 KB/s — nothing. At 50 concurrent streams it's a few hundred KB/s through one persistent socket on the leader process. The leader's uplink is the bottleneck.
+
+This is fine for moderate scale. It is not what you want for serving hundreds of concurrent users from a residential leader. Direct-LAN mode — agent advertises a reachable address, leader probes it, data plane goes direct when both ends can actually reach each other — is on the list precisely to skip this hop when it isn't needed.
 
 ## Public-internet exposure
 
-The defaults bind both listeners to localhost. For open-internet exposure,
-make the bind explicit with `berth deploy bootstrap`, then harden:
+Both listeners bind to localhost by default. To expose either one, make the bind explicit and then harden.
+
+For a full VPS bring-up (config, DB, CA, first admin key, a Caddyfile), use `berth deploy bootstrap --domain api.example.com [--cluster-domain cluster.example.com]`. It writes everything and prints the next steps. To set binds by hand, use `config set-*`.
 
 ### Public listener cert
 
-External SDK clients won't trust the self-signed cluster CA. Supply a
-publicly-trusted cert via `[public_tls]` in `config.toml` or
-`--public-cert` / `--public-key` flags. Standard sources: Let's Encrypt
-(`certbot --standalone --preferred-challenges http -d api.example.com`,
-or a DNS-01 challenge for behind-NAT), an internal corp CA, or a
-managed cert from your cloud provider.
+External SDK clients won't trust your self-signed cluster CA. Give the public listener a real cert through `[public_tls]` in `config.toml` or the `--public-cert` / `--public-key` flags. Usual sources: Let's Encrypt (`certbot --standalone --preferred-challenges http -d api.example.com`, or a DNS-01 challenge if you're behind NAT), an internal corp CA, or a managed cert from your cloud provider.
 
-If you don't, the daemon prints a loud warning on startup and serves
-the cluster-CA cert on the public listener. Fine for demos and
-internal use, not fine for browser clients.
+Skip it and the daemon prints a loud warning on startup and serves the cluster-CA cert on the public listener. Fine for demos and internal use. Not fine for browser clients.
 
 ### Cluster listener bind
 
-If your leader has a VPN / private interface, bind the cluster
-listener to it:
+If the leader has a VPN or private interface, bind the cluster listener to it:
 
 ```bash
 berth config set-cluster bind=10.0.0.1
 ```
 
-Now only hosts on the VPN can reach `/cluster/agent`. Agents on the
-public internet (e.g., remote GPU box, no VPN) will need the public
-interface — in that case leave `bind = 0.0.0.0` but firewall the
-cluster port to known agent source IPs.
+Now only hosts on the VPN can reach `/cluster/agent`. If some agents live on the open internet with no VPN, they need the public interface — leave `bind = 0.0.0.0` and firewall the cluster port down to your known agent source IPs.
 
-### Built-in defenses
+### What's built in
 
-- `/admin/nodes/register` is rate-limited: 10 attempts per source IP
-  per minute. Returns 429 + `Retry-After` on overflow.
-- Every register attempt (success and failure) is logged via the
-  `berth.audit` logger with source IP and token prefix.
+- `/admin/nodes/register` is rate-limited to 10 attempts per source IP per minute. Overflow gets a 429 with `Retry-After`.
+- Every register attempt, success or failure, is logged through the `berth.audit` logger with the source IP and a token prefix.
 - Enrollment tokens are single-use and expire after 10 minutes.
-- `berth nodes remove <id>` causes the next WS handshake from that
-  agent to be rejected — the cert fingerprint is re-checked against
-  the DB on every connection, not cached in-process.
-
-### What this design does *not* protect against
-
-- **Root on the leader.** Anyone with root can mint agent certs from
-  `~/.berth/ca/ca.key`. Protect that file.
-- **Stolen public-cert key.** If your `[public_tls]` key leaks, an
-  attacker can MITM your public listener. Standard cert-management
-  hygiene applies; this design doesn't help or hurt.
-- **DDoS / volumetric abuse.** The fixed-window rate limit slows
-  brute force but is not a DDoS defense. Put a CDN / WAF in front of
-  the public listener if you expect hostile traffic.
-- **Compromised agent host.** mTLS authenticates a cert, not a human;
-  whoever controls an enrolled agent host can stream traffic into
-  your fleet until you `berth nodes remove` them.
-
-## Reverse-Proxy Fingerprint Mode
-
-The pre-secure-by-default deployment style (reverse proxy in front of
-plain-HTTP uvicorn, forwarding `x-berth-client-fingerprint`) is
-supported as an opt-in for operators who already run TLS termination
-upstream:
+- `berth nodes remove <id>` makes the next WS handshake from that agent fail. The cert fingerprint is re-checked against the DB on every connection — it's never cached in-process, so revocation is immediate.
+
+### What this design does not protect against
+
+I'd rather be clear about the edges than imply they're covered.
+
+- **Root on the leader.** Anyone with root can mint agent certs from `~/.berth/ca/ca.key`. Protect that file.
+- **A stolen public-cert key.** If your `[public_tls]` key leaks, an attacker can MITM the public listener. Normal cert hygiene applies; this design neither helps nor hurts.
+- **DDoS and volumetric abuse.** The fixed-window rate limit slows brute force. It is not a DDoS defense. Put a CDN or WAF in front of the public listener if you expect hostile traffic.
+- **A compromised agent host.** mTLS authenticates a cert, not a human. Whoever controls an enrolled agent host can stream traffic into your fleet until you `berth nodes remove` them.
+
+## Reverse-proxy fingerprint mode
+
+The older deployment style — a reverse proxy in front of plain-HTTP uvicorn, forwarding `x-berth-client-fingerprint` — is still supported as an opt-in, for operators who already terminate TLS upstream:
 
 ```bash
 BERTH_TRUST_FORWARDED_FP=1 berth daemon start
 ```
 
-With that flag set, `LeaderHub` will accept the proxy-forwarded
-fingerprint header when no TLS peer cert is present, but only from
-direct peers in `BERTH_FORWARDED_ALLOW_IPS` (default: `127.0.0.1`;
-only `BERTH_*` names are supported). **Do not set this
-on an internet-exposed leader without an upstream proxy doing real mTLS
-verification** — the header is unauthenticated by itself.
+With that set, `LeaderHub` accepts the proxy-forwarded fingerprint header when no TLS peer cert is present, but only from direct peers in `BERTH_FORWARDED_ALLOW_IPS` (default `127.0.0.1`). Do not set this on an internet-exposed leader without an upstream proxy doing real mTLS verification. The header is unauthenticated on its own, so anything that can reach the port can spoof it.
 
-## Status — what works today
+## Status: what works today
 
 What you can rely on:
 
-- Two-listener TLS termination directly inside uvicorn — no reverse
-  proxy required for either `/v1/*` or `/cluster/agent`.
-- Enrollment via single-paste URI with CA-fingerprint pin.
-- Single-use token consumption, rate-limited registration, audit log.
-- mTLS WebSocket connection with real TLS peer-cert verification on
-  every connection (DB lookup, no in-process fingerprint cache).
-- `berth nodes ls / show / enroll / remove` and `berth agent
-  register / start / status`.
+- Two-listener TLS termination inside uvicorn — no reverse proxy required for either `/v1/*` or `/cluster/agent`.
+- Enrollment via single-paste URI with a CA-fingerprint pin.
+- Single-use token consumption, rate-limited registration, an audit log.
+- mTLS WebSocket connections with real TLS peer-cert verification on every connection (a DB lookup, no in-process fingerprint cache).
+- `berth nodes ls / show / enroll / remove`, `berth agent register / start / status / logs / adopt / adopted / unadopt / install-service`.
 - `berth config show / set-public / set-cluster / set-public-tls`.
-- Heartbeat-based health watcher (`ready` → `unreachable` after 15 s
-  of silence; auto-recovers on reconnect).
-- Remote `start_deployment`, `stop_deployment`, health probe, and log
-  streaming through `AgentLink`.
-- Tunneled `/v1/*` data plane through `RemoteAgentLink.proxy_request`
-  (exercised in `tests/integration/test_remote_agent_roundtrip.py`).
+- A heartbeat health watcher: `ready` flips to `unreachable` after 15 s of silence and recovers on reconnect.
+- Remote `start_deployment`, `stop_deployment`, health probe, and log streaming through `AgentLink`.
+- A tunneled `/v1/*` data plane through `RemoteAgentLink.proxy_request`, covered by `tests/integration/test_remote_agent_roundtrip.py`. The same path serves `/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`, `/v1/responses`, and `/v1/models`.
 - `berth run --node <label>` and service-profile `node_label` targeting.
-- Cluster UI surface for nodes, transport summary, GPU inventory, and
-  sparkline metrics.
+- A cluster UI for nodes, transport summary, GPU inventory, and sparkline metrics.
 
-Current gaps:
+What's still missing:
 
-- Direct-LAN data-plane mode (advertised `reachable_as` + leader
-  probing).
-- ACME / Let's Encrypt auto-issuance for the public-listener cert
-  (bring your own cert today).
-- Replicas of the same service profile across nodes.
-- Per-agent request attribution is still coarse; see Metrics below.
-- Reconnect reconciliation still favors keeping remote rows live rather
-  than aggressively killing orphaned remote containers.
+- Direct-LAN data-plane mode (advertised `reachable_as` plus leader probing).
+- ACME / Let's Encrypt auto-issuance for the public-listener cert. Bring your own cert today.
+- Replicas of one service profile across nodes.
+- Per-agent request attribution is still coarse — see [Observability](#observability).
+- Reconnect reconciliation favors keeping remote rows live over aggressively killing orphaned remote containers.
 
-In other words: the tunneled path is real, but this is still a small control
-plane, not a full scheduler.
+In other words: the tunneled path is real, but this is still a small control plane, not a full scheduler.
 
 ## Troubleshooting
 
 **`berth agent register --uri` fails with "CA fingerprint mismatch".**
-
-Either the URI was tampered with in transit, or you're talking to a
-different leader than the one that minted it (e.g., the leader's CA
-was regenerated by deleting `~/.berth/ca/`). Re-mint:
+Either the URI was tampered with in transit, or you're talking to a different leader than the one that minted it — e.g. the leader's CA got regenerated because someone deleted `~/.berth/ca/`. Re-mint:
 
 ```bash
 berth nodes enroll <label>
 ```
 
-**`berth agent start` connects but the WS handshake closes immediately
-with 1008.**
-
-The leader rejected the peer cert. Possible causes:
-
-- The agent's `agent.yaml` points at the wrong leader / port (it now
-  defaults to `:11501` for cluster, not `:11500`). Re-register.
-- The leader's CA was rotated since enrollment. Re-register.
-- The node was removed from the DB. Check `berth nodes ls` on the
-  leader.
-- Logs on the leader (`~/.berth/logs/daemon.log`) should show
-  `cluster ws reject:` with the cause.
-
-**`berth nodes ls` shows the node as `unreachable` even though
-`berth agent start` is running.**
+**`berth agent start` connects, then the WS handshake closes immediately with 1008.**
+The leader rejected the peer cert. Usual causes:
 
-The health watcher flips to `unreachable` after 15 s without a
-heartbeat. If the agent is alive but the row is stale, the WS isn't
-connected — check the agent logs for reconnect attempts.
+- The agent's `agent.yaml` points at the wrong leader or port. The cluster port is `:11501`, not `:11500`. Re-register.
+- The leader's CA rotated since enrollment. Re-register.
+- The node was removed from the DB. Check `berth nodes ls` on the leader.
+- The leader's `~/.berth/logs/daemon.log` should have a `cluster ws reject:` line with the cause.
 
-**`berth agent register` returns 403 `invalid or expired enrollment
-token`.**
+**`berth nodes ls` shows the node `unreachable` even though `berth agent start` is running.**
+The health watcher flips to `unreachable` after 15 s without a heartbeat. If the agent is alive but the row is stale, the WS isn't actually connected — check the agent logs for reconnect attempts.
 
-Tokens are single-use and expire after 10 minutes. Re-run `berth nodes
-enroll <label>` on the leader to mint a fresh URI.
+**`berth agent register` returns 403 "invalid or expired enrollment token".**
+Tokens are single-use and expire after 10 minutes. Re-run `berth nodes enroll <label>` for a fresh URI.
 
-**`berth daemon start` fails with `port already in use` on 11501.**
-
-Either another daemon is running (`berth status`) or another
-process holds the port. Pick a different cluster port:
+**`berth daemon start` fails with "port already in use" on 11501.**
+Either another daemon is up (`berth status`) or another process holds the port. Pick a different cluster port:
 
 ```bash
 berth config set-cluster port=21501
 berth daemon start
 ```
 
-Existing agents will still try the old port — re-enroll them.
+Existing agents will keep trying the old port, so re-enroll them.
 
 **Re-enrolling an existing agent.**
-
-`berth nodes enroll <existing-label>` is allowed and rotates the cert
-fingerprint on the next register. The agent will need a fresh
-`berth agent register --uri …` run.
+`berth nodes enroll <existing-label>` is allowed. It rotates the cert fingerprint on the next register, so the agent needs a fresh `berth agent register --uri …` run.
 
 ## Decommissioning a node
 
@@ -446,38 +359,43 @@ On the leader:
 berth nodes remove <id>
 ```
 
-This unregisters any live AgentLink, deletes the row, and the cert
-fingerprint stops authenticating new connections (the DB lookup
-happens on every WS handshake, so revocation is immediate). The agent
-process keeps trying to reconnect; stop it on the agent host
-(`Ctrl-C` or your service manager). The local node (`label=local`)
-cannot be removed.
+This unregisters any live AgentLink, deletes the row, and stops the cert fingerprint from authenticating new connections. The DB lookup runs on every WS handshake, so revocation takes effect immediately. The agent process keeps trying to reconnect — stop it on the agent host (Ctrl-C, or your service manager: `systemctl --user stop berth-agent`). The local node (`label=local`) can't be removed.
 
 ## Adopting an externally-hosted model
 
-An agent can adopt an already-running OpenAI-compatible inference server on its host. The model becomes routable through the leader's gateway without berth launching, stopping, or managing the server — berth registers the endpoint and routes `/v1/*` requests to it. This is useful for integrating legacy services, third-party providers, or manual deployments.
+An agent can adopt an OpenAI-compatible server that's already running on its host. The model becomes routable through the leader's gateway, but berth never starts, stops, or manages the server — it registers the endpoint and routes `/v1/*` to it. Useful for a legacy service, a third-party provider, or something you deployed by hand.
 
 ### Register an adopted endpoint
 
-By **docker container name** (berth introspects the published port, GPU device-requests, and `/v1/models` list):
+By **docker container name** — berth introspects the published port, the GPU device-requests, and the `/v1/models` list:
 
 ```bash
 berth agent adopt --container my-inference-server
 ```
 
-By **host and port** (you supply details):
+By **host and port**, where you supply the details:
 
 ```bash
 berth agent adopt --port 30011 --model nvidia/MiniMax-M2.7-NVFP4 \
   --host 127.0.0.1 --gpus 0 --vram-mb 5000
 ```
 
-The **served name** is the routing name clients pass to the leader's gateway, determined in this order:
+The flags for the `--port` form:
+
+- `--port <p>` — the port the external server listens on. Required.
+- `--model <m>` — the local registry/label. Required with `--port`.
+- `--host <h>` — defaults to `127.0.0.1`.
+- `--gpus <ids>` — comma-separated GPU ids, e.g. `0,7`.
+- `--vram-mb <n>` — VRAM to reserve for those GPUs (0 leaves the scheduler to treat them as full).
+- `--served-model-name <s>` — the routing name (see below).
+- `--name <label>` — a local label; defaults to the model name.
 
-- If `--served-model-name S` is given, that is the served name.
-- Otherwise berth queries the endpoint's `/v1/models` and uses the first model's `id`.
+The **served name** is the name clients pass to the leader's gateway. It's resolved in this order:
 
-The `--model` flag is the local registry/label; when no `--served-model-name` is given it is not necessarily the routing name. Clients reach the model at the leader gateway using the served name.
+- If you pass `--served-model-name S`, that's it.
+- Otherwise berth queries the endpoint's `/v1/models` and takes the first model's `id`.
+
+`--model` is the local registry name. When you don't pass `--served-model-name`, it is not necessarily the routing name. Clients reach the model at the leader using the served name. Adoption takes effect on the running agent — the agent re-reports its adopted set on the next tick.
 
 ### List adopted endpoints
 
@@ -485,7 +403,7 @@ The `--model` flag is the local registry/label; when no `--served-model-name` is
 berth agent adopted
 ```
 
-Shows all adopted endpoints on the current agent host.
+Prints each endpoint's name, address:port, served model name, and reserved GPUs, for the current agent host.
 
 ### Remove an adopted endpoint
 
@@ -493,51 +411,35 @@ Shows all adopted endpoints on the current agent host.
 berth agent unadopt nvidia/MiniMax-M2.7-NVFP4
 ```
 
-The server keeps running — the route is dropped only. If you remove the adoption from the report (or `unadopt`), berth stops routing but does not stop the external process.
+The argument is the adopted endpoint's name (the local label — `--name`, or the model name if you didn't set one). The route drops on the next agent report. The external server keeps running; berth only stops routing to it.
 
 ### Notes
 
-- **Model name.** Adopted models are routable at the leader's gateway under their **served name** (`--served-model-name`, else the first `/v1/models` `id`; see above). SDK clients call the leader with that served name, and the request is proxied through the agent to the external server.
-- **Lifecycle.** berth never starts, stops, restarts, or idle-evicts an adopted server. The operator or another orchestration system is responsible for keeping it running. berth only registers the endpoint and routes `/v1/*` requests to it. `unadopt` removes the route only.
-- **Liveness.** berth does **not** currently actively health-probe adopted endpoints; they are reported alive on (re)connect. If the upstream server is down, requests to it fail at proxy time and surface as errors to the client. Active liveness probing of adopted endpoints is a planned enhancement.
-- **GPU reservation.** Adopted endpoints reserve their declared GPU(s) in berth's scheduler, preventing other models from being placed on those GPUs. If you change the GPU allocation on the external server, update the adoption with `berth agent adopt --gpus` or re-adopt. Note: berth's automatic placement/scheduler runs for leader-local deployments; on remote agent nodes GPU assignment is operator-driven, so an adopted endpoint's reserved GPUs are recorded for accounting/visibility but the operator is responsible for not double-assigning them there.
-- **Persistence.** The adopted set is stored in `~/.berth/adopted.yaml` on the agent and reported to the leader on every connect (and re-reported when that file changes), so adoptions survive agent restarts.
+A few things worth knowing about adopted endpoints.
+
+- **Routing.** They're reachable at the leader gateway under their served name (`--served-model-name`, else the first `/v1/models` `id`). SDK clients call the leader with that name and the request is proxied through the agent to the external server.
+- **Lifecycle.** berth never starts, stops, restarts, or idle-evicts an adopted server. Keeping it running is on you or whatever else manages it. `unadopt` removes the route only.
+- **Liveness.** berth does not currently health-probe adopted endpoints. They're reported alive on (re)connect. If the upstream is down, requests fail at proxy time and surface as errors to the client. Active liveness probing is planned.
+- **GPU reservation.** Adopted endpoints reserve their declared GPUs in berth's scheduler so other models won't get placed there. If you change the external server's GPU allocation, re-adopt or run `berth agent adopt --gpus …` again. Note that berth's automatic placement runs only for leader-local deployments — on remote agent nodes the operator assigns GPUs, so an adopted endpoint's reserved GPUs are recorded for accounting and visibility but you're the one who has to avoid double-assigning them.
+- **Persistence.** The adopted set lives in `~/.berth/adopted.yaml` on the agent and is reported to the leader on every connect (and re-reported when the file changes), so adoptions survive agent restarts.
 
 ## Tuning
 
-Most defaults are sensible for a small fleet. If you need to change
-them:
-
-- **Heartbeat interval.** Agent sends every 5 s; leader marks a node
-  `unreachable` after 15 s of silence. Both live in
-  `src/berth/cluster/agent_client.py` (heartbeat task) and
-  `src/berth/cluster/health_watcher.py` (`stale_after_s`).
-  Hard-coded for v1; lift to config when you actually need to tune.
-- **Reconnect backoff.** Agent starts at 1 s, doubles to 30 s cap.
-  See `run_agent()` in `agent_client.py`.
-- **Enrollment token TTL.** Default 600 s. See `EnrollmentTokens` in
-  `src/berth/cluster/enrollment.py`.
-- **Registration rate limit.** Default 10 attempts / IP / 60 s.
-  See `_rate_limit` in `src/berth/daemon/admin.py`.
-- **Server-cert validity.** 5 years. Regenerated automatically when
-  `public_host` / `cluster_host` change and the existing SAN doesn't
-  cover the new value. See `ensure_server_cert` in
-  `src/berth/cluster/ca.py`.
+Most defaults are fine for a small fleet. If you need to change one, here's where it lives. Several are hard-coded for now — lift them to config when you actually hit the limit.
+
+- **Heartbeat interval.** Agent sends every 5 s; the leader marks a node `unreachable` after 15 s of silence. See the heartbeat task in `src/berth/cluster/agent_client.py` and `stale_after_s` in `src/berth/cluster/health_watcher.py`.
+- **Reconnect backoff.** Agent starts at 1 s and doubles to a 30 s cap. See `run_agent()` in `agent_client.py`.
+- **Enrollment token TTL.** Default 600 s. See `EnrollmentTokens` in `src/berth/cluster/enrollment.py`.
+- **Registration rate limit.** Default 10 attempts / IP / 60 s. See `_rate_limit` in `src/berth/daemon/admin.py`.
+- **Server-cert validity.** 5 years. Regenerated automatically when `public_host` or `cluster_host` changes and the existing SAN doesn't cover the new value. See `ensure_server_cert` in `src/berth/cluster/ca.py`.
 
 ## Observability
 
-Each agent sends GPU stats on every heartbeat tick (5 s by default) over the
-existing WebSocket. The leader's own node also publishes local request counters
-into the same `MetricsAggregator`. The schema has per-deployment request and
-latency fields; remote-agent request attribution is still coarse, noted below.
-The aggregator keeps a 60 s rolling window per node and exposes the data three
-ways:
+Each agent sends GPU stats on every heartbeat tick (5 s by default) over the existing WebSocket. The leader's own node publishes local request counters into the same `MetricsAggregator`. The schema has per-deployment request and latency fields, though remote-agent request attribution is still coarse (noted at the end). The aggregator keeps a 60 s rolling window per node and exposes it three ways.
 
 ### Prometheus
 
-`GET /metrics` (on the public listener) appends the cluster series
-after the existing daemon and engine sections. Stable label sets, safe
-to scrape with the default 30 s interval.
+`GET /metrics` on the public listener appends the cluster series after the existing daemon and engine sections. The label sets are stable, so it's safe to scrape at the default 30 s interval.
 
 | Series | Type | Labels |
 | --- | --- | --- |
@@ -549,142 +451,75 @@ to scrape with the default 30 s interval.
 | `berth_deployment_latency_p95_ms` | gauge | `node`, `deployment`, `model` |
 | `berth_deployment_errors_total` | counter | `node`, `deployment`, `model` |
 
-The leader's own node also appears in these series — a small background
-task on the daemon mirrors the agent heartbeat for the local node so
-operators get one consistent surface regardless of whether a metric is
-local or remote.
+The leader's own node shows up in these series too. A small background task on the daemon mirrors the agent heartbeat for the local node, so you get one consistent surface whether a metric is local or remote.
 
-### Sample Grafana dashboard
+### Grafana dashboard
 
-`docs/dashboards/berth.json` ships a six-panel starter:
-GPU utilization, GPU memory, in-flight, p95 latency, request rate,
-error rate. Import it in Grafana's "Import dashboard" page; no auto-
-provisioning. Tune the panel queries for your label conventions.
+`docs/dashboards/berth.json` is a six-panel starter: GPU utilization, GPU memory, in-flight, p95 latency, request rate, error rate. Import it from Grafana's "Import dashboard" page. There's no auto-provisioning, and you'll want to tune the panel queries to your own label conventions.
 
 ### Admin snapshot endpoint
 
-`GET /admin/metrics/snapshot` returns the latest per-node sample plus
-short sparkline series. The UI Cluster page consumes it on a 5 s poll
-and renders inline SVG sparklines on each node card.
+`GET /admin/metrics/snapshot` returns the latest per-node sample plus short sparkline series. The UI's Cluster page polls it every 5 s and renders inline SVG sparklines on each node card.
 
-### Known limitations (today)
+### Known limitations today
 
-- The leader's in-flight counter increments for every request the
-  proxy dispatches, including those routed to remote nodes. The local
-  sample therefore over-counts when remote deploys are active. Per-node
-  attribution is part of the smart-routing follow-up.
-- Remote agents currently report empty deployment lists — instrumenting
-  the agent's `_run_http_stream` dispatch path to populate in-flight +
-  latency is a small follow-up.
+- The leader's in-flight counter increments for every request the proxy dispatches, including the ones routed to remote nodes. So the local sample over-counts when remote deploys are active. Per-node attribution is part of the smart-routing follow-up.
+- Remote agents currently report empty deployment lists. Instrumenting the agent's `_run_http_stream` dispatch path to populate in-flight and latency is a small follow-up.
 
-## Routing & resilience
+## Routing and resilience
 
-Multi-deployment selection is driven by a load-aware scorer
-(`src/berth/routing/scorer.py`). For a given (base, adapter)
-target, the proxy:
+When more than one deployment can serve a request, a load-aware scorer (`src/berth/routing/scorer.py`) picks one. For a given (base, adapter) target, the proxy:
 
 1. Collects every ready deployment as a candidate.
-2. For adapter requests, applies the existing tier filter
-   (already-loaded > free-slot > needs-evict). Only the best tier is
-   scored — we don't mix tiers, because that would hide cold-load
-   latency behind a fast idle node.
-3. Calls the scorer with per-node `NodeSignals` derived from the
-   metrics aggregator (mem free, in-flight, p95 latency).
+2. For adapter requests, applies the tier filter — already-loaded beats free-slot beats needs-evict. Only the best tier gets scored. Mixing tiers would hide cold-load latency behind a fast idle node.
+3. Calls the scorer with per-node `NodeSignals` from the metrics aggregator: free memory, in-flight, p95 latency.
 
 ### Default scorer
 
-Hard memory filter then lexicographic rank by:
+A hard memory filter, then a lexicographic rank:
 
-1. `affinity_hit` (1 if the leader's affinity map points at this node).
-2. `-in_flight` (less loaded first).
-3. `-p95_latency_ms` (faster recent performance first).
+1. `affinity_hit` — 1 if the leader's affinity map already points at this node.
+2. `-in_flight` — less loaded first.
+3. `-p95_latency_ms` — faster recent performance first.
 
-Explicit tiers rather than weighted floats so it's debuggable. A node
-with no aggregator entry yet (just-enrolled) is kept as a candidate but
-ranked last — it can't be filtered for memory without evidence, and
-preferring a known-fit known-fast node is the right bias.
+Explicit tiers, not weighted floats, so the decision is debuggable. A just-enrolled node with no aggregator entry yet stays a candidate but ranks last — you can't memory-filter it without evidence, and preferring a known-fit, known-fast node is the right bias.
 
 ### Affinity
 
-`RoutingAffinity` is a bounded LRU `affinity_key → node_id` map. The
-key precedence is `X-Session-Id` > `X-Conversation-Id` > the API key.
-On every successful dispatch the proxy records the chosen node;
-subsequent requests with the same key get a `affinity_hit=1` boost,
-which keeps a conversation pinned to whichever node holds its KV
-cache. Best-effort: lost on process restart, cleared per-node when a
-node transitions to `unreachable`.
+`RoutingAffinity` is a bounded LRU map of `affinity_key → node_id`. The key precedence is `X-Session-Id`, then `X-Conversation-Id`, then the API key. On every successful dispatch the proxy records the chosen node; later requests with the same key get an `affinity_hit=1` boost, which keeps a conversation pinned to whichever node holds its KV cache. It's best-effort: lost on process restart, and cleared per-node when a node goes `unreachable`.
 
 ### Node-loss audit
 
-When the health watcher demotes a node to `unreachable`, it emits a
-`node_loss_audit` warning with the node id and label, and clears the
-affinity entries pointing at that node. Routing decisions thereafter
-treat the node as gone until it re-handshakes.
+When the health watcher demotes a node to `unreachable`, it emits a `node_loss_audit` warning with the node id and label, and clears the affinity entries pointing at that node. Routing treats the node as gone until it re-handshakes.
 
 ### Request-level retry
 
-`dispatch_with_retry` (`src/berth/daemon/retry_dispatcher.py`)
-wraps the dispatch step. For a bare-base request the proxy gets the
-full scorer-ranked candidate list and walks it, retrying when the
-chosen node raises a retryable pre-first-byte error: connection
-refused, timeout, 502/503/504 upstream, or `NodeUnreachableError`
-(the AgentLink isn't ready or has no container for that deployment).
-
-- **Budget**: 2 retries (3 total attempts) by default for bare-base
-  requests; **0 retries** for adapter requests — the adapter is loaded
-  on the chosen head deployment only, so falling through to another
-  candidate would land on an engine without the right LoRA slot.
-- **Distinct nodes**: each node is tried at most once per request.
-  Multiple candidates on the same node don't burn extra attempts.
-- **Pre-first-byte only**: once any body byte has been sent to the
-  client, the streamer commits to that upstream. A node dying mid-
-  generation propagates the error — KV-cache transfer is not on the
-  roadmap.
-
-The dispatch step itself was carved out of `openai_proxy.py` into
-`src/berth/daemon/dispatch.py:open_upstream_stream`. The unit
-knows nothing about request context or usage tracking — it just opens
-a stream and returns once status + headers are known. The proxy wraps
-the returned `body_iter` in one unified streamer that handles
-in-flight/latency/usage attribution against the **landing** deployment.
+`dispatch_with_retry` (`src/berth/daemon/retry_dispatcher.py`) wraps the dispatch step. For a bare-base request the proxy gets the full scorer-ranked candidate list and walks it, retrying when the chosen node raises a retryable pre-first-byte error: connection refused, timeout, a 502/503/504 upstream, or `NodeUnreachableError` (the AgentLink isn't ready or has no container for that deployment).
+
+- **Budget.** 2 retries (3 attempts total) by default for bare-base requests. Zero retries for adapter requests — the adapter is loaded on the chosen head deployment only, so falling through would land on an engine without the right LoRA slot.
+- **Distinct nodes.** Each node is tried at most once per request. Multiple candidates on the same node don't burn extra attempts.
+- **Pre-first-byte only.** Once any body byte has reached the client, the streamer commits to that upstream. A node dying mid-generation propagates the error — KV-cache transfer is not on the roadmap.
+
+The dispatch step itself was carved out of `openai_proxy.py` into `src/berth/daemon/dispatch.py:open_upstream_stream`. That unit knows nothing about request context or usage tracking — it opens a stream and returns once status and headers are known. The proxy wraps the returned `body_iter` in one unified streamer that handles in-flight, latency, and usage attribution against the **landing** deployment.
 
 ### SSE backpressure
 
-`_bounded_pipe` (`src/berth/daemon/openai_proxy.py`) sits
-between the upstream reader task and the FastAPI streamer. It uses an
-`asyncio.Queue(maxsize=N)` to cap how far the engine can run ahead of
-a slow client: once the queue is full, the reader blocks on `put()`
-and that backpressure propagates through the upstream stream to the
-engine, so no more bytes are pulled until the client drains a chunk.
-
-- **Default depth**: 64 chunks. Tunable per-app via
-  `app.state.sse_queue_depth`.
-- **Exception forwarding**: errors raised by the upstream iterator are
-  passed through the queue and re-raised in the streamer, so the
-  proxy's existing usage-tracker + tracer finalize path always runs.
-- **Early-close cleanup**: if the client disconnects, the streamer's
-  `finally` cancels the reader task — no lingering pull on the upstream.
+`_bounded_pipe` (`src/berth/daemon/openai_proxy.py`) sits between the upstream reader task and the FastAPI streamer. It uses an `asyncio.Queue(maxsize=N)` to cap how far the engine can run ahead of a slow client: once the queue is full, the reader blocks on `put()` and that backpressure propagates through the upstream stream to the engine, so no more bytes get pulled until the client drains a chunk.
+
+- **Default depth.** 64 chunks. Tunable per-app via `app.state.sse_queue_depth`.
+- **Exception forwarding.** Errors from the upstream iterator pass through the queue and re-raise in the streamer, so the usage-tracker and tracer finalize path always runs.
+- **Early-close cleanup.** If the client disconnects, the streamer's `finally` cancels the reader task — no lingering pull on the upstream.
 
 ## Production deploy
 
-For standing up a public-facing leader (Caddy + ACME TLS, systemd,
-proper auth + backups), see [deploy.md](deploy.md) and
-[caddy.md](caddy.md). `berth backup create` snapshots the DR set
-(db, ca/, key_pepper, config.toml).
+For a public-facing leader — Caddy plus ACME TLS, systemd, real auth, backups — see [deploy.md](deploy.md) and [caddy.md](caddy.md). `berth backup create` snapshots the disaster-recovery set: the DB, `ca/`, `key_pepper`, and `config.toml`.
 
 ## Roadmap
 
-Likely next work, in priority order:
+Likely next work, in rough priority order:
 
-1. **Direct-LAN ingress.** Agent opens a guarded mTLS ingress on its
-   `reachable_as` address; leader probes and switches the data plane
-   to direct routing when reachable. Falls back to tunnel
-   automatically.
-2. **ACME for the public listener.** Auto-issue and auto-renew via
-   Let's Encrypt so a single-command public deploy works without
-   external certbot orchestration.
+1. **Direct-LAN ingress.** The agent opens a guarded mTLS ingress on its `reachable_as` address; the leader probes it and switches the data plane to direct routing when reachable, falling back to the tunnel automatically.
+2. **ACME for the public listener.** Auto-issue and auto-renew via Let's Encrypt, so a one-command public deploy works without external certbot orchestration.
 3. **Replica fan-out across nodes.**
-4. **Per-agent request metrics.** Attribute in-flight and latency samples
-   on the agent side instead of over-counting on the leader.
-5. **Reconnect reconciliation polish** (orphan-container kill, drift
-   correction).
+4. **Per-agent request metrics.** Attribute in-flight and latency on the agent side instead of over-counting on the leader.
+5. **Reconnect reconciliation polish** — orphan-container kill, drift correction.
diff --git a/docs/predictor.md b/docs/predictor.md
index e16006e..c5221d0 100644
--- a/docs/predictor.md
+++ b/docs/predictor.md
@@ -1,77 +1,121 @@
 # Predictor
 
-The predictor is an optional pre-warm loop. It watches recorded usage and
-asks the lifecycle manager to start base deployments and load LoRA adapters
-that are likely to be hit soon.
+The predictor is an optional pre-warm loop. It watches what you've actually
+run, guesses what's likely to get hit next, and asks the lifecycle manager to
+start that base or hot-load that adapter ahead of the request. It's off by
+default. You opt in with a config file.
+
+The whole thing lives in `src/berth/lifecycle/predictor.py` (the rules) and
+`src/berth/lifecycle/predictor_task.py` (the tick loop).
 
 ## What it does
 
-The predictor tick reads `usage_events`, scores candidates with a small set
-of rules, and asks the manager to pre-warm the top ones. Pre-warming reuses
-existing deployment plans recorded in `deployment_plans.reached_ready_at` —
-the predictor never invents a configuration it has never seen succeed.
+Every tick, the predictor reads the `usage_events` table, scores a handful of
+candidates with three rules, dedupes them, and pre-warms the top few. That's
+it. There's no model, no training step. It's SQL over your own history.
+
+Two things keep it from doing anything stupid:
+
+- It never invents a configuration it hasn't seen work. A base only gets
+  pre-warmed from a plan recorded in `deployment_plans.reached_ready_at` — an
+  exact config that already reached ready once on this box. No recorded plan,
+  no base pre-warm.
+- Pre-warming is advisory. A real request always wins. Real `/v1/*` traffic
+  goes through the normal placement path and can evict an idle pre-warmed
+  deployment exactly like it would evict anything else. The predictor won't
+  pre-warm over a deployment that's already loaded, and it won't start a base
+  that's already ready or mid-load.
+
+If one rule throws, the tick logs it and keeps the other rules. A bad rule
+can't poison the queue or take down the loop.
+
+You can see what it's thinking without restarting anything:
+
+```bash
+berth predict           # current top candidates, with scores and reasons
+berth predict --stats   # tick-loop counters (attempts, successes, skips)
+```
 
-Pre-warming is advisory. A real request always wins:
+Both read live from the daemon. `--stats` shows the running config and the
+preload/base-prewarm counters straight off the tick loop.
 
-- Real `/v1/*` traffic uses the normal placement path and can evict an
-  idle pre-warmed deployment the same way it would evict any other.
-- The predictor never pre-warms over a pinned deployment or one already
-  loaded.
-- Bad rules are isolated — if one rule raises, the tick logs and keeps the
-  others.
+There are also two offline modes that don't need the daemon, for poking at the
+history directly:
+
+```bash
+berth predict --export trace.jsonl       # dump usage_events to JSONL
+berth predict --replay trace.jsonl       # replay it against an LRU baseline
+berth predict --replay trace.jsonl --slots 8   # LRU slots per base (default 4)
+```
+
+`--replay` reports how many cold-loads your recorded run had versus a plain
+LRU cache, so you can sanity-check whether the predictor is buying you
+anything. `--slots` should match your deployment's `max_loras`.
 
 ## The three rules
 
-All three live in `src/berth/lifecycle/predictor.py` and read only
-from `usage_events`.
+All three read only from `usage_events`. Each one emits candidates with a
+score in `[0, 1]` and a reason string, so the scores are comparable and the
+`berth predict` output tells you why something showed up.
 
-### `time_of_day`
+### time_of_day
 
-Pre-warm models the operator's traffic has historically used in the
-upcoming hour-of-week. Score is the count of activations in that hourly
-bucket over the past `retention_days`, normalized to `[0, 1]` so it is
-comparable to the other rules.
+Pre-warm models your traffic has historically used in the *upcoming*
+hour-of-week. I look one hour ahead, not at the current hour — by the time a
+base finishes warming you're already into the next bucket. The score is the
+number of activations in that hourly bucket over the last `retention_days`,
+divided by the busiest model in the bucket so it lands in `[0, 1]`.
 
-### `sequencing`
+### sequencing
 
-When a request for X arrives, pre-warm models that historically follow X
-within `window_s` seconds. The score is the empirical conditional
-probability `P(Y | X within window)`, filtered by `min_p`. The rule only
-fires when X has at least two historical events in the retention window.
+When X was just requested, pre-warm the models that historically follow X
+within `window_s` seconds. The trigger is the most recent event inside that
+window. For each candidate Y, the score is the empirical conditional
+probability `P(Y | X within window)` over the retention window, filtered by
+`min_p`. It only fires when X has at least two historical events to compute
+from — one data point isn't a pattern.
 
-### `key_affinity`
+### key_affinity
 
-When an idle API key starts firing again (`idle_seconds` since its last
-event), pre-warm its `top_k_per_key` most-used `(base, adapter)` pairs
-from the past 7 days. Score is normalized per-key against that key's own
-max.
+When an API key that had gone quiet starts firing again (an event within the
+last `idle_seconds`), pre-warm that key's `top_k_per_key` most-used
+`(base, adapter)` pairs from the past 7 days. The score is normalized per key
+against that key's own busiest model. The 7-day window here is fixed; it isn't
+tied to `retention_days`.
 
-## `~/.berth/predictor.yaml`
+## ~/.berth/predictor.yaml
 
-Fields and defaults, from `PredictorConfig` in
-`src/berth/lifecycle/predictor.py`:
+The daemon reads this file once at startup. Every field is optional — ship a
+partial file and override only what you care about. Missing keys, a missing
+file, or malformed YAML all fall back to the defaults below, silently. By
+default `enabled` is `false`, so the file does nothing until you turn it on.
+
+These are the fields and their defaults, straight from `PredictorConfig` in
+`src/berth/lifecycle/predictor.py`. Keep the key names exactly as written.
 
 | Field | Default | Meaning |
 |---|---|---|
 | `enabled` | `false` | Master switch. `false` skips the tick loop entirely. |
-| `tick_interval_s` | `30` | Seconds between predictor ticks. |
+| `tick_interval_s` | `30` | Seconds between ticks. |
 | `max_prewarm_per_tick` | `2` | Total pre-warm actions (base + adapter) per tick. |
-| `max_base_prewarm_per_tick` | `1` | Subset of the above that may start a base deployment. `0` disables base pre-warming. |
+| `max_base_prewarm_per_tick` | `1` | How many of those may start a *base* deployment. `0` disables base pre-warming. |
 | `retention_days` | `30` | History window for `time_of_day` and `sequencing`. |
 | `rules.time_of_day.enabled` | `true` | Toggle the time-of-day rule. |
 | `rules.time_of_day.weight` | `1.0` | Score weight. |
 | `rules.sequencing.enabled` | `true` | Toggle the sequencing rule. |
 | `rules.sequencing.weight` | `1.0` | Score weight. |
-| `rules.sequencing.window_s` | `30` | Pair-window for `P(Y | X)`. |
-| `rules.sequencing.min_p` | `0.30` | Minimum conditional probability to emit. |
+| `rules.sequencing.window_s` | `30` | Pair window for `P(Y | X)`, in seconds. |
+| `rules.sequencing.min_p` | `0.30` | Minimum conditional probability to emit a candidate. |
 | `rules.key_affinity.enabled` | `true` | Toggle the key-affinity rule. |
 | `rules.key_affinity.weight` | `1.0` | Score weight. |
 | `rules.key_affinity.top_k_per_key` | `5` | Models pulled per active key. |
-| `rules.key_affinity.idle_seconds` | `300` | A key counts as "active" if it fired within this window. |
+| `rules.key_affinity.idle_seconds` | `300` | A key counts as active if it fired within this many seconds. |
 
-Missing keys, missing file, or malformed YAML all fall back to defaults.
-By default the predictor is off; create this file with `enabled: true`
-to opt in.
+A note on `max_base_prewarm_per_tick`: starting a base from scratch is 30-60s
+of engine warmup plus a container, far more disruptive than a sub-second LoRA
+hot-load. That's why it has its own budget. The default of `1` keeps the loop
+conservative. Set it to `0` and the predictor will still hot-load adapters onto
+bases you started, but it'll never bring a base up on its own.
 
 Minimal example:
 
@@ -94,32 +138,41 @@ rules:
 
 ## How to disable
 
-The predictor is disabled by default. If you previously enabled it,
-write:
+It's off by default, so usually there's nothing to do. If you turned it on and
+want it back off, set:
 
 ```yaml
 enabled: false
 ```
 
-to `~/.berth/predictor.yaml`, then restart the daemon:
+in `~/.berth/predictor.yaml`. The config is read at startup, so restart the
+daemon to pick it up:
 
 ```bash
 berth daemon stop
 berth daemon start
 ```
 
-## Operator-stop interaction
+## Operator stops
 
-Known gap: if you `berth stop` a deployment that the rules still score
-highly, the next predictor tick may re-launch it from its recorded plan.
+Here's a rough edge I'll be honest about. The predictor doesn't know you meant
+it. If you `berth stop` a deployment that the rules still score highly, the
+next tick can re-launch it from its recorded plan. You stop it, the loop
+brings it back.
 
-Workarounds:
+There's no "leave this one alone" mark yet. Until there is, two workarounds:
 
 - Set `max_base_prewarm_per_tick: 0` in `~/.berth/predictor.yaml`. The
-  predictor will still hot-load LoRA adapters onto bases you started, but
-  it will not bring a base back up on its own.
-- Or disable the predictor entirely (`enabled: false`).
+  predictor keeps hot-loading adapters onto bases you started, but it won't
+  bring a base back up on its own — so a `berth stop` of a base sticks.
+- Or turn the predictor off entirely with `enabled: false`.
+
+I expect a future revision to honor a short-lived "do not pre-warm" mark left
+behind by an operator stop. It isn't built yet. Until it is, treat those two
+workarounds as the contract.
+
+## See also
 
-A future revision is expected to honor a short-lived "do not pre-warm"
-mark left behind by an operator stop; until then, treat the two
-workarounds above as the contract.
+- [../README.md](../README.md) for the overall picture and the rest of the CLI.
+- [troubleshooting.md](troubleshooting.md) if the daemon or a deployment is
+  misbehaving.
diff --git a/docs/release.md b/docs/release.md
index d223075..7c6104d 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -1,20 +1,43 @@
 # Release Process
 
-berth is currently released from source plus GitHub release artifacts.
-PyPI publishing is intentionally not wired up yet; if that changes, add it as
-an explicit release step with trusted publishing.
+These are my notes for cutting a berth release. A release is a `v*` git tag plus
+the artifacts the tag-triggered workflow builds: a GitHub Release with the
+wheel/sdist attached, and a daemon image on GHCR. I don't publish to PyPI. If I
+ever do, I'll add it as an explicit step with trusted publishing.
+
+The current version is 0.5.0. The worked examples below use that; bump them when
+you bump the version.
 
 ## Version
 
-Keep these in sync:
+The version lives in three places, and all three have to match the tag:
+
+- `pyproject.toml` — `version = "0.5.0"`
+- `src/berth/__init__.py` — `__version__ = "0.5.0"`
+- `uv.lock` — the project's own entry. Run `uv lock` after editing the first two
+  so the lockfile picks up the new version.
+
+Edit the first two by hand, then:
+
+```bash
+uv lock
+```
+
+I also update [`../CHANGELOG.md`](../CHANGELOG.md) as part of cutting the
+release: move the unreleased notes under a new `## 0.5.0 - <date>` heading.
 
-- `pyproject.toml`
-- `src/berth/__init__.py`
-- `uv.lock`
-- `CHANGELOG.md`
+A note on dependency bumps, since they touch the lockfile: I don't bump Python
+deps by hand here, and Dependabot doesn't do them either — it can't read
+`uv.lock`. They're refreshed by `.github/workflows/uv-upgrade.yml`, which runs
+`uv lock --upgrade` weekly, validates the result the way CI does, and opens one
+PR with the whole upgraded set. Dependabot still handles GitHub Actions and the
+npm deps under `ui/`. None of that touches the `>=` floors in `pyproject.toml`;
+those are deliberate minimums I raise by hand.
 
 ## Checklist
 
+Run this top to bottom from a clean tree before tagging:
+
 ```bash
 uv lock
 uv lock --check
@@ -33,10 +56,16 @@ rm -rf dist
 uv build
 ```
 
-## Security Probe
+The `npm run build` step regenerates the bundled UI under `src/berth/ui`. The
+release workflow rebuilds it too and fails if what's committed is stale, so make
+sure the rebuilt UI is committed before you tag.
+
+## Security probe
 
 Before tagging, run the black-box listener probe against the exact staging
-deployment shape you plan to publish:
+deployment shape you plan to publish. The probe (`scripts/security_probe.py`)
+only pokes HTTP-visible boundaries, so point it at a running daemon / reverse
+proxy:
 
 ```bash
 python scripts/security_probe.py \
@@ -45,8 +74,8 @@ python scripts/security_probe.py \
   --token "$BERTH_API_KEY"
 ```
 
-For local daemon smoke tests or generated staging certificates, add
-`--insecure`:
+For a local daemon or generated/self-signed staging certs, add `--insecure` to
+skip TLS verification:
 
 ```bash
 python scripts/security_probe.py \
@@ -55,22 +84,33 @@ python scripts/security_probe.py \
   --insecure
 ```
 
-The probe fails closed if public/cluster listeners expose generated FastAPI
-docs, omit baseline browser security headers, omit `no-store` cache headers
-on sensitive routes, drop public auth, or let cluster-only/public-only routes
-bleed across listeners. When `--token` is supplied it also verifies an
-authenticated `/v1/models` call and the browser stream-ticket boundary:
-non-stream paths must be rejected, and a ticket minted for one stream route
-must not authorize another stream route.
+It exits non-zero if any check fails. What it checks:
+
+- Both listeners hide the generated FastAPI docs (`/openapi.json`, `/docs`,
+  `/redoc` return 404) and serve the baseline browser security headers (CSP,
+  `permissions-policy`, `referrer-policy`, `x-content-type-options`,
+  `x-frame-options`) on `/healthz`.
+- Public listener: `/metrics`, `/admin/keys`, and `/v1/chat/completions` require
+  auth (401), sensitive routes carry `cache-control: no-store` and
+  `pragma: no-cache`, the cluster CA isn't mounted (`/admin/ca.pem` → 404), and
+  agent registration isn't callable there.
+- Cluster listener: serves the CA for pinned enrollment, rejects an invalid
+  enrollment token with 403, and does NOT mount the public-only routes
+  (`/v1/chat/completions`, `/metrics`, `/admin/keys` → 404).
+
+When `--token` is supplied it also runs the authenticated checks: a real
+`/v1/models` call works (200), and the browser stream-ticket boundary holds — a
+ticket minted for one stream path can't be used to mint or reach another, and
+the non-stream path is rejected.
 
-Inspect the wheel for packaged runtime data:
+Then inspect the built wheel for the runtime data that has to ship inside it:
 
 ```bash
 uv run --frozen python -m zipfile -l dist/berth-*.whl \
   | rg 'berth/(store/migrations|backends/.*yaml|auth/tiers.yaml|ui/index.html)'
 ```
 
-## Tag And Publish
+## Tag and publish
 
 ```bash
 git push origin main
@@ -78,21 +118,32 @@ git tag -a v0.5.0 -m "berth 0.5.0"
 git push origin v0.5.0
 ```
 
-Pushing a `v*` tag runs `.github/workflows/release.yml`. That workflow uploads
-the wheel and sdist to the GitHub Release and publishes the daemon image to:
+Pushing the `v*` tag runs `.github/workflows/release.yml`. It:
+
+1. Rebuilds the UI (`ui`), then fails if the committed `src/berth/ui` differs
+   from the fresh build — so a stale bundle stops the release.
+2. Runs `uv build` and creates a public GitHub Release with auto-generated notes,
+   attaching the `.whl` and `.tar.gz`.
+3. Builds and pushes the daemon image to GHCR with build provenance (`mode=max`)
+   and an SBOM, tagged with the version and `latest`:
 
 ```text
-ghcr.io/mapika/berth/daemon:<tag>
+ghcr.io/mapika/berth/daemon:v0.5.0
+ghcr.io/mapika/berth/daemon:latest
 ```
 
-## Install From A Release
+It does not publish to PyPI.
+
+## Install from a release
 
 ```bash
 uv tool install \
   https://github.com/Mapika/berth/releases/download/v0.5.0/berth-0.5.0-py3-none-any.whl
 ```
 
-## Smoke Test A Built Wheel
+## Smoke-test a built wheel
+
+Quick check that the wheel installs and the CLI runs in a throwaway venv:
 
 ```bash
 tmp=$(mktemp -d)
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index cf899e9..2336447 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,6 +1,6 @@
 # Troubleshooting
 
-Start with:
+When something is wrong, start here:
 
 ```bash
 berth doctor
@@ -9,74 +9,93 @@ berth ps
 berth logs
 ```
 
-Most failures are Docker, NVIDIA runtime, Hugging Face auth, TLS, or an engine
-that never became healthy.
+`berth doctor` checks the host: the `~/.berth` directory, port 11500, Docker,
+GPUs, your Hugging Face token, and whether the engine images are already
+pulled. `status` and `ps` tell you what's deployed and how it's doing. `logs`
+streams the active engine container.
 
-## Docker Cannot See The GPU
+Almost every problem is one of five things: Docker can't reach the GPU, the
+NVIDIA runtime isn't set up, Hugging Face auth, TLS, or an engine that never
+got healthy. The sections below are roughly in the order you'll hit them.
+
+## Docker can't see the GPU
 
 Symptoms:
 
 - `berth doctor` warns about Docker GPU access.
-- Engine containers start and immediately fail.
+- Engine containers start and then die immediately.
 - Docker errors mention `nvidia`, `device_requests`, or CDI.
 
-Checks:
+Check it directly:
 
 ```bash
 docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
 docker info | grep -i nvidia
 ```
 
+If the first command can't see the GPUs, berth can't either. Note that Docker
+28 and up uses CDI and no longer lists an `nvidia` runtime in `docker info`, so
+an empty grep isn't proof of anything by itself. `berth doctor` accounts for
+this: it falls back to actually launching a throwaway GPU container.
+
 Fix:
 
 - Install or repair `nvidia-container-toolkit`.
-- Restart Docker.
+- Restart the Docker daemon.
 - Re-run `berth doctor`.
 
-## Browser Warns About The Certificate
+If `docker info` itself fails or you get permission errors, your user probably
+isn't in the `docker` group.
+
+## The browser warns about the certificate
 
-First-run berth uses a generated local CA when `[public_tls]` is not
-configured. Browsers and SDKs will not trust it by default.
+On first run, when you haven't set `[public_tls]`, berth serves the public
+endpoint with a cert from its own local CA. Browsers and SDKs won't trust that
+by default, and that's expected.
 
-For quick local API testing:
+For quick local testing, skip verification:
 
 ```bash
 curl -k https://127.0.0.1:11500/healthz
 ```
 
-For a real exposed service, prefer:
+For anything you actually expose, get a real cert. Bootstrap behind a reverse
+proxy:
 
 ```bash
 berth deploy bootstrap --domain berth.example.com
 ```
 
-Then put Caddy or Nginx in front. See `docs/caddy.md`.
+That writes a behind-Caddy config and prints a ready-to-paste Caddyfile. Put
+Caddy or Nginx in front and let it handle TLS. See [caddy.md](caddy.md).
 
-## Model Download Fails
+## Model download fails
 
 Symptoms:
 
-- `berth pull` fails with a 401, 403, or gated-model message.
-- The model exists on Hugging Face but cannot be fetched.
+- `berth pull` fails with a 401, 403, or a gated-model message.
+- The model exists on Hugging Face but won't fetch.
 
-Fix:
+Set a token and pull again:
 
 ```bash
 export HF_TOKEN=hf_...
 berth pull owner/repo --name local-name
 ```
 
-For private or gated models, make sure the token belongs to an account with
-access to the repo.
+For private or gated repos, the token has to belong to an account that's been
+granted access to that repo. `berth doctor` warns when `HF_TOKEN` is unset, but
+it can't tell you whether the token has the right grants. (Either `HF_TOKEN` or
+`HUGGING_FACE_HUB_TOKEN` works.)
 
-## Engine Never Becomes Healthy
+## Engine never becomes healthy
 
 Symptoms:
 
-- Deployment stays `loading`, then moves to `failed`.
+- The deployment sits at `loading`, then flips to `failed`.
 - `berth logs` shows engine startup errors.
 
-Checks:
+Look at what the engine is saying:
 
 ```bash
 berth ps
@@ -84,25 +103,32 @@ berth logs
 docker ps -a --filter name=berth-
 ```
 
-Common causes:
+Usual causes:
 
-- Bad engine image tag.
-- Model does not fit with the requested context/concurrency.
-- Engine-specific launch flag is invalid.
-- Hugging Face download path is incomplete.
+- Wrong engine image tag.
+- The model doesn't fit at the requested context and concurrency.
+- An engine-specific launch flag is invalid.
+- The Hugging Face download is incomplete.
 
-Try a smaller context or lower concurrency:
+The fastest thing to try is asking for less. Drop the context and the
+concurrency:
 
 ```bash
 berth run qwen-0_5b --gpu 0 --engine vllm --ctx 1024 --max-seqs 4
 ```
 
-## Placement Refuses To Start
+`--max-seqs` caps concurrent decode sequences (vLLM `--max-num-seqs`, SGLang
+`--max-running-requests`) and feeds KV-pool sizing. Lower it hard for
+hybrid/Mamba models, where every sequence holds a state-cache block. If a
+specific engine flag is the problem, pass raw flags with `--extra` (repeatable),
+e.g. `-x '--reasoning-parser=qwen3'`.
+
+## Placement refuses to start
 
-This is usually intentional. berth estimated the requested deployment
-would not fit beside what is already loaded.
+Usually this is on purpose. berth estimated the deployment wouldn't fit beside
+what's already loaded, so it failed the launch instead of OOMing the host.
 
-Useful commands:
+See what's taking the room, free some, and retry:
 
 ```bash
 berth ps
@@ -110,51 +136,66 @@ berth stop <deployment-id>
 berth run <model> --gpu 0 --ctx 2048 --max-seqs 8
 ```
 
-Pinned deployments are not evicted automatically. Unpin or stop them first:
+Pinned deployments are never auto-evicted. If the thing in the way is pinned,
+unpin it (by model name) or stop it (by id) first:
 
 ```bash
 berth unpin <model-name>
 berth stop <deployment-id>
 ```
 
-## Port Or Listener Confusion
+You can also just ask for a smaller footprint with `--ctx` and `--max-seqs`,
+same as the section above.
+
+## Port or listener confusion
 
-Defaults:
+There are three listeners, and mixing them up is a classic. Defaults:
 
-- Public API/UI: `https://<public_host>:11500`
-- Cluster agent listener: `https://<cluster_host>:11501`
+- Public API and UI: `https://<public_host>:11500`
+- Cluster agent listener (mTLS): `https://<cluster_host>:11501`
 - Local CLI control socket: `~/.berth/sock`
 
-Show resolved config:
+The CLI talks to the daemon over the local socket, not over the network. The
+`:11500` listener is for clients (OpenAI-compatible API, the UI). The `:11501`
+listener is only for enrolled agents.
+
+See what actually resolved, and where each value came from:
 
 ```bash
 berth config show
 ```
 
-For local-only testing:
+For local-only testing, bind the public listener to loopback:
 
 ```bash
 BERTH_PUBLIC_BIND=127.0.0.1 berth daemon start
 ```
 
-For reverse proxy mode, use `docs/caddy.md` or:
+For reverse-proxy mode, see [caddy.md](caddy.md) or bootstrap one:
 
 ```bash
 berth deploy bootstrap --domain berth.example.com
 ```
 
-## API Key Fails
+If `berth daemon start` warns that the cluster listener is on `0.0.0.0` and
+internet-reachable, set `[cluster] bind` in `~/.berth/config.toml` to a
+private or VPN interface. More on the cluster side in
+[multi-node.md](multi-node.md).
+
+## API key fails
 
-Create a new admin key over the local socket:
+Keys can only be minted over the local control socket, so you create them from
+the box itself. Tiers are `admin`, `standard`, and `trial`:
 
 ```bash
 berth key create web --tier admin
 ```
 
-For the packaged systemd layout, the `/usr/local/bin/berth` wrapper handles
-the service user and `/var/lib/berth` state directory.
+For the packaged systemd layout, the `/usr/local/bin/berth` wrapper runs as the
+service user against the `/var/lib/berth` state directory, so create keys
+through that wrapper.
 
-Then:
+The secret is printed once. Then point a client at it:
 
 ```bash
 export BERTH_TOKEN=sk-...
@@ -162,5 +203,12 @@ export BERTH_URL=https://127.0.0.1:11500
 curl -k "$BERTH_URL/v1/models" -H "Authorization: Bearer $BERTH_TOKEN"
 ```
 
-If the key pepper file was lost from `~/.berth/key_pepper`, old keys cannot be
-verified. Mint new keys and back up `db.sqlite` and `key_pepper` together.
+If a key that used to work suddenly fails everywhere, check that
+`~/.berth/key_pepper` is still there. Keys are verified against that file. Lose
+it and no existing key can be verified again — you'd have to mint new ones. So
+back it up together with `db.sqlite`. The easiest way is one tarball of the
+whole recoverable set (db, CA, pepper, config):
+
+```bash
+berth backup create /var/backups/berth-$(date +%F).tar.gz
+```
diff --git a/examples/README.md b/examples/README.md
index cb230c5..aeba665 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,15 +1,18 @@
 # Examples
 
-These are small copyable starting points. They are not required for normal use;
-the CLI can create the same state through `berth pull`, `berth run`, and the
-admin API.
+Small, copyable starting points. None of these are required — the CLI and the
+admin API can build the same state through `berth pull`, `berth run`, and a
+couple of POSTs. They're here so you don't have to write the JSON from scratch.
 
-- `single-node-config.toml`: local single-host daemon settings.
-- `behind-caddy-config.toml`: public listener behind a TLS-terminating reverse proxy.
-- `service-profile-qwen.json`: reusable vLLM launch definition.
-- `service-route-chat.json`: public `model="chat"` route to that profile.
+- `single-node-config.toml` — daemon settings for a local single-host box.
+- `behind-caddy-config.toml` — the public listener when it sits behind a
+  TLS-terminating reverse proxy (see [../docs/caddy.md](../docs/caddy.md)).
+- `service-profile-qwen.json` — a reusable vLLM launch definition.
+- `service-route-chat.json` — a public `model="chat"` route pointing at that
+  profile.
 
-Apply the profile and route:
+To apply the profile and its route, point `$BERTH_URL` and `$BERTH_TOKEN` at your
+daemon and POST the two files:
 
 ```bash
 curl -k -X POST "$BERTH_URL/admin/service-profiles" \
@@ -22,3 +25,7 @@ curl -k -X POST "$BERTH_URL/admin/routes" \
   -H "Content-Type: application/json" \
   --data @examples/service-route-chat.json
 ```
+
+After that, a request for `model="chat"` lands on the `qwen-vllm` profile. There's
+more on profiles and routes in the [README](../README.md) and
+[docs/multi-node.md](../docs/multi-node.md).