@vibelord/lanes 1.2.0 → 1.5.0

package/payload/lanes/docs/USERGUIDE.md

@@ -41,7 +41,7 @@ Phone / tablet / laptop ── HTTPS (Tailscale :8443) ┤
                                                    ▼
   Linux workspace host (one unprivileged account)
     one Zellij view session per device: workspace tabs, lane sidebar, 1–3 viewports
-    lanes-statusd · registry sync · upload intake · web services
+    lanes-statusd · registry sync · upload intake · docs service · web services
                                                    │  /proc/<container init pid>/root
                                                    ▼
   Workspace containers (home /home/coder, uid 1000)
@@ -52,7 +52,7 @@ Phone / tablet / laptop ── HTTPS (Tailscale :8443) ┤
 
 | Layer | Owns | Lifetime |
 | --- | --- | --- |
-| Host | Views, the registry, status, uploads, web services | Services restart freely; nothing here holds an agent |
+| Host | Views, the registry, status, uploads, the docs store, web services | Services restart freely; nothing here holds an agent |
 | Container | Each lane's tmux session and the agent in it | Survives every view, reconnect and rebuild |
 | View | One Zellij session per device (`mac`, `phone`, `browser`, …) | Disposable: `lanes rebuild <device>` recreates it, agents untouched |
 
@@ -442,7 +442,7 @@ redeemed from a second machine yet.
 
 After a server update — with `--update-only` the installer runs these steps itself once the new release is switched
 in, in this order: `systemctl --user daemon-reload`, `lanes sync`, the statusd restart, a `try-restart` of each
