@vibelord/lanes 1.2.0 → 1.5.0

package/payload/lanes/docs/ARCHITECTURE.md

@@ -36,7 +36,8 @@ for operations, the [runbook](RUNBOOK.md).
    Each workspace container that has the lane contract (`~/.lz/bin/lane`) also gets its own slice of the
    observation as `~/.lz/status.json` (LNS-32, `statusd.write_container_status`), because nothing in a container
    can read the host's `status.json`: `{v: 1, at, lanes{<id>: {state, agent?, attached?, viewers?, activity?, size?,
-   stale?}}, unregistered[{id, name, workspace, boards, tmux, identity}]}`. `lanes` holds the container's declared
+   stale?, docs?}}, unregistered[{id, name, workspace, boards, tmux, identity}]}` (`docs`, the host row's `{n, at}`
+   verbatim, since plan W10 W7). `lanes` holds the container's declared
    and registered lanes (the ids its `.lz/registry.json` holds) and its unregistered sessions; a lane no cycle has
    observed yet is `unknown`; the host-side details (cwd, pid, tty, command, probe outcome) stay on the host; a
    session listed under several boards is one `unregistered` row naming them all. zmx lanes are not in it — `lane
@@ -54,20 +55,96 @@ for operations, the [runbook](RUNBOOK.md).
    per container per cycle through `/proc/<container init pid>/root` without spawning anything. Precedence: a
    hook sidecar > a Claude `~/.claude/sessions/<pid>.json` naming the pane
    `<session>:@<win>.%<pane>` (live pids only, checked in the container's pid namespace, recycled pids rejected
-   by `procStart`) > the Codex pane title (`[ ! ] Action Required` → `needs_approval`, braille spinner →
-   `working`, a task title → `idle`) > the window bell (an idle title plus a bell is `done`; an approval title
-   wins over the bell). A Codex title over a bare-shell foreground whose shell has no child process
-   (`pane_has_child`, read from `/proc/<pid>/task/*/children`) is `shell`: the harness ended and tmux kept its
-   title. Unknown liveness leaves that key unset and never demotes. The tmux columns this needs
-   (`window_bell_flag`, `window_id`, `pane_id`, `pane_title`) are appended to the listing format, the free-text
-   title last so a tab inside it cannot shift another column.
+   by `procStart`) > a Kimi Code session file > the Grok Build observer (`harness_grok`: its session file, else its
+   title read with the blink memory) > the Grok Build title on a pane observed as `grok` that no observer claimed
+   (`harness_grok.parse_grok_title`, `source: grok-title`) > the Codex pane title, only where Codex can be (`[ ! ]
+   Action Required` → `needs_approval`, braille spinner → `working`, a task title → `idle`) > the observed harness
+   itself (`source: process`). The window bell applies throughout: an idle title, a finished Kimi turn or a completed
+   Grok turn plus a bell is `done` (an approval title wins over the bell; a question Kimi still asks stays
+   `needs_input`; `harness_grok` applies its own rule, so a cancelled or interrupted Grok turn stays `needs_input`). A
+   Codex title over a bare-shell foreground whose shell has no child process (`pane_has_child`, read from
+   `/proc/<pid>/task/*/children`) is `shell`: the harness ended and tmux kept its title. Unknown liveness leaves that
+   key unset and never demotes. The tmux columns this needs (`window_bell_flag`, `window_id`, `pane_id`,
+   `pane_title`) are appended to the listing format, the free-text title last so a tab inside it cannot shift another
+   column.
+
+   **The harness is observed (W12, Lanes 1.5.0; spec
+   `docs/superpowers/specs/2026-10-15-lanes-harness-observers-design.md`; DM-LANES-STATUS, DM-LANES-CONTAINER-STATUS).**
+   `agent.harness` is one of `claude | codex | kimi | grok | grok-cli | shell | unknown` (`shell` is the walk's word for a
+   pane and never reaches a published `agent{}`), an OBSERVED fact read from
+   the pane's process tree, not a side effect of which title parser matched: `agent_state.harness_walk` reads
+   `/proc/<pane pid>/task/*/children` (the reads `pane_has_child` already makes) and each process's `comm` in the
+   container's /proc, breadth first from the pane's root down four levels and at most 64 processes, and the first
+   process whose comm is `claude`, `codex`, `kimi`/`kimi-code` or `grok` — or whose `/proc/<pid>/exe` holds
+   `/claude/versions/`, native Claude Code before 2.1.299 running with its version (`2.1.295`) as comm (DEF-1993) —
+   names it. Codex runs as `bash` → `node` → `codex`, so it is found one level down; two `grok` binaries are told
+   apart by `/proc/<pid>/exe`: `…/downloads/grok-linux-<arch>` is Grok Build (the rule of
+   `harness_grok.harness_of_exe`; the container walks of `lane-signal` and `lane_core` match
+   `/downloads/grok-linux-x86_64`, the one arch measured), anything else grok-cli, an unreadable link `unknown`. Only
+   shells is `shell`; anything else, a cut tree or an unreadable read is `unknown`. `statusd.HARNESS_CACHE`
+   (`agent_state.HarnessCache`) keeps the answer per pane pid with the harness process's comm, and walks again when
+   the pane's own children changed or that process exited or now runs under another comm (so a native Claude that
+   exits below an unchanged wrapper is walked again); `shell` and `unknown` are never kept. When it names a harness,
+   the observed harness is the published `harness` whatever signal decided the status (a Claude-installed hook firing
+   inside another harness says `claude`). The Codex title (`parse_codex_title`) is read only where Codex can be: on a
+   pane observed as Codex, on an `unknown` pane only its spinner and `[ ! ] Action Required` shapes, on a bare shell
+   or an unobserved pane also its `<task> | <dir>` idle shape — the former "any title of two or more words is Codex idle" rule
+   published every Kimi lane as `codex / idle` (DEF-1970). The last rung is the observed harness itself: nothing above
+   claimed the pane, so it is that harness, `idle` (`done` with the bell), `source: process`. The values are
+   additive: the `agent` object keeps its keys.
+
+   **Kimi Code (observed, no hooks needed).** For the panes whose walk found `kimi`, `agent_state.kimi_sessions`
+   lists `~/.kimi-code/sessions/wd_*/session_<uuid>/` through the container's root with every directory opened
+   `O_NOFOLLOW` (a link planted there is refused, never followed), stats `state.json` and `agents/main/wire.jsonl`
+   (a session neither file of which moved within an hour is not read), reads `state.json` (at most 256 KiB:
+   `cwd`, `updatedAt`, `lastTurnReason`, `title`, `id`) and the last 64 KiB of the wire log (whole lines only), and
+   joins a pane's kimi pid to the session whose `cwd` equals `/proc/<pid>/cwd` — the newest when several are
+   fresh. Two kimi panes in one cwd cannot be told apart: neither is claimed and both fall back to hooks, title and
+   bell (DEF-1971). `agent_state.kimi_status` maps the log: `agent.turn.started`/`turn.prompt` and, inside a turn,
+   `context.append_loop_event` (tool calls among them) and `llm.request` → `working`; an `interaction.request`
+   of kind `approval` with no `interaction.resolved` → `needs_approval` (a `question` → `needs_input`);
+   `turn.ended` completed/cancelled and `agent.turn.ended{outcome: done}` → `needs_input` (`done` with the bell),
+   `turn.ended` failed → `errored`; with no such event in the window `state.json`'s `lastTurnReason` decides. A
+   session whose newest content is more than an hour old makes no claim. The verdict has `source:
+   kimi-session-file`, the session uuid as `session_id`, the kimi pid as `pid`, the deciding wire event (or
+   `state.json`) as `event`, and the session title (cut at 120 characters) as `name`.
+
+   **Grok Build and grok-cli** (W12, spec §4–§5; `libexec/harness_grok.py`). One observer contract:
+   `agent_state.grok_sessions(root, panes, grok_home='.grok-build', *, home='/home/coder', titles=None)` forwards its
+   arguments to `harness_grok.grok_sessions`, a module looked up at the call (none shipped, no observer), and keeps
+   the verdicts whose status is a vocabulary word or the observer's `unknown`. `statusd.agent_signals` passes the tmux
+   rows ({pane key: row}) of every pane its walk observed as `grok`, as `shell` (the observer decides by the title
+   whether that is a Grok Build pane whose harness ended), and as `unknown` with a harness pid (a `grok` whose exe
+   could not be read: Grok Build only when `active_sessions.json` names its pid), and `statusd.GROK_TITLES` as `titles`
+   — one dict per container root, kept between cycles like `HARNESS_CACHE`, pruned to the panes passed each cycle and
+   dropped with the container. The observer returns the same per-pane verdict a Claude session file gives `merge`
+   (`harness: grok`, `source: grok-session-file | grok-title`), read through the container root like the other
+   signals, with no spawn and no write. Lanes runs Grok Build with `GROK_HOME=~/.grok-build` (its installer would
+   otherwise replace grok-cli's `~/.grok/bin/grok`). The pane's process tree (depth ≤ 4) names the grok pid;
+   `$GROK_HOME/active_sessions.json` (`{session_id, pid, cwd, opened_at}`, the TUI's own pid) joins it to a session —
+   dead pids, pids no longer `grok` and pids that started after `opened_at` are ignored, two live entries for one pid
+   fall back to the title — and the last 64 KiB of `sessions/<URL-encoded cwd>/<session id>/events.jsonl`, whole lines
+   only, give the state: `phase_changed{permission_prompt}` / `permission_requested` → `needs_approval`;
+   `turn_started`, the other phases, `permission_resolved` and in-turn events → `working`; `turn_ended` `completed` →
+   `needs_input` (`done` with the bell), `error` → `errored`, `cancelled | interrupted` → `needs_input`; no turn yet →
+   `idle`. `summary.json` `generated_title` is the name. Otherwise the title decides (`⚠ Action Required …` →
+   `needs_approval`, braille spinner → `working`, `grok` / `<name> - grok` → `idle`); the prefix blinks on an
+   unfocused pane, so a busy title right after a prefixed sample — the previous cycle's, from `titles` — stays
+   `needs_approval` (DEF-1982). A Grok title over a tree read in full with no grok in it is `shell`. Every path below
+   the container root is walked `O_NOFOLLOW` and every file opened non-blocking and bounded: a symlinked `GROK_HOME`,
+   session directory or log is refused. Leader mode (a `leader*.sock` socket, or a session for the pane's cwd that
+   only a grok outside every pane holds) is out of scope: the observer reports status `unknown` with a `note`, and
+   `merge` publishes no `agent{}` for that pane (nothing below it guesses) unless a hook sidecar or a Claude session
+   file outranks it (DEF-1983). grok-cli writes nothing a host can read (no title, no bell, no pid in its database):
+   it reaches `agent{}` only through the hook sidecar (DEF-1980). The Grok Build file shapes come from its source and
+   user guide; no logged-in session was measured yet (DEF-1981).
 
    What is published is not `merge`'s word itself but its debounced form, `agent_state.settle`, with three more
    additive keys (`raw_status`, `raw_since`, `stable_since`): see [Attention queue](#attention-queue).
 
    The hook sidecar is `~/.lz/state/hooks/<lane id>.json` in the container, written by `~/.lz/bin/lane-signal`
-   (Python 3 stdlib, installed by `lanes install-container`) when an opt-in Claude Code or Codex hook fires:
-   `{v: 1, lane, harness, status, since, at, event, pid, start, session}` — `since` when the status began (kept
+   (Python 3 stdlib, installed by `lanes install-container`) when an opt-in hook fires (Claude Code, Codex, Kimi
+   Code, Grok Build, grok-cli): `{v: 1, lane, harness, status, since, at, event, pid, start, session}` — `since` when the status began (kept
    while the same status is re-signalled), `at` the last event, `pid`/`start` the agent process and its
    starttime — plus `name`, the agent's own note when it reported one (`lanes_signal`, LNS-35: kept while the status
    repeats, dropped when it changes). A report (`event: lanes_signal`) stands against the same agent's hooks — the
@@ -84,8 +161,65 @@ for operations, the [runbook](RUNBOOK.md).
    container `lane ls` read (DEF-1572). A zmx lane's sidecar is therefore named by its zmx session, not by the
    `<ws>--z-<name>` id statusd publishes, and does not reach that lane's `agent{}` yet — the zmx lane's `agent` key
    stays lane-run's record (DEF-1573). A published sidecar adds `event` to `agent{}` and has `source: hook`. Hooks are
-   never installed implicitly: `lanes hooks install --agent claude|codex --container <name>` prints the merge and
-   writes only with `--write` (RUNBOOK "Installing agent hooks").
+   never installed implicitly: `lanes hooks install --agent claude|codex|kimi|grok|grok-cli --container <name>`
+   prints the merge and writes only with `--write` (RUNBOOK "Installing agent hooks" and "Harnesses").
+
+   **The container side** (W12 Track C). `lane-signal`'s default harness is `--harness`, else `LANE_HARNESS`, else
+   the parent processes' (`comm` in the same set, a `grok` split by its exe, a native Claude Code file by its exe),
+   else `unknown` — never `codex`; `lane-mcp` names the client's harness from its MCP client name (`claude`, `codex`,
+   `kimi-code`/`kimi`, `grok-shell-*` → `grok`, `grok-cli*` → `grok-cli`), else the parent rule. The per-harness
+   operator steps are RUNBOOK "Harnesses"; what a person sees, the user guide's "Harnesses".
+
+   **Fleet and Throttle facts** (W11, spec `docs/superpowers/specs/2026-10-11-lanes-fleet-dashboard-design.md` §2;
+   DM-LANES-THROTTLE-PULSE, DM-LANES-FLEET). Two additive `status.json` keys feed the sidebar's fleet block and
+   `lanes doctor`, which read nothing else for it: `throttle`, the Throttle daemon's facts, and `fleet`, the host's.
+
+   *The pulse.* The daemon's facts come the way the hooks' do, from a writer inside the container: the daemon binds
+   its container's `127.0.0.1` (DEF-1525), so the host cannot poll it. `~/.lz/bin/throttle-pulse` (a contract file,
+   Python 3 stdlib) runs as a loop only in the daemon's container — site.conf `LANES_THROTTLE_CONTAINER`, else the
+   container of the registry's `tools--throttle-monitor` tab — where `lanes install-container` starts it, once, as
+   `tmux -L lanes-pulse` session `pulse`. Every 10 s it GETs the open `/pools/{claude,codex,kimi}/ready` and
+   `/metrics`, and the guarded `/pools/{claude,codex,kimi}/status` only with the bearer the operator adopted into
+   `~/.lz/throttle-token` (`lanes throttle adopt-token`; the control port has no loopback exemption, DEF-1930), and
+   writes `~/.lz/state/throttle.json` by rename when a value changed or 60 s passed — never anything else, never a
+   POST (RUNBOOK "Throttle pulse"). The kimi pool (W12) rides the daemon's generic pool routes (`scoped_pool_state`):
+   a daemon with no Kimi account reports it with nothing configured, and since Kimi has no paid overflow lane its
+   `overflow` is always null (`MONEY_POOLS` is claude and codex). The sidebar draws one provider row per pool —
+   `◆ anthropic`, `◆ openai`, `◆ moonshot` — so the full block is a rule and six rows from 25 pane rows
+   (`FLEET_FULL`), and the three-row form shows the pool with the smallest usable share, a pool with nothing
+   configured never (DEF-2002). There is no Grok row: Throttle has no xAI pool.
+
+   *`throttle`.* On every cycle statusd copies that file into `status.json`. It looks the daemon's container up again
+   on a registry reload and every 300 s, never per cycle, and makes ONE stat per cycle through `/proc/<init>/root` with
+   every directory opened `O_NOFOLLOW`, a read only when (pid, mtime, inode, size) moved, through `read_regular_at` (a
+   regular file of at most 64 KiB, never a link or FIFO). Only the spec's keys of their own types are copied
+   (`statusd.pulse_projection`: counts, finite numbers, booleans, a one-word phase, a printable error — never an escape
+   sequence). The copy is `stale: true` when its `at` is more than 90 s old (`PULSE_STALE_S`: the pulse's 60 s
+   heartbeat on an int-truncated `at` and a 10 s loop is routinely read 60–84 s late, DEF-1941; `lanes doctor` and the
+   sidebar use the same 90 s) or the file is absent or refused, keeping the last values. The one spawn this adds is
+   `statusd.rearm_pulse`, between two cycles in `main()`: when the pulse file is older than 90 s (or not there) while
+   the daemon's container runs and the host is not `critical`, at most once per 600 s, one bounded (10 s)
+   `docker exec -d -u 1000 -e HOME=/home/coder <c> tmux -L lanes-pulse new -d -s pulse
+   /home/coder/.lz/bin/throttle-pulse --loop` (byte for byte the argv `lanes install-container` starts it with,
+   DEF-1940), journalled with its outcome — and nothing when `~/.lz/bin/throttle-pulse` is not installed there.
+
+   *`fleet`.* Every `FLEET_INTERVAL` (10 s) the cycle asks `lanes_lib.compute_health(sample=True)`, which reads —
+   from plain files, no subprocess, and nothing at all on a `critical` host — the aggregate `cpu` line of
+   `/proc/stat`, `MemTotal`/`MemAvailable` from the `/proc/meminfo` it reads anyway, the inotify watch CEILING
+   (`/proc/sys/fs/inotify/max_user_watches`; the watches in use are never counted: that walks every process's
+   fdinfo), and per recorded container (`containers.json`) its cgroup `memory.current` and `cpu.stat` `usage_usec`.
+   Those counters are cumulative: `lanes_lib.fleet_facts` turns this sample and the previous one — kept in statusd's
+   context, never in a global — into rates (`/proc/stat` busy ÷ total jiffies; per container `usage_usec` delta ÷
+   interval ÷ logical cpus × 100, null for a container whose init pid changed or whose counter went back) and
+   publishes `fleet` with OpenTelemetry names as the keys verbatim: `host.name` (`/etc/hostname`, read once per
+   daemon start, only a DNS host name), `system.cpu.utilization`, `system.cpu.logical.count`,
+   `system.cpu.load_average.1m`, `system.memory.utilization`, `system.memory.usage{used, total}`,
+   `system.linux.memory.available`, `system.pressure{cpu.some.avg10, memory.some.avg10, memory.full.avg10,
+   io.some.avg10}`, `system.inotify.max_user_watches`, and `containers` — the three biggest by memory
+   (`container.name`, `container.memory.usage.total`, `container.cpu.percent`). The first sample has no rate (null,
+   never a since-boot average). Every figure is quantized (fractions and percents to 1 %, bytes to 0.1 GiB, the load
+   to 0.1) and the sample's own `at` is left out of the rewrite comparison, so a sample that moved nothing visible
+   does not rewrite the file; a due sample that was not taken (critical) keeps the last facts with `stale: true`.
 5. A lane's `source` is the container's spelling of its `terminals.json`. Every host-side reader of that file
    maps it to the container's home volume first (`statusd.registry_source_paths`, deduplicated by that host path:
    one repository cloned in two containers is two files): the status daemon's hot-sync
@@ -286,6 +420,11 @@ while it ran); `status.json` and `resolve.dynamic/` are projections.
 answered (a container whose listing timed out or failed is absent; its `zmx` groups are then the previous ones
 republished). It sits outside the change comparison, so the file is still rewritten only on change or the heartbeat;
 the co-located Studio Host prunes a lane it started only on such a listing (docs/SHARING.md, design §8.10 C1).
+The docs cockpit (plan W10 W7) adds two keys, both absent when there is nothing to say: a lane row's `docs: {n, at}`
+while `docs/counts.json` counts documents for that lane (statusd stats that file once per cycle and reads it only when
+it moved), and the document's `web_origin`, `https://<name>:8443`, the name the enrolment service announces (site.conf's
+`LANES_SERVER_NAME`, else this node's MagicDNS name), which statusd looks up between two cycles at most every 300 s
+and never again under pressure once it has one. The sidebar builds its OSC 8 links to `/lanes-docs/` on it.
 The pre-persistence Docker-shell tracker (`legacy-sessions/`, `legacy_sessions.py`, `lanes verify-legacy`) was
 retired by plan Task 19: statusd no longer reads that directory (a record still there is inert — kept on disk,
 never observed, never closed), and a `legacy` row from an older status.json is refused by close. See
