@vibelord/lanes 1.2.0 → 1.3.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
@@ -822,7 +823,14 @@ 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).
+3. **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).
 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.
@@ -845,7 +853,7 @@ 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 ·
+`…` `~` clipped · `×` `x` close · `+` `+` new / add · `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now · `▤` `#` docs ·
 `⚠` `!` warning or starving · `↓` `v` downgraded · `$` `$` paid. The full tables, colours and mockups are in
 [DESIGN.md](DESIGN.md).
 
@@ -863,7 +871,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 ?`), 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):
@@ -891,6 +899,7 @@ to this table and ends with `Ctrl-Alt-l` — not a sidebar key but the chord tha
 | `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) |
 | `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 +938,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 +1229,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 +1269,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 +1382,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 +1394,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
@@ -1516,10 +1656,15 @@ 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 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
@@ -1655,6 +1800,7 @@ verbs, so the holder stays swappable.
 | `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 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 +1821,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
@@ -1691,7 +1849,7 @@ only 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 +1859,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 +1874,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.
@@ -1845,7 +2007,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 +2137,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 |
@@ -2027,6 +2190,7 @@ Clients also get `lanes-helper.service` and `lanes-upload.path`/`.service` (Linu
 | 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 |
 | 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 +2237,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 +2259,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 +2271,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 +2360,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 +2421,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 +2430,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 |

package/payload/lanes/holders.lock

@@ -16,3 +16,8 @@ glow 3.0.0 13e05e4b2acc18d2aee44291aefe6325b077ec321b631a0cfa780e8e3bc33f78 http
 # a locally built binary with `lanes studio-host install --from PATH [--sha256 HEX]` (also sha256-verified).
 # Template (fill from the release's two .sha256 sidecars, then uncomment):
 # throttle-rc node-<sha12> <tarball-sha256> https://github.com/bwllaming/bw-tools/releases/download/node/<sha12>/throttle-rc-x86_64-unknown-linux-gnu.tar.gz opt-in throttle-rc-x86_64-unknown-linux-gnu/throttle-rc <binary-sha256>
+# mermaid 11.17.2 (the docs page's diagrams, plan W10 W6, LNS-107): the npm tarball, 17,796,365 B, whose sha512 is the
+# registry's dist.integrity; the member is the classic-script (IIFE) build, 3,572,661 B, that web/docs.js loads with
+# this digest as its SRI. Both sha256s measured 2026-10-08. install/enable-docs.sh installs it into
+# ~/.local/share/lanes/vendor/; to bump it see docs/RUNBOOK.md "Mermaid pin".
+mermaid 11.17.2 6ad2f42c3fc26bbf9e45cbb6d11898972573ea52b33a5f4ff51952899f950ffd https://registry.npmjs.org/mermaid/-/mermaid-11.17.2.tgz opt-in package/dist/mermaid.min.js 581ed7d74bd9048d0e3a91363927d72ef22942d7722546b27f7cc29e35390eb8

package/payload/lanes/install/enable-docs.sh

@@ -0,0 +1,78 @@
+#!/bin/sh
+# The docs page's pinned Mermaid (plan W10 W6, LNS-107; docs/RUNBOOK.md "Mermaid pin"). Every server install runs it
+# right after lanes-docsd's restart and every update (--update-only) as the post-commit step `enable-docs` (W8, LNS-109:
+# host-install.sh, libexec/update.py DOCS_STEP), never fatally; it runs by hand as well. As the workspace account, never
+# root. Reads holders.lock's `mermaid` opt-in pin, downloads its npm tarball into a temporary
+# directory, checks the tarball's sha256, extracts ONLY the pinned member (never a link), checks the member's sha256,
+# and installs it as $LANES_SHARE/vendor/mermaid-<version>.min.js (0644, by rename) with the relative link
+# mermaid.min.js -> that file. Caddy serves the directory at /lanes-assets/vendor/ (web/Caddyfile); web/docs.js
+# loads the versioned name with the member digest as its SRI. Idempotent: an installed file whose digest is the pin's
+# is kept and nothing is downloaded; one that differs is replaced from a verified download. Older versions stay.
+# Exit status: 0 installed, or already present; 1 a prerequisite is missing or the download failed; 2 usage;
+# 3 refused — holders.lock has no valid mermaid pin, a digest differs, or the member is missing or not a regular file.
+# A refusal or failure installs nothing.
+set -eu
+repo=$(cd "$(dirname "$0")/.." && pwd)
+usage='usage: enable-docs.sh [--help]'
+case "$#:${1:-}" in
+    0:) ;;
+    1:-h|1:--help)
+        echo "$usage"
+        echo 'Installs the Mermaid that holders.lock pins (opt-in line `mermaid`) into ~/.local/share/lanes/vendor/'
+        echo '($LANES_SHARE/vendor), after checking the sha256 of the npm tarball and of its member.'
+        echo 'Exit status: 0 installed or already present; 1 a prerequisite is missing or the download failed;'
+        echo '2 usage; 3 refused (no valid pin, a sha256 mismatch, the member missing or not a regular file).'
+        exit 0 ;;
+    *) echo "$usage" >&2; exit 2 ;;
+esac
+[ "$(id -u)" != 0 ] || { echo 'Run as the workspace account, not root.' >&2; exit 1; }
+for command in curl tar sha256sum install mktemp; do
+    command -v "$command" >/dev/null 2>&1 || { echo "Missing prerequisite: $command (see docs/INSTALL.md)" >&2; exit 1; }
+done
+share=${LANES_SHARE:-$HOME/.local/share/lanes}
+lock=$repo/holders.lock
+refuse() { echo "enable-docs: refused, nothing was installed: $*" >&2; exit 3; }
+hex64() { [ "${#1}" -eq 64 ] && case $1 in *[!0-9a-f]*) false ;; esac; }
+
+# The pin: exactly one `mermaid` line of the 7-field opt-in grammar (holders.lock's header; studio_host.parse_lock).
+pins=$(grep -v '^[[:space:]]*#' "$lock" | awk '$1 == "mermaid"') || :
+[ -n "$pins" ] || refuse "$lock has no mermaid line"
+[ "$(printf '%s\n' "$pins" | wc -l)" -eq 1 ] || refuse "$lock pins mermaid more than once"
+# shellcheck disable=SC2086 # the line's words are the fields; no pathname expansion of them
+set -f
+set -- $pins
+set +f
+[ "$#" -eq 7 ] && [ "$5" = opt-in ] || refuse "$lock: the mermaid line is not 'name version sha256 url opt-in member sha256'"
+version=$2 sha=$3 url=$4 member=$6 member_sha=$7
+case $version in ''|*[!A-Za-z0-9._-]*) refuse "$lock: mermaid version '$version' is not a plain word" ;; esac
+hex64 "$sha" || refuse "$lock: the mermaid tarball digest is not 64 lowercase hex"
+hex64 "$member_sha" || refuse "$lock: the mermaid member digest is not 64 lowercase hex"
+case $url in https://*) ;; *) refuse "$lock: the mermaid url is not https" ;; esac
+case /$member/ in //*|*/../*|*/./*|*//*) refuse "$lock: member '$member' is not a plain relative path" ;; esac
+
+vendor=$share/vendor
+target=$vendor/mermaid-$version.min.js
+if [ -f "$target" ] && [ ! -L "$target" ] && [ "$(sha256sum "$target" | cut -d' ' -f1)" = "$member_sha" ]; then
+    ln -sfn "mermaid-$version.min.js" "$vendor/mermaid.min.js"
+    echo "ok  mermaid $version ($target)"
+    exit 0
+fi
+
+temporary=$(mktemp -d)
+trap 'rm -rf "$temporary"' EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM HUP
+curl -fsSL --retry 3 -o "$temporary/mermaid.tgz" "$url" || { echo "enable-docs: download failed: $url" >&2; exit 1; }
+actual=$(sha256sum "$temporary/mermaid.tgz" | cut -d' ' -f1)
+[ "$actual" = "$sha" ] || refuse "sha256 mismatch for the mermaid $version tarball: $actual, pinned $sha"
+mkdir "$temporary/x"
+tar -xzf "$temporary/mermaid.tgz" -C "$temporary/x" "$member" 2>/dev/null || refuse "the tarball has no $member"
+file=$temporary/x/$member
+[ -f "$file" ] && [ ! -L "$file" ] || refuse "$member in the tarball is not a regular file"
+actual=$(sha256sum "$file" | cut -d' ' -f1)
+[ "$actual" = "$member_sha" ] || refuse "sha256 mismatch for $member: $actual, pinned $member_sha"
+mkdir -p "$vendor"
+install -m 0644 "$file" "$vendor/.mermaid-$version.min.js.$$"
+mv -f "$vendor/.mermaid-$version.min.js.$$" "$target"
+ln -sfn "mermaid-$version.min.js" "$vendor/mermaid.min.js"
+echo "installed $target (sha256 $member_sha)"