-optional service that runs (economy, notify, enrolment, `lanes-mobile`, `lanes-web` and the Studio Host — restarted,
+optional service that runs (economy, notify, enrolment, docs, `lanes-mobile`, `lanes-web` and the Studio Host — restarted,
 not re-checked as `enable-studio-host.sh` does; one that is off stays off), `lanes install-container` for every
 container `lanes sync` recorded, `lanes reload-views` and `lanes ensure --if-layout-changed`. A step that fails is
 reported and the next one still runs. `lanes sync` exiting 1 — a board with an error, such as a container that no longer exists, whose
@@ -550,7 +550,7 @@ would put the bad release back, is refused (install it by hand with `npx @vibelo
   tree's `VERSION` and the commit of its npm stamp (none for a checkout), the tree (`pkg/<version>` for an npm
   install), whether `~/.local/share/lanes/current` names that tree (`current pkg/1.2.0 ✗` when it names another: this
   `lanes` was started from an old tree), then the tree each long-running process recorded when it last started
-  (`~/.local/state/lanes/run/<name>.tree`: statusd, enrold, notify, economy, studio_host and the newest sidebar).
+  (`~/.local/state/lanes/run/<name>.tree`: statusd, enrold, docsd, notify, economy, studio_host and the newest sidebar).
   Each `✗` there names a process that does not run the current code: its last start ran another tree
   (`statusd runs 1.1.0 ✗`), or ran the current tree before its code last changed (`statusd started before its tree
   changed ✗` — a checkout updated in place keeps its path, so `lanes version` compares the record's time with the
@@ -564,7 +564,8 @@ would put the bad release back, is refused (install it by hand with `npx @vibelo
 - The client installer prints `lanes client <version>` and copies `VERSION` into `~/.local/share/lanes/client/`.
   `lanes-launch --version` prints it (`lanes-launch 1.2.0`; a checkout's client reads `lanes/VERSION`; `dev` without
   either), and the dim line a window shows while it connects names it: `lanes 1.2.0: connecting to lanes…`.
-- On a phone or tablet, **More** shows the server's release as its first row, **Lanes v1.2.0**, above **Text size**:
+- On a phone or tablet, **More** shows the server's release as its first row, **Lanes v1.2.0**, above **Docs** and
+  **Text size**:
   the shell asks the enrolment service's `/enrol/site` once when it opens (the release that service runs; the server
   installer restarts it on every install). Nothing is shown when the service does not answer.
 - `lanes-launch` passes that version to `lanes attach` (`--client-version`). A client older than the server gets one
@@ -603,6 +604,10 @@ would put the bad release back, is refused (install it by hand with `npx @vibelo
   client folder afterwards. A question without an answer (no server, a busy one, or a server from before
   1.2.0, which takes the flag for a device name) is only logged (`self-update:` lines in `launch-<target>.log`): the
   connection that follows says what is wrong with the path.
+- A client from before 1.2.0 does not update itself: its `lanes-launch` never asks `lanes hello --client-version`. Run
+  `npx @vibelord/lanes@1.5.0` once on that machine (your remembered options are given again); from then on its windows
+  follow the server by themselves. A 1.4.0 window asking a 1.5.0 server, for example, is answered ` update=1.5.0` and
+  installs exactly that release.
 - A first install with an invite is the server's release too (W9 K3): the npm installer asks the enrolment service's
   `/enrol/site` for the server's release before it installs anything and, when that is newer, runs `npx --yes
   @vibelord/lanes@<release>` instead, which redeems the code ([Join with an invite](#join-with-an-invite)). The phone's
@@ -699,6 +704,7 @@ browser view). `lanes user show <login>` prints it.
 | The lanes you opened, so a Done lane opened on the phone leaves Done on the Mac, and the last lane you opened | The device's own record of what it opened (`clients/<device>.seen.json`: an older release reads it) |
 | Board order and hidden boards (`lanes workspaces order\|hide\|show`) | The layout (desktop or phone), viewports, the machine a window belongs to, its owner |
 | Pinned and hidden lanes (`lanes lane pin\|unpin\|hide\|show`) | |
+| The fleet block folded or not (the sidebar's `i`: `look.fleet_collapsed`) | A device nobody owns: that sidebar's own, until it restarts |
 | Your own quiet window for pushes, `notify.quiet_s` (section 8; no verb sets it yet) | |
 
 - **Per user or per device.** A look flag on a device with an owner goes to your profile, and every sidebar of every
@@ -822,10 +828,24 @@ Top to bottom, a desktop sidebar is:
    would leave the pane. Then `zmx lanes (N)` when any exist, then **Unregistered (N)**
    with its `+ New shell` row. A list longer than the pane ends in `⋮ N more`; moving onto that row or clicking it
    scrolls instead of opening.
-3. **Upload strip** (panes of 14 rows or more): ` ↑ uploads · click, then drop  (U)` (section 5).
-4. **Strip row** (panes of 18 rows or more): the fleet economy line when the opt-in poller runs (section 8), otherwise
-   the other workspaces that need you, e.g. ` ◆1 Worlds · ◇2 Code`; blank when there is nothing to say.
-5. A rule, then the **footer**: one line, by priority.
+3. **Fleet block** (panes of 18 rows or more, once the server's statusd publishes the fleet facts), pinned above the
+   upload strip; the lane list scrolls in the rows left. Throttle in one row, a bar per provider, the host and its
+   biggest containers; `i` folds it to one line. What each row says, its colours and where the figures come from:
+   [Fleet](#fleet).
+4. **Upload strip** (panes of 14 rows or more): ` ↑ uploads · click, then drop  (U)` (section 5). Once this
+   workspace's lanes have published documents (the docs cockpit) it reads ` ↑ uploads · ▤ docs 3  (U)` — the count
+   is every document of its lanes, whoever published it — and the whole strip is a link to the docs page,
+   `https://<server>:8443/lanes-docs/` (⌘-click in Ghostty and iTerm2, Ctrl-click elsewhere); a plain click still
+   arms the upload. The cursor row's name is a link to that lane's own documents
+   (`/lanes-docs/?ws=<workspace>&lane=<lane id>`) while it has any, and `d` shows the link in the footer. The links
+   need the server's Tailscale name (statusd learns it as the enrolment service does): without it the strip still
+   counts and `d` shows the path alone. What the page holds and who sees what: section 4, [Docs](#docs).
+5. **Strip row** (panes of 18 rows or more): the fleet economy line when the opt-in poller runs (section 8) and the
+   fleet block's Throttle row does not show the overflow money and every part after it (no block, the block folded,
+   an untokened ` up …` or a ` down` Throttle row, or a row that dropped `spill` or `429` to fit the pane: the economy
+   line keeps its place), otherwise the other workspaces that need you, e.g. ` ◆1 Worlds · ◇2 Code`;
+   blank when there is nothing to say.
+6. A rule, then the **footer**: one line, by priority.
 
 A workspace whose lanes live on another SSH host (`sshWorkspaces` with `layout: "lanes"`) is attach-only: it has no
 Unregistered section, no upload strip and no `+`, and its footer has no `x close`.
@@ -845,8 +865,9 @@ Unregistered section, no upload strip and no `+`, and its footer has no `x close
 | 35 | `×` close, on unregistered sessions only |
 
 Marks and their ASCII twins: `▌` `|` cursor · `›` `=` viewing · `²` `2` / `³` `3` other viewport · `▲` `^` pinned · `·` `.` viewer ·
-`…` `~` clipped · `×` `x` close · `+` `+` new / add · `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now ·
-`⚠` `!` warning or starving · `↓` `v` downgraded · `$` `$` paid. The full tables, colours and mockups are in
+`…` `~` clipped · `×` `x` close · `+` `+` new / add · `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now · `▤` `#` docs ·
+`⚠` `!` warning or starving · `↓` `v` downgraded · `$` `$` paid · the fleet block's `⚙` `@` Throttle, `◆` `*` provider,
+`▣` `[` host, and its bar `▰` `=` usable, `▱` `~` cooling, `▪` `:` benched, `·` `.` dead. The full tables, colours and mockups are in
 [DESIGN.md](DESIGN.md).
 
 **Footer**, highest priority first: the open prompt — the sidebar asks one thing at a time, in one of two shapes. A
@@ -863,7 +884,7 @@ draws the same footer (its picker says ` Choose a workspace · Tap Cancel`, and
 idle). An empty workspace shows `no lanes declared · + New shell` on its New shell row.
 
 **Sidebar keys** (`?` shows the short form of this table in place of the list until the next key; that key only closes
-the sheet). Its first row says which lanes: `lanes <installed version> · view <the version this sidebar runs>`. The sheet puts companion keys on one line (`J K`, `Tab S-Tab`, `+ U`, `u z`, `p h`, `H o`, `r ?`), leaves `PageUp` / `PageDown`
+the sheet). Its first row says which lanes: `lanes <installed version> · view <the version this sidebar runs>`. The sheet puts companion keys on one line (`J K`, `Tab S-Tab`, `+ U d`, `u z`, `p h`, `H o`, `r i ?`), leaves `PageUp` / `PageDown`
 to this table and ends with `Ctrl-Alt-l` — not a sidebar key but the chord that brings the keyboard here from a lane
 (section [Keybindings](#keybindings)). Every key below does something in the sidebar, and no other key does
 (`tests/unit/test_sidebar.py` `DocumentedKeys` presses each one and every other key a keyboard sends):
@@ -890,7 +911,9 @@ to this table and ends with `Ctrl-Alt-l` — not a sidebar key but the chord tha
 | `h` | Hide the cursor lane on every device you own (` Hid ‘name’ · o shows it`); on a hidden lane `o` shows, show it again |
 | `H` | Hide this workspace on every device you own: `y` arms, `Enter` hides — its tab closes, its lanes keep running (the last workspace shown stays) |
 | `o` | Show / hide again the lanes you hid (shown faint) |
+| `i` | Fold the fleet block to one line, or unfold it, on every device you own (` fleet folded · i unfolds`); then the keyboard goes back to the lane |
 | `U` | Arm the upload strip |
+| `d` | Show the cursor lane's docs link in the footer for 3 s: `https://<server>:8443/lanes-docs/?ws=<workspace>&lane=<lane id>`, as much as the row holds, the whole line one link to all of it (⌘/Ctrl-click, or your terminal's Copy Link); then the keyboard goes back to the lane. ` no docs in ‘name’` on a lane without documents |
 | `r` | Reload and repaint; while the footer says `update ready · reload (r)`, rebuild this view on the installed release (the window reconnects, agents are untouched); the keyboard goes back to the lane |
 | `?` | The key sheet |
 
@@ -929,7 +952,7 @@ back clears it at once. On the phone the picker is a whole tab and has no such l
 **A message stays 3 seconds, or until your next action.** What an action says in the footer (` Closed sh`,
 ` Renamed → …`, ` Cancelled`, ` view not running yet`, or why a close failed) stays after the keyboard has gone back
 to the lane, for 3 seconds (within a second more: the sidebar looks once a second), then the legend returns. The next
-action you start in the sidebar — opening a lane, `x`, `R`, `P`, `a`, `u`, `z`, `/`, `U`, `+`, `r`, `?`, `Tab`, a chord —
+action you start in the sidebar — opening a lane, `x`, `R`, `P`, `a`, `u`, `z`, `/`, `U`, `+`, `r`, `?`, `d`, `Tab`, a chord —
 replaces it at once. Moving the cursor, typing in a field, `Esc`, the wheel, a mouse release or the focus leaving and
 coming back does not clear it.
 
@@ -1220,13 +1243,14 @@ The frontend chooses once per page load, by capability:
 | --- | --- | --- |
 | Phone | An iPhone / iPod / Android phone user agent, or a touch screen at most 600 px wide or 500 px tall | The phone shell: **Workspaces**, **Lanes**, **Panes**, **Type here** and **More** controls; the lane picker |
 | Tablet | Any other touch screen | The same shell with the controls in a top bar and the workspace list as a left panel; the whole tab is shown, so a desktop view's sidebar sits beside its lanes (**More → Single pane** shows one pane for that load) |
-| Desktop | A fine pointer (mouse, trackpad) | The plain Zellij web client plus a **Lanes** chip (top right) that opens workspace and lane pickers in an overlay bar; the terminal keeps its size and every key |
+| Desktop | A fine pointer (mouse, trackpad) | The plain Zellij web client plus a **Lanes** chip (top right) that opens workspace and lane pickers and a **Docs** link (the docs page in a new tab) in an overlay bar; the terminal keeps its size and every key |
 
 ### Phone controls
 
 - **Workspaces** (or the title in the header) opens the workspace sheet with a search field (each card shows its
   counts, `◆ 1 · ◇ 2`); **Lanes** opens the current workspace's lane picker; **Panes** switches panes; **More** opens
-  the client's own menu, where Lanes adds **Text size** (remembered on the phone) and, above it, the server's release
+  the client's own menu, where Lanes adds **Text size** (remembered on the phone), above it **Docs** — the docs page,
+  `/lanes-docs/`, in a new tab, so the terminal stays where it is — and at the top the server's release
   (**Lanes v1.2.0**, see [Versions](#versions)). The light/dark toggle repaints the whole terminal.
 - The keyboard opens only when you tap **Type here** or another input. Swipes, live updates and reconnects leave it
   closed. **Type here** is an ordinary text field: the normal keyboard with its suggestion bar, never the password
@@ -1259,12 +1283,110 @@ The frontend chooses once per page load, by capability:
   on a row while the picker asks cancels the question or the name first, then opens that lane, so nothing is left
   half-asked on the picker when you come back to it.
 
+### Docs
+
+The Docs page is where an agent shows you its work and where you hand files to an agent — every item with a sha256
+receipt the server computed. There is one per server, `https://<server>:8443/lanes-docs/`: on the tailnet only, and
+open only to your own tailnet login. No token and no second password: you see your own uploads and what was
+published for you, and nobody else's documents.
+
+**Open it.**
+
+| From | How |
+| --- | --- |
+| Phone or tablet | **More → Docs**: the page opens in a new tab, so the terminal stays where it was |
+| Laptop browser | The **Lanes** chip (top right), then **Docs** in its bar (a new tab) |
+| Desktop sidebar | The upload strip says ` ↑ uploads · ▤ docs 3  (U)` once the workspace's lanes have documents: ⌘-click (Ghostty, iTerm2) or Ctrl-click it for the page; the cursor row's name is a link to that lane's documents, and `d` shows that link in the footer ([The sidebar](#the-sidebar)) |
+| A push notification | A `published` push opens the document when the server's `action_url` uses `{doc}` (section 8) |
+| An address you type, bookmark or open from a terminal | `/lanes-docs/` everything you may see · `/lanes-docs/?ws=<workspace>&lane=<lane id>` one lane (either key alone works) · `/lanes-docs/d/<id>` one document · `/lanes-docs/d/<id>/raw` its bytes · `/lanes-docs/receipt/<id>.json` its receipt |
+
+Keep the slash: `/lanes-docs` without it is a view's address and opens the terminal page instead.
+
+**What it shows.** The index lists your documents by workspace, then lane, newest first, with counts, and above them
+the upload form. A document opens by its kind:
+
+| Kind | Opens as |
+| --- | --- |
+| `md` (`.md`, `.markdown`) | Rendered on the page, with ```` ```mermaid ```` fences drawn as diagrams (a fence Mermaid cannot read stays as its source); over 1 MiB it is not rendered: download it |
+| `html`, `svg` | A link, **Open the HTML artifact** (or SVG): the artifact on a page of its own, in a sandbox (below) |
+| `file` (anything else) | Its facts and a download |
+
+Every document page also has **Download**, **Receipt** and the facts: kind, name, size, workspace, lane, time, who
+put it there, how it came (`publish`, `web`, `ssh`) and its sha256.
+
+**Publish from a lane.** An agent publishes with the MCP tool `lanes_publish` (`path`, optional `title`, `for`,
+`kind`; section 7, [Agent tools (MCP)](#agent-tools-mcp)); in a lane's shell you do it with the `lane` command:
+
+```sh
+~/.lz/bin/lane publish report.md                             # the kind follows the extension
+~/.lz/bin/lane publish out/queue.svg --title 'Queue design' --for anna@example.com
+```
+
+`lane publish <file> [--title T] [--for <login>] [--kind md|html|svg|file]` takes a file of the container under
+`/home/coder`, at most 32 MiB, and copies nothing: it hashes the file once, leaves a small request in
+`~/.lz/state/publish/<lane id>/` and prints it as JSON — the request `id`, `path`, `kind`, `bytes`, `sha256`, the
+`receipt` path the answer will have, `picked_up_by: "lanes-docsd"` and `expected_within_s: 5`. Within about 5 s the
+server reads the file out of the container, checks that its sha256 is the one the request named (a file changed in
+between is refused, not stored), keeps its own copy and writes the receipt beside the request: `outcome: "ok"` with
+the document's `id`, `sha256`, `bytes` and `url` (`/lanes-docs/d/<id>`), or `outcome: "refused"` with a `reason`
+(RUNBOOK "Docs service", publish pick-up). The agent sees that answer as `published` in `lanes_status` of its lane.
+The document is listed under the lane it came from, and the sidebar's ` ▤ docs N` counts it within a few seconds.
+Change the file only after the receipt is there; publishing it again makes a new document.
+
+**Who sees what.**
+
+- An upload: your login alone.
+- A published document: the login `--for` names (it must be a member's); without `--for`, the person who last opened
+  that lane, on any of their devices; when nobody has, everyone whose member record grants the lane's workspace. A
+  record that lists no workspace grants every workspace the server serves.
+- Anyone else gets *not found*, exactly as for a document that does not exist. The one exception is the count:
+  everyone who sees a lane's ` ▤ docs N` sees how many documents it holds (a number, never a title).
+
+**Upload, with a receipt.** On the Docs page pick the lane, drop files on the dashed area — or tap it to choose them,
+several at once, 32 MiB in all — and **Upload**. Each file lands in that workspace's `uploads/` folder in its
+container, exactly as every other upload does ([Uploads](#5-uploads)), and the page lists its receipt: the name (a
+link to the document), size, sha256 and where it landed (`/home/coder/<repo>/uploads/<name>`) — give the agent that
+path. Every other way in (the sidebar's strip, the watch folder, `lanes-upload`, the macOS droplet) records the same
+receipt for you (section 5, "Receipts").
+
+**The sandbox.** Nothing an agent publishes is trusted. Markdown is rendered on the server by Lanes's own renderer:
+raw HTML in it stays text, a link opens in a new tab and tells the target nothing of where it came from, and an image
+shows only from the Docs pages themselves or inline. An HTML or SVG artifact is never shown inside a Docs page:
+**Open the … artifact** loads it as a page of its own under a browser sandbox, where its scripts run on an opaque
+origin of their own — they cannot read the Docs pages, cannot reach your terminal session or its sign-in, and cannot
+type into a lane. No Docs page can be framed by another page. That is how the server serves it (unit-tested); a check
+in a real browser is the operator's (RUNBOOK checklist; DEF-1853).
+
+**Encrypted at rest.** Off by default. With the operator's `age` switch on, the server keeps new store copies
+encrypted; your receipts stay the sha256 of what you sent and the files in `uploads/` stay plain for the agents
+(section 5, "Encrypted at rest").
+
+**For the administrator.**
+
+- The full server install, `npx @vibelord/lanes@<release> --server`, enables the docs service (`lanes-docsd`) and
+  installs the page's pinned Mermaid (`install/enable-docs.sh`). An update with `--update-only` enables nothing, so a
+  server set up before the docs service needs one full install, or `systemctl --user enable --now
+  lanes-docsd.service`. `lanes install-container <name>` gives a container `lane publish` and the `lanes_publish`
+  tool (new agent sessions load it).
+- **The pin gate.** The Docs page answers nobody until the Serve header check has run and its result is pinned with
+  `lanes enrol mode request` (RUNBOOK "Enrolment service", Operator verification). Until then every request is
+  refused `not-pinned`.
+- `lanes doctor` prints five docs lines (section 6): the service answering on its loopback port, the pin gate, the
+  store's size, the Mermaid pin and the `age` switch.
+- `lanes docs push <id>` prints one document's receipt and exits 2, `not configured`: the hook for pushing documents
+  to the data service's publication surface, which is not built yet.
+- The unit, `docs.log`, the routes, the limits and the operator's live checklist:
+  [RUNBOOK](RUNBOOK.md#docs-service-lanes-docsd-w10-w3).
+
+Not yet verified on a device: the Docs page on a real phone (the rendering, a Mermaid diagram, the drop area), the
+artifact sandbox in a real browser (DEF-1853), and the Mermaid route through a running Caddy (DEF-1871).
+
 ### What works, what does not, what is unverified
 
 - Works: everything the desktop view shows, through the same Zellij sessions; the phone has its own view selection of
-  the same agents; the server keeps serving when your Mac sleeps.
-- Does not: a public URL (Tailscale only), uploads from a phone browser (the drop helper is a desktop client feature),
-  approving an agent's permission prompt from a push notification.
+  the same agents; the server keeps serving when your Mac sleeps; uploads from the phone and what agents publish, on
+  the Docs page (**More → Docs**, [Docs](#docs)).
+- Does not: a public URL (Tailscale only), approving an agent's permission prompt from a push notification.
 - Not yet verified on a device: the quick keys, the lane filter, the text keyboard, paste, **Copy** and **Paste** on a
   real iPhone (the [runbook](RUNBOOK.md) lists the check), the light/dark terminal repaint, the counts that the
   picker's pane title carries to the Workspaces sheet and the **Lanes** button (a phone view created before that
@@ -1274,7 +1396,10 @@ The frontend chooses once per page load, by capability:
 ## 5. Uploads
 
 Files land in the workspace's `uploads/` folder in its container, the same folder Cursor users drop files into. The
-in-container path ends up on your clipboard and in a notification, and can be typed into the lane for the agent.
+in-container path ends up on your clipboard and in a notification, and can be typed into the lane for the agent. Every
+upload, whichever way it came, also gets a **receipt**: its sha256 computed on the server as the bytes arrived, kept
+with a copy in the docs store, so it shows on the Docs page (`/lanes-docs/`, section 4, [Docs](#docs)) and in the
+sidebar's ` ▤ docs N` count.
 
 | Way | How |
 | --- | --- |
@@ -1283,12 +1408,41 @@ in-container path ends up on your clipboard and in a notification, and can be ty
 | Command | `lanes-upload [-w <workspace>] [--paste] <files…>` · `lanes-upload --clipboard [-w <workspace>] [--paste]` (clipboard image or copied files) |
 | macOS droplet | `~/Applications/Lanes Upload.app`: drop files on it; double-click uploads the clipboard screenshot |
 | Omarchy | `Super+Shift+U` uploads the clipboard and types the path into the lane |
+| Docs page (phone, laptop) | **More → Docs** on the phone, **Docs** in the laptop bar, or `https://<server>:8443/lanes-docs/`: pick the lane, then drop files on the dashed area or tap it to choose them (several at once, 32 MiB in all), **Upload**. Each file's receipt is listed: its name (a link to the document), size, sha256 and where it landed in the container (`/home/coder/<repo>/uploads/<name>`) — tell the agent that path |
 | Server | `lanes upload <workspace> \| --active <device> [--paste]` reads a tar stream on stdin |
 
 **Where files land.** `<workspace folder>/uploads/<name>` in the container, where the workspace folder is its first
 lane's repository folder (else the workspace's working directory). An existing name is never overwritten: the next
-one becomes `<name>-1.<ext>`. The folder is created on first use and, in a git repository that does not ignore it
-yet, added to the repository-local `.git/info/exclude`, so uploads are never committed.
+one becomes `<name>-1.<ext>`. The folder is created on first use and, in a git repository whose `.git/info/exclude`
+does not name it yet, added there, so uploads are never committed. The Docs page lands a file exactly the same way
+(its name keeps only letters, digits, `.`, `_` and `-`). The server refuses to follow a symbolic link anywhere on the
+way, so an agent cannot redirect an upload outside its container: a folder reached through a link answers
+`uploads/ … not a directory (a symbolic link is refused)` (or, on the Docs page, *cannot be written now*).
+
+**Receipts.** Each file is also a document in the docs store with a receipt — `sha256`, size, time and its page
+`/lanes-docs/d/<id>` — for you only (`for` your login): the Docs page lists it under its workspace and lane, and the
+sidebar counts it. `lanes upload` prints one `# docs: <name> <size> B sha256 <hash> <id>` line per file on stderr (the
+helper's log, or your terminal with `lanes-upload`). The kind follows the extension: `.md` opens rendered (with Mermaid
+diagrams), `.html`/`.svg` open as sandboxed artifacts, anything else as a download. The store keeps its own copy, so
+an agent editing its `uploads/` file never changes what the receipt names. What gets no receipt, though it still
+lands: a file over 32 MiB sent with `lanes upload` (the store keeps at most 32 MiB a file), a device no member record
+owns (the server logs its hash in `docs.log`), and files past the 64th of one `lanes upload`. A file name taken in only
+one of the two places (an agent's own file in `uploads/`, or an earlier upload you removed from the store) can get
+`-1` in one and not the other; the receipt names both.
+
+**Encrypted at rest (optional).** The operator can have the server keep its docs-store copies encrypted with
+[`age`](https://age-encryption.org) (`LANES_DOCS_AGE_RECIPIENT`, [RUNBOOK](RUNBOOK.md#docs-service-lanes-docsd-w10-w3)).
+Nothing changes in `uploads/` — the agent reads plain files there — and receipts stay the hash of what you sent. When
+the docs service also holds the key, documents open as usual; when it does not, a download answers *encrypted at
+rest* and you fetch the file from the workspace's `uploads/` folder instead.
+
+**Opening the Docs page from elsewhere.** Any link to a document opens it: the shell's **Docs** link, the sidebar's
+links, a notification, the address bar, and a link on another website — a web mail, a chat in the browser, ntfy's web
+app. What the docs service refuses from another website is everything that is not you following a link: a page's own
+background requests, images and scripts, and an upload — so an HTML artifact cannot read anything of yours, and only
+the Docs page itself uploads. A browser too old to say where a request came from sees *Refused: this request came from
+another site*. Viewing very quickly (over 300 pages a minute) answers *Too many requests* for a
+minute; an upload that trickles in slower than about 64 KiB/s is stopped and says so, with nothing stored.
 
 **Why click first.** A terminal delivers a drop as a paste of the local path into the focused pane, so the strip must
 hold the focus when you let go. The server receives only the path; the **upload helper** on your machine sends the
@@ -1502,7 +1656,10 @@ Names must be non-empty and free of control characters. The id, resolve file and
   each container running, the statusd heartbeat, all registry lanes observed and present (stale lanes counted as
   "shown with their last known state"), the process table, no host-side tmux servers, coexistence mode, Zellij
   reachable, phone picker panes current, and the host not under critical memory pressure.
-- Information: lanes per create-recipe class (`idempotent`, `attach-only`, `null`, `external`, `retired-path`), how many
+- Information: the harness mix (1.5.0, [Harnesses](#harnesses)): `lanes: claude 50 · codex 20 · kimi 3 · grok 0 ·
+  grok-cli 0 · shell 0`, from each lane's `agent.harness` (`unknown` only when a lane has it; a lane with no agent is
+  not counted; `shell` stays 0 in practice: a lane whose harness ended into its shell is published under that
+  harness's name with the status `shell`); lanes per create-recipe class (`idempotent`, `attach-only`, `null`, `external`, `retired-path`), how many
   create with their identity, where the `lane` contract is installed, zmx-held lanes, the preview renderer, the live
   view sessions, and the pressure summary.
 - Warnings (`⚠`, never a `✗`): lanes that `lane open` cannot recreate (fix: `lanes cursor-sync --canonicalize`),
@@ -1516,10 +1673,23 @@ Names must be non-empty and free of control characters. The id, resolve file and
   present (`✓`), missing or pointing elsewhere (`✗` once a web unit is enabled, `⚠` before), or not checked (`⚠`: no
   tailscale, no answer, or no Tailscale name on the host — then `lanes web` configures no Serve and prints a loopback
   URL, so doctor does not ask for the mapping either).
+- The docs service (W10): `lanes-docsd` enabled, active and answering on its loopback port (`✓`; `⚠` not enabled; `✗`
+  enabled but not running, or not answering), the pin gate (`✓ docs: pinned`, else `⚠ docs: refuses until the Serve
+  header check is pinned`), the store (documents, bytes, `docs.log`'s size), the pinned Mermaid (`✓`, `⚠` not installed
+  — `install/enable-docs.sh`, which every server install and update runs —, `✗` a file that is not the pinned build) and
+  the `age` switch (`✗` when it is set without an `age` binary); RUNBOOK "Docs service" has every line.
+- The fleet (W11, [Fleet](#fleet)): `throttle pulse: 4 s old (container bw-tools), daemon up, tokened: no — lanes
+  throttle adopt-token bw-tools` (`✓`; `⚠` when the daemon does not answer, when the pulse is more than 90 s old — it
+  stopped — or when status.json has none yet, with `lanes install-container <container>`, which starts it), `throttle
+  pools: claude 12/19 · codex 3/5 · kimi 0/0 usable` (1.5.0: the three pools the pulse reports; `?` for one it did not,
+  `⚠` when a configured pool has no usable account), `fleet: cpu
+  42% · mem 61% · psi 3% · containers 7` (psi is the highest PSI avg10; `⚠` when stale or missing — a statusd from
+  before 1.4.0), and `fleet dashboard: LANES_FLEET_DASHBOARD_URL unset`, or the URL, or `⚠ … ignored — not an https
+  URL`. None of them is ever a `✗`: Lanes runs without Throttle.
 - The release that runs, against `~/.local/share/lanes/current` (the tree an install makes current; without the link,
   a `⚠` and this `lanes`'s own tree): the link names a tree that exists, whose `VERSION` agrees with its
   `pkg/<version>` name and its npm stamp, and that this `lanes` runs (`✗` with the fix: run the current one, or re-run
-  the server installer). Every lanes process running now (statusd, enrold, notify, economy, a sidebar — found in the
+  the server installer). Every lanes process running now (statusd, enrold, docsd, notify, economy, a sidebar — found in the
   same process-table sweep by the command Lanes starts it with, `python3 -S -E <tree>/libexec/<script>`, so a file
   open in an editor or a one-shot such as `notify.py --test` is not one) has a [run record](#versions) of the current
   code (`✗ … statusd runs 1.1.0`, or `statusd runs without a run record (started by an older release)`, then
@@ -1553,11 +1723,15 @@ anything, picks the first signal that applies:
    turn keep it, unless the report was `working`.
 2. A **Claude Code session file** `~/.claude/sessions/<pid>.json` naming the pane, for a live pid (recycled pids are
    rejected).
-3. The **Codex pane title**: `[ ! ] Action Required` is needs approval, a braille spinner is working, a task title is
-   idle.
-4. The **window bell**: an idle title plus a bell is done.
+3. **Kimi Code's session files**, then **Grok Build's** (which session the pane's `grok` runs, its event log, else its
+   pane title), for a pane whose process is that harness ([Harnesses](#harnesses)).
+4. The **Codex pane title**, only where Codex can run: `[ ! ] Action Required` is needs approval, a braille spinner is
+   working, a task title is idle.
+5. The **harness process itself**: nothing above claimed the pane, so it is the harness the pane runs, idle.
+6. The **window bell**, throughout: an idle lane or a finished turn plus a bell is done.
 
-A Codex title left on a bare shell with no child process is `shell` (the harness ended).
+A Codex title left on a bare shell with no child process, or a Grok Build title over a pane that runs only shells, is
+`shell` (the harness ended). Since 1.5.0 the harness itself is observed, not guessed: see [Harnesses](#harnesses).
 
 What the sidebar shows is not that word itself but a debounced one. The sections rank Needs you > Working > Done > the
 workspace's other lanes: a status that moves the lane up is shown at once, one that moves it down only after it has
@@ -1570,6 +1744,107 @@ starts signals Working (`PreToolUse`); that hook fires before the permission dia
 A Codex approval read from its pane title (a lane without hooks) keeps the same 8 s dwell once approved. The full rules:
 [Attention queue](ARCHITECTURE.md#attention-queue).
 
+### Harnesses
+
+Lanes 1.5.0 (W12, [spec](../../docs/superpowers/specs/2026-10-15-lanes-harness-observers-design.md)) reads five agent
+harnesses: Claude Code, Codex, Kimi Code, Grok Build (xAI's official `grok`) and grok-cli (the community `grok`).
+Which one runs in a lane is an **observed fact**: statusd walks the pane's process tree (plain `/proc` reads, no new
+process) and publishes `agent.harness` as `claude`, `codex`, `kimi` (Kimi Code), `grok` (Grok Build), `grok-cli` or
+`unknown`; a pane that runs only shells is `shell` to the walk and shows no agent of its own (or the harness that ended
+there, with the status shell). A pane title that looks like Codex's is read as Codex only where Codex runs: before 1.5.0 any
+title of two or more words read as an idle Codex, so a Kimi lane showed `codex / idle`. `lanes doctor` prints the mix:
+`lanes: claude 50 · codex 20 · kimi 3 · grok 0 · grok-cli 0 · shell 0`. Each harness gets the lane-signal hooks, the
+Lanes MCP server and the Throttle trace its own files allow:
+
+| Harness | What Lanes reads with no hooks (observed) | Hooks (`lanes hooks install --agent …`, a dry run until `--write`) | MCP server |
+| --- | --- | --- | --- |
+| Claude Code | `~/.claude/sessions/<pid>.json`, the window bell | `--agent claude`: `~/.claude/settings.json` ("Hooks" below) | `~/.claude.json` ("Agent tools (MCP)" below) |
+| Codex | the pane title, the window bell | `--agent codex`: `~/.codex/hooks.json` and `notify` | `~/.codex/config.toml` |
+| Kimi Code 2.1.1 | its session files: `~/.kimi-code/sessions/wd_*/session_<uuid>/state.json` and the last 64 KiB of `agents/main/wire.jsonl` | `--agent kimi`: a `# >>> lanes hooks >>>` block of `[[hooks]]` in `~/.kimi-code/config.toml` | `~/.kimi-code/mcp.json` |
+| Grok Build 1.0.52 | `$GROK_HOME/active_sessions.json` (which pid runs which session), the session's `events.jsonl` and `summary.json` (its title), the pane title | `--agent grok`: `~/.grok-build/hooks/lanes.json` plus blocks in `~/.grok-build/config.toml` | a `# >>> lanes mcp >>>` block in `~/.grok-build/config.toml` |
+| grok-cli 1.1.7 | nothing: it sets no title and rings no bell | `--agent grok-cli`: `hooks` in `~/.grok/user-settings.json` | the `mcp.servers` item `lanes` in `~/.grok/user-settings.json` |
+
+Per container, on the server (each a dry run that prints its diff until `--write`):
+
+```sh
+lanes hooks install --agent kimi --container <name> --write       # Kimi Code: ~/.kimi-code/config.toml
+lanes hooks install --agent grok --container <name> --write       # Grok Build: ~/.grok-build/hooks/lanes.json, config.toml
+lanes hooks install --agent grok-cli --container <name> --write   # grok-cli: ~/.grok/user-settings.json
+```
+
+What the hooks of the three newer harnesses give the boards (Claude Code's and Codex's: "Hooks" below):
+
+| 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` | errored |
+| Kimi Code | `SessionStart` / `SessionEnd` | 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` | errored |
+| Grok Build | `SessionStart` / `SessionEnd` | idle / shell |
+| grok-cli | `UserPromptSubmit`, `PreToolUse`, `PostToolUse` | working |
+| grok-cli | `Stop` / `StopFailure` / `SessionEnd` | needs_input / errored / shell |
+
+**Kimi Code** comes from its own installer (`~/.kimi-code`). Without hooks, a Kimi session is joined to its lane by
+working folder: the lane's Kimi process whose folder is the session's `cwd`, newest `updatedAt` first. Two Kimi lanes
+in one folder are ambiguous, and then the lane falls back to hooks and the title. From `wire.jsonl`: a turn that
+starts, a prompt or a tool call is working; an approval request not yet resolved is needs approval; a finished turn is
+needs input (done when the window rang); a failed turn is errored. A session file more than an hour old says nothing.
+The hooks make it event-driven. Lanes writes only its own marked block into `~/.kimi-code/config.toml` and never
+rewrites the rest of the file; it never touches Kimi's device identity files. Kimi rings the terminal bell only when
+told to: `lanes onboard`'s optional `--step kimi-notify` sets `notification_condition = "always"` in
+`~/.kimi-code/tui.toml`, so Kimi Code rings the bell focused or not (the operator decides, per container). Kimi's own
+default file already has the `[notifications]` table: that one line is edited and its old value kept in a comment.
+
+**Grok Build lives in `GROK_HOME=~/.grok-build`, never `~/.grok`.** Its own installer would replace grok-cli's
+`~/.grok/bin/grok` with a link to itself, so every lane recipe sets `GROK_HOME=/home/coder/.grok-build`, and
+`lanes onboard <login> --container <name> --step grok-build --write` installs it there from the stable channel
+(`https://x.ai/cli/stable`, the binary and its `bin/grok` link, `[cli] installer = "internal"`). That channel publishes
+no checksum, so the receipt records the download's size and sha256 as unverified for you to check. grok-cli keeps
+`~/.grok`.
+
+**Grok Build without hooks.** From `events.jsonl`: a permission prompt is needs approval; waiting for the model,
+streaming or running a tool is working; a completed turn is needs input (done when the window rang), an error
+errored, a cancelled or interrupted turn needs input. The title says the same: `⚠ Action Required …` is needs approval
+(it blinks while the pane is not focused, so a busy title right after it still reads needs approval), a braille spinner
+is working, `grok` or `<name> - grok` is idle; a Grok title left over a pane that runs only shells is shell. Grok
+Build's leader mode (`use_leader = true`) is not read: such a lane shows no agent state until its hooks speak.
+
+**Grok Build's hooks install** writes the hooks file (the events above; it runs Claude Code's hooks by default, which
+would report `claude`) and two options in `~/.grok-build/config.toml`: `[compat.claude] hooks = false, mcps = false`,
+so Claude Code's hooks and its `lane-mcp` entry do not also run inside Grok, and `[ui.notifications] condition =
+"always", method = "bel"`, so every turn end, approval and error rings the pane's bell. If the file already has a
+`[compat.claude]` or `[ui.notifications]` table of yours, the install changes nothing and asks you to set those keys
+there.
+
+**grok-cli** comes from its own installer (`~/.grok`) and has hooks only, with exact-string matchers. It has no
+approval signal and no title or bell: its lane shows working, needs input, errored or shell, never needs approval.
+
+**Agent tools (MCP).** `~/.lz/bin/lane mcp install` (which `lanes install-container` runs, or `lane mcp install
+--agent kimi|grok|grok-cli`) writes the Lanes server into each harness's file in the table above: Kimi Code's
+`~/.kimi-code/mcp.json` (the Claude `mcpServers` shape), Grok Build's `[mcp_servers.lanes]` as a marked block (its
+`[compat.claude] mcps = false` keeps `lane-mcp` from starting twice; Grok Build passes its session id to the server),
+and grok-cli's `mcp.servers`. grok-cli starts MCP servers with a stripped environment, so `lanes_whoami` reads the
+lane's identity from the environment of the grok-cli process that started it.
+
+**The Throttle trace.** Kimi Code blanks `ANTHROPIC_CUSTOM_HEADERS`, so every recipe that sets it also sets
+`KIMI_CODE_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>'`. Grok Build's global extra headers would trace every
+lane alike, so recipes export `LANES_TRACE` and its hooks install writes `env_http_headers = {"x-throttle-trace" =
+"LANES_TRACE"}` for its built-in models `grok-4.6` and `grok-4.5`. grok-cli sends no custom headers: its requests carry
+no trace. A trace only matters for a harness attached to a Throttle pool: Kimi Code when `throttle setup
+--install-clients` attached it, Grok not at all (Throttle has no xAI pool).
+
+**Files Lanes changes.** Each is kept as `<file>.bak-<UTC>` first. In a TOML file Lanes changes only its marked block,
+so to undo, delete the block. The diff a dry run prints shows a credential's value (grok-cli's `apiKey`) as `…`.
+`lane-signal` without `--harness` takes the harness from `LANE_HARNESS`, else from the agent process above it, else
+records `unknown`.
+
+Operator steps per container: [RUNBOOK "Harnesses"](RUNBOOK.md#harnesses).
+
 ### A user's agents in one step: `lanes onboard`
 
 On the server, one command gives a new user's workspace container what its agents need. Without `--write` it prints
@@ -1585,13 +1860,14 @@ lanes onboard anna --container ws-anna --workspace anna-tools --repo /home/coder
 | Board | A workspace tab for the repository (`lanes workspaces add`, section 6) on every device's view |
 | Contract | `lane`, `lane-run`, `lane-signal`, `lane-edit`, the quick-edit `vimrc`, `lane-mcp` and the hook definitions in the container's `~/.lz` (`lanes install-container`) |
 | Agent tools | The Lanes MCP server in Claude Code's and Codex's configuration, so an agent can see the lanes around it ("Agent tools (MCP)" below) |
-| Hooks | The lane-signal hooks for Claude Code and Codex ("Hooks" below), so the sidebar's agent glyphs are event-driven |
+| Hooks | The lane-signal hooks for Claude Code and Codex ("Hooks" below), and for Kimi Code, Grok Build and grok-cli where they are installed ([Harnesses](#harnesses)), so the sidebar's agent glyphs are event-driven |
 | Throttle | `throttle setup --install-clients` inside the container when Throttle is installed and configured there, so the agents' requests go through the pool; otherwise the one-time setup to run on a terminal is printed (a first setup signs in, which needs a person; Lanes runs without Throttle) |
 | Recipes | `lanes cursor-sync <id> --canonicalize --write` when the repository has a `.vscode/terminals.json`: each lane's create recipe gives it its identity and trace ("Lane identity" below) |
 | Sync and doctor | The registry knows the new lanes; `lanes doctor`'s result is reported, never fatal |
 
 The receipt is `~/.local/state/lanes/onboard/<login>-<UTC>.json`, and running the command again changes nothing that
-is already done. `--no-mcp` leaves out `lane-mcp` and its entries in the agents' configuration. Every step
+is already done. `--no-mcp` leaves out `lane-mcp` and its entries in the agents' configuration. Two steps run only
+when named: `--step kimi-notify` and `--step grok-build` ([Harnesses](#harnesses)). Every step
 and status: [install guide](INSTALL.md#onboard-a-users-container).
 
 **Laptop agents on the pool (operator-gated).** Agents a user runs on their own laptop, outside any lane, can use the
@@ -1612,10 +1888,11 @@ lanes hooks install --agent claude --container <name> --write    # applies it (b
 lanes hooks install --agent codex --container <name> --write     # ~/.codex/hooks.json (+ notify in config.toml)
 ```
 
-`lanes hooks install --agent claude|codex (--container <name> | --home <dir>) [--dry-run | --write]`: a dry run
-unless `--write`; your own hooks and keys stay, and an earlier lane-signal install is replaced, not duplicated. An
-install that is already current is left where it is, even when another tool (Throttle's `setup --install-clients`)
-has put its own group before or after it or re-sorted the file's keys, so running it again writes nothing. For
+`lanes hooks install --agent claude|codex|kimi|grok|grok-cli (--container <name> | --home <dir>) [--dry-run | --write]`
+is a dry run unless `--write` (Kimi Code, Grok Build and grok-cli: [Harnesses](#harnesses)); your own hooks and
+keys stay, and an earlier lane-signal install is replaced, not duplicated. An install that is already current is
+left where it is, even when another tool (Throttle's `setup --install-clients`) has put its own group before or
+after it or re-sorted the file's keys, so running it again writes nothing. For
 Codex it also adds a top-level `notify` to `~/.codex/config.toml` only when none exists. Codex asks you to review and
 trust new hooks; Lanes never writes that trust. Expect hooks to reach agent sessions started after the install
 (inferred from how both harnesses read their configuration, not measured). Undo:
@@ -1654,7 +1931,8 @@ verbs, so the holder stays swappable.
 | `lane kill <id> --yes [--force]` | End the lane (the only verb that ends an agent); refuses while the hook sidecar says `working` unless `--force` |
 | `lane new <id> [--ws W] [--title T] [--cwd DIR] [--icon I] [--color C] -- <command…>` | Create a zmx-held lane |
 | `lane gc --sockets` | Unlink this container's tmux socket files that tmux is refused on (no server listens); a live, empty or silent server keeps its file |
-| `lane mcp install [--agent claude\|codex\|all] [--write]` | Add the Lanes MCP server to `~/.claude.json` and `~/.codex/config.toml` ("Agent tools (MCP)" below); a dry run until `--write` |
+| `lane mcp install [--agent claude\|codex\|kimi\|grok\|grok-cli\|all] [--write]` | Add the Lanes MCP server to `~/.claude.json` and `~/.codex/config.toml`, and to Kimi Code's, Grok Build's and grok-cli's files where they are installed ("Agent tools (MCP)" below); a dry run until `--write` |
+| `lane publish <file> [--title T] [--for <login>] [--kind md\|html\|svg\|file]` | Put a file of this container on the docs page from the lane it runs in ("Publish to the docs page" below); prints the request as JSON |
 
 Every tmux client these verbs start runs with `-N`, so none of them can start a tmux server: an attach to a lane
 whose server has just ended fails instead of leaving an empty server and its socket file behind.
@@ -1675,6 +1953,18 @@ file is written in place (it keeps its mode and owner), swap and backup files go
 beside the file, modelines are off, a file without a final newline keeps none, and no `~/.viminfo` is written.
 Everything it creates is private (`umask 077`). Quitting the editor closes the pane.
 
+### Publish to the docs page
+
+An agent (or you, in a lane's shell) puts a file on the [Docs page](#docs) with `~/.lz/bin/lane publish <file>` or
+the MCP tool `lanes_publish`: Markdown with Mermaid diagrams is rendered there, an HTML or SVG artifact opens
+sandboxed on its own page, and any other file is a download, each with the sha256 the server computed. The verb writes
+a small request in `~/.lz/state/publish/<lane>/` and copies nothing; within about 5 s the docs service on the server
+reads the file from the container, checks its hash against the request's (a file changed in between is refused, not
+stored) and writes `<id>.receipt.json` beside the request — `lanes_status` shows it as `published`, with the
+document's link. The file must be under `/home/coder` and at most 32 MiB. Who sees it (`--for`, else the person who
+last opened the lane, else everyone whose member record grants its workspace), the receipt's fields and how each kind
+opens: section 4, [Docs](#docs).
+
 ### Agent tools (MCP)
 
 `lane-mcp` is an MCP server in each container (`~/.lz/bin/lane-mcp`). Claude Code and Codex start it from their own
@@ -1684,14 +1974,14 @@ only read:
 | Tool | Answers |
 | --- | --- |
 | `lanes_whoami` | Which lane the agent runs in: id, board, name, kind (declared, registered or unregistered), tmux socket and session. It comes from `LANE_ID`, else from the agent's own tmux pane. Outside a lane the answer is `lane: null` with the reason |
-| `lanes_list` | Every lane in this container with its state and its agent (harness, status, task). Filters: `workspace`, `needs_you: true` (needs approval, errored or needs input, the sidebar's "Needs you" section) and `agent` (`any`, `none`, `claude`, `codex`). `status.fresh` is false once the host's observation is more than 60 s old |
+| `lanes_list` | Every lane in this container with its state and its agent (harness, status, task). Filters: `workspace`, `needs_you: true` (needs approval, errored or needs input, the sidebar's "Needs you" section) and `agent` (`any`, `none`, `claude`, `codex`, `kimi`, `grok` for Grok Build, `grok-cli`). `status.fresh` is false once the host's observation is more than 60 s old |
 | `lanes_status` | One lane in full: what the registry says, the observed state and agent, whether its tmux session is alive now (`null` when tmux does not answer in 5 s) and its hook sidecar |
 | `lanes_capture` | The last `lines` (1 to 500, default 100) non-blank lines of a lane's screen and scrollback, as plain text. Any lane of the container can be read |
 
 Where the answers come from: `~/.lz/registry.json`, which `lanes sync` writes, and `~/.lz/status.json`, which the
 status daemon writes. A container that has neither yet answers with empty lists and says why.
 
-Six tools write. Each reaches the lanes of its own container only, and answers what it changed, what picks the
+Seven tools write. Each reaches the lanes of its own container only, and answers what it changed, what picks the
 change up (`picked_up_by`) and how soon (`expected_within_s`):
 
 | Tool | Changes | Seen on the boards |
@@ -1701,6 +1991,7 @@ change up (`picked_up_by`) and how soon (`expected_within_s`):
 | `lanes_rename` | Sets the lane's `displayName` in its terminals.json; the id never changes. The lane's own title removes it. A name the host sets for the lane in its workspace manifest still wins, and the answer says so (`host_override`) | same |
 | `lanes_new` | `name`, optional `cwd`, `command`, `workspace`, `repo`. Declares a lane on the board's shell socket `lanes-shells-<workspace>` and starts its session (detached, 100x30) with the lane's identity; the workspace defaults to the agent's own board, the folder to the repository's, the command to `bash -l`. When that starts the board's shell server, the server gets the account and locale variables (and `TMUX_TMPDIR`), never the agent's own environment, which every later shell on the board would inherit | the session at once; the lane after the next `lanes sync` |
 | `lanes_send` | `lane`, `text`, optional `enter` (default true), `force`. Types printable text into the lane, then Enter half a second later as a separate keystroke, so an agent's prompt submits it instead of taking it as a paste | at once |
+| `lanes_publish` | `path` (an absolute path under `/home/coder`), optional `title`, `for` (a login), `kind` (`md`, `html`, `svg`, `file`; default from the extension). Writes a publish request for the file from the agent's own lane ("Publish to the docs page" below); the docs service reads the file itself and answers with a receipt that `lanes_status` shows as `published` | on the docs page within about 5 s |
 | `lanes_signal` | `status` (the agent words: `working`, `needs_input`, `needs_approval`, `done`, `errored`, `shell`, `idle`), optional `note`. Reports the agent's own status through `lane-signal`; the note (one line, at most 120 characters) is shown as the lane's task line. The report stands until the agent does something new: its next tool call, a new prompt, a permission prompt, a failed turn or the session's end. The end of its turn keeps it (a `working` report ends there), so an agent reports `needs_input`, `done` or `errored` as the last thing before it stops. A `working` note stays while the agent keeps working | on the next status cycle, within about 5 s |
 
 What they refuse. A refusal is `isError` with `{"refused": <code>, "why", "human"}`: `human` says what a person can
@@ -1715,7 +2006,10 @@ refuses an unregistered session (register it first) and a name with a control ch
 folder outside `/home/coder` or one that does not exist (`invalid_cwd`), a name or session in use and a command with
 a control character. `lanes_send` types nothing while the lane's agent is working or waiting for an approval
 (`agent_working`, `agent_needs_approval`) unless `force` is true, and never a control character: no newline, tab,
-escape or Ctrl-C (`invalid_text`). Every tool refuses a lane of another container (`not_in_container`). The edits go
+escape or Ctrl-C (`invalid_text`). `lanes_publish` refuses a file outside `/home/coder` once every link is resolved
+(`outside_home`), anything but a regular file (`not_a_file`), a file over 32 MiB (`too_large`), a title or login that
+is not one printable line (`invalid_title`, `invalid_for`), and an agent outside a lane (`not_in_lane`). Every tool
+refuses a lane of another container (`not_in_container`). The edits go
 through the same minimal editor as everything else here: one span of strict JSON, the file re-read just before the
 atomic write, never the root `throttle` object, never a rename or reorder of terminals. The file is the
 repository's, so its history is git's: no backup file is written.
@@ -1762,13 +2056,17 @@ are in the [runbook](RUNBOOK.md#install-check-uninstall). What to tell your agen
 ### Lane identity and the canonical recipe
 
 A lane's identity is its environment: `LANE_ID` (`<ws>--<slug>`), `LANE_WS` (`<ws>`), and the Throttle trace
-`lanes/<ws>/<id>` as `THROTTLE_TRACE` and as `ANTHROPIC_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>'`. A tmux
+`lanes/<ws>/<id>` as `THROTTLE_TRACE`, as `LANES_TRACE` (Grok Build's `env_http_headers` read it), and as
+`ANTHROPIC_CUSTOM_HEADERS` and `KIMI_CODE_CUSTOM_HEADERS` (`'x-throttle-trace: lanes/<ws>/<id>'`; Kimi Code ignores the
+Anthropic one). The recipe also sets `GROK_HOME=/home/coder/.grok-build` ("Harnesses" above). A tmux
 lane gets it only from the `-e` flags of its create recipe; `lane open` deliberately exports none (the client that
 starts a shared tmux server would hand its environment to every later session there). The canonical recipe is:
 
 ```sh
 tmux -L <socket> new -ADs <session> -c <folder> -e LANE_ID=<id> -e LANE_WS=<ws> \
-  -e ANTHROPIC_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>' -e THROTTLE_TRACE=lanes/<ws>/<id> bash -l
+  -e ANTHROPIC_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>' -e THROTTLE_TRACE=lanes/<ws>/<id> \
+  -e KIMI_CODE_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>' -e LANES_TRACE=lanes/<ws>/<id> \
+  -e GROK_HOME=/home/coder/.grok-build bash -l
 ```
 
 `-A` attaches when the session exists, so the identity lands only on a real create. A running lane gains it when it is
@@ -1782,6 +2080,69 @@ zmx lane's agent state yet (DEF-1573). Gate results: [ZMX-RING0.md](ZMX-RING0.md
 
 ## 8. Economy and notifications
 
+### Fleet
+
+The sidebar's free rows hold a pinned health block (Lanes 1.4.0, W11): on panes of 18 rows or more, once the server's
+statusd publishes the fleet facts, it sits above the upload strip and the lane list scrolls in the rows left. It is
+live (statusd rewrites it at most every 10 s), local, and needs no collector. At 25 rows or more it is a rule and six
+rows (1.5.0 added the Kimi pool's row; 1.4.0 drew five from 24 rows):
+
+```
+ ── fleet ──────────────────────────
+ ⚙ throttle  $8.5k/16k 53% · 429 +4 · spill 76%
+ ◆ anthropic ▰▰▰▰▰▰▱▱▱▱ 12/19 · wk 61% · reset 2h
+ ◆ openai    ▰▰▰▱▱▱▱▱▱▱ 3/5 · 5h 28%
+ ◆ moonshot  ▰▰▰▰▰▰▱▪▪· 5/8 · wk 44% · 5h 12%
+ ▣ productbox cpu 42% · mem 61% · load 37 · psi 3%
+ ▣ bw-tools 15G · worlds 9G · sakio 4G
+```
+
+| Row | What it shows |
+| --- | --- |
+| `⚙ throttle` | One line for the Throttle pool: with the opt-in token, overflow spend today against the daily cap, new 429s and the spill fraction — one pool's figure, never a sum: the Anthropic and OpenAI overflow budgets are separate money, so the row shows the pool nearest its cap, one at its alert level first (Kimi has no paid overflow, so its pool never gives the money); without the token ` ⚙ throttle  up · spill 76% · 429 +4`, and ` down` in red when the daemon does not answer |
+| `◆ anthropic`, `◆ openai`, `◆ moonshot` | One availability bar per provider pool — Claude, Codex and (1.5.0) Kimi Code's, whose vendor is Moonshot AI: ten cells of usable `▰`, cooling `▱`, benched `▪` and dead `·` accounts (ASCII `=` `~` `:` `.`), then the usable count of the configured ones (` ◆ anthropic ▰▰▰▰▰▰▱▪·· 12/19`), then — with the token — the worst weekly or 5-hour burn and the soonest reset. A daemon with no Kimi account shows ` ◆ moonshot  ·········· 0/0`, which is no alarm; `no data` means the pulse did not report the pool (a pulse from before 1.5.0 still running: [RUNBOOK](RUNBOOK.md#harnesses)). There is no Grok row: Throttle has no xAI pool |
+| `▣ productbox` | The host: CPU and memory utilization, the 1-minute load, the highest pressure (PSI) figure |
+| `▣ <container> …` | The three workspace containers using the most memory |
+
+At 18–24 rows the block is three rows — Throttle, the provider with the smallest usable share (a pool with nothing
+configured is never that one), the host — and smaller panes show none. Parts that do not fit are dropped from the end. A row turns amber when overflow spend reaches its alert
+level, a provider has no usable account, memory is fully stalled, memory use reaches 90 % or the CPU 95 % (its lead
+mark turns amber even when that part was dropped); red when the daemon does not answer. The whole block is dim, with a
+`?` after `throttle`, when its figures are frozen because statusd or the Throttle pulse stopped: the host's more than a
+minute old, the pulse's more than 90 s (it rewrites every 60 s and is read up to about 84 s later).
+
+**`i`** folds the block to one line, ` fleet ✓ · throttle 53% · cpu 42% · mem 61%` (`⚠` something amber, `✗` Throttle
+down), and unfolds it again; the choice is kept in your profile (`look.fleet_collapsed`), so every device you own
+follows it. The `?` key sheet takes the block's rows while it shows. On the phone the same block is drawn above the
+footer.
+
+The strip row keeps its economy line and gives way only when the block already shows the same facts: while the
+unfolded block's Throttle row shows the overflow money and every part after it, the strip row leaves the economy line
+to it. At the default 36 columns that row drops `spill` to fit, so the strip keeps the line; a wider pane shows the
+whole row.
+
+Where the figures come from: the host's own `/proc` (statusd, skipped while the host is under critical pressure) and a
+small pulse that runs inside the container where the Throttle daemon runs — the daemon listens only on that container's
+loopback, so the host cannot ask it itself. `lanes install-container` starts that pulse in the daemon's container (the
+one `LANES_THROTTLE_CONTAINER` in the server's `~/.config/lanes/site.conf` names, else the container of the Throttle
+tab) and every server update ships it again. The pulse only reads (GET), never changes the daemon, and writes one small
+file.
+
+**Money and burn are opt-in.** Without a token the pulse reads only the daemon's open routes (readiness and metrics):
+no spend, no burn figures. The operator turns them on once, per daemon container: `lanes throttle adopt-token
+<container>` copies the container's own local Throttle client token (the local proxy bearer in its
+`~/.claude/settings.json`, never an Anthropic credential) into the pulse's token file (`~/.lz/throttle-token`, mode
+0600). Nothing does it automatically.
+
+**The dashboard link is off until it is safe.** History (days, weeks) belongs to the fleet-management Grafana, not to
+the cockpit. When the server's `~/.config/lanes/site.conf` names `LANES_FLEET_DASHBOARD_URL=https://…`, the
+`▣ productbox` row becomes a link to it and the phone's menu gains a **Fleet** row. It stays unset until an
+authenticated Grafana deployment exists; only an `https://host[:port][/path]` URL is accepted, and no Lanes command
+ever writes it. `lanes doctor` says which it is.
+
+The host the block names is the Lanes server itself: the Hetzner machine `productbox` (tailnet address 100.91.241.52,
+the address the bundled `beyondwork` site profile connects to), not `devbox3`.
+
 ### Economy projection (opt-in, operator gate)
 
 `lanes-economy.service` polls the Throttle daemon's control port (`GET /status` and `/sessions`, default
@@ -1797,7 +2158,7 @@ systemctl --user enable --now lanes-economy.service
 
 `lanes economy --once [--dry-run] [--status-file F --sessions-file F]` runs one poll; stderr names each source it
 could not read. Settings: `LANES_THROTTLE_CONTROL` (base URL, or `none` for no request), `LANES_THROTTLE_TOKEN_FILE`
-(a bearer in a file), `LANES_THROTTLE_CONTAINER` (read the log through that container's home volume),
+(a bearer in a file — `/status` and `/sessions` need it on loopback too, else they answer `HTTP 401`), `LANES_THROTTLE_CONTAINER` (read the log through that container's home volume),
 `LANES_THROTTLE_LOG_DIR` (where `proxy.log` lives). A daemon bound to loopback inside its container is not reachable
 from the host: use `LANES_THROTTLE_CONTROL=none` there (the log fold still works). Details:
 [RUNBOOK](RUNBOOK.md#economy-projection-opt-in).
@@ -1845,7 +2206,7 @@ you configure, so enabling it is your decision. Not yet run against a real ntfy
 | `topic` | required | `[A-Za-z0-9_-]{1,64}`; on a public server the topic name is the only secret |
 | `token_file` | unset | A file holding an ntfy access token (an unreadable file disables sending; written, rotated or made readable later, it is picked up within 3 s) |
 | `quiet_when_device_active_s` | `120` | Presence window; `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}`; becomes the tap target and an **Open lane** button |
+| `action_url` | unset | A URL template over `{lane}`; becomes the tap target and an **Open lane** button. `{doc}` is the docs page of the document a `published` push names (`/lanes-docs/d/<id>`, so `https://<server>:8443{doc}` opens it) and empty in a needs-you push. The docs service sends a `published` push (lane name, kind and size, never the title) when it stores a document an agent published, at most one per lane per minute, muted like the others while you are at a desk |
 
 Nothing is sent when the status did not change, when the service just started (no burst on restart), or when a desk
 device was present within the presence window: a `lanes attach` from any device, or a lane opened from a desk
@@ -1975,6 +2336,7 @@ All units run in `lanes.slice` and are rendered by the server installer from `la
 | `lanes-gc.timer` / `.service` | Daily | Server install | `lanes gc`: truncate zmx logs over 5 MB, drop stale dynamic resolve files, prune old npm-staged trees — each folder keeps its 3 newest and every older tree `current`, `current.previous`, a view layout, a running daemon's run record or a process of this account uses; none when `/proc` cannot be read ([INSTALL](INSTALL.md#6-updates-optional-operations-and-removal)) |
 | `lanes-update.timer` / `.service` | 15 min after boot, then every 30 min (+0–5 min) | Server install (the full one: `--update-only` enables nothing — `systemctl --user enable --now lanes-update.timer` on a server set up before 1.2.0) | `lanes update --timer`: install the newest npm release when it is newer ([Update](#update)); a checkout server is left alone; stopped after 1 h |
 | `lanes-enrold.service` | Always on | Server install (enabled and restarted by every one) | Enrolment service on `127.0.0.1:8184`, reached as `https://<host>:8443/enrol/*`: invite redemption, enrolment requests, `/enrol/pending` approvals ([RUNBOOK](RUNBOOK.md#enrolment-service-lanes-enrold-w8-a3)) |
+| `lanes-docsd.service` | Always on | Server install (enabled and restarted by every one) | Docs service on `127.0.0.1:8185`, reached as `https://<host>:8443/lanes-docs/`: login-bound documents, sandboxed artifacts and uploads with receipts; refuses every request until `lanes enrol mode request` is pinned ([RUNBOOK](RUNBOOK.md#docs-service-lanes-docsd-w10-w3)) |
 | `lanes-web.service` | Always on | `enable-web.sh` (via `lanes web` / `enable-phone.sh`) | Zellij web server on `127.0.0.1:8082` |
 | `lanes-mobile.service` | Always on | `enable-web.sh` | Caddy frontend on `127.0.0.1:8083` |
 | `lanes-studio-host.service` | Always on | `enable-studio-host.sh` (opt-in) | The co-located Throttle Studio Host |
@@ -2025,8 +2387,9 @@ Clients also get `lanes-helper.service` and `lanes-upload.path`/`.service` (Linu
 | Editor | `lanes cursor-commit [ws…] [--push]` | Section 6 |
 | Containers | `lanes install-container <name> [--no-mcp]` | Install the `lane` contract (section 2) and the agents' MCP entries for `lane-mcp` (section 7, "Agent tools (MCP)"); `--no-mcp` leaves both out |
 | Containers | `lanes onboard <login> --container <name> [--workspace <id> --repo <path> [--title T]] [--write] [--no-mcp]` | One user's container in one command: board, contract, Claude and Codex hooks, Throttle attachment, canonical recipes, sync, doctor, and a receipt (a dry run until `--write`; section 2) |
-| Containers | `lanes hooks install --agent claude\|codex (--container <name> \| --home <dir>) [--dry-run \| --write]` | Section 7 |
+| Containers | `lanes hooks install --agent claude\|codex\|kimi\|grok\|grok-cli (--container <name> \| --home <dir>) [--dry-run \| --write]` | Section 7 ([Harnesses](#harnesses)) |
 | Uploads | `lanes upload <ws> \| --active <device> [--paste]` | Read a tar stream into that workspace's `uploads/` |
+| Uploads | `lanes docs push <id>` | Print one docs-store document's receipt (any login's: you are the operator) and exit 2 `not configured`: the hook for the data service's publication surface, not built yet ([Docs](#docs)) |
 | Client | `lanes hello [device] [--client-version V]` | Prove path, key and server version; ` update=<version>` when V is older |
 | Client | `lanes client-config` | Site facts for clients (`LANES_*` lines from `~/.config/lanes/site.conf`) |
 | Access | `lanes keys list \| add <device> <pubkey-file\|-> \| revoke <device> \| adopt [--dry-run] [--login LOGIN]` | Who may log in: the lanes-managed block of `~/.ssh/authorized_keys`, projected from `members/`; `--login` names the owner of every key adopt moves in and folds their views into that profile |
@@ -2073,7 +2436,7 @@ Server (`~/.local/state/lanes/`, `$LANES_STATE`):
 | --- | --- |
 | `registry.json`, `registry.synced`, `resolve/`, `resolve.dynamic/` | The published registry, the last sync time, per-lane targets |
 | `status.json`, `health` | statusd's snapshot and the one-line health record |
-| `run/<name>.tree` | The tree each long-running process started from — `statusd`, `enrold`, `economy`, `notify`, `studio_host` (the enable step its enrolment timer runs) and `sidebar` (the most recently started one): one resolved path, rewritten at every start, so a record that differs from where `~/.local/share/lanes/current` points is a process still running an older version |
+| `run/<name>.tree` | The tree each long-running process started from — `statusd`, `enrold`, `docsd`, `economy`, `notify`, `studio_host` (the enable step its enrolment timer runs) and `sidebar` (the most recently started one): one resolved path, rewritten at every start, so a record that differs from where `~/.local/share/lanes/current` points is a process still running an older version |
 | `containers.json`, `containers/` | Container init pids and home volumes |
 | `devices/<device>.json` | Each known device: layout, viewports, base device, owner, look (colour, theme, glyphs, dim; `device_only` lists the keys `--device-only` kept for this device alone), desktop notifications on/off and the quick-edit editor |
 | `layouts/<device>.kdl` | The layout a view session was built from |
@@ -2095,7 +2458,9 @@ Server (`~/.local/state/lanes/`, `$LANES_STATE`):
 | `invites/<id>.json` | Invites minted by `lanes invite`: the code's hash only (never the code), who minted it, expiry, invitee, and the redemption or revocation |
 | `enrol-requests/<id>.json` | Enrolment requests waiting for, or past, a member's approval (24 h) |
 | `enrol.log` | The enrolment audit log, one line per attempt, invite, revocation, offboard and mode change (0600, append-only; never a code) |
-| `enrol-mode` | Request mode as `lanes enrol mode request\|invite` pinned it (0600; absent = auto); the enrolment service reads it on every request |
+| `enrol-mode` | Request mode as `lanes enrol mode request\|invite` pinned it (0600; absent = auto); the enrolment service and the docs service read it on every request (docsd serves only while it says `request`) |
+| `docs/<login>/<ws>/<lane>/<id>/`, `docs/counts.json` | The docs store: each document with its `meta.json` and sha256 `receipt.json` (0700/0600; `<name>.age` when encrypted at rest); counts per lane. Written by every upload (the Docs page and `lanes upload`) and by the docs service's publish pick-up (`lane publish`, `lanes_publish`), read by the docs service ([RUNBOOK](RUNBOOK.md#docs-service-lanes-docsd-w10-w3)) |
+| `docs.log` | The docs audit log: one line per intake, removal, read, upload refusal, publish request and docs-service denial (0600, append-only; never content, a title or a name) |
 | `web-tokens.json`, `web-tokens.lock` | Which view — and which machine — each web login token `lanes web --token` minted was for (names and creation times only, never a token; `lanes offboard` signs a machine out by it) and the lock every mint and revocation holds (section 4, "Tokens") |
 | `onboard/<login>-<UTC>.json` | One receipt per `lanes onboard` run: each step with its status (section 7) |
 | `update/last.json`, `update/last.log`, `update/.lock` | The last `install.sh --server --update-only` run: `{checked_at, latest, installed, previous, result, steps: [{name, rc}], log}` with `result` `ok`, `partial`, `refused` or `failed` (a step whose exit status is a warning — `lanes sync` reporting a board with an error — carries `"warning": true`; keys it does not own are kept), and that run's full output; the run lock every server install and update holds while it runs (`{pid, mode, started}` of the last one to take it). `lanes update` adds `check` — its last check, `{at, by: timer\|hand, channel, tag, latest, installed, outcome, said[, exit]}`, `outcome` one of `current`, `older`, `bad`, `unanswered`, `refused`, `installing`, `installed`, `failed` — `bad` (the release a rollback left, written with the record of its flip, before its post-commit) and `rerun` (the release whose post-commit it ran again; a rollback drops it); a rollback's run is recorded with the step `rollback` first, `partial` until its post-commit has run |
@@ -2105,7 +2470,8 @@ Server (`~/.local/state/lanes/`, `$LANES_STATE`):
 Other server paths: `~/.config/lanes/` (`workspaces/`, `site.conf`, `notify.conf`, `update.conf` — `channel=stable`
 makes `lanes update` follow the `lanes-stable` dist-tag — and the optional invite key files
 `resend.key` and `tailscale-api.key`), `~/.local/share/lanes/` (pinned
-binaries in `bin/`, the `current` link to the installed tree — the path units and layouts name —,
+binaries in `bin/`, the docs page's pinned Mermaid in `vendor/` — `install/enable-docs.sh`, which every server install and update runs —, the `current`
+link to the installed tree — the path units and layouts name —,
 `current.previous`, the tree it named before the last install that moved it, and `.install.lock`, the lock installs
 and unit re-renders take turns on; npm-staged `pkg/<version>/`), and
 `~/.lz/<container>` (links to each
@@ -2193,12 +2559,18 @@ Server and views:
 | `LANES_ENROL_PORT` | `libexec/enrold.py` | `8184` | The enrolment service's loopback port (the Caddyfile's `/enrol/*` route must follow) |
 | `LANES_ENROL_DOMAINS` | `libexec/enrold.py` | `beyondwork.ai` | Login domains that may file an access request or approve one on `/enrol/pending` (comma or space separated; `*` = any); invites are not gated |
 | `LANES_ENROL_REQUEST_MODE` | `libexec/enrold.py` | unset | `1` forces request mode on, `0` forces invite-only, over any `lanes enrol mode` pin; unset, the pin decides, and without one the first request through Tailscale Serve after a start (RUNBOOK "Enrolment service") |
+| `LANES_DOCS_PORT` | `libexec/docsd.py` | `8185` | The docs service's loopback port (the Caddyfile's `/lanes-docs/*` route must follow) |
+| `LANES_DOCS_DOMAINS` | `libexec/docsd.py` | `LANES_ENROL_DOMAINS`, else `beyondwork.ai` | Login domains the docs service answers (comma or space separated; `*` = any) |
+| `LANES_DOCS_AGE_RECIPIENT` | `libexec/docs_store.py` (the docs service and `lanes upload`) | unset (off) | Keep new docs-store copies as `age -r <recipient>` output; the server install refuses it without an `age` binary ([RUNBOOK](RUNBOOK.md#docs-service-lanes-docsd-w10-w3)) |
+| `LANES_DOCS_AGE_IDENTITY` | `libexec/docsd.py` | unset | The `age` identity file the docs service decrypts with; without it an encrypted document's download answers 409 |
 | `LANES_DEVICE` | `libexec/enrol.py` (`lanes invite`) | unset | Recorded as `minted_by.device` of an invite when it is a device name (a claim, not an identity) |
 | `SSH_CLIENT` | `libexec/enrol.py` (`lanes enrol approve\|deny`) | set by sshd | Its address is recorded in the approver `cli[:<device>]@<address>`; `local` without one |
 | `LANES_TESTS_FORCE` | `tests/guards.py` | unset | `1` runs live suites on a busy host (on purpose only) |
 
 `LANES_THROTTLE_*` and `LANES_NOTIFY_CONF` set in the installer's environment are rendered into their units only. The
-`LANES_ENROL_*` settings go in a drop-in, `systemctl --user edit lanes-enrold.service`, which a re-install keeps.
+`LANES_ENROL_*` settings go in a drop-in, `systemctl --user edit lanes-enrold.service`, which a re-install keeps; the
+`LANES_DOCS_*` settings in lanes-docsd's, `systemctl --user edit lanes-docsd.service` (`lanes upload` reads the age
+switch from the same files).
 `LANES_REPO`, `LANES_ZELLIJ` and `LANES_WS` are set by Lanes itself for its units and panes.
 
 Client:
@@ -2248,6 +2620,7 @@ Container:
 | `lanes preview` / `next` / `prev` / `edit` without `--focused` | `2` |
 | `lanes edit --focused` | the editor's own status once a file is picked (`docker exec` passes on `lane-edit`'s) · `0` closed with `q`/`Esc`, nothing to edit, or another Edit pane in this tab now has the focus · `1` another Edit pane is open in another tab (or zellij would not focus it), zellij did not answer, a lane that is not a tmux lane, a container that is not running or has no `lane-edit`, no git checkout, docker could not be started, or another error |
 | `lanes version` | `0` (a stale process is shown, not an exit status) · `2` an argument other than `--json` |
+| `lanes docs push <id>` | `2` not configured (the receipt printed, nothing sent) · `1` no document with that id, an id that is not one, or another argument (the usage) |
 | `lanes update` | `0` nothing to do (up to date, not due, an older or bad release) or installed `ok` · `4` partial (the install's, or a post-commit run again) · `3` refused, nothing done: another update or install is running, a checkout server, no installed release, a bad `update.conf`, no release to roll back to — under `--timer` these are `0` · `1` failed: the registry gave no release, no usable recorded npx, the install failed or recorded nothing · `2` usage; `--status`: `0`, or `1` when nothing is recorded yet |
 | `lanes studio-host status` | `0` only when running enrolled; `1` otherwise; `2` usage |
 | `lanes invite <name>` | `0` minted (the kit printed; a failed email or Tailscale mint is a note, not an error) · `2` not on a terminal, nothing minted · `1` error |
@@ -2256,9 +2629,11 @@ Container:
 | `enable-studio-host.sh` | `0` running or waiting for enrolment · `2` usage · `3` typed refusal · `1` failure |
 | `enable-phone.sh` | `0` · `2` usage · `64` not in your own terminal, Tailscale Serve refused, or the running `lanes-web` reads another token database (from `lanes web`) · `1` a `lanes web` error |
 | `enable-web.sh` | `0` · `2` usage · `1` Caddy missing |
+| `enable-docs.sh` | `0` the pinned Mermaid installed or already there · `1` a prerequisite or the download failed · `2` usage · `3` refused (no valid pin, a digest mismatch, the member missing): nothing installed |
 | `lanes-launch` | `64` invalid name or option (it never exits on its own otherwise); server exits 64–78 are refusals it retries after 60 s |
 | `lanes-window` | `64` invalid suffix, or `--device-only` without `--ascii`/`--light`/`--dark` · `69` no Ghostty (macOS) or neither Ghostty nor Foot (Linux) |
 | `lanes-upload` | `64` usage · `66` no such file or empty clipboard · otherwise the transfer's status |
 | `lane status` | `1` when the lane is not running |
+| `lane publish <file>` | `0` the request is written (the receipt follows within about 5 s) · `1` refused or a usage error (one line on stderr) |
 | `lane-edit <file>` (container) | the editor's own status · `2` usage · `127` no editor on PATH; on a terminal both refusals wait for `Enter` first |
 | Live test suites (`tests/*.py`) | `75` host busy, not started |