@@ -328,10 +467,11 @@ shim, so `EVAL_CLAUDE_REAL_BIN=<checkout>/.bw-tools/bin/claude eval-claude` comp
 
 `~/.lz/bin/lane-mcp` is the Agent API (the cockpit v3 plan's Track M, LNS-32…36). It is an MCP server inside each
 workspace container: the agent in a lane uses it to see the lanes of its container and, within guardrails, to change
-their declarations, type into a sibling lane and report its own status. It is the container's half of Lanes. It
-reads the two projections the host writes into `~/.lz` and the container's own tmux, and it writes only inside the
-container: a repository's `.vscode/terminals.json`, a tmux session, the lane's hook sidecar. What it changes reaches
-the boards through the host's ordinary readers (`lanes sync`, `lanes-statusd`); nothing on the host listens to it.
+their declarations, type into a sibling lane, report its own status and publish a file to the docs page. It is the
+container's half of Lanes. It reads the two projections the host writes into `~/.lz` and the container's own tmux,
+and it writes only inside the container: a repository's `.vscode/terminals.json`, a tmux session, the lane's hook
+sidecar, a publish request. What it changes reaches the boards through the host's ordinary readers (`lanes sync`,
+`lanes-statusd`, `lanes-docsd`'s pick-up); nothing on the host listens to it.
 **[OPERATOR-GATED]** in a live container: `lanes install-container <container>` ships it and adds it to Claude Code
 and Codex (the plan's operator gate 3), and new agent sessions load it. How an agent should use it:
 [`skills/lanes-agent-tools`](../../skills/lanes-agent-tools/SKILL.md). Every argument and refusal, for people:
@@ -344,7 +484,7 @@ and Codex (the plan's operator gate 3), and new agent sessions load it. How an a
 | --- | --- | --- | --- | --- |
 | `lanes_whoami` | read | `$LANE_ID`, else the agent's own tmux pane, looked up in `~/.lz/registry.json` and `~/.lz/status.json` | — | now |
 | `lanes_list` | read | `~/.lz/registry.json` and `~/.lz/status.json` only, no tmux | — | now; the observation is fresh while `status.fresh` (renewed within 60 s) |
-| `lanes_status` | read | the two projections, one `has-session`, the lane's hook sidecar | — | now (`alive: null` when tmux does not answer in 5 s) |
+| `lanes_status` | read | the two projections, one `has-session`, the lane's hook sidecar, its newest publish receipt (`published`) | — | now (`alive: null` when tmux does not answer in 5 s) |
 | `lanes_capture` | read | one `capture-pane` of the lane | — | now |
 | `lanes_register` | write | a repository's `terminals.json`: one terminal appended | `lanes sync`, started by `lanes-statusd`'s hot sync | 15 s |
 | `lanes_unregister` | write | the same file: one terminal removed; its session keeps running | `lanes sync` | 15 s |
@@ -352,11 +492,13 @@ and Codex (the plan's operator gate 3), and new agent sessions load it. How an a
 | `lanes_new` | exec | the same file: one terminal appended; and a new tmux session running `command` | `lanes sync` | 15 s (the session runs at once) |
 | `lanes_send` | exec | keystrokes into a lane's active pane | the program in the lane's active pane | 0 s (its Enter half a second after the text) |
 | `lanes_signal` | write | the agent's own hook sidecar, through `lane-signal` | `lanes-statusd` | 5 s |
+| `lanes_publish` | write | a publish request `~/.lz/state/publish/<lane>/<id>.json` naming a file of the container (the file itself is read by the host) | `lanes-docsd` | 5 s (its pick-up cycle; the receipt comes back beside the request) |
 
 "Seen within" is the `expected_within_s` each write answers (`test_docs.AgentApi` reads it from `lane-mcp` and holds
 this table to it). A terminals.json edit: `lanes-statusd` checks every cycle (3 s, `LANES_STATUS_INTERVAL`) whether a
 terminals.json its registry names has changed (`statusd.hot_sync`) and starts one `lanes sync` at most every 10 s;
-the `lanes-sync.timer` sync every 2 minutes catches anything else. A sidecar is read on the next statusd cycle.
+the `lanes-sync.timer` sync every 2 minutes catches anything else. A sidecar is read on the next statusd cycle. A
+publish request is taken by the docs service's own pick-up cycle (5 s, "Docs service" below).
 "Effect" is the tool gateway's classification (`read`, `write`, `exec`: arbitrary command execution). `lanes_new` runs
 its `command`, and `lanes_send` types a line that a shell lane runs, so both are `exec`; the gateway recipe below
 carries the same classes.
@@ -380,7 +522,7 @@ way: only when missing, `<file>.bak-<UTC>` first, re-read before the write, and
 something else is never replaced.
 
 The write tools (LNS-35) are `lanes_register`, `lanes_unregister`, `lanes_rename`, `lanes_new`, `lanes_send` and
-`lanes_signal`. The first four change a lane's DECLARATION, a repository's terminals.json in the container, and
+`lanes_signal`; plan W10 W4 (LNS-105) appended `lanes_publish`. The first four change a lane's DECLARATION, a repository's terminals.json in the container, and
 never the host: `lanes-statusd`'s hot-sync notices the changed file and starts one `lanes sync`, which publishes it
 (about 15 s). To answer with the id that sync will give, the container carries ports of the host's rules —
 `slug`, `shown_key`, `lane_trace`, `canonical_recipe`, the id grammar — each pinned equal to its `lanes_lib`
@@ -400,7 +542,12 @@ reads the text and its CR as one chunk, which an agent's prompt takes as a paste
 target's agent is `working` or `needs_approval` (the host's observation or the lane's own sidecar) unless forced.
 `lanes_signal` runs `lane-signal` with `--agent-pid` (the server's parent, the agent), `--note` (the sidecar's
 `name`, which `agent_state.read_sidecar_dict` already publishes as the agent's task line) and the agent's
-`CLAUDE_CODE_SESSION_ID` when its environment carries one, so the report and the agent's hooks name the same agent. Each write answers what changed, what
+`CLAUDE_CODE_SESSION_ID` when its environment carries one, so the report and the agent's hooks name the same agent.
+`lanes_publish` (and the `lane publish` verb, the same `lane_core.publish`) resolves the file inside the container's
+home, hashes it once and writes the request; it never copies the file. The host trusts nothing in the request: the
+docs service resolves and hashes the file again and refuses a hash that differs. The tool reads its answer back as
+`lanes_status`'s `published` (`lane_core.latest_receipt`), from the receipt in the container, never through
+`status.json`. Each write answers what changed, what
 picks it up and when; each refusal a machine code and what a person can do instead. On the host,
 `session_actions.unregister_declared` runs the same `lane_core` editor (loaded once per process by
 `lanes_lib.lane_core()`) through the container's home volume with `root=` set, so a symbolic link there is refused
@@ -420,7 +567,8 @@ No tool exists for these. An agent that needs one asks a person; a refusal's `hu
 - **Answering an approval** prompt. `lanes_send` refuses a lane whose agent waits for an approval
   (`agent_needs_approval`); `force` is for an answer the agent was asked to type.
 - **Opening or attaching** a lane, or changing what a view shows.
-- **Uploads**.
+- **Uploads**: a person's file into a lane (the Docs page, the desktop drop). The reverse, an agent's own file onto
+  the docs page, is `lanes_publish`.
 - The host's **`lanes sync`, `lanes gc`, `lanes ensure`** and every other host verb. The container cannot run them;
   its changes reach the host only as files the host reads.
 - **Renaming a tmux session** (`rename-session`). `lanes_rename` changes the name the boards show, never the id or the
@@ -439,9 +587,10 @@ the result and refusal shapes below. `lane-mcp` names it `WIRE = 1` (its `start`
 MCP protocol versions 2025-06-18, 2025-03-26 and 2024-11-05: `initialize` answers the client's version when it is one
 of these, else 2025-06-18. The data-model row is DM-LANES-LANE-MCP in `docs/master-datamodel.md`.
 
-- **Frozen in v1:** the ten tool names and their order; every input property's name, type and meaning; which
-  arguments are required; the closed schemas (`additionalProperties: false`); the read-only annotations of the four
-  readers and the hints of the six writers; the result shapes below.
+- **Frozen in v1:** the eleven tool names and their order (`lanes_publish`, plan W10 W4, appended after the other
+  ten); every input property's name, type and meaning; which arguments are required; the closed schemas
+  (`additionalProperties: false`); the read-only annotations of the four readers and the hints of the seven writers;
+  the result shapes below.
 - **Additive only within v1:** a new tool appended after the others; a new optional argument whose default keeps
   today's behaviour; a new key in a JSON result; a new refusal code. A reader ignores keys it does not know and treats
   an unknown `refused` code as a refusal. A description may be clarified; the golden then changes visibly.
@@ -451,7 +600,11 @@ of these, else 2025-06-18. The data-model row is DM-LANES-LANE-MCP in `docs/mast
 - **Results** are one `text` content block. The readers answer JSON (`lanes_whoami`, `lanes_list`, `lanes_status`)
   or plain text (`lanes_capture`); a reader that cannot answer is `isError: true` with a sentence. The writers always
   answer one JSON object. On success it holds what changed (`changed`), what picks the change up (`picked_up_by`) and
-  how soon (`expected_within_s`); `lanes_signal` adds `stands_until`. On a refusal it is `isError: true` with the
+  how soon (`expected_within_s`); `lanes_signal` adds `stands_until`; `lanes_publish` the request's `id`, the file's
+  container `path`, `kind`, `bytes`, `sha256` and where the request and its receipt are (`request`, `receipt`).
+  `lanes_status` carries `published` (`{id, url, at, outcome, request, reason?}`, the newest receipt) when the lane
+  has one, and `docs` (`{n, at}`) when the docs page holds documents for it — both additive, absent otherwise. On a
+  refusal it is `isError: true` with the
   machine code (`refused`), the reason (`why`) and what a person can do instead (`human`). A refusal changed nothing
   unless it carries `changed`: `tmux_failed` after `lanes_new` declared its lane, or after `lanes_send` typed its text
   but not its Enter. There is no `outputSchema` or `structuredContent`, so every protocol version reads the same thing.
@@ -471,7 +624,9 @@ The refusal codes (`refused`), each with the `human` sentence `lane-mcp`'s `HUMA
 - which file: `no_source`, `ambiguous_source`, `ambiguous_workspace`, `source_missing`, `source_invalid`,
   `source_unreadable`, `source_link`, `no_lanes_block`, `not_declared_here`, `unknown_prefix`;
 - the edit: `edit_conflict`, `edit_refused`, `last_terminal`, `duplicate_name`, `duplicate_binding`, `slug_collision`;
-- a value: `invalid_name`, `invalid_session`, `invalid_cwd`, `invalid_command`, `invalid_text`, `invalid_note`;
+- a value: `invalid_name`, `invalid_session`, `invalid_cwd`, `invalid_command`, `invalid_text`, `invalid_note`,
+  `invalid_title`, `invalid_for`, `invalid_kind`;
+- the file to publish: `outside_home`, `not_a_file`, `too_large`;
 - the target's agent: `agent_working`, `agent_needs_approval`;
 - tmux and the sidecar: `tmux_unanswered`, `tmux_failed`, `signal_not_written`.
 
@@ -513,7 +668,8 @@ at a pinned commit, never by hand:
   {"name": "lanes_rename", "description": "<harvested>", "effect": "write", "state": "planned", "description_sha256": "<harvested>"},
   {"name": "lanes_new", "description": "<harvested>", "effect": "exec", "state": "planned", "description_sha256": "<harvested>"},
   {"name": "lanes_send", "description": "<harvested>", "effect": "exec", "state": "planned", "description_sha256": "<harvested>"},
-  {"name": "lanes_signal", "description": "<harvested>", "effect": "write", "state": "planned", "description_sha256": "<harvested>"}
+  {"name": "lanes_signal", "description": "<harvested>", "effect": "write", "state": "planned", "description_sha256": "<harvested>"},
+  {"name": "lanes_publish", "description": "<harvested>", "effect": "write", "state": "planned", "description_sha256": "<harvested>"}
  ]
 }
 ```
@@ -561,6 +717,32 @@ workspace's `uploads/` folder without overwriting files; an optional paste place
 selected lane. Active transfers have an idle timeout, not a short total-duration limit. Credentials, `.git`
 metadata and disallowed folders cannot be uploaded through the helper.
 
+**Uploads converge on the docs store** (docs cockpit W10 task W5, LNS-106). Both ways in — `lanes upload` over SSH and
+the Docs page's `POST /up` (the phone and laptop drop area) — go through `libexec/uploads.py`: the file lands in
+`<folder>/uploads/` exactly as before (first lane folder, else the workspace's working directory; `-1` on a
+collision; the repository's `.git/info/exclude` line) and each chunk read from the upload is written there AND handed
+to `docs_store.intake` in the same pass (a `Tee`), so the store's sha256 receipt is of exactly the bytes that arrived,
+never of a file an agent could rewrite first. The store keeps a copy — a hard link would share an inode with a file
+the container may write — for the uploader's login (`source` `ssh` or `web`, kind by extension), and the Docs page and
+the sidebar's count show it. The folder is the container's, written by the host as the agents' own uid, so the walk
+never follows a link (directories opened component by component, files `O_EXCL|O_NOFOLLOW`, the tar stream unpacked
+member by member instead of `tarfile.extractall`) and no git process runs in the repository (its config's
+`core.fsmonitor` would be a command the container chose). An `age` switch (`LANES_DOCS_AGE_RECIPIENT`, default off)
+encrypts the store copy only; the docs service decrypts on the fly when it holds an identity, else answers 409.
+
+**Docs store** (docs cockpit W10 task W1, LNS-102; read by the docs service, W3, and written by both upload paths
+through `libexec/uploads.py`, W5, and by the publish pick-up, W4 — `docsd.Pickup`, `source` `publish`):
+`libexec/docs_store.py` keeps documents per person in host state, under
+`docs/<login, percent-encoded as for profiles>/<workspace>/<lane>/<id>/`: the file itself, `meta.json` and
+`receipt.json`, both with the sha256 the host computed while streaming the bytes in (a claimed hash is never taken).
+A byte cap refuses an oversize document and leaves nothing behind. Ids are base36 seconds plus six random
+characters; a name keeps only its basename's letters, digits, `.`, `_` and `-`, and gains `-1`, `-2` within a lane as
+an upload does in `uploads/`. Nothing is written or read through a symbolic link. A document is visible to the person
+whose store holds it, to every member when it names nobody, otherwise to the logins it names; `docs/counts.json`
+counts each lane's documents and the append-only `docs.log` records each intake and removal without content, titles
+or names. The docs service, the publish verb, receipted uploads and the sidebar's count build on it (plan
+`docs/superpowers/plans/2026-10-08-lanes-docs-cockpit.md`).
+
 **Quick edit** (`Ctrl-Alt-e`, cockpit v3 E1–E3) is the opposite direction and moves no file at all. The floating
 **Edit** pane runs `lanes edit --focused` on the server: it resolves the focused tmux lane as the preview does, finds
 the lane's git checkout and, for a linked worktree, its main checkout (`lanes_lib.repo_roots`, walking up to `.git`, a
@@ -626,8 +808,26 @@ DM-LANES-INSTALL-HANDOVER).
 
 Tailscale Serve terminates private HTTPS on 8443 and forwards to the dedicated Caddy user service on loopback
 8083. Caddy serves `web/` and forwards native assets, authentication and WebSockets to Zellij on loopback 8082.
-Zellij's existing token/cookie checks remain authoritative; the mobile layer adds no second login system. The one
-other route, `/enrol/*`, goes to the enrolment service on loopback 8184 (see Access).
+Zellij's existing token/cookie checks remain authoritative; the mobile layer adds no second login system. Two other
+routes go to services of their own, each bound to the tailnet login Serve injects and never to Zellij's cookie:
+`/enrol/*` to the enrolment service on loopback 8184 (see Access) and `/lanes-docs/*` to the docs service on loopback
+8185 (Docs service, below). Caddy's route list, in the order it is declared:
+
+| Path | Goes to | Headers |
+| --- | --- | --- |
+| `/lanes-docs/*` (prefix stripped) | `lanes-docsd` 127.0.0.1:8185, keeping Serve's `X-Forwarded-For` | docsd's own, per route (the site-wide set skips it: `header @notdocs`) |
+| `/lanes-assets/vendor/*` (prefix stripped) | `$LANES_SHARE/vendor` files: the pinned Mermaid `install/enable-docs.sh` installs (`Cache-Control: public, max-age=31536000, immutable`; a page names the versioned file, DEF-1870) | site-wide |
+| `/lanes-assets/*` (prefix stripped) | `web/` files (`no-cache`) | site-wide |
+| `/enrol/*` (prefix stripped) | `lanes-enrold` 127.0.0.1:8184, keeping Serve's `X-Forwarded-For` | site-wide |
+| `/assets/*`, `/ws/*`, `/command/*`, `/info/*`, `/session`, `/session-list` | Zellij web 127.0.0.1:8082 | site-wide |
+| `GET /<device>` (one path segment, or `/`) | `web/index.html` (`no-store`) | site-wide |
+| anything else | Zellij web 127.0.0.1:8082 | site-wide |
+
+A view session is served at `/<device>`, so `bin/lanes` `device_name` refuses the service roots as device names
+(`enrol`, `lanes-docs`, `lanes-assets`, casefolded). Caddy sorts the routes before it runs them: a single-path `handle`
+goes ahead of another only when that one has a single path too (DEF-1872), so the vendor route stays with the
+single-path routes above the named-matcher ones; its order is proven on a model of that sort
+(`test_docs_assets.VendorRoute`), not on a running Caddy (DEF-1871, open until the RUNBOOK's operator check).
 
 The phone shell uses the pinned client's window hooks for workspaces, panes, input and sizing. A visible
 **Type here** field holds the original terminal input, as a text field. Programmatic input focus is blocked on
@@ -665,6 +865,93 @@ reads the enrolment service's `GET /site` on the same origin (`/enrol/site`) and
 enables the services through `install/enable-web.sh` and prints the private URL; without a flag a known device
 keeps its layout.
 
+**Docs cockpit (plan W10, LNS-102…110).** Agents put content where people open it, and people hand files to agents,
+on one login-bound page per server, `/lanes-docs/`: `lane publish` / `lanes_publish` in the container write a
+request that `lanes-docsd`'s own 5 s pick-up reads through `/proc/<pid>/root` (publish pick-up, below); both upload
+paths land a file in the workspace's `uploads/` and the store in one pass ("Desktop and uploads"); the per-login store
+`libexec/docs_store.py` keeps every document with its sha256 receipt; `libexec/mdlite.py` renders Markdown and the
+pinned Mermaid draws its fences (docs rendering, below); `libexec/docsd.py` serves it all to the tailnet login Serve
+injects, only after the operator pinned the Serve header check (docs service, below); `lanes-statusd` carries each
+lane's count and the web origin into `status.json`, from which the sidebar's ` ▤ docs N` strip, its OSC 8 links and
+the `d` key build ("Views and panes"), and the phone's **More → Docs** and the laptop bar's **Docs** link it from the
+shell (above). `lanes doctor` reports the unit, the pin, the store, the Mermaid pin and the `age` switch. What
+`lanes docs push <id>` would hand to the data service's publication surface is not built (it prints the receipt and
+exits 2). Operations, limits and the operator's live checklist: RUNBOOK "Docs service"; the user's view: the user
+guide's [Docs](USERGUIDE.md#docs).
+
+**Docs rendering (W10 W2, LNS-103).** Markdown an agent publishes from a lane is turned into an
+HTML fragment by `libexec/mdlite.py` `render(text)`, which the docs cockpit's `lanes-docsd` (W3) embeds: standard
+library only, deterministic, at most 1 MiB of UTF-8 (`TooLarge` past it), every algorithm linear in its input. Agent
+content is treated as hostile: every text node and attribute value is escaped exactly once, raw HTML stays text, a
+link keeps its URL only for `http://`, `https://`, `mailto:`, `/lanes-docs/` or `#` (the web ones open in a new tab
+with `rel="noopener noreferrer"`) and only without a backslash or a `.`/`..` path segment (`%2e` spellings included,
+which a browser resolves before it requests; on this site no `%2f`/`%5c` either: security review 2026-10-08), an image only for a document's own bytes
+(`/lanes-docs/d/<id>/raw` or `/artifact`) or a base64 `data:image/png|jpeg|gif|webp`; any other destination is dropped
+and its text kept. A `mermaid` fence becomes `<pre class="mermaid">` for the pinned Mermaid (W6). The subset and the
+output contract are DM-LANES-DOCS-RENDER in the master data-model ledger.
+
+**Docs service (W10 W3, LNS-104).** `libexec/docsd.py` (`lanes-docsd.service`, loopback 127.0.0.1:8185, reached as
+`/lanes-docs/*`) serves the docs store to the person it belongs to. A request is answered only when it came through
+Tailscale Serve (its `X-Forwarded-For` names a tailnet address), carries Serve's identity headers (a tagged device has
+none), names a valid login that owns a member record in an allowed domain, and the operator has pinned the Serve
+header check (`lanes enrol mode request`), and — on every route since the security review of 2026-10-08 — its
+`Sec-Fetch-Site` is `same-origin` or `none`, or it is a GET/HEAD top-level navigation (`Sec-Fetch-Mode: navigate`,
+`Sec-Fetch-Dest: document`: a link followed from any site); a sandboxed artifact's `fetch()` and subresource loads are
+`cross-site` and not navigations, another `*.ts.net` host's are `same-site`, and `POST /up` takes `same-origin` or
+`none` only; otherwise 403. It uses enrold's own checks
+(`through_serve`, `caller_of`, `member_logins`, `read_mode`, the domain rule), never Zellij's cookie, and listens on
+loopback only (DEF-1645 stays the open risk; the pin gate is the mitigation). A person sees their own store, what
+names them in `for`, and — for a document that names nobody — what lies in a workspace their member record grants; any
+other document is a 404 like a missing one. Pages: the index (workspace → lane → newest first, with counts; filtered
+by `?ws=<ws>&lane=<lane>`, the sidebar's deep link), a document page by kind (Markdown rendered by mdlite; an HTML or
+SVG artifact only linked, never embedded; a file's facts and its download), the raw bytes as an attachment with
+`X-Lanes-Sha256`, the artifact as a top-level document under `Content-Security-Policy: sandbox allow-scripts` (an
+opaque origin: its scripts run but cannot read this site), the receipt, and `docs.css`/`docs.js` from `web/`. Every
+reference a page emits is relative, because Caddy strips `/lanes-docs`. Pages carry `default-src 'none'; style-src
+'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; connect-src 'self'; form-action 'self'; base-uri
+'none'` (W5 added `connect-src 'self'` for the drop area's own request), and the site-wide Caddy header set skips
+`/lanes-docs/*` (`header @notdocs`), so these are the only policies a document gets. Per process it bounds what one
+login can make it do: 300 requests a minute, two Markdown renders at once (a rendered document is kept in an 8 MiB
+cache by its sha256, so a second view renders nothing), two 32 MiB buffers at once shared by uploads and decryptions
+and at most one of them per login, and a deadline on each upload body; refusals are coalesced in `docs.log` and the
+log rotates at 8 MiB (RUNBOOK "Docs service", Limits). `POST /up` takes a multipart form
+from the Docs page (32 MiB, 30 uploads per login in 10 minutes, two at once, one per login) into a
+lane of one of the person's workspaces through `uploads.receive` — the workspace's `uploads/` and `docs_store.intake`,
+both or neither — and answers each file's receipt with the in-container path it landed at. A refused body is read away
+before the answer (at most 64 MiB, then a short linger), so the client reads the refusal instead of a reset
+(DEF-1854). The index loads the drop area's `upload.css`/`upload.js` (their own files: `docs.js` had no room). RUNBOOK
+"Docs service" has the unit, the pin gate and the wire contract (DM-LANES-DOCS-WIRE). A member record's `workspaces`
+grants the boards it lists; a record that lists none grants every workspace the host serves, as nowhere else in Lanes
+narrows by that list (DEF-1852).
+
+**Publish pick-up (W10 W4, LNS-105).** An agent publishes from a lane with `lane publish <file>` or `lanes_publish`:
+the container writes a request, `~/.lz/state/publish/<lane>/<id>.json` (`{v, path, title, kind, claimed_sha256,
+mime, bytes, for}`, DM-LANES-PUBLISH-REQUEST), and nothing else. The docs service runs its own pick-up cycle every
+5 s on a thread beside the HTTP server (`docsd.Pickup`; statusd's tick is not involved). For each container
+`containers.json` names whose init pid is alive — and whose `/proc/<pid>/root` is not the host's own root, so a
+recycled pid never turns the host's home into a container's, and, where the account can see the home volume
+`containers.json` records, whose `/home/coder` is that volume (another container that got the pid is skipped) — it
+surveys `~/.lz/state/publish/` and each lane directory with `os.scandir` (opened by `lanes_lib.open_real_dir`, a link
+is never followed), reading at most 4,096 entries of a container per cycle: a container that holds more is refused for
+the cycle and said in the journal once an hour, so what one container plants never costs the service its memory or
+the other containers their cycle. It claims a request by renaming it to `.<id>.taking` (a directory planted at that
+name, or at the receipt's, is removed or moved aside; a request that still cannot be claimed is skipped for the next),
+reads it with `read_regular_at` (no link, no FIFO, at most 16 KiB) and checks it. The file is
+resolved inside the container (`container_realpath`: an absolute link restarts at the container's root) to a path
+under `/home/coder`, its directories are opened without following a link and the file `O_NOFOLLOW|O_NONBLOCK`, a
+regular file of at most 32 MiB; a link swapped in meanwhile, a FIFO, a device or a larger file is refused, so a
+container can never make the host read outside its home. The bytes stream into `docs_store.intake` (`source`
+`publish`, `by` the lane id) through a reader that hashes them and refuses, inside intake, a sha256 other than the
+claimed one, so nothing is stored. The answer goes back beside the request as `<id>.receipt.json` (`{v, id,
+request, sha256, bytes, url, at, outcome, reason?}`, DM-LANES-PUBLISH-RECEIPT), written by rename like statusd's
+`~/.lz/status.json`; the claim is removed and the lane keeps its 16 newest receipts. The document is for the request's
+`for` (a member login), else for the member whose profile last opened the lane, else for every member whose record
+grants its workspace; a request whose `for` names no member, or that has nobody to go to, is answered
+`not-delivered` either way, so a container cannot learn from the reason whether a login is a member (docs.log keeps
+the precise word). One `published` push per lane per minute goes through `notify` (its config and desk-presence
+rule; kind and size only, never a title). At most 16 requests per container per cycle and 30 per container per 10
+minutes are taken; more are refused `rate-limited`.
+
 ## Installed files and services
 
 `install/services.py` renders the service templates against the installed binary paths and the `current` link.
@@ -714,7 +1001,9 @@ release untouched; `services.py --install` is the commit, and its refusals (the
 symlink, a path no unit can hold — each raised before its first write as a `services.Refusal`) exit 3. After it,
 `libexec/update.py post-commit` runs from the new tree, with its own `bin/lanes`: daemon-reload, `lanes sync`, the
 statusd restart, a `try-restart` of each optional unit (`update.TRY_RESTART`), `install-container` for each container
-`containers.json` records with a home volume (read after the sync), `lanes reload-views`,
+`containers.json` records with a home volume (read after the sync), then for the Throttle daemon's container when sync
+did not record it (`update.daemon_container`; skipped with a warning when sync or docker said it is gone or has no home
+volume, `update.daemon_gone`, so a stale name never leaves every update `partial`), `lanes reload-views`,
 `lanes ensure --if-layout-changed` — each step in its own session, bounded (`STEP_TIMEOUT`, then its process group is
 stopped), its output in `update/last.log`, its exit status in `update/last.json`, and run whatever the one before
 returned — `lanes sync`'s exit 1 (a board with an error) being a warning that leaves the result `ok`
@@ -805,7 +1094,7 @@ only the full server install enables it, and an update (`--update-only`) enables
 an update has moved past. A tree is staged (`lanes_lib.staged_tree`) when it sits in the default `…/pkg/<version>`
 root or carries the npm wrapper's `.lanes-package.json` stamp, so a `$LANES_PKG_ROOT` of any name is followed through
 the link too (DEF-1757); only the link under the home counts for such a root. `tree_version` and `tree_stamp` read a
-tree's `VERSION` and that stamp. Every long-running process — statusd, enrold, the economy poller, the notifier, the
+tree's `VERSION` and that stamp. Every long-running process — statusd, enrold, docsd, the economy poller, the notifier, the
 Studio Host enable step and each sidebar — writes the resolved tree it started from to
 `~/.local/state/lanes/run/<name>.tree` (`lanes_lib.record_tree`), so what still runs an old tree is a file
 comparison, not a process scan. `lanes version` makes it: each record against the resolved target of the `current`
@@ -824,7 +1113,9 @@ layout's commands (`libexec/sidebar`, `libexec/view.sh`, `holders/ssh.sh`) resol
 unescaped as `services.unit_value` escaped it) resolves to it.
 No service requires the checkout to be named `~/lanes`. Re-run the server installer after moving it.
 
-Core units are the status observer and sync, ensure and garbage-collection timers. The web units are opt-in.
+Core units are the status observer and sync, ensure and garbage-collection timers. The web units are opt-in. The
+enrolment and docs services (`lanes-enrold`, `lanes-docsd`) and `lanes-update.timer` are enabled by every full server
+install; an update (`--update-only`) enables nothing and only restarts what runs (DEF-1900 for `lanes-docsd`).
 The co-located Throttle Studio Host (`lanes-studio-host.service` and its enrolment retry timer) is opt-in too:
 `install/enable-studio-host.sh` enables it, and its binary is selected by `lanes studio-host install` from an
 `opt-in` line of `holders.lock` or a local build, sha256-verified either way (`libexec/studio_host.py`).
@@ -836,6 +1127,37 @@ The package uses Python's standard library and POSIX shell. Host binaries are ve
 in `holders.lock`; Zellij's web assets are served by that binary and integrity-pinned in `web/index.html`.
 Deployment profiles, workspace catalogs and runtime state remain distinct from shared source code.
 
+**What the docs cockpit installs (plan W10, W1–W8).** Nothing is vendored into the tree: Mermaid is downloaded and
+checked against `holders.lock`'s pin, and every other piece is the standard library, POSIX shell or a file Caddy
+serves:
+
+| Piece | Where | Installed or run by |
+| --- | --- | --- |
+| `lanes-docsd.service` (`libexec/docsd.py`: the HTTP service on 127.0.0.1:8185 and its publish pick-up thread) | `~/.config/systemd/user/`, `lanes.slice` | `services.py` renders it; every full server install enables and restarts it after `lanes-enrold`; an update only restarts it when it runs (DEF-1900) |
+| `libexec/docs_store.py`, `libexec/mdlite.py`, `libexec/uploads.py` | the installed tree | the server install; no unit of their own (docsd, `lanes upload`, statusd and `lanes doctor` import them) |
+| `web/docs.css`, `web/docs.js`, `web/upload.css`, `web/upload.js` | the installed tree; docsd serves them at `/lanes-docs/docs.css` and so on | the server install |
+| The Caddy routes `/lanes-docs/*` and `/lanes-assets/vendor/*`, and `header @notdocs` | `web/Caddyfile`, run by `lanes-mobile.service` | the server install, which `try-restart`s `lanes-mobile` so Caddy reads the new file |
+| Mermaid 11.17.2, `holders.lock`'s opt-in `mermaid` line (DM-LANES-DOCS-VENDOR) | `~/.local/share/lanes/vendor/mermaid-11.17.2.min.js` and the link `mermaid.min.js` | `install/enable-docs.sh`: every full server install and every update (never fatal), and by hand |
+| The docs store, `docs/counts.json`, `docs.log` (DM-LANES-DOCS-STORE, -RECEIPT, -COUNTS, -LOG) | `~/.local/state/lanes/docs/`, `~/.local/state/lanes/docs.log` | written by docsd (uploads, publishes, reads and refusals) and `lanes upload`; read by statusd (counts) and `lanes doctor` |
+| `lane publish` and `lane-mcp`'s `lanes_publish` | each container's `~/.lz/bin/` (`lane`, `lane_core.py`, `lane-mcp`) | `lanes install-container <name>`, which every update runs again for each container `containers.json` records |
+| Publish requests and their receipts (DM-LANES-PUBLISH-REQUEST, -RECEIPT) | each container's `~/.lz/state/publish/<lane id>/` | the request by `lane publish` / `lanes_publish`, the receipt by docsd's pick-up |
+| `LANES_DOCS_PORT`, `LANES_DOCS_DOMAINS`, `LANES_DOCS_AGE_RECIPIENT`, `LANES_DOCS_AGE_IDENTITY` | lanes-docsd's drop-in (`systemctl --user edit lanes-docsd.service`) | the operator; `host-install.sh` `check_docs_age` refuses the recipient where no `age` binary is on PATH |
+
+**What the fleet block installs (plan W11, 1.4.0; spec `docs/superpowers/specs/2026-10-11-lanes-fleet-dashboard-design.md`).**
+No collector and no new unit: one container-side file, two additive `status.json` keys, one opt-in token file and one
+site fact. Routes of truth: the pulse file is the daemon's facts as the pulse last read them (DM-LANES-THROTTLE-PULSE);
+`status.json`'s `throttle` is statusd's copy of it with `stale`, its `fleet` statusd's own host reading (DM-LANES-FLEET);
+the sidebar and `lanes doctor` read `status.json` only.
+
+| Piece | Where | Installed or run by |
+| --- | --- | --- |
+| `throttle-pulse` (a contract file, `bin/lanes` `CONTRACT_FILES`; stdlib Python; GET only, 3 s timeout, 1 MiB cap, no redirect) | each container's `~/.lz/bin/`; its loop runs only in the daemon's container, on the tmux socket `lanes-pulse` | `lanes install-container <name>` installs it everywhere and starts the loop in the container `LANES_THROTTLE_CONTAINER` in the server's `~/.config/lanes/site.conf` names, else the Throttle tab's; every update runs install-container again for each container `containers.json` records and for that daemon container (the same site.conf resolution); statusd re-arms a stopped loop at most once per 10 min, never while the host is critical |
+| The pulse file (DM-LANES-THROTTLE-PULSE) | the daemon container's `~/.lz/state/throttle.json` | the pulse, by rename, when a value changed or 60 s passed; read by statusd through `/proc/<init>/root` (one stat per cycle, ≤ 64 KiB, no link) |
+| `throttle`, `fleet` in `status.json` (DM-LANES-STATUS, DM-LANES-FLEET) | `~/.local/state/lanes/status.json` | statusd: `throttle` copied with `stale` (pulse `at` > 90 s old, or the file absent or refused); `fleet` every 10 s from `/proc` and the containers' cgroups, skipped while the host is critical |
+| `~/.lz/throttle-token` (opt-in, 0600) | the daemon container's home | the operator only: `lanes throttle adopt-token <container>` (the container's local Throttle client token, never an Anthropic credential); read by the pulse for the guarded `/pools/<pool>/status` |
+| `LANES_FLEET_DASHBOARD_URL` | the server's `~/.config/lanes/site.conf` | the operator only, once an authenticated Grafana exists; https only (`bin/lanes` `fleet_dashboard_url`); no code path writes it; `lanes doctor` shows it, unset, or why it is ignored |
+| `lanes doctor`'s `throttle pulse:`, `throttle pools:` (1.5.0), `fleet:`, `fleet dashboard:` lines, and its harness mix `lanes: claude N · codex N · …` (1.5.0) | — | `bin/lanes` `fleet_doctor` and `harness_line`, from `status.json`, the registry's Throttle tab and site.conf (it never asks the daemon, starts the pulse or runs docker); a `⚠` at worst — a pulse that is absent, down or more than 90 s old by `at` (statusd's bound, DEF-1941), a configured pool with no usable account, a `fleet` that is stale or absent, a dashboard URL that is refused — never a `✗` |
+
 ## Access
 
 Clients log in to one Unix account over SSH (tailnet, or the `lanes-public` fallback). Who may do so is the
@@ -880,8 +1202,9 @@ owner's look on that device instead of spreading it into the new owner's profile
 decides whenever one exists, so a claim never overrides one), and it, `lanes keys adopt --login` and `lanes keys
 owner` fold the devices they name; `lanes user list|show` read the store. The sidebar of a device with an owner
 (cockpit v3 R3) resolves that owner exactly as `lanes attach` does (`users.login_for`, at start and whenever the device
-file changes — a claim, a hand-over) and adds the profile's mtime to its reload stamp, the one extra stat per tick an
-owned device pays: on a change it re-reads the profile, merges its opened-lane marks into its own (the later per lane)
+file changes — a claim, a hand-over) and adds the profile's `(st_ino, st_mtime_ns, st_size)` to its reload stamp, the
+one extra stat per tick an owned device pays (`users.update` replaces the file by rename, so every write has a new
+inode and two writes inside one timestamp tick are both seen, DEF-1972): on a change it re-reads the profile, merges its opened-lane marks into its own (the later per lane)
 and paints its look over the device file's (`layered_look`: `--device-only` keys → profile → unmarked device keys →
 environment → defaults).
 Opening a lane there (`open_lane`, or `lanes next|prev`) writes the device's own `clients/<device>.seen.json` as before