@vibelord/lanes 1.2.0 → 1.5.0

package/payload/lanes/docs/RUNBOOK.md

@@ -24,6 +24,7 @@ measurements; substitute your account, containers and paths in operational comma
 | Scroll a lane | mouse wheel / tmux copy-mode as before (history lives in the lane, not in the viewer) |
 | Edit a lane's AGENTS.md, CLAUDE.md or .env.local | `Ctrl-Alt-e`: a floating **Edit** pane runs `lanes edit --focused`, one key picks (`1`–`5`; `q`/`Esc` closes), then `docker exec -it -u coder -w <checkout> <container> ~/.lz/bin/lane-edit <file>` replaces it — the editor runs in the lane's container as uid 1000, the server only checks the paths through `/proc/<init>/root` and copies nothing out ([guide](USERGUIDE.md#quick-edit)). `lanes edit: lane-edit is not installed in <c>` → `lanes install-container <c>`; `lane-edit: no editor on PATH` (exit 127) → the container has none of micro, hx, nvim, vim, vi (Lanes installs none); `container <c> is not running` → nothing to edit until it runs; `no git checkout in or above <dir>` → the lane works outside a checkout. The editor is the device's `lanes attach <device> --editor E` choice |
 | Throttle monitor | its own full-size tab, `Throttle` (next to `Host`); it starts when you first open the tab and restarts itself if it exits. It is no longer an entry in every board's sidebar. |
+| Open what an agent published, or upload from a phone | the Docs page, `https://<server>:8443/lanes-docs/`: phone **More → Docs**, the laptop bar's **Docs**, a ⌘/Ctrl-click on the sidebar's ` ↑ uploads · ▤ docs N` strip, or `d` on a lane for its own link; an agent publishes with `~/.lz/bin/lane publish <file>` or `lanes_publish` (section "Docs service"; the [user guide's Docs](USERGUIDE.md#docs)) |
 | Detach | `Ctrl-Alt-o` then `d` — or just close the window. Nothing on the server stops. |
 
 Sidebar glyphs: see the legend in [`docs/DESIGN.md`](DESIGN.md) (agent column `◆ ◇ ▸ ✓ ✗ _ ·`, terminal column
@@ -194,7 +195,7 @@ lanes keys revoke <device>   remove one machine     lanes keys adopt [--dry-run]
 lanes invite <name> --email ADDR   one-time join code (own terminal)   lanes invite list | revoke <id>
 lanes enrol list        open access requests      lanes enrol approve <id> | deny <id>   decide one
 lanes offboard <device> --yes   key, device, view (own terminal)   lanes token revoke <view>   sign a browser out
-lanes onboard <login> --container <name> [--workspace <id> --repo <path>] [--write]   a user's container, dry run first
+lanes onboard <login> --container <name> [--workspace <id> --repo <path>] [--step kimi-notify|grok-build] [--write]   a user's container, dry run first
 systemctl --user status lanes-statusd lanes-sync.timer lanes-ensure.timer lanes-web lanes-enrold
 lanes update --status   the last update and the last check (update/last.json)   lanes update --now   check and install now
 lanes update --rollback the release before again, the one left marked bad   systemctl --user status lanes-update.timer
@@ -208,10 +209,13 @@ lanes studio-host re-key --yes       after the owner revoked the Host: a new mac
   outcome; the full output is `~/.local/state/lanes/update/last.log`, the outcome `update/last.json`. Read it with
   `python3 -m json.tool ~/.local/state/lanes/update/last.json`: `result` `ok` (a step with `"warning": true` — `sync`
   exiting 1 for a board with an error, e.g. a removed container — needs the board fixed, not the update: `lanes sync`
-  names it); `partial` (exit 4) — the release is installed and a step after the switch failed: each step with a
+  names it; `enable-docs` with `"outcome": "skipped"` or `"refused"` and its `reason` is the docs page's Mermaid, never
+  fatal — see "Mermaid pin" — and the summary line says `mermaid ok`, `mermaid skipped: <reason>` or `mermaid
+  refused: <reason>`); `partial` (exit 4) — the release is installed and a step after the switch failed: each step with a
   non-zero `rc` is the one to run by hand (`sync` → `lanes sync`, `restart lanes-statusd` →
   `systemctl --user restart lanes-statusd.service`, `install-container <c>` → `lanes install-container <c>`,
-  `reload-views` → `lanes reload-views`, `ensure` → `lanes ensure --if-layout-changed`); `refused` (exit 3) — nothing changed: the last step names what said no
+  `reload-views` → `lanes reload-views`, `ensure` → `lanes ensure --if-layout-changed`, `enable-docs` with `"outcome":
+  "failed"` → `sh ~/.local/share/lanes/current/install/enable-docs.sh`); `refused` (exit 3) — nothing changed: the last step names what said no
   (`preflight`: a prerequisite, the user manager or Docker, or no installed release — `no release is installed here`:
   run the full `./install.sh --server` / `npx @vibelord/lanes@<release> --server` first; `commit`: another install
   holds `~/.local/share/lanes/.install.lock`, or a link is no symlink). A run that printed only
@@ -489,7 +493,7 @@ lanes studio-host re-key --yes       after the owner revoked the Host: a new mac
   and phone) > the legend ` ⏎ open · / find · x close · ? keys` (phone: ` Swipe to scroll ·
   Tap to open`). The last
   message lasts 3 s (`MESSAGE_S`, measured on the 1 s tick: `Sidebar.expire_message`) or until the next action begins
-  (`Sidebar.begin_action`: open, `x`/`×`, `R`, `P`, `a`/`+`, `u`, `z`, `p`, `h`, `H`, `o`, `/`, `U`, `+`, `r`, `?`, `Tab`, a chord) — never just until
+  (`Sidebar.begin_action`: open, `x`/`×`, `R`, `P`, `a`/`+`, `u`, `z`, `p`, `h`, `H`, `o`, `i`, `/`, `U`, `+`, `r`, `?`, `Tab`, a chord) — never just until
   a key: a cursor move, typing in a field, `Esc`, a focus report, the theme's OSC 11 answer, a wheel tick or a mouse
   release leaves it (DEF-1822; DEF-1815 before it kept it from the focus report only). `?` shows
   the key sheet (`  lanes <current> · view <tree>` first — cockpit v3 V2 — then `sidebar.KEY_SHEET`, 18 lines since R5's
@@ -928,6 +932,7 @@ only normalizes HOW a terminal reaches its lane:
 
 ## Installing agent hooks (opt-in, per container, dry run first)
 
+This section is Claude Code's and Codex's; Kimi Code, Grok Build and grok-cli (1.5.0) are in [Harnesses](#harnesses) below.
 Without hooks the sidebar's agent glyph comes from Claude's session files and Codex's pane title. Hooks make it
 event-driven: Claude Code or Codex runs `~/.lz/bin/lane-signal <status>` on a turn event, which writes
 `~/.lz/state/hooks/<lane id>.json` in the container, and `lanes-statusd` prefers that over the other signals while
@@ -989,6 +994,242 @@ next tool call: after a denied prompt, or an approved call that failed (`Permiss
 write nothing). A lane whose agent crashed loses its sidecar at once (dead pid); one
 whose agent is alive but silent keeps the last word for up to an hour.
 
+## Harnesses
+
+Since 1.5.0 (W12, spec `docs/superpowers/specs/2026-10-15-lanes-harness-observers-design.md`) Lanes reads Kimi Code,
+Grok Build and grok-cli lanes as well as Claude Code and Codex ones; what each status means for the person at the
+board is the user guide's [Harnesses](USERGUIDE.md#harnesses). This section is the operator's: what to install per
+container, how statusd decides, and how to check each harness. Claude Code's and Codex's hooks are in "Installing
+agent hooks" above.
+
+**Per container, once, in order.** Each `hooks install` prints its
+diff first and writes only with `--write`; each changes only its own entries; `--write` refuses a container whose home
+this account cannot write for uid 1000, as for Claude and Codex. Every file is kept as `<file>.bak-<UTC>` before it
+changes, a symbolic link below the container home refuses the file, and in a TOML file only Lanes' own marked block
+(`# >>> lanes <name> >>>` … `# <<< lanes <name> <<<`) is ever rewritten: to undo, delete the block.
+
+1. `lanes install-container <name>` — ships 1.5.0's contract: `lane-signal` (its harness, when no `--harness` or
+   `LANE_HARNESS` names one, read from the parent processes, never assumed `codex`), `lane-mcp` and its editors, and
+   the hook definitions in `~/.lz/hooks/` (`kimi-hooks.toml`, `grok-hooks.json`, `grok-cli-hooks.json`). Unless
+   `--no-mcp`, it also runs `~/.lz/bin/lane mcp install`, which adds the Lanes MCP server for each harness installed
+   there, beside Claude's and Codex's entries (each subsection below names its file).
+2. The hooks of each harness the container has, each with its dry run first: `lanes hooks install --agent kimi
+   --container <name>` ([Kimi Code](#kimi-code)), `--agent grok` ([Grok Build](#grok-build), after Grok Build is
+   installed) and `--agent grok-cli` ([grok-cli](#grok-cli)).
+3. Optional, the operator's call per container: `lanes onboard <login> --container <name> --step kimi-notify --write`
+   (Kimi Code's bell) and `--step grok-build --write` (installs Grok Build).
+4. New agent sessions read the hooks and the MCP entry; a running session keeps what it started with (inferred from
+   how the harnesses read their configuration at start, not measured).
+
+`lanes onboard` runs step 2 by itself for each harness whose home is in the container (`hooks-kimi`, `hooks-grok`,
+`hooks-grok-cli`; `skipped` otherwise); `kimi-notify` and `grok-build` run only when named with `--step`
+(`grok-build` right after the board, before the contract, so the same run writes Grok Build's MCP entry and hooks).
+
+What each event writes (`agent{}` vocabulary):
+
+| Harness | Event | status |
+|---|---|---|
+| Kimi Code | `UserPromptSubmit`, `TurnStarted`, `PreToolUse`, `PostToolUse`, `PermissionResult` | `working` |
+| Kimi Code | `PermissionRequest` | `needs_approval` |
+| Kimi Code | `Stop`, `Interrupt` | `needs_input` |
+| Kimi Code | `StopFailure` / `SessionStart` / `SessionEnd` | `errored` / `idle` / `shell` |
+| Grok Build | `UserPromptSubmit`, `PreToolUse`, `PostToolUse` | `working` |
+| Grok Build | `Notification` (`permission_prompt`) | `needs_approval` |
+| Grok Build | `Stop`, `StopCancelled`, `Notification` (`idle_prompt`) | `needs_input` |
+| Grok Build | `StopFailure` / `SessionStart` / `SessionEnd` | `errored` / `idle` / `shell` |
+| grok-cli | `UserPromptSubmit`, `PreToolUse`, `PostToolUse` | `working` |
+| grok-cli | `Stop` / `StopFailure` / `SessionEnd` | `needs_input` / `errored` / `shell` |
+
+Verified event names (2026-10-15, this host): Kimi Code 2.1.1's `HOOK_EVENT_TYPES` and its strict `[[hooks]]` schema
+(`event`, `matcher?`, `command`, `timeout?` 1–600) in its binary; grok-cli 1.1.7's hook events, its exact-string
+matcher, `sh -c` with its own environment, and its MCP server entry (`{id, label, enabled, transport, command, args,
+env}`, client name `grok-cli-<id>`) in the source its binary carries; Grok Build 1.0.52's events from its source and
+user guide (`docs/superpowers/specs/evidence/2026-10-15-grok-build-measurement.md` §3). Not yet proven on a live,
+logged-in session: that each harness fires these hooks in a lane as the source says.
+
+### The observed harness
+
+Which harness runs in a lane needs nothing installed: statusd OBSERVES it instead of guessing it from the pane title.
+It walks the pane's process tree in the container's `/proc` (`/proc/<pid>/task/*/children` and the `comm` of each
+process, breadth first from the pane's root, at most four levels and 64 processes, no spawn) and publishes
+`agent.harness` as `claude`, `codex`, `kimi`, `grok` (Grok Build), `grok-cli`, `shell` or `unknown`. The first process
+whose `comm` is `claude`, `codex`, `kimi`/`kimi-code` or `grok`, or whose executable holds `/claude/versions/`, names
+it: native Claude Code before 2.1.299 runs with its version as `comm` (`2.1.295`), so its executable names it
+(DEF-1993; the same rule as `lane-signal`'s and `lane_core`'s). A `grok` is Grok Build when its executable is
+`…/downloads/grok-linux-<arch>` (`readlink /proc/<pid>/exe`), any other is grok-cli; one whose executable cannot be read
+is `unknown`. Only shells is `shell`; anything else, a cut tree or an unreadable read is `unknown`. The answer is kept
+per pane pid (`statusd.HARNESS_CACHE`) and walked again when the pane's own children change or the harness process it
+found exited or now runs under another `comm`; `shell` and `unknown` are never kept.
+
+| Harness | Process | Observed without hooks | `source` |
+|---|---|---|---|
+| Claude Code | `claude` (or a native file `…/claude/versions/<version>`) | `~/.claude/sessions/<pid>.json` | `claude-session-file` |
+| Codex | `codex` (under the npm wrapper `node`) | the pane title and the bell | `title` |
+| Kimi Code | `kimi-code` (or `kimi`) | `~/.kimi-code/sessions/…/state.json` + `agents/main/wire.jsonl` | `kimi-session-file` |
+| Grok Build | `grok`, exe `$GROK_HOME/downloads/grok-linux-<arch>` | `$GROK_HOME/active_sessions.json` + the session's `events.jsonl` and `summary.json`, else its pane title | `grok-session-file`, `grok-title` |
+| grok-cli | `grok`, any other exe | nothing: no title, no bell, no pid in its database | — (hooks only) |
+| any of them, nothing else claiming | — | the process itself: `idle`, `done` with the bell | `process` |
+
+The order statusd takes them in: a hook sidecar > a Claude session file > a Kimi session file > the Grok Build
+observer (its session file, else its title) > the Grok Build title on a pane observed as `grok` > the Codex title (only
+where Codex can be) > the observed harness itself; the window bell turns an idle or finished turn into `done`. When
+the walk names a harness, that is the published `harness` whatever signal decided the status. Check it:
+
+```sh
+lanes doctor | grep '  lanes: '        # lanes: claude 50 · codex 20 · kimi 3 · grok 0 · grok-cli 0 · shell 0
+jq '[.lanes[].agent.harness // empty] | group_by(.) | map({(.[0]): length}) | add' ~/.local/state/lanes/status.json
+```
+
+To see what statusd decided for one lane:
+
+```bash
+python3 -c 'import json,sys; a=json.load(open(sys.argv[1]))["lanes"][sys.argv[2]].get("agent"); print(a)' \
+  ~/.local/state/lanes/status.json <lane id>
+```
+
+`harness` wrong: look at the pane's tree the way statusd does, read-only — with `P=/proc/$(cat
+~/.local/state/lanes/containers/<name>.pid)/root/proc` and the lane's `pid` from status.json (the pane's root
+process), `cat $P/<pid>/task/*/children` lists its children, `cat $P/<child>/comm` names each and `readlink
+$P/<child>/exe` its file. A harness more than four levels below the pane is `unknown`; so is a pane whose tree holds
+anything but shells and no harness. Before 1.5.0 a Kimi lane read `codex / idle`: the title rule took any title of two
+or more words for Codex's (DEF-1970).
+
+### Kimi Code
+
+**Observed.** statusd reads the newest session in `~/.kimi-code/sessions/wd_*/` whose `state.json` `cwd` equals the
+kimi process's working directory (`/proc/<pid>/cwd`). Expect `source: process` instead of `kimi-session-file` when two
+kimi lanes run in the same directory (they cannot be told apart, DEF-1971 — give each its own worktree, or install the
+hooks: each lane's sidecar outranks the session file), when the session has written nothing for an hour, or when
+`~/.kimi-code` or a session directory is a symlink (refused, never followed). Kimi rings no bell by default, so its
+finished turn shows `needs_input`, not `done`, until `kimi-notify` (below).
+
+**Hooks** (installed when the container has `~/.kimi-code/`): `lanes hooks install --agent kimi --container <name>`,
+read the diff, then add `--write`. It writes one marker-delimited `hooks` block of `[[hooks]]` into the container's
+`~/.kimi-code/config.toml` (from `~/.lz/hooks/kimi-hooks.toml`: PreToolUse, PostToolUse, PermissionRequest,
+PermissionResult, UserPromptSubmit, TurnStarted, Stop, StopFailure, Interrupt, SessionStart, SessionEnd →
+`~/.lz/bin/lane-signal … --harness kimi`); running it again replaces that block and nothing else, and the rest of the
+file is never rewritten. Another writer's `[[hooks]]` stay — Throttle's session observer and its other entries
+(`throttle setup --install-clients`: provider `throttle-kimi`) included, even when its writer put them inside the
+block: they are moved just below it. A `hooks` that is not `[[hooks]]` tables refuses. Undo: delete the lines between
+the markers. **The `.kimi-code` no-touch doctrine** (`docs/plans/workspace-session-registry-native-resume.md`,
+`src/provider/kimi_device.rs`) is about the Kimi CLI's device identity — its `~/.kimi-code/device_id` slot, which no
+Lanes or Throttle path reads or writes — not about this block, which is ours (spec §3, recorded).
+
+**Bell, MCP, trace.** `lanes onboard`'s `kimi-notify` step sets `notification_condition = "always"` in
+`~/.kimi-code/tui.toml`, in place in Kimi's own `[notifications]` table (its old value kept in a comment), so its bell
+reaches tmux and the observer marks a finished turn `done`. `lane mcp install` writes `mcpServers.lanes` into
+`~/.kimi-code/mcp.json` (the Claude shape; the environment passes through). Every canonical recipe that sets
+`ANTHROPIC_CUSTOM_HEADERS` also sets `KIMI_CODE_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>'`: Kimi Code
+blanks the Anthropic variable.
+
+### Grok Build
+
+**Where it lives.** Lanes expects Grok Build (xAI's official `grok`, 1.0.52 measured) under
+**`GROK_HOME=~/.grok-build`**, never the default `~/.grok`: that directory belongs to grok-cli (superagent-ai) in our
+containers, and Grok Build's installer replaces grok-cli's `~/.grok/bin/grok` with a symlink to its own binary. Every
+lane recipe exports `GROK_HOME=/home/coder/.grok-build`. Install it with `lanes onboard <login> --container <name>
+--step grok-build --write`: that runs, in the container as uid 1000, the stable-channel recipe
+(`https://x.ai/cli/stable`, the `.zst` artifact when `zstd` is there, else the plain one; `downloads/grok-linux-x86_64`,
+the relative link `bin/grok`, `[cli] installer = "internal"`). It edits no shell rc file and links nothing into
+`~/.local/bin`. The channel publishes no checksum: the receipt's `warn` row carries the download's size and sha256,
+marked unverified, for the operator to check (DEF-1997). Both CLIs show `grok` as the pane's command; `readlink
+/proc/<pid>/exe` tells them apart — `~/.grok-build/downloads/grok-linux-x86_64` is Grok Build, `~/.grok/bin/grok` is
+grok-cli.
+
+**Observed** (no hook installed; `libexec/harness_grok.py`, ARCHITECTURE "Grok Build and grok-cli"):
+
+| Signal | Read from | Gives |
+|---|---|---|
+| pid → session | `$GROK_HOME/active_sessions.json` (`session_id`, `pid`, `cwd`, `opened_at`) | the session of the pane's grok |
+| state | the last 64 KiB of `$GROK_HOME/sessions/<URL-encoded cwd>/<session id>/events.jsonl` | `working`, `needs_approval`, `needs_input` (`done` with the bell), `errored`, `idle` |
+| name | that session's `summary.json` `generated_title` | the lane's task line |
+| fallback | the pane title (`⚠ Action Required - …`, a braille spinner, `grok`, `<name> - grok`) | the same words, `source: grok-title` |
+
+statusd hands the observer every pane its walk found running Grok Build, every `shell` pane (a Grok-shaped title over
+a tree with no grok left is that harness ended: `grok` / `shell`) and every `unknown` pane whose `grok` could not be
+told apart by its executable (Grok Build only when `active_sessions.json` names its pid), with one title memory per
+container kept between cycles (`statusd.GROK_TITLES`): the `⚠ Action Required` prefix blinks while the pane is
+unfocused, so a busy title right after a prefixed one still reads `needs_approval` (DEF-1982).
+
+**Hooks:** `lanes hooks install --agent grok --container <name>`, then `--write`. It writes
+`~/.grok-build/hooks/lanes.json` (the whole file is Lanes'; Claude Code's JSON shape, which Grok Build reads from every
+`$GROK_HOME/hooks/*.json`: `Notification` as two groups, `permission_prompt` → `needs_approval` and `idle_prompt` →
+`needs_input`, then `Stop`, `StopFailure`, `StopCancelled`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`,
+`PreToolUse`, `PostToolUse` → lane-signal `--harness grok`) and two blocks in `~/.grok-build/config.toml`. `hooks` sets
+`[compat.claude] hooks = false, mcps = false` — without it Grok Build also runs the hooks in `~/.claude/settings.json`,
+which say `--harness claude`, and registers lane-mcp a second time — and `[ui.notifications] condition = "always",
+method = "bel", events = [turn_complete, approval_required, task_complete, agent_error]`, so the window bell is
+reliable inside tmux. `trace` sets `[model."grok-4.6"]` and `[model."grok-4.5"]` `env_http_headers = {
+"x-throttle-trace" = "LANES_TRACE" }` (quoted ids: a bare `[model.grok-4.6]` is the table `grok-4` → `6`, DEF-1995):
+Grok Build's `[models] extra_headers` is global, one trace for every lane, so recipes export `LANES_TRACE` instead. A
+`[compat.claude]` or `[ui.notifications]` table of the person's refuses the install: set the keys there by hand. A
+model they already configure is left out of `trace` and named. The MCP entry is the `mcp` block `lane mcp install`
+writes (`[mcp_servers.lanes]` with `command` only: Grok Build starts a stdio server with its own environment plus
+`GROK_SESSION_ID`, the session a `lanes_signal` report and every hook then name), a file edit rather than `grok mcp
+add`; `mcps = false` comes with the hooks block.
+
+What needs hooks: the sustained-idle backstop (`Notification` `idle_prompt`), why a turn stopped (`StopFailure`,
+`StopCancelled`) and a reliable bell. Not handled: leader mode (`[cli] use_leader = true`; DEF-1983, accepted) — the
+observer answers `unknown` with a note, and statusd then publishes no agent state for the lane until a hook speaks for
+it.
+
+To confirm a Grok Build lane is joined, in its container:
+
+1. `cat ~/.grok-build/active_sessions.json` — an entry whose `pid` is the pane's grok (`tmux display -p
+   '#{pane_pid}'`, then its child named `grok`). No entry while the lane sits at the welcome screen before a session
+   opens; then only the title speaks.
+2. `ls ~/.grok-build/sessions/` — the cwd's directory (the cwd URL-encoded, e.g. `%2Fhome%2Fcoder%2Fsrc%2Fbw-tools`)
+   holding a directory named by that `session_id` with `events.jsonl` and `summary.json`.
+3. `tail -n 3 ~/.grok-build/sessions/<dir>/<session id>/events.jsonl` — the last `type` names the state (`turn_ended`
+   with its `outcome`, a `phase_changed`, a `permission_requested`).
+
+The observer refuses a `GROK_HOME`, session directory or `events.jsonl` that is a symlink, and ignores a stale entry
+(dead pid, a pid that no longer runs grok, or one that started after the entry was opened). The file shapes come from
+Grok Build's source and user guide; no logged-in session has been measured yet, so a first live lane is worth checking
+against the three steps above (DEF-1981). Do not pipe `grok doctor --json` into `head`: 1.0.52 aborts on the closed
+pipe and leaves a `core` file in the cwd.
+
+### grok-cli
+
+grok-cli has no observable signal at all — no title, no bell, no pid in its database — so a grok-cli lane shows a
+state only through its hooks, and never `needs_approval`: it has no approval event (DEF-1980). Hooks (installed when
+the container has `~/.grok/`): `lanes hooks install --agent grok-cli --container <name>`, then `--write`, merges the
+lane-signal groups into the `hooks` of `~/.grok/user-settings.json` (UserPromptSubmit, PreToolUse, PostToolUse, Stop,
+StopFailure, SessionEnd; no matchers: grok-cli compares a matcher to the tool name exactly). Only that member changes;
+the file holds grok-cli's `apiKey`, and a dry run's diff prints any key, token or secret value as `…`. Its MCP entry is
+the `lanes` item of `mcp.servers` in the same file. grok-cli starts MCP servers with only HOME, LOGNAME, PATH, SHELL,
+TERM and USER, so `lane-mcp` reads `LANE_ID`, `LANE_WS`, `TMUX` and `TMUX_PANE` from grok-cli's own
+`/proc/<pid>/environ`, and only when that parent process is a harness (DEF-1992). grok-cli sends no custom headers: its
+requests carry no trace.
+
+### Throttle-side notes
+
+A trace only matters for a harness attached to a Throttle pool; a running lane gets the recipe's trace variables when
+it is next created.
+
+**The fleet's Kimi row after the update.** The 1.5.0 pulse reports the kimi pool (`/pools/kimi/ready`, `/metrics`,
+and `/pools/kimi/status` when tokened), but an update only ships the new `throttle-pulse` file: `lanes
+install-container` starts nothing while the `pulse` session runs, so the 1.4.0 loop keeps running and the sidebar's
+`◆ moonshot` row says `no data` (`lanes doctor`: `kimi ?`) until it is restarted (DEF-2003): `docker exec -u 1000
+<container> tmux -L lanes-pulse kill-session -t pulse`, then `lanes install-container <container>`.
+
+**Throttle-side items (the Throttle provider lane's; filed, not built in Lanes):**
+
+- DEF-2000 — Throttle's managed MCP entry for Kimi is written to `~/.kimi/mcp.json` (`src/cli.rs`
+  `stage_additional_gateway_user_entries` and its remove twin), a path Kimi Code 2.1.1 does not read: it reads
+  `~/.kimi-code/mcp.json`.
+- DEF-2001 — Throttle synthesizes `cc-session/` and `codex-session/` flows for untraced Claude and Codex requests, but
+  no `kimi-session/` flow: Kimi sends no session id on the Anthropic wire. A Kimi lane's requests join their lane only
+  through the `KIMI_CODE_CUSTOM_HEADERS` trace.
+- Grok: Throttle has no xAI pool, so there is no Grok fleet row and no Grok trace join. The paid-API lane and the
+  subscription pool, and their gates (O-XAI-key, O-XAI-capture, O-XAI-legal, O-XAI-oauth), are the review's
+  (`docs/plans/2026-10-14-xai-grok-pool-review.md`).
+- **Operator note, not a defect:** Kimi Code on productbox is not attached to Throttle — no `[pools.kimi]` in its
+  configuration, port 8095 closed — so its requests go to Kimi directly and the fleet's kimi row reads `0/0`.
+  Attaching it is a Throttle step (`throttle accounts add <name> --provider kimi --pool kimi`, then `throttle setup
+  --install-clients`; the [`throttle-kimi-provider`](../../skills/throttle-kimi-provider/SKILL.md) skill), outside
+  Lanes.
+
 ## The agents' MCP entries (`lane-mcp`, on by default)
 
 `lanes install-container <name>` ships `~/.lz/bin/lane-mcp` (with `lane_core.py`) and adds it to both agents in that
@@ -1018,7 +1259,7 @@ hand.
   the file. Same exit 1 and reason as `lanes hooks install` (DEF-1727). A symbolic link at `~/.claude.json`,
   `~/.codex` or `config.toml` is refused too, also by `lane mcp install`: from the host it would resolve outside
   the container. Add the entry to the file it points at by hand.
-- Inside the container: `~/.lz/bin/lane mcp install [--agent claude|codex|all]` prints the diff, `--write` applies it.
+- Inside the container: `~/.lz/bin/lane mcp install [--agent claude|codex|kimi|grok|grok-cli|all]` prints the diff, `--write` applies it (`all`, the default: Claude Code, Codex and each of Kimi Code, Grok Build and grok-cli whose home is there; a harness named on its own is written even without its home).
 - New agent sessions load the server; a running one keeps its tools. Check from a lane with the agent's own MCP
   listing (`/mcp` in Claude Code). The server's log is `~/.lz/s/logs/lane-mcp.log` (one line per request, rotated
   at 1 MiB; never a capture's text, a sent text or a note).
@@ -1086,6 +1327,10 @@ lands where, and how to take it back:
   lane's task line). The report stands until the agent's next tool call, prompt or permission prompt; the end of
   its turn keeps it unless it is `working` (DEF-1801). `cat ~/.lz/state/hooks/<lane id>.json` shows it: `event`
   stays `lanes_signal` while it stands.
+- `lanes_publish` (and `lane publish <file>` in a lane's shell) writes a publish request,
+  `~/.lz/state/publish/<lane id>/<id>.json`, naming a file under `/home/coder`; the docs service takes it within
+  about 5 s and answers in `<id>.receipt.json` beside it ("Docs service", "Publish pick-up"). `lanes_status` shows the
+  newest receipt as `published`. The file is read by the host, never sent by the agent.
 - Nothing an agent does ends, interrupts or attaches a lane, uploads a file, runs `lanes sync`, `lanes gc` or
   `lanes ensure`, renames a tmux session, or touches a session added with `lanes register` (`registered-sessions.json`
   on the host).
@@ -1121,8 +1366,8 @@ printf '%s\n' \
 ```
 
 It prints two frames, one line each, exit 0 and nothing on stderr. Frame `id` 1 carries `protocolVersion`
-`2025-06-18` and `serverInfo` `{"name": "lanes", "version": <~/.lz/VERSION>}`. Frame `id` 2 lists the ten tools in
-wire order, the same tools `lanes/tests/unit/golden/lane-mcp-tools.json` pins. The list is deterministic: run the
+`2025-06-18` and `serverInfo` `{"name": "lanes", "version": <~/.lz/VERSION>}`. Frame `id` 2 lists the eleven tools in
+wire order (`lanes_publish`, W10 W4, last), the same tools `lanes/tests/unit/golden/lane-mcp-tools.json` pins. The list is deterministic: run the
 command twice through `sha256sum` and the two digests match. The log gains a `start lane-mcp <version> wire 1` line.
 No output at all means the server could not start, for example because `lane_core.py` is missing beside it; run
 `lanes install-container <container>` on the host. `test_docs.AgentApi` runs this block exactly as printed here.
@@ -1203,7 +1448,7 @@ Settings (environment of the installer — `install/services.py` renders them in
 | Variable | Default | Meaning |
 |---|---|---|
 | `LANES_THROTTLE_CONTROL` | `http://127.0.0.1:19181` | control base URL, resolved in the poller's network namespace (see above); `none` sends no request at all (the log fold still runs) |
-| `LANES_THROTTLE_TOKEN_FILE` | unset | file holding a bearer; a loopback daemon without `remote_key` needs none. Never written to `economy.json` or the cursor |
+| `LANES_THROTTLE_TOKEN_FILE` | unset | file holding the control bearer (the daemon's `remote_key`, or the local client token `lanes throttle adopt-token` copies). `/status` and `/sessions` are guarded control routes: without it they answer `HTTP 401`, loopback or not — the control port has no loopback exemption (DEF-1930). Never written to `economy.json` or the cursor |
 | `LANES_THROTTLE_CONTAINER` | unset | the container whose home volume holds the daemon's log; the log dir becomes its `/home/coder/.local/share/throttle` (via `containers.json`) |
 | `LANES_THROTTLE_LOG_DIR` | `~/.local/share/throttle` | where `proxy.log` and `proxy.log.<day>` are read (read only); wins over `LANES_THROTTLE_CONTAINER` |
 
@@ -1216,6 +1461,157 @@ when it recovers; the reason is never written to `economy.json`. `economy.json`
 the next poll re-folds today. For a look without the daemon: `LANES_THROTTLE_CONTROL=none lanes economy --once
 --dry-run --status-file status.json --sessions-file sessions.json` with saved documents.
 
+## Fleet block and Throttle pulse: operator steps (1.4.0)
+
+1.5.0 adds the Kimi pool to the pulse and the block (`◆ moonshot`): after that update restart the pulse once, as
+"Harnesses" above says (DEF-2003); everything else below is unchanged.
+
+The sidebar's fleet block (user guide "Fleet") needs nothing from you to show the host and its containers. Its Throttle
+rows need the pulse running in the daemon's container, and its money and burn figures need one opt-in. In order (the
+reference follows: "Throttle pulse" for the container side, "Fleet facts" for what statusd publishes):
+
+1. **Install 1.4.0.** On an npm-installed server with `lanes-update.timer` on, the publish is the deploy: the update
+   restarts statusd (the new `fleet`/`throttle` keys) and re-runs `lanes install-container` for every container `lanes
+   sync` recorded, and for the daemon's container when sync did not record it, which ships `~/.lz/bin/throttle-pulse`
+   and starts its loop in the daemon's container. Otherwise: `npx @vibelord/lanes@1.4.0 --server --update-only`, or
+   `lanes update --now`.
+2. **Check the pulse.** `lanes doctor` prints `throttle pulse: 4 s old (container <c>), daemon up, tokened: no — lanes
+   throttle adopt-token <c>`. `none in status.json` means no pulse yet: the daemon's container is not one `lanes sync`
+   recorded (not on a board), or it is not the one Lanes picked (the Throttle tab's container) — put
+   `LANES_THROTTLE_CONTAINER=<c>` into the server's `~/.config/lanes/site.conf` (the one place Lanes reads it for the
+   pulse: `lanes install-container`, `lanes doctor` and every update's re-ship, re-runs and rollbacks included; never
+   the environment) and run `lanes install-container <c>` once. A name there (or a Throttle tab) whose container docker
+   no longer knows, or that has no home volume, is skipped by every update with a warning (`WARN  install-container <c>
+   (skipped: docker has no such container)`; the result stays `ok`): correct or remove the line. `stale` (the pulse's
+   `at` more than 90 s old, the bound statusd uses too) means the loop stopped: statusd starts it again within 10
+   minutes ("The re-arm" below, in its journal), or run `lanes install-container <c>`. `daemon down (connection
+   refused)` is the daemon, not the pulse.
+3. **Opt in to money and burn (optional).** `lanes throttle adopt-token <c>` copies the container's own local Throttle
+   client token into `~/.lz/throttle-token`; the pulse then reads the guarded `/pools/<pool>/status` ("The token"
+   below). Every guarded control route needs that bearer, loopback included (DEF-1930): there is no token-free way to
+   read spend. To opt out, delete the file; the next pulse says `tokened: no`.
+4. **The dashboard link (only after an authenticated Grafana).** Put `LANES_FLEET_DASHBOARD_URL=https://<host>[:port]
+   [/path]` into the server's `~/.config/lanes/site.conf` once the fleet-management Grafana (`christian-fleet`) is
+   behind authentication — never before: the link would hand every tailnet viewer the URL. No Lanes command writes
+   it. `lanes doctor` prints the URL, `unset`, or `⚠ … ignored — not an https URL`; a query string, a user part or a
+   fragment is refused too.
+5. **Laptops with a client from before 1.2.0** do not update themselves: their owner runs `npx @vibelord/lanes@1.4.0`
+   once. Newer clients ask `lanes hello --client-version` and install 1.4.0 within 6 h of the server running it.
+
+The pulse only reads (GET, no redirect) and writes one file; it never changes the daemon. Removing it: stop the loop
+as the user it runs as (`docker exec -u 1000 <c> tmux -L lanes-pulse kill-server`) and delete
+`~/.lz/bin/throttle-pulse`, `~/.lz/state/throttle.json` and `~/.lz/throttle-token` in that container; the block's
+Throttle rows then show the stale mark. The pulse is part of the container contract, so the next update ships it and
+starts it in the daemon's container again.
+
+## Throttle pulse
+
+The Throttle daemon binds its own container's `127.0.0.1` (DEF-1525), so the host cannot ask it anything. The pulse
+asks from inside: `~/.lz/bin/throttle-pulse` (Python 3 stdlib), shipped to every workspace container by `lanes
+install-container` with the rest of the contract, runs as a loop **only in the daemon's container** and writes what
+it learns to `~/.lz/state/throttle.json` there, which `lanes-statusd` reads through `/proc/<init>/root` for the
+sidebar's fleet block.
+
+**Which container.** `LANES_THROTTLE_CONTAINER=<name>` in `~/.config/lanes/site.conf`, else the container of the
+registry's Throttle Monitor tab (`tools--throttle-monitor`, the container that hosts most boards' monitor). `lanes
+install-container <that container>` starts the loop; for any other container it ships the file and says
+`throttle pulse: installed, not started here — …`.
+
+**How it runs.** A tmux session `pulse` on the socket `lanes-pulse`, as uid 1000 with `HOME=/home/coder`:
+
+```sh
+docker exec -d -u 1000 -e HOME=/home/coder <container> tmux -L lanes-pulse new -d -s pulse /home/coder/.lz/bin/throttle-pulse --loop
+```
+
+`lanes install-container` asks `tmux -L lanes-pulse has-session -t =pulse` first and starts nothing when the session
+runs (`throttle pulse: already running in …`); a start docker refuses is printed and makes the exit 1, after
+everything else was installed. To restart it after an update, end the session and install again:
+`docker exec -u 1000 <container> tmux -L lanes-pulse kill-session -t pulse`, then `lanes install-container
+<container>`. Its pane holds the journal: `docker exec -u 1000 <container> tmux -L lanes-pulse capture-pane -p -t
+pulse` (one line each time the reason a source failed changes, `ok` when it recovers; never the token).
+
+**What it reads.** Every 10 s, GET only, on `http://127.0.0.1:$LANES_THROTTLE_CONTROL_PORT` (19181 when the
+container's environment does not set it), 3 s timeout, at most 1 MiB per answer, no redirect followed, no proxy:
+
+| Route | Guarded | Gives |
+|---|---|---|
+| `/pools/claude/ready`, `/pools/codex/ready`, `/pools/kimi/ready` | no | configured / usable / exhausted / auth-failed / benched subscriptions, overflow ready (a `503` is a pool that is not ready; its body is read). A daemon with no Kimi account answers the kimi route with nothing configured; one from before its Kimi pool answers `404` (journalled; the other pools are read) |
+| `/metrics` | no | `throttle_pool_pressure_phase`, `throttle_pool_spill_fraction`, `throttle_overflow_in_flight`, `throttle_upstream_429_total` per pool |
+| `/pools/claude/status`, `/pools/codex/status`, `/pools/kimi/status` | yes | per pool: the worst measured 7-day and 5-hour utilization over its subscription accounts, the soonest reset; the overflow spend, enforced daily budget, fraction and alert level — for claude and codex only: Kimi has no paid overflow lane, so `overflow.kimi` stays `null` whatever its status renders |
+
+`cooling` is what is left of `configured` after usable, exhausted, auth-failed, disabled, billing- or
+organization-blocked and unhealthy accounts (the daemon's buckets overlap; floored at 0).
+
+**The token (opt-in, never automatic).** The `status` routes are guarded: the daemon's ControlAuth answers `401`
+to any request without its bearer, loopback included (DEF-1930). Without a token the pulse reads the open routes only
+and the burn and money fields stay `null`. The operator opts in once per daemon container:
+
+```sh
+lanes throttle adopt-token <container>
+```
+
+It copies `env.ANTHROPIC_API_KEY` from that container's own `~/.claude/settings.json` — the LOCAL proxy bearer
+`throttle setup --install-clients` wrote there, which must start `throttle_`; it is never a provider credential — to
+the container's `~/.lz/throttle-token` (0600, by rename, never through a link) and prints `adopted: …` or why not,
+never the value. The pulse picks it up on its next cycle and sends it only to the `status` routes. It uses a
+token file that is not a regular file or is readable by group or other (mode not 0600) as no token, and says so in
+its journal. To withdraw the opt-in, remove the file: `docker exec -u 1000 <container> rm ~/.lz/throttle-token`. After
+`throttle setup` changes the client token, adopt it again.
+
+**How to see it.**
+
+```sh
+docker exec -u 1000 <container> cat /home/coder/.lz/state/throttle.json
+docker exec -u 1000 -e HOME=/home/coder <container> /home/coder/.lz/bin/throttle-pulse --once   # one cycle, printed; exit 1 when the daemon did not answer
+```
+
+`{"v": 1, "at", "up", "tokened", "pools": {"claude", "codex", "kimi"}, "overflow": {"claude", "codex", "kimi"},
+"error"}` (the spec §2.1 shape, with W12's kimi pool; DM-LANES-THROTTLE-PULSE). The file is rewritten only when a value changed or 60 s passed, so `at` is a
+heartbeat: an `at` more than 90 s old means the loop stopped (a healthy pulse is read up to about 84 s after its
+`at`: the 60 s heartbeat lands on the next 10 s cycle, DEF-1941). `up: false` with `error` (`connection refused`,
+`timed out`, `HTTP 500`, …) means no open route answered; the pools then keep their last values. Utilizations and
+fractions are 0–1, rounded to three places; resets are epoch seconds.
+
+## Fleet facts (`fleet` and `throttle` in status.json, W11)
+
+statusd publishes two additive blocks in `~/.local/state/lanes/status.json` that the sidebar's fleet block and
+`lanes doctor` read (they read nothing else for it). No collector, no new service, no new spawn per cycle.
+
+**`fleet` — the host and its biggest containers.** Every `FLEET_INTERVAL` (10 s) statusd reads, from plain files:
+the `cpu` line of `/proc/stat`, `MemTotal`/`MemAvailable` from `/proc/meminfo`, `/proc/sys/fs/inotify/max_user_watches`
+(the ceiling only — watches in use are not counted in the loop), the PSI and load it reads every cycle anyway, and
+per container recorded in `containers.json` its cgroup `memory.current` and `cpu.stat` `usage_usec`. Rates come from
+two samples 10 s apart, so right after a statusd restart `system.cpu.utilization` and every `container.cpu.percent`
+are `null` for one interval. `container.cpu.percent` is of the whole host (`usage_usec` delta ÷ interval ÷ logical
+cpus × 100): 12 % of a 64-cpu host is about 8 cpus busy. `containers` holds the three biggest by memory. Figures are
+quantized (1 %, 0.1 GiB, 0.1 load), so `status.json` is rewritten only when one of them visibly moves or at the 15 s
+heartbeat. On a `critical` host no sample is taken: the last facts stay, `"stale": true`, until the host recovers.
+
+```sh
+jq .fleet ~/.local/state/lanes/status.json            # the facts; "stale": true = not sampled since the host went critical
+jq '.fleet.containers' ~/.local/state/lanes/status.json
+```
+
+**`throttle` — the Throttle pulse's last document.** The pulse ("Throttle pulse" above) writes
+`~/.lz/state/throttle.json` in the daemon's container and statusd copies it: one `stat` per cycle through
+`/proc/<init>/root`, a read only when the file moved, at most 64 KiB, never through a link. statusd names the daemon's
+container as the pulse section's "Which container" says (the tab's container: `jq '.tools'
+~/.local/state/lanes/registry.json`) and looks it up again after a `lanes sync` that changed the registry and every 5
+min (edit site.conf, then wait or `systemctl --user restart lanes-statusd`). No container known = no `throttle` key at
+all. `"stale": true` means the pulse's `at` is more than 90 s old (a healthy pulse rewrites every 60 s and is read up
+to about 84 s after its `at`, so 60–90 s is normal; `lanes doctor` and the sidebar use the same 90 s, DEF-1941), the
+file is absent, or it was refused (a link, a FIFO, more than 64 KiB, no v1 document) — the last values are kept and
+shown dim.
+
+**The re-arm (the only spawn this adds).** When the pulse file is older than 90 s (or missing) while the daemon's
+container runs and the host is not `critical`, statusd — between two cycles, never inside one — runs the start command
+of "How it runs" above, byte for byte (DEF-1940), at most once per 10 min and bounded to 10 s, and journals it
+(`journalctl --user -u lanes-statusd | grep 'throttle pulse'`: the file's age, `re-armed (exit N)` and the argv). It
+starts nothing when `~/.lz/bin/throttle-pulse` is not installed in that container (`lanes install-container <c>` ships
+it), and it never runs on a `critical` host — a pulse that keeps going quiet on a healthy host is a pulse that
+crashes: run it by hand in the container (`~/.lz/bin/throttle-pulse` without `--loop`, as "How to see it" above
+shows) and read its stderr.
+
 ## Push notifications (opt-in)
 
 `lanes-notify.service` sends one push to an [ntfy](https://ntfy.sh) topic when a lane's agent ENTERS needs-you —
@@ -1298,7 +1694,7 @@ that becomes readable switches the pushes on within one tick and a removed one s
 | `topic` | required | `[A-Za-z0-9_-]{1,64}`; on a public server the topic name is the only secret — pick a long random one |
 | `token_file` | unset | a file holding an ntfy access token (sent as a bearer). An unreadable file disables sending rather than sending unauthenticated (or with the token it held before). Keep the token in that file (`chmod 600`), never in `notify.conf` |
 | `quiet_when_device_active_s` | `120` | presence window above; `0` never suppresses — except for the one person present when their profile sets a `notify.quiet_s` of its own |
-| `action_url` | unset | a URL template over `{lane}` (the lane id, URL-quoted), e.g. a page of yours that opens it; becomes the push's tap target and an **Open lane** button |
+| `action_url` | unset | a URL template over `{lane}` (the lane id, URL-quoted), e.g. a page of yours that opens it; becomes the push's tap target and an **Open lane** button. `{doc}` (plan W10 W7) is the docs page of the document a `published` push names, `/lanes-docs/d/<id>` (`https://<server>:8443{doc}` opens it), empty in a needs-you push. The `published` push (plan W10 W4) is sent by the docs service's publish pick-up, not by this unit: same config, same desk-presence rule, `{title: Published, message: <lane name> published a document (<kind>, <size>) + its page, priority 2}`, at most one per lane per minute, never the document's title or name |
 
 Without a valid `url` and `topic` the service only tracks transitions and sends nothing. Turn it on:
 
@@ -1374,12 +1770,27 @@ The Studio's design of record is `docs/design/throttle-studio.md` (§1.1 "The la
 ## Uploads (the Cursor `uploads/` folder, without Cursor)
 
 Files land in `<board folder>/uploads/` on the server — the same folder you drop into from Cursor. The folder is
-created on first use and kept out of commits through the repo-local `.git/info/exclude` when the repo does not
-already ignore it. Afterwards the in-container path is on your clipboard and in a notification.
+created on first use (0755) and kept out of commits through the repo-local `.git/info/exclude` when that file does not
+name it yet. Afterwards the in-container path is on your clipboard and in a notification. Every upload — these ways
+and the Docs page's drop area ("Docs service" below) — also becomes a docs-store document with a sha256 receipt (W10
+W5): one module, `libexec/uploads.py`, lands the file and hands the same bytes to `docs_store.intake` in one pass, so
+the receipt is of exactly what arrived; the store keeps a copy (never a hard link to the container's file, which an
+agent could rewrite under an unchanged receipt). `lanes upload` says each receipt on stderr (`# docs: <name> <bytes> B
+sha256 <hash> <id>`, in the helper's log) and records it for the login that owns the asking device, under the lane its
+view shows; a device nobody owns gets a `docs.log` line (`upload - - <lane> <bytes> <sha256> no-owner`) and no
+document; a file over 32 MiB lands without one (`intake … too-large`). stdout and the spool's `<request>.done` are what
+they always were.
+
+The host never follows a symbolic link in the container's folder (an absolute link would resolve against the host's
+root: DEF-1891) and runs no git there (`git check-ignore` runs the repository's `core.fsmonitor`, a command the
+container chose: DEF-1890). A folder or `uploads/` reached through a link is refused (`lanes: uploads/ in the
+workspace folder is not a directory (a symbolic link is refused)`): replace the link with the real directory in the
+container. The tar stream is unpacked member by member: links that leave the upload, `..`, devices and FIFOs refuse
+the whole upload, as tar's data filter did.
 
 | Way | How |
 |---|---|
-| Upload strip in the sidebar | The one row above the footer rule, ` ↑ uploads · click, then drop  (U)`. Click it (or press `U` in the sidebar, `Ctrl-Alt-u` from anywhere in the tab) — it turns into ` ↓ DROP FILES NOW · anywhere · Esc` — then **drop the files anywhere on the window**. The file goes to the board of that tab and its path is typed into the lane, ready for the agent. `Esc` cancels. While it sends the strip says ` ↑ sending 2 files · 12.4 MiB` and repaints only when the helper reports progress (no spinner, no fast tick); the result stays 8 s as ` ✓ name, name` or ` ✗ reason`. |
+| Upload strip in the sidebar | The one row above the footer rule, ` ↑ uploads · click, then drop  (U)` — ` ↑ uploads · ▤ docs 3  (U)` once the workspace's lanes have published documents, the whole row then a link to the docs page (plan W10 W7). Click it (or press `U` in the sidebar, `Ctrl-Alt-u` from anywhere in the tab) — it turns into ` ↓ DROP FILES NOW · anywhere · Esc` — then **drop the files anywhere on the window**. The file goes to the board of that tab and its path is typed into the lane, ready for the agent. `Esc` cancels. While it sends the strip says ` ↑ sending 2 files · 12.4 MiB` and repaints only when the helper reports progress (no spinner, no fast tick); the result stays 8 s as ` ✓ name, name` or ` ✗ reason`. |
 | Watch folder | `~/Lanes Uploads/` → the board your view shows; `~/Lanes Uploads/<board>/` → that board. Sent files move to `.sent/<date>/`. Point CleanShot's save folder here for instant screenshot upload. |
 | Command | `lanes-upload [-w <board>] [--paste] <files…>` · `lanes-upload --clipboard [--paste]` (clipboard image or copied files) |
 | macOS droplet | `~/Applications/Lanes Upload.app`: drop files on it (Dock); double-click uploads the clipboard screenshot |
@@ -1542,6 +1953,10 @@ Laptop and tablet browsers: see the [installation guide](INSTALL.md#laptop-and-t
 - **`lanes web` printed a `127.0.0.1` URL**: the host has no Tailscale name. Connect Tailscale on the host;
   there is no public fallback.
 
+The Docs page (`/lanes-docs/`: the phone's **More → Docs**, the laptop bar's **Docs**, the sidebar's ` ▤ docs N`) is
+a service of its own behind the same Serve and Caddy, with its own pinned Mermaid: section "Docs service" (its unit,
+pin gate, `docs.log`, routes, Mermaid pin, doctor lines and the operator's live checklist).
+
 ### Tailscale Serve
 
 `lanes web` (not `--print-only`) makes Tailscale Serve forward `https:8443` to `http://127.0.0.1:8083` after it
@@ -1823,6 +2238,340 @@ signed out in step 3; their views are named, not ended — offboard each by name
 open with the key keeps running until it ends (step 1 says so). `enrol.log` gets one `offboard` line with the key's
 fingerprint and `ok` or `incomplete`.
 
+## Docs service (`lanes-docsd`, W10 W3)
+
+The docs cockpit's web half: what an agent publishes from a lane (W4, "Publish pick-up" below) and what a person
+uploads (W5: the Docs page's drop area and every `lanes upload`) is opened at
+`https://<host>.<tailnet>.ts.net:8443/lanes-docs/` from the phone or laptop shell, bound to the person's
+tailnet login. `lanes-docsd.service` runs `libexec/docsd.py` on **127.0.0.1:8185**; the `lanes-mobile` Caddy forwards
+`/lanes-docs/*` to it (`handle_path /lanes-docs/*` in `web/Caddyfile`, which strips the prefix and is the FIRST handle of
+the site, before the Zellij routes) and keeps Serve's `X-Forwarded-For` (`trusted_proxies 127.0.0.0/8`, as on
+`/enrol/*`). The site-wide Caddy header block is `header @notdocs` (`@notdocs not path /lanes-docs/*`), so a docs
+response carries docsd's headers only. Every server install enables and restarts it after `lanes-enrold`, then runs
+`install/enable-docs.sh` for the page's Mermaid ("Mermaid pin" below; never fatal); an update (`--update-only`)
+restarts it when it runs (`update.TRY_RESTART`), runs `enable-docs.sh` right after, and, like every update, enables
+nothing — a server set up before the docs service and only updated since has no `lanes-docsd` until one full `--server`
+install (or `systemctl --user enable --now lanes-docsd.service`); `lanes doctor` says so (DEF-1900, mitigated). In
+order below: the unit, the pin gate and who sees what, the routes, uploads, encryption, `docs.log`, the publish
+pick-up and the Caddy reload; then "Mermaid pin", "What `lanes doctor` says" and the operator's live checklist
+("Operator verification"). `lanes docs push <id>` prints one document's receipt and exits 2 `not configured`: the
+hook for the data service's publication surface, not built (operator gate 3 of the plan).
+
+The unit, `lanes-docsd.service` (rendered from `systemd/lanes-docsd.service` by `install/services.py`), runs
+`python3 -S -E libexec/docsd.py` in `lanes.slice` with `Restart=on-failure` (10 s), `NoNewPrivileges=true`,
+`UMask=0077`, `MemoryHigh=128M` and `MemoryMax=192M`, and `WantedBy=default.target`; no `ProtectHome` (it writes
+`~/.local/state/lanes/docs/` and `docs.log`, its publish pick-up reads each workspace container through
+`/proc/<pid>/root`, as `lanes-statusd` does, and an upload lands in the workspace's `uploads/` through the container's
+home volume). MEASURED 2026-10-08 on the development host (`/usr/bin/python3`
+3.12.3 `-S -E`, load about 70; not the ceobox service): idle VmHWM 25 MB, one 32 MiB upload 56 MB, two at once (the
+most it parses: `UPLOAD_SLOTS`) 89 MB; the security review (2026-10-08) measured 94 MiB for two. A decryption now
+takes one of the same two slots (it holds up to 32 MiB of plaintext), so at most two 32 MiB buffers are held at once;
+the composed peak under `MemoryMax` (two buffers, two renders, the render cache, a pick-up survey) is not measured
+(DEF-1917, mitigated). `LANES_DOCS_PORT` (or `--port`) moves it off 8185 (the Caddyfile route must follow); `--bind`
+takes a loopback address only.
+
+```sh
+systemctl --user status lanes-docsd.service
+journalctl --user -u lanes-docsd.service -n 30     # "listening on 127.0.0.1:8185; pinned request (…); domains …"
+tail ~/.local/state/lanes/docs.log                 # one line per read, upload refusal, publish, intake and denial
+lanes doctor                                       # the five docs lines below
+```
+
+**The pin gate.** docsd answers NOTHING until the operator has run the enrolment service's Serve header check (section
+"Enrolment service", Operator verification) and pinned its result with `lanes enrol mode request` (it reads
+`~/.local/state/lanes/enrol-mode` on every request: no restart). Unpinned (`auto`), pinned `invite`, or a pin that
+cannot be read: every request is `403 not-pinned`, and the start line says `NOT pinned`. `LANES_ENROL_REQUEST_MODE`
+in enrold's unit is enrold's alone and is not a pin here. After the pin, a request is answered only when ALL hold —
+else `403` with the word, a short page for a browser:
+
+| Check | Refusal |
+|---|---|
+| it came through Tailscale Serve: its `X-Forwarded-For` (Serve sets it, Caddy keeps it) names a non-loopback address | `not-through-serve` (a probe of 127.0.0.1:8185 or of Caddy from this host) |
+| Serve's identity header set: `Tailscale-User-Login` and `Tailscale-User-Name` | `no-identity` (a tagged device) |
+| the login validates as a member login | `invalid-login` |
+| the pin above | `not-pinned` |
+| the login owns a valid `members/<device>.json` (casefolded) | `not-a-member` (`lanes keys owner <device> <login>`) |
+| its domain is in `LANES_DOCS_DOMAINS`, else `LANES_ENROL_DOMAINS` (default `beyondwork.ai`, `*` = any) — set it in this unit's drop-in | `domain-not-allowed` |
+| its `Sec-Fetch-Site` is `same-origin` (a page, script, stylesheet or image of the Docs pages, the phone/laptop shell's **Docs** link) or `none` (an address typed or bookmarked, a link opened from a terminal or a phone app); or it is a top-level navigation — a GET or HEAD with `Sec-Fetch-Mode: navigate` and `Sec-Fetch-Dest: document` — from any site (a link followed in ntfy's web app, a chat, a mail); `POST /up` only `same-origin` or `none` — every route, since the security review of 2026-10-08 | `cross-site` (anything else from another site — `cross-site`, `same-site` (`*.ts.net` is a public suffix, so another tailnet host's page is same-site) — that is not such a navigation: a `fetch()`, an image, a script, a frame, a form posted to `/up`; or no `Sec-Fetch-Site` on a request that is not a navigation: a browser too old to send it, or `curl`) |
+
+No Zellij cookie is consulted. The `cross-site` check is why a sandboxed artifact (an opaque origin) cannot spend the
+viewer's login here: its `fetch()` and subresource loads are not navigations. A link to a docs page followed from
+another website (a web mail, a chat in a browser, ntfy's web app) is a top-level navigation and is served. The
+artifact's sandbox (`sandbox allow-scripts` only) cannot open a window, submit a form or navigate another browsing
+context; the one navigation its script can start is of its own page, which replaces it unless the answer is a download
+the sandbox blocks, so what it can request that way is bounded by the 300-a-minute limit (the HTML standard's rules,
+not measured in a browser).
+**Trust boundary:** as for enrold (DEF-1645, open), a process on this host that reaches loopback can send the headers
+itself and read any member's documents; the pin and the Serve-only check are the controls, and the same `docker ps
+--filter network=host` audit applies. And a member's device key carries `restrict,pty` but no `command=`
+(`libexec/keys.py` `OPTIONS`): a member who can SSH in has a shell as the lanes account and can read every store
+directly, so the per-login separation of the docs service holds between people who only use the web, not against a
+member with a device key (DEF-1919, open). Never expose 8443 through Tailscale Funnel (Funnel traffic carries no
+identity headers).
+
+**Who sees what.** A person sees the documents in their own store (their uploads), the documents whose `for` names
+them, and a document that names nobody when a member record they own grants its workspace. A record's `workspaces`
+(the board ids an invite recorded with `lanes invite --workspaces`) grants those boards; a record that lists none —
+a key added with `lanes keys add|adopt`, a device enrolled by request, an invite minted without `--workspaces` —
+grants every workspace the server serves (the registry's), because nothing else in Lanes narrows by that list
+(DEF-1852, closed). The same grant decides the lanes the upload form offers and `POST /up` accepts. A document a
+person cannot see answers `404`, like one that does not exist.
+
+| Route (after Caddy strips `/lanes-docs`) | Answer (wire contract v1, DM-LANES-DOCS-WIRE) |
+|---|---|
+| `GET /` · `GET /?ws=<ws>&lane=<lane>` | the index page: workspace → lane → newest first, counts, the upload form; the filter (either key optional) must name a workspace/lane the person knows, else `404` |
+| `GET /d/<id>` | the document page: Markdown rendered (mdlite; over 1 MiB not rendered; from the render cache when its sha256 was rendered before; `503 busy` + `Retry-After` when two renders run and none ends within 1 s), an HTML/SVG artifact linked (never embedded), a file's facts and download |
+| `GET /d/<id>/raw` | the bytes, `Content-Disposition: attachment; filename="<name>"`, `X-Lanes-Sha256` |
+| `GET /d/<id>/artifact` | kind html/svg only: the bytes as a top-level document under `Content-Security-Policy: sandbox allow-scripts` |
+| `GET /receipt/<id>.json` | `receipt.json` (`{v, id, sha256, bytes, url, at}`) |
+| `GET /docs.css`, `GET /docs.js` | `web/docs.css` / `web/docs.js` of the running tree (W6), else `404` |
+| `GET /upload.css`, `GET /upload.js` | `web/upload.css` / `web/upload.js` (W5, the index's drop area), else `404` |
+| `POST /up` | multipart form: `lane` (+ optional `ws`), files; each lands in the workspace's `uploads/` AND the store, both or neither; `200 {receipts: [{id, name, sha256, bytes, url, at, landed}]}` or a page; `429` (30 per login per 10 min) + `Retry-After`, `503 busy` (two big buffers at once — uploads and decryptions —, one per login, or the store lock), `415`, `411`, `413` (32 MiB), `408 request-timeout` (the body did not arrive within 30 s + its length at 64 KiB/s), `400 bad-request\|no-file\|no-lane\|unknown-lane\|unknown-workspace`, `503 registry-unavailable`, `503 uploads-unavailable` (the container's folder: home volume unknown, a link on the way), `500 encrypt-failed` |
+| every route but `POST /up` | `429 rate-limited` + `Retry-After` past 300 requests per login per minute (one `docs.log` line per minute) |
+
+**Limits** (per `lanes-docsd` process; security review 2026-10-08 — each pinned by a test in `tests/unit/test_docsd.py`
+or `test_docs_store.py`, values in `libexec/docsd.py` / `docs_store.py`):
+
+| Limit | Value | Past it |
+|---|---|---|
+| requests per login, every route but `POST /up` (`VIEWS` / `VIEW_WINDOW`) | 300 per 60 s, a fixed window | `429 rate-limited` + `Retry-After`; one `view … rate-limited` line per window |
+| Markdown renders at once (`RENDER_SLOTS`, `RENDER_WAIT_S`) | 2; a view waits 1 s for one | `503 busy` + `Retry-After: 5` |
+| render cache (`RENDER_CACHE_BYTES`, `RENDER_CACHE_ENTRY`) | 8 MiB in all, by the document's sha256, least recently used out; a render over 2 MiB is not kept | a second view of a cached document renders nothing and needs no slot |
+| big buffers at once (`UPLOAD_SLOTS`), shared by uploads and decryptions | 2, at most 1 per login; a decryption also one at a time and waits 5 s for a slot | `503 busy` + `Retry-After: 5` |
+| uploads per login (`UPLOADS` / `UPLOAD_WINDOW`) | 30 per 10 min, counted at the start | `429 rate-limited` |
+| upload body deadline (`BODY_GRACE_S`, `BODY_MIN_RATE`) | 30 s + length / 64 KiB/s (32 MiB: 542 s) for the whole body; each read still times out after 30 s without data | `408 request-timeout`, connection closed, the slot free again |
+| refused body read away (`DRAIN_LIMIT`, `LINGER_S`) | 64 MiB before the answer, then 5 s | the client may see a reset |
+| pick-up survey (`MAX_ENTRIES`) | 4,096 directory entries per container per cycle (its publish directory and lane directories together) | the container is refused for the cycle: nothing taken; the journal says `pick-up <container>: refused: more than 4096 entries …` once an hour (`OVER_CAP_SAY_S`) |
+| pick-up per container (`MAX_PICKUPS`, `PUBLISHES`) | 16 per cycle, 30 per 10 min | the rest wait; past 30 refused `rate-limited` |
+| `docs.log` refusal lines (`DENIED_REPEAT_S`, `MAX_DENIED_SOURCES`, `MAX_DENIED_LOGIN`) | one `denied` line per source (the tailnet address Serve forwarded, else the peer) and word, then one `denied-repeat` line per minute with the count; 1,024 sources remembered; a login logged at most 64 characters | — |
+| `docs.log` size (`docs_store.LOG_ROTATE_BYTES`) | 8 MiB, then `docs.log.1` (one generation) | the older generation is replaced |
+
+Every response has `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` and a
+CSP: pages `default-src 'none'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; connect-src
+'self'; form-action 'self'; base-uri 'none'` (`connect-src` for the drop area's own `POST up`), an artifact exactly
+`sandbox allow-scripts`, everything else `default-src 'none'; sandbox`.
+Links and assets in a page are relative (`docs.css`, `d/<id>`), so the pages work under the stripped prefix; open the
+index as `/lanes-docs/` with the slash (`/lanes-docs` alone is the page route a device of that name would have, which
+is why `lanes-docs`, `lanes-assets` and `enrol` are not device names). An upload goes through `uploads.receive` (W5):
+it lands in the lane's workspace's `uploads/` (`<folder>/uploads/<name>`, `-1` on a collision, exactly as `lanes
+upload` lands one) and `docs_store.intake` (`source` `web`, kind by extension, `for` and `by` the uploader) takes the
+same bytes into the person's store; the receipt's `landed` is the in-container path to tell the agent. The drop area is
+a plain form that works without a script; `web/upload.js` (loaded by the index only) adds the drop onto the whole area,
+a size check before sending, progress and the receipt list.
+The multipart body is split by docsd's own bytes scan, each part's headers parsed by `email.parser`: parsing a 32 MiB
+body whole with `email.parser` MEASURED about 430 MB peak RSS and 3.8 s, the scan 0.05 s and no copy.
+
+**A refused upload is answered, not reset (DEF-1854, closed by W5).** A browser sends its whole body before it reads
+the answer, and a server that answers and closes while the body is still arriving resets the connection under its own
+answer. docsd now reads a refused body away up to its `Content-Length` — at most 64 MiB (`DRAIN_LIMIT`, twice the cap) —
+before it answers (with `Connection: close`); past that it answers, shuts its write side and reads the rest for at
+most 5 s (`LINGER_S`). MEASURED 2026-10-08 against a real `python3 -S -E docsd.py` (development host, load ~15–20 on
+64 cores), three concurrent 32 MiB uploads then a 48 MiB and a 100 MiB one: before (the W3 tree) 200, 200 and a
+`BrokenPipeError`, and both oversize uploads `BrokenPipeError`; after, three runs, 200, 200, `503 busy` and both `413`
+read by the client. Over a slow link a body past 64 MiB can still be reset; upload.js refuses a set over 32 MiB before
+it sends.
+
+**Encryption at rest (`age`, W5; off by default).** `LANES_DOCS_AGE_RECIPIENT=<age recipient>` in lanes-docsd's
+drop-in makes the docs store keep each NEW document as `age -r <recipient>` output (`<name>.age`, meta.json `enc:
+{alg, file, bytes, recipient}`); the file in the workspace's `uploads/` stays plain (agents read it), and receipts stay
+the sha256 of the plaintext, computed before encryption (age output is randomised, so a hash of it would match nothing
+anyone holds). `lanes upload` runs over SSH, outside the unit, and reads the same drop-in files, so both paths follow
+one switch. For docsd to open encrypted documents, give it an identity file with `LANES_DOCS_AGE_IDENTITY=<path>`: raw
+downloads and artifacts are then decrypted on the fly (at most 32 MiB, one at a time) and checked against the receipt;
+without it they answer `409 encrypted` (a page that sends the person to `uploads/`) and a document page shows its facts
+only. Documents stored before the switch stay plain. Every server install refuses the setting where no `age` binary is
+on PATH (`host-install.sh` `check_docs_age` → `python3 libexec/docs_store.py check-age`, exit 1 with the reason; an
+update records it `refused`, nothing changed); install `age` first.
+
+```sh
+systemctl --user edit lanes-docsd.service   # [Service]
+                                            # Environment=LANES_DOCS_AGE_RECIPIENT=age1...
+                                            # Environment=LANES_DOCS_AGE_IDENTITY=/home/<you>/.config/lanes/docs-age.key
+python3 ~/.local/share/lanes/current/libexec/docs_store.py check-age && systemctl --user restart lanes-docsd.service
+```
+
+**docs.log** (`~/.local/state/lanes/docs.log`, 0600, append-only, DM-LANES-DOCS-LOG): `<at> <login> <event> <id> <lane>
+<bytes> <sha256> <outcome>` — docsd adds `denied` (outcome = the refusal word; the first refusal of a source and word,
+the login cut to 64 characters) and `denied-repeat` (one a minute while that source keeps being refused: the `bytes`
+field is how many refusals the line folds, the login the latest), `view`/`raw`/`artifact`/`receipt` (`ok`,
+`not-found`, `encrypted`, `busy`, and `view … rate-limited` once a window), `upload` (a refusal before any file
+reaches intake, `request-timeout` included) and `publish` (one per request the pick-up takes: `ok` or the refusal
+reason — the precise word, also where the receipt says `not-delivered`); each stored file is intake's own `intake`
+line; `lanes upload` adds `upload … no-owner`/`no-lane`/`too-many` lines with a file's size and sha256 when it lands
+without a document. Never content, a title or a file name. At 8 MiB the file is renamed `docs.log.1` (replacing the
+one before) and a new one begun, by whichever writer finds it full first (an exclusive `flock`; the others append to
+the new file), so the two files never hold much more than 16 MiB. Before the security review (2026-10-08) refusals
+from any tailnet device appended 269 B each without bound (DEF-1913).
+
+**Publish pick-up (W10 W4).** `lane publish <file>` and the agents' `lanes_publish` write a request in the container,
+`~/.lz/state/publish/<lane id>/<id>.json` (`{v: 1, path, title, kind, claimed_sha256, mime, bytes, for}`;
+DM-LANES-PUBLISH-REQUEST). A thread of `lanes-docsd` takes them every 5 s — for each container `containers.json` names
+whose init pid is alive (a pid whose `/proc/<pid>/root` is the host's own `/` is skipped, and so is one whose
+`/home/coder` is not the home volume `containers.json` records, when this account can see that volume), at most 16 per
+container per cycle and 30 per container per 10 minutes (more are refused `rate-limited`). It first surveys the
+container's publish directory and lane directories, at most 4,096 entries in all; a container that holds more is
+refused for the cycle (Limits above). It renames the request to `.<id>.taking` (a directory planted at that name is
+removed when empty, else moved aside to `.<name>.<random>.planted`; a request it still cannot rename is left alone, the
+next one is taken and the journal says why once), reads it, resolves the file inside
+the container to a regular file under `/home/coder` (never through a link, never a FIFO), streams it into the store and
+compares the sha256. The answer is written back beside the request as `<id>.receipt.json` (0644; DM-LANES-PUBLISH-RECEIPT):
+
+```json
+{"v": 1, "id": "<document id>", "request": "<id>", "sha256": "…", "bytes": 1234, "url": "/lanes-docs/d/<document id>", "at": "2026-10-08T12:00:00Z", "outcome": "ok"}
+{"v": 1, "id": null, "request": "<id>", "sha256": null, "bytes": null, "url": null, "at": "…", "outcome": "refused", "reason": "outside-home"}
+```
+
+then the claim is removed and the lane keeps its 16 newest receipts (a directory planted at the receipt's name is
+removed or moved aside first, so the answer is always written). A refused receipt carries the host's sha256 and size
+when it read the file (`sha256-mismatch`, `too-large`). Refusal reasons (the receipt's word):
+
+| Reason | Meaning |
+|---|---|
+| `unreadable-request` | the request is not a regular JSON object file of at most 16 KiB (a link, a FIFO, a directory, not JSON) |
+| `bad-version` · `bad-request` · `bad-kind` · `bad-title` | `v` is not 1; a field of the wrong type (`path` not absolute, `claimed_sha256` not 64 hex, `bytes` not a count); `kind` not `md`/`html`/`svg`/`file`; a title that is not one printable line of at most 200 characters |
+| `too-large` | the claimed or the real size is over 32 MiB |
+| `unknown-lane` | the registry places no lane of that id in this container |
+| `rate-limited` | over 30 requests from this container in 10 minutes |
+| `not-delivered` | `for` names a login that owns no member record, or — no `for`, nobody opened the lane — no member record grants its workspace. One word for both (security review 2026-10-08, DEF-1915): the two words told a container whether a login it named is a member. `docs.log`'s `publish` line keeps the precise one, `for-not-a-member` or `no-recipient`; a `for` that names a member still answers `ok` |
+| `outside-home` | the path, every link resolved inside the container, is not under `/home/coder` |
+| `not-a-file` | missing, a directory, a FIFO or device, or a link appeared on the way after it was resolved |
+| `sha256-mismatch` | the file's bytes are not the ones the request hashed (it changed): nothing is stored |
+| `invalid` | the store refused it (a name or login it cannot hold) |
+| `error` | anything else went wrong after the claim (the journal names it): the request is answered and removed, never dropped silently |
+
+Who it is for: `for` (stored in that member's store, for them alone); else the member whose profile last opened the lane
+(`users/<login>.json` `last_opened`); else every member whose record grants the lane's workspace (`for` empty). A busy
+store leaves the request for the next cycle, and without a `registry.json` nothing is taken (the requests wait). Each stored document sends one `published` push through notify (above;
+at most one per lane per minute). From inside a container the latest answer is `lanes_status`'s `published`, or:
+
+```sh
+ls -t ~/.lz/state/publish/<lane id>/ | head; cat ~/.lz/state/publish/<lane id>/<id>.receipt.json
+```
+
+A crash between the claim and the receipt leaves `.<id>.taking` without a receipt; publish again.
+
+**Caddy picks up the route** as for `/enrol/*` (section "Enrolment service"): a server install restarts a running
+`lanes-mobile`; after editing the Caddyfile in place, `systemctl --user restart lanes-mobile.service`. If
+`/lanes-docs/` answers with the Zellij page, `lanes-mobile` runs an older Caddyfile. Settings go in a drop-in:
+
+```sh
+systemctl --user edit lanes-docsd.service        # [Service] Environment=LANES_DOCS_DOMAINS=beyondwork.ai,example.com
+systemctl --user restart lanes-docsd.service
+```
+
+### Mermaid pin
+
+The docs page (plan W10, `docs/superpowers/plans/2026-10-08-lanes-docs-cockpit.md`) draws ```` ```mermaid ```` fences
+with Mermaid 11.17.2, pinned in `holders.lock` as an opt-in line: the npm tarball's sha256 and the sha256 of its member
+`package/dist/mermaid.min.js`, the classic-script build (3 572 661 B). The server installer's pinned-binaries loop
+skips it; `install/enable-docs.sh` installs it. As the workspace account, `sh
+~/.local/share/lanes/current/install/enable-docs.sh` downloads the tarball into a
+temporary directory, refuses unless both digests match, and installs `~/.local/share/lanes/vendor/mermaid-11.17.2.min.js`
+(0644; `$LANES_SHARE/vendor`) and the link `mermaid.min.js`; run again, it finds the pinned digest and downloads
+nothing. Exit status: 0 installed or present, 1 a prerequisite or the download failed, 2 usage, 3 refused (no valid
+pin, a digest mismatch, the member missing or not a regular file) — a refusal installs nothing.
+
+**The server install runs it (plan W8, LNS-109), never fatally.** The full `./install.sh --server` (or `npx
+@vibelord/lanes@<release> --server`) runs it right after `lanes-docsd`'s enable and restart, shows its own line, goes
+on whatever it exits, and ends its summary with one line: `Mermaid for the docs page: ok`, `… skipped (<its last
+line>) — diagrams show as source until sh <tree>/install/enable-docs.sh succeeds` (exit 1: a prerequisite or the
+network), `… refused (<its last line>) — nothing was installed; see RUNBOOK "Mermaid pin"` (exit 3), or `… failed (exit
+N: …)`; `--no-start` does not run it and says so. **An update (`--update-only`)** runs it as the post-commit step
+`enable-docs`, right after `try-restart lanes-docsd` (`libexec/update.py` `DOCS_STEP`; a release rolled back to that
+has no script gets no step): exit 0 is `ok`; exit 1, and a download stopped after the step's 300 s (`rc` 124), are
+recorded `"warning": true, "outcome": "skipped"`, exit 3 `"warning": true, "outcome": "refused"`, each with `reason`
+(the script's last line) — warnings, so the update stays `ok` and `lanes update` does not re-run the post-commit for
+them; any other status is a failed step (`"outcome": "failed"`, `partial`). The update's summary line names it:
+`…; every step ran; mermaid skipped: enable-docs: download failed: https://… — log …`. A re-run (every update, every
+install) finds the pinned file and downloads nothing. To install by hand after a skip, run the script; `lanes doctor`
+says which state the pin is in ("What `lanes doctor` says" below). Caddy serves the directory at `/lanes-assets/vendor/`
+(`lanes-mobile.service`; a new Caddyfile takes `systemctl --user try-restart lanes-mobile.service`, which the server
+installer does) as `immutable`, so `web/docs.js` names the versioned file and carries the member digest as its SRI
+(DEF-1870). Without the file, or on an integrity mismatch, every fence shows its source as a plain `<pre>`. Check:
+`curl -sI http://127.0.0.1:8083/lanes-assets/vendor/mermaid-11.17.2.min.js` answers 200 with `cache-control: public,
+max-age=31536000, immutable` (step 3 of "Operator verification" below; DEF-1871 stays open until that is seen on a
+server).
+
+The pin needs no `'unsafe-eval'` (MEASURED 2026-10-08): the member has no `new Function(`; its four
+`Function("return this")` (lodash's global lookup) sit behind `self`, which every page has, and its one `(0,eval)`
+(chevrotain) follows a `return`. In headless Chromium 153 under `default-src 'none'; script-src 'self'; style-src
+'self' 'unsafe-inline'`, docs.js drew a flowchart and a sequence diagram with no violation, while a control page's
+`eval` was refused and reported. Mermaid's SVG needs `style-src 'unsafe-inline'` (without it: unstyled, 88 violations).
+
+To bump the pin (12.x — npm's latest, 12.1.0 on 2026-10-08 — is a separate decision): download the tarball once
+(`curl -fsSLO https://registry.npmjs.org/mermaid/-/mermaid-<v>.tgz`) and compare its sha512 with `npm view
+mermaid@<v> dist.integrity`; take `sha256sum mermaid-<v>.tgz` and `tar -xzOf mermaid-<v>.tgz
+package/dist/mermaid.min.js | sha256sum`; check that the member is still a classic script (no `import`/`export`, ends
+by assigning `globalThis["mermaid"]`) and repeat the `'unsafe-eval'` check above. Then change, in one commit, the
+`mermaid` line of `holders.lock` (and its comment) and `SRC`/`SRI` in `web/docs.js` — the SRI is `sha256-` plus the
+base64 of the raw member digest: `python3 -c 'import base64,sys; print("sha256-" +
+base64.b64encode(bytes.fromhex(sys.argv[1])).decode())' <member-sha256>`. `test_docs_assets` and
+`tests/web/docs.test.mjs` are red while the lock and docs.js disagree. The install or update of that release runs
+`enable-docs.sh`, which downloads the new pin (a skip says why: run it again by hand); older `vendor/mermaid-*.min.js`
+files stay (harmless; remove them by hand).
+
+### What `lanes doctor` says
+
+Five lines (plan W8, LNS-109), after the browser/phone lines and before the release lines, read-only (one bounded
+`systemctl --user show`, one loopback connect that sends nothing — docsd answers nothing and writes no docs.log line
+for it — and file reads):
+
+| Line | Marks |
+|---|---|
+| `lanes-docsd.service active, answering on 127.0.0.1:8185` | `✓` enabled, active and the port (its drop-in's `LANES_DOCS_PORT`, else 8185) accepts a connection; `✗` `enabled but failed` (or any state but active), `active, but 127.0.0.1:8185 does not answer`, a `LANES_DOCS_PORT` that is no port, or systemctl silent — each with `journalctl --user -u lanes-docsd.service; systemctl --user restart lanes-docsd.service`; `⚠` `not enabled, so there is no docs page` (the full server install enables it; `--update-only` never does) or active but not enabled (a reboot loses it) |
+| `docs: pinned — lanes-docsd answers members through Tailscale Serve` | `✓` `enrol-mode` pins `request`, read as docsd reads it on every request; `⚠ docs: refuses until the Serve header check is pinned (unpinned: auto \| pinned invite only \| <why the pin cannot be read>)` with the pointer to "Enrolment service" (Operator verification) and this section — an operator gate, never a `✗` |
+| `docs store: N documents in M lanes (counts.json), <size> under ~/.local/state/lanes/docs; docs.log <size>` | information: the documents and lanes `docs/counts.json` counts, the bytes of the regular files under `docs/` (never through a link), docs.log's size (`no docs.log yet`) |
+| `docs: Mermaid 11.17.2 pinned (~/.local/share/lanes/vendor/mermaid-11.17.2.min.js, sha256 581ed7d74bd9…)` | `✓` a regular file whose sha256 is `holders.lock`'s member digest; `⚠ … not installed …, so diagrams show as source — run sh …/install/enable-docs.sh`; `✗ … refused — … is not the pinned build (sha256 …, holders.lock …)` or `… is not a regular file` (a link or a FIFO, never followed or waited on) — browsers refuse it by its integrity; the script replaces it from a verified download; `✗ docs: Mermaid not checked — …/holders.lock: …` without a valid opt-in pin |
+| `docs: age encryption off (LANES_DOCS_AGE_RECIPIENT unset; age at /usr/bin/age)` | information while the switch is off (and whether an `age` is on PATH); `✓ … on — new store copies are age output (age at …); lanes-docsd opens them with LANES_DOCS_AGE_IDENTITY` (or `no LANES_DOCS_AGE_IDENTITY, so their downloads answer 409 encrypted`); `✗` set without an `age` binary (every upload and publish fails `encrypt-failed`) or a value that is no recipient. The recipient is never printed. The `age` looked for is the one on doctor's PATH, which may not be the unit's |
+
+### Operator verification (docs plan gate 1, not yet run on ceobox)
+
+Unit-proven only so far: `tests/unit/test_docsd.py` runs a real docsd on a loopback port, `test_install.DocsRoute`
+models the shipped Caddyfile's routes and headers in front of it, `test_docs_assets.VendorRoute` models Caddy's route
+sort for the Mermaid route, and `tests/web/docs.test.mjs` and `tests/web/upload.test.mjs` drive the page scripts
+against fakes. Nothing below has been run on a server, a phone or a real browser. After the server install of the
+first release with the docs cockpit (1.3.0), run it once, in order, and record the date, the devices and each step's
+result here:
+
+1. **Install.** On the server, the full install: `npx @vibelord/lanes@1.3.0 --server` — it enables and restarts
+   `lanes-docsd`, restarts `lanes-mobile` on the new Caddyfile and runs `enable-docs.sh`; its last lines say
+   `Mermaid for the docs page: ok`. Then `lanes install-container <name>` for each container whose agents should
+   publish (the `lane publish` verb and the `lanes_publish` tool; new agent sessions load the tool).
+2. **Pin.** From another tailnet device signed in as yourself, run the Serve header check (section "Enrolment
+   service", Operator verification); on the server, `lanes enrol mode request`. `lanes doctor` then shows
+   `✓ lanes-docsd.service active, answering on 127.0.0.1:8185`, `✓ docs: pinned …` and
+   `✓ docs: Mermaid 11.17.2 pinned …`.
+3. **The Mermaid route (DEF-1871).** On the server, `curl -sI
+   http://127.0.0.1:8083/lanes-assets/vendor/mermaid-11.17.2.min.js` answers `200` with `cache-control: public,
+   max-age=31536000, immutable`. Seen once on the server, that closes DEF-1871 (the route proven on a running Caddy,
+   not only on a model of its sort).
+4. **Publish.** In a lane of a container from step 1, `~/.lz/bin/lane publish README.md` (a README with a
+   ```` ```mermaid ```` fence; add a small flowchart if it has none). The JSON says `"picked_up_by": "lanes-docsd"`;
+   within about 5 s `cat ~/.lz/state/publish/<lane id>/<id>.receipt.json` says `"outcome": "ok"` with a `url`.
+5. **Sidebar.** Within a few seconds that workspace's upload strip reads ` ↑ uploads · ▤ docs 1  (U)`. With the
+   cursor on the lane, `d` shows `https://<name>:8443/lanes-docs/?ws=<workspace>&lane=<lane id>` in the footer; a
+   ⌘-click or Ctrl-click on it (or on the strip) opens the page.
+6. **Phone.** **More → Docs** opens the index in a new tab, signed in as you; the README opens rendered and its
+   ```` ```mermaid ```` fence is drawn as a diagram, not shown as source.
+7. **Artifact sandbox (DEF-1853).** Publish an HTML file whose script tries to reach this site and writes what it
+   got into its own page: `fetch('/lanes-docs/')`, `fetch('/')`, `document.cookie`, and a WebSocket to the same
+   server's `/ws/` path that the terminal page itself opens (the browser's network panel on a view shows it). **Open
+   the HTML artifact**: the script runs (the page shows its writing), every one of those attempts fails or comes back
+   empty, and no lane receives a keystroke. Record the browser and what each attempt answered: that is DEF-1853's
+   measurement.
+8. **Upload.** On the Docs page pick a lane, drop a file on the dashed area, **Upload**: the receipt lists the name,
+   size, sha256 and `/home/coder/<repo>/uploads/<name>`; in that lane's shell, `sha256sum
+   /home/coder/<repo>/uploads/<name>` prints the receipt's sha256. The sidebar's count goes up by one.
+9. **Not a member.** From a tailnet login that owns no member record, `https://<name>:8443/lanes-docs/` answers 403
+   `not-a-member`; on the server, `curl -s http://127.0.0.1:8185/` answers `{"error": "not-through-serve"}`.
+10. **Forged header: the known DEF-1645 case.** A process in the host's network namespace can send Serve's headers
+    itself: list such containers with `docker ps --filter network=host` and record the answer. From one (or from the
+    host as the workspace account), `curl -s -H 'Tailscale-User-Login: <a member login>' -H 'Tailscale-User-Name: x'
+    -H 'X-Forwarded-For: 100.64.0.9' -H 'Sec-Fetch-Site: none' http://127.0.0.1:8083/lanes-docs/` is answered as that
+    member. That is expected and stays DEF-1645 (open): the pin gate and the Serve-only check are the controls against
+    every other client, not against a process on this host. If another account or a host-network container exists,
+    weigh `lanes enrol mode invite` (which also stops the Docs page) against it.
+
 ## Safety rules baked into the code (do not remove)
 
 - tmux is always called with `-N` (`attach-session`, `new-session` and `start-server` on a missing socket start