@vibelord/lanes 1.2.0 → 1.3.0

package/payload/lanes/docs/RUNBOOK.md

@@ -24,6 +24,7 @@ measurements; substitute your account, containers and paths in operational comma
 | Scroll a lane | mouse wheel / tmux copy-mode as before (history lives in the lane, not in the viewer) |
 | Edit a lane's AGENTS.md, CLAUDE.md or .env.local | `Ctrl-Alt-e`: a floating **Edit** pane runs `lanes edit --focused`, one key picks (`1`–`5`; `q`/`Esc` closes), then `docker exec -it -u coder -w <checkout> <container> ~/.lz/bin/lane-edit <file>` replaces it — the editor runs in the lane's container as uid 1000, the server only checks the paths through `/proc/<init>/root` and copies nothing out ([guide](USERGUIDE.md#quick-edit)). `lanes edit: lane-edit is not installed in <c>` → `lanes install-container <c>`; `lane-edit: no editor on PATH` (exit 127) → the container has none of micro, hx, nvim, vim, vi (Lanes installs none); `container <c> is not running` → nothing to edit until it runs; `no git checkout in or above <dir>` → the lane works outside a checkout. The editor is the device's `lanes attach <device> --editor E` choice |
 | Throttle monitor | its own full-size tab, `Throttle` (next to `Host`); it starts when you first open the tab and restarts itself if it exits. It is no longer an entry in every board's sidebar. |
+| Open what an agent published, or upload from a phone | the Docs page, `https://<server>:8443/lanes-docs/`: phone **More → Docs**, the laptop bar's **Docs**, a ⌘/Ctrl-click on the sidebar's ` ↑ uploads · ▤ docs N` strip, or `d` on a lane for its own link; an agent publishes with `~/.lz/bin/lane publish <file>` or `lanes_publish` (section "Docs service"; the [user guide's Docs](USERGUIDE.md#docs)) |
 | Detach | `Ctrl-Alt-o` then `d` — or just close the window. Nothing on the server stops. |
 
 Sidebar glyphs: see the legend in [`docs/DESIGN.md`](DESIGN.md) (agent column `◆ ◇ ▸ ✓ ✗ _ ·`, terminal column
@@ -208,10 +209,13 @@ lanes studio-host re-key --yes       after the owner revoked the Host: a new mac
   outcome; the full output is `~/.local/state/lanes/update/last.log`, the outcome `update/last.json`. Read it with
   `python3 -m json.tool ~/.local/state/lanes/update/last.json`: `result` `ok` (a step with `"warning": true` — `sync`
   exiting 1 for a board with an error, e.g. a removed container — needs the board fixed, not the update: `lanes sync`
-  names it); `partial` (exit 4) — the release is installed and a step after the switch failed: each step with a
+  names it; `enable-docs` with `"outcome": "skipped"` or `"refused"` and its `reason` is the docs page's Mermaid, never
+  fatal — see "Mermaid pin" — and the summary line says `mermaid ok`, `mermaid skipped: <reason>` or `mermaid
+  refused: <reason>`); `partial` (exit 4) — the release is installed and a step after the switch failed: each step with a
   non-zero `rc` is the one to run by hand (`sync` → `lanes sync`, `restart lanes-statusd` →
   `systemctl --user restart lanes-statusd.service`, `install-container <c>` → `lanes install-container <c>`,
-  `reload-views` → `lanes reload-views`, `ensure` → `lanes ensure --if-layout-changed`); `refused` (exit 3) — nothing changed: the last step names what said no
+  `reload-views` → `lanes reload-views`, `ensure` → `lanes ensure --if-layout-changed`, `enable-docs` with `"outcome":
+  "failed"` → `sh ~/.local/share/lanes/current/install/enable-docs.sh`); `refused` (exit 3) — nothing changed: the last step names what said no
   (`preflight`: a prerequisite, the user manager or Docker, or no installed release — `no release is installed here`:
   run the full `./install.sh --server` / `npx @vibelord/lanes@<release> --server` first; `commit`: another install
   holds `~/.local/share/lanes/.install.lock`, or a link is no symlink). A run that printed only
@@ -1086,6 +1090,10 @@ lands where, and how to take it back:
   lane's task line). The report stands until the agent's next tool call, prompt or permission prompt; the end of
   its turn keeps it unless it is `working` (DEF-1801). `cat ~/.lz/state/hooks/<lane id>.json` shows it: `event`
   stays `lanes_signal` while it stands.
+- `lanes_publish` (and `lane publish <file>` in a lane's shell) writes a publish request,
+  `~/.lz/state/publish/<lane id>/<id>.json`, naming a file under `/home/coder`; the docs service takes it within
+  about 5 s and answers in `<id>.receipt.json` beside it ("Docs service", "Publish pick-up"). `lanes_status` shows the
+  newest receipt as `published`. The file is read by the host, never sent by the agent.
 - Nothing an agent does ends, interrupts or attaches a lane, uploads a file, runs `lanes sync`, `lanes gc` or
   `lanes ensure`, renames a tmux session, or touches a session added with `lanes register` (`registered-sessions.json`
   on the host).
@@ -1121,8 +1129,8 @@ printf '%s\n' \
 ```
 
 It prints two frames, one line each, exit 0 and nothing on stderr. Frame `id` 1 carries `protocolVersion`
-`2025-06-18` and `serverInfo` `{"name": "lanes", "version": <~/.lz/VERSION>}`. Frame `id` 2 lists the ten tools in
-wire order, the same tools `lanes/tests/unit/golden/lane-mcp-tools.json` pins. The list is deterministic: run the
+`2025-06-18` and `serverInfo` `{"name": "lanes", "version": <~/.lz/VERSION>}`. Frame `id` 2 lists the eleven tools in
+wire order (`lanes_publish`, W10 W4, last), the same tools `lanes/tests/unit/golden/lane-mcp-tools.json` pins. The list is deterministic: run the
 command twice through `sha256sum` and the two digests match. The log gains a `start lane-mcp <version> wire 1` line.
 No output at all means the server could not start, for example because `lane_core.py` is missing beside it; run
 `lanes install-container <container>` on the host. `test_docs.AgentApi` runs this block exactly as printed here.
@@ -1298,7 +1306,7 @@ that becomes readable switches the pushes on within one tick and a removed one s
 | `topic` | required | `[A-Za-z0-9_-]{1,64}`; on a public server the topic name is the only secret — pick a long random one |
 | `token_file` | unset | a file holding an ntfy access token (sent as a bearer). An unreadable file disables sending rather than sending unauthenticated (or with the token it held before). Keep the token in that file (`chmod 600`), never in `notify.conf` |
 | `quiet_when_device_active_s` | `120` | presence window above; `0` never suppresses — except for the one person present when their profile sets a `notify.quiet_s` of its own |
-| `action_url` | unset | a URL template over `{lane}` (the lane id, URL-quoted), e.g. a page of yours that opens it; becomes the push's tap target and an **Open lane** button |
+| `action_url` | unset | a URL template over `{lane}` (the lane id, URL-quoted), e.g. a page of yours that opens it; becomes the push's tap target and an **Open lane** button. `{doc}` (plan W10 W7) is the docs page of the document a `published` push names, `/lanes-docs/d/<id>` (`https://<server>:8443{doc}` opens it), empty in a needs-you push. The `published` push (plan W10 W4) is sent by the docs service's publish pick-up, not by this unit: same config, same desk-presence rule, `{title: Published, message: <lane name> published a document (<kind>, <size>) + its page, priority 2}`, at most one per lane per minute, never the document's title or name |
 
 Without a valid `url` and `topic` the service only tracks transitions and sends nothing. Turn it on:
 
@@ -1374,12 +1382,27 @@ The Studio's design of record is `docs/design/throttle-studio.md` (§1.1 "The la
 ## Uploads (the Cursor `uploads/` folder, without Cursor)
 
 Files land in `<board folder>/uploads/` on the server — the same folder you drop into from Cursor. The folder is
-created on first use and kept out of commits through the repo-local `.git/info/exclude` when the repo does not
-already ignore it. Afterwards the in-container path is on your clipboard and in a notification.
+created on first use (0755) and kept out of commits through the repo-local `.git/info/exclude` when that file does not
+name it yet. Afterwards the in-container path is on your clipboard and in a notification. Every upload — these ways
+and the Docs page's drop area ("Docs service" below) — also becomes a docs-store document with a sha256 receipt (W10
+W5): one module, `libexec/uploads.py`, lands the file and hands the same bytes to `docs_store.intake` in one pass, so
+the receipt is of exactly what arrived; the store keeps a copy (never a hard link to the container's file, which an
+agent could rewrite under an unchanged receipt). `lanes upload` says each receipt on stderr (`# docs: <name> <bytes> B
+sha256 <hash> <id>`, in the helper's log) and records it for the login that owns the asking device, under the lane its
+view shows; a device nobody owns gets a `docs.log` line (`upload - - <lane> <bytes> <sha256> no-owner`) and no
+document; a file over 32 MiB lands without one (`intake … too-large`). stdout and the spool's `<request>.done` are what
+they always were.
+
+The host never follows a symbolic link in the container's folder (an absolute link would resolve against the host's
+root: DEF-1891) and runs no git there (`git check-ignore` runs the repository's `core.fsmonitor`, a command the
+container chose: DEF-1890). A folder or `uploads/` reached through a link is refused (`lanes: uploads/ in the
+workspace folder is not a directory (a symbolic link is refused)`): replace the link with the real directory in the
+container. The tar stream is unpacked member by member: links that leave the upload, `..`, devices and FIFOs refuse
+the whole upload, as tar's data filter did.
 
 | Way | How |
 |---|---|
-| Upload strip in the sidebar | The one row above the footer rule, ` ↑ uploads · click, then drop  (U)`. Click it (or press `U` in the sidebar, `Ctrl-Alt-u` from anywhere in the tab) — it turns into ` ↓ DROP FILES NOW · anywhere · Esc` — then **drop the files anywhere on the window**. The file goes to the board of that tab and its path is typed into the lane, ready for the agent. `Esc` cancels. While it sends the strip says ` ↑ sending 2 files · 12.4 MiB` and repaints only when the helper reports progress (no spinner, no fast tick); the result stays 8 s as ` ✓ name, name` or ` ✗ reason`. |
+| Upload strip in the sidebar | The one row above the footer rule, ` ↑ uploads · click, then drop  (U)` — ` ↑ uploads · ▤ docs 3  (U)` once the workspace's lanes have published documents, the whole row then a link to the docs page (plan W10 W7). Click it (or press `U` in the sidebar, `Ctrl-Alt-u` from anywhere in the tab) — it turns into ` ↓ DROP FILES NOW · anywhere · Esc` — then **drop the files anywhere on the window**. The file goes to the board of that tab and its path is typed into the lane, ready for the agent. `Esc` cancels. While it sends the strip says ` ↑ sending 2 files · 12.4 MiB` and repaints only when the helper reports progress (no spinner, no fast tick); the result stays 8 s as ` ✓ name, name` or ` ✗ reason`. |
 | Watch folder | `~/Lanes Uploads/` → the board your view shows; `~/Lanes Uploads/<board>/` → that board. Sent files move to `.sent/<date>/`. Point CleanShot's save folder here for instant screenshot upload. |
 | Command | `lanes-upload [-w <board>] [--paste] <files…>` · `lanes-upload --clipboard [--paste]` (clipboard image or copied files) |
 | macOS droplet | `~/Applications/Lanes Upload.app`: drop files on it (Dock); double-click uploads the clipboard screenshot |
@@ -1542,6 +1565,10 @@ Laptop and tablet browsers: see the [installation guide](INSTALL.md#laptop-and-t
 - **`lanes web` printed a `127.0.0.1` URL**: the host has no Tailscale name. Connect Tailscale on the host;
   there is no public fallback.
 
+The Docs page (`/lanes-docs/`: the phone's **More → Docs**, the laptop bar's **Docs**, the sidebar's ` ▤ docs N`) is
+a service of its own behind the same Serve and Caddy, with its own pinned Mermaid: section "Docs service" (its unit,
+pin gate, `docs.log`, routes, Mermaid pin, doctor lines and the operator's live checklist).
+
 ### Tailscale Serve
 
 `lanes web` (not `--print-only`) makes Tailscale Serve forward `https:8443` to `http://127.0.0.1:8083` after it
@@ -1823,6 +1850,340 @@ signed out in step 3; their views are named, not ended — offboard each by name
 open with the key keeps running until it ends (step 1 says so). `enrol.log` gets one `offboard` line with the key's
 fingerprint and `ok` or `incomplete`.
 
+## Docs service (`lanes-docsd`, W10 W3)
+
+The docs cockpit's web half: what an agent publishes from a lane (W4, "Publish pick-up" below) and what a person
+uploads (W5: the Docs page's drop area and every `lanes upload`) is opened at
+`https://<host>.<tailnet>.ts.net:8443/lanes-docs/` from the phone or laptop shell, bound to the person's
+tailnet login. `lanes-docsd.service` runs `libexec/docsd.py` on **127.0.0.1:8185**; the `lanes-mobile` Caddy forwards
+`/lanes-docs/*` to it (`handle_path /lanes-docs/*` in `web/Caddyfile`, which strips the prefix and is the FIRST handle of
+the site, before the Zellij routes) and keeps Serve's `X-Forwarded-For` (`trusted_proxies 127.0.0.0/8`, as on
+`/enrol/*`). The site-wide Caddy header block is `header @notdocs` (`@notdocs not path /lanes-docs/*`), so a docs
+response carries docsd's headers only. Every server install enables and restarts it after `lanes-enrold`, then runs
+`install/enable-docs.sh` for the page's Mermaid ("Mermaid pin" below; never fatal); an update (`--update-only`)
+restarts it when it runs (`update.TRY_RESTART`), runs `enable-docs.sh` right after, and, like every update, enables
+nothing — a server set up before the docs service and only updated since has no `lanes-docsd` until one full `--server`
+install (or `systemctl --user enable --now lanes-docsd.service`); `lanes doctor` says so (DEF-1900, mitigated). In
+order below: the unit, the pin gate and who sees what, the routes, uploads, encryption, `docs.log`, the publish
+pick-up and the Caddy reload; then "Mermaid pin", "What `lanes doctor` says" and the operator's live checklist
+("Operator verification"). `lanes docs push <id>` prints one document's receipt and exits 2 `not configured`: the
+hook for the data service's publication surface, not built (operator gate 3 of the plan).
+
+The unit, `lanes-docsd.service` (rendered from `systemd/lanes-docsd.service` by `install/services.py`), runs
+`python3 -S -E libexec/docsd.py` in `lanes.slice` with `Restart=on-failure` (10 s), `NoNewPrivileges=true`,
+`UMask=0077`, `MemoryHigh=128M` and `MemoryMax=192M`, and `WantedBy=default.target`; no `ProtectHome` (it writes
+`~/.local/state/lanes/docs/` and `docs.log`, its publish pick-up reads each workspace container through
+`/proc/<pid>/root`, as `lanes-statusd` does, and an upload lands in the workspace's `uploads/` through the container's
+home volume). MEASURED 2026-10-08 on the development host (`/usr/bin/python3`
+3.12.3 `-S -E`, load about 70; not the ceobox service): idle VmHWM 25 MB, one 32 MiB upload 56 MB, two at once (the
+most it parses: `UPLOAD_SLOTS`) 89 MB; the security review (2026-10-08) measured 94 MiB for two. A decryption now
+takes one of the same two slots (it holds up to 32 MiB of plaintext), so at most two 32 MiB buffers are held at once;
+the composed peak under `MemoryMax` (two buffers, two renders, the render cache, a pick-up survey) is not measured
+(DEF-1917, mitigated). `LANES_DOCS_PORT` (or `--port`) moves it off 8185 (the Caddyfile route must follow); `--bind`
+takes a loopback address only.
+
+```sh
+systemctl --user status lanes-docsd.service
+journalctl --user -u lanes-docsd.service -n 30     # "listening on 127.0.0.1:8185; pinned request (…); domains …"
+tail ~/.local/state/lanes/docs.log                 # one line per read, upload refusal, publish, intake and denial
+lanes doctor                                       # the five docs lines below
+```
+
+**The pin gate.** docsd answers NOTHING until the operator has run the enrolment service's Serve header check (section
+"Enrolment service", Operator verification) and pinned its result with `lanes enrol mode request` (it reads
+`~/.local/state/lanes/enrol-mode` on every request: no restart). Unpinned (`auto`), pinned `invite`, or a pin that
+cannot be read: every request is `403 not-pinned`, and the start line says `NOT pinned`. `LANES_ENROL_REQUEST_MODE`
+in enrold's unit is enrold's alone and is not a pin here. After the pin, a request is answered only when ALL hold —
+else `403` with the word, a short page for a browser:
+
+| Check | Refusal |
+|---|---|
+| it came through Tailscale Serve: its `X-Forwarded-For` (Serve sets it, Caddy keeps it) names a non-loopback address | `not-through-serve` (a probe of 127.0.0.1:8185 or of Caddy from this host) |
+| Serve's identity header set: `Tailscale-User-Login` and `Tailscale-User-Name` | `no-identity` (a tagged device) |
+| the login validates as a member login | `invalid-login` |
+| the pin above | `not-pinned` |
+| the login owns a valid `members/<device>.json` (casefolded) | `not-a-member` (`lanes keys owner <device> <login>`) |
+| its domain is in `LANES_DOCS_DOMAINS`, else `LANES_ENROL_DOMAINS` (default `beyondwork.ai`, `*` = any) — set it in this unit's drop-in | `domain-not-allowed` |
+| its `Sec-Fetch-Site` is `same-origin` (a page, script, stylesheet or image of the Docs pages, the phone/laptop shell's **Docs** link) or `none` (an address typed or bookmarked, a link opened from a terminal or a phone app); or it is a top-level navigation — a GET or HEAD with `Sec-Fetch-Mode: navigate` and `Sec-Fetch-Dest: document` — from any site (a link followed in ntfy's web app, a chat, a mail); `POST /up` only `same-origin` or `none` — every route, since the security review of 2026-10-08 | `cross-site` (anything else from another site — `cross-site`, `same-site` (`*.ts.net` is a public suffix, so another tailnet host's page is same-site) — that is not such a navigation: a `fetch()`, an image, a script, a frame, a form posted to `/up`; or no `Sec-Fetch-Site` on a request that is not a navigation: a browser too old to send it, or `curl`) |
+
+No Zellij cookie is consulted. The `cross-site` check is why a sandboxed artifact (an opaque origin) cannot spend the
+viewer's login here: its `fetch()` and subresource loads are not navigations. A link to a docs page followed from
+another website (a web mail, a chat in a browser, ntfy's web app) is a top-level navigation and is served. The
+artifact's sandbox (`sandbox allow-scripts` only) cannot open a window, submit a form or navigate another browsing
+context; the one navigation its script can start is of its own page, which replaces it unless the answer is a download
+the sandbox blocks, so what it can request that way is bounded by the 300-a-minute limit (the HTML standard's rules,
+not measured in a browser).
+**Trust boundary:** as for enrold (DEF-1645, open), a process on this host that reaches loopback can send the headers
+itself and read any member's documents; the pin and the Serve-only check are the controls, and the same `docker ps
+--filter network=host` audit applies. And a member's device key carries `restrict,pty` but no `command=`
+(`libexec/keys.py` `OPTIONS`): a member who can SSH in has a shell as the lanes account and can read every store
+directly, so the per-login separation of the docs service holds between people who only use the web, not against a
+member with a device key (DEF-1919, open). Never expose 8443 through Tailscale Funnel (Funnel traffic carries no
+identity headers).
+
+**Who sees what.** A person sees the documents in their own store (their uploads), the documents whose `for` names
+them, and a document that names nobody when a member record they own grants its workspace. A record's `workspaces`
+(the board ids an invite recorded with `lanes invite --workspaces`) grants those boards; a record that lists none —
+a key added with `lanes keys add|adopt`, a device enrolled by request, an invite minted without `--workspaces` —
+grants every workspace the server serves (the registry's), because nothing else in Lanes narrows by that list
+(DEF-1852, closed). The same grant decides the lanes the upload form offers and `POST /up` accepts. A document a
+person cannot see answers `404`, like one that does not exist.
+
+| Route (after Caddy strips `/lanes-docs`) | Answer (wire contract v1, DM-LANES-DOCS-WIRE) |
+|---|---|
+| `GET /` · `GET /?ws=<ws>&lane=<lane>` | the index page: workspace → lane → newest first, counts, the upload form; the filter (either key optional) must name a workspace/lane the person knows, else `404` |
+| `GET /d/<id>` | the document page: Markdown rendered (mdlite; over 1 MiB not rendered; from the render cache when its sha256 was rendered before; `503 busy` + `Retry-After` when two renders run and none ends within 1 s), an HTML/SVG artifact linked (never embedded), a file's facts and download |
+| `GET /d/<id>/raw` | the bytes, `Content-Disposition: attachment; filename="<name>"`, `X-Lanes-Sha256` |
+| `GET /d/<id>/artifact` | kind html/svg only: the bytes as a top-level document under `Content-Security-Policy: sandbox allow-scripts` |
+| `GET /receipt/<id>.json` | `receipt.json` (`{v, id, sha256, bytes, url, at}`) |
+| `GET /docs.css`, `GET /docs.js` | `web/docs.css` / `web/docs.js` of the running tree (W6), else `404` |
+| `GET /upload.css`, `GET /upload.js` | `web/upload.css` / `web/upload.js` (W5, the index's drop area), else `404` |
+| `POST /up` | multipart form: `lane` (+ optional `ws`), files; each lands in the workspace's `uploads/` AND the store, both or neither; `200 {receipts: [{id, name, sha256, bytes, url, at, landed}]}` or a page; `429` (30 per login per 10 min) + `Retry-After`, `503 busy` (two big buffers at once — uploads and decryptions —, one per login, or the store lock), `415`, `411`, `413` (32 MiB), `408 request-timeout` (the body did not arrive within 30 s + its length at 64 KiB/s), `400 bad-request\|no-file\|no-lane\|unknown-lane\|unknown-workspace`, `503 registry-unavailable`, `503 uploads-unavailable` (the container's folder: home volume unknown, a link on the way), `500 encrypt-failed` |
+| every route but `POST /up` | `429 rate-limited` + `Retry-After` past 300 requests per login per minute (one `docs.log` line per minute) |
+
+**Limits** (per `lanes-docsd` process; security review 2026-10-08 — each pinned by a test in `tests/unit/test_docsd.py`
+or `test_docs_store.py`, values in `libexec/docsd.py` / `docs_store.py`):
+
+| Limit | Value | Past it |
+|---|---|---|
+| requests per login, every route but `POST /up` (`VIEWS` / `VIEW_WINDOW`) | 300 per 60 s, a fixed window | `429 rate-limited` + `Retry-After`; one `view … rate-limited` line per window |
+| Markdown renders at once (`RENDER_SLOTS`, `RENDER_WAIT_S`) | 2; a view waits 1 s for one | `503 busy` + `Retry-After: 5` |
+| render cache (`RENDER_CACHE_BYTES`, `RENDER_CACHE_ENTRY`) | 8 MiB in all, by the document's sha256, least recently used out; a render over 2 MiB is not kept | a second view of a cached document renders nothing and needs no slot |
+| big buffers at once (`UPLOAD_SLOTS`), shared by uploads and decryptions | 2, at most 1 per login; a decryption also one at a time and waits 5 s for a slot | `503 busy` + `Retry-After: 5` |
+| uploads per login (`UPLOADS` / `UPLOAD_WINDOW`) | 30 per 10 min, counted at the start | `429 rate-limited` |
+| upload body deadline (`BODY_GRACE_S`, `BODY_MIN_RATE`) | 30 s + length / 64 KiB/s (32 MiB: 542 s) for the whole body; each read still times out after 30 s without data | `408 request-timeout`, connection closed, the slot free again |
+| refused body read away (`DRAIN_LIMIT`, `LINGER_S`) | 64 MiB before the answer, then 5 s | the client may see a reset |
+| pick-up survey (`MAX_ENTRIES`) | 4,096 directory entries per container per cycle (its publish directory and lane directories together) | the container is refused for the cycle: nothing taken; the journal says `pick-up <container>: refused: more than 4096 entries …` once an hour (`OVER_CAP_SAY_S`) |
+| pick-up per container (`MAX_PICKUPS`, `PUBLISHES`) | 16 per cycle, 30 per 10 min | the rest wait; past 30 refused `rate-limited` |
+| `docs.log` refusal lines (`DENIED_REPEAT_S`, `MAX_DENIED_SOURCES`, `MAX_DENIED_LOGIN`) | one `denied` line per source (the tailnet address Serve forwarded, else the peer) and word, then one `denied-repeat` line per minute with the count; 1,024 sources remembered; a login logged at most 64 characters | — |
+| `docs.log` size (`docs_store.LOG_ROTATE_BYTES`) | 8 MiB, then `docs.log.1` (one generation) | the older generation is replaced |
+
+Every response has `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` and a
+CSP: pages `default-src 'none'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; connect-src
+'self'; form-action 'self'; base-uri 'none'` (`connect-src` for the drop area's own `POST up`), an artifact exactly
+`sandbox allow-scripts`, everything else `default-src 'none'; sandbox`.
+Links and assets in a page are relative (`docs.css`, `d/<id>`), so the pages work under the stripped prefix; open the
+index as `/lanes-docs/` with the slash (`/lanes-docs` alone is the page route a device of that name would have, which
+is why `lanes-docs`, `lanes-assets` and `enrol` are not device names). An upload goes through `uploads.receive` (W5):
+it lands in the lane's workspace's `uploads/` (`<folder>/uploads/<name>`, `-1` on a collision, exactly as `lanes
+upload` lands one) and `docs_store.intake` (`source` `web`, kind by extension, `for` and `by` the uploader) takes the
+same bytes into the person's store; the receipt's `landed` is the in-container path to tell the agent. The drop area is
+a plain form that works without a script; `web/upload.js` (loaded by the index only) adds the drop onto the whole area,
+a size check before sending, progress and the receipt list.
+The multipart body is split by docsd's own bytes scan, each part's headers parsed by `email.parser`: parsing a 32 MiB
+body whole with `email.parser` MEASURED about 430 MB peak RSS and 3.8 s, the scan 0.05 s and no copy.
+
+**A refused upload is answered, not reset (DEF-1854, closed by W5).** A browser sends its whole body before it reads
+the answer, and a server that answers and closes while the body is still arriving resets the connection under its own
+answer. docsd now reads a refused body away up to its `Content-Length` — at most 64 MiB (`DRAIN_LIMIT`, twice the cap) —
+before it answers (with `Connection: close`); past that it answers, shuts its write side and reads the rest for at
+most 5 s (`LINGER_S`). MEASURED 2026-10-08 against a real `python3 -S -E docsd.py` (development host, load ~15–20 on
+64 cores), three concurrent 32 MiB uploads then a 48 MiB and a 100 MiB one: before (the W3 tree) 200, 200 and a
+`BrokenPipeError`, and both oversize uploads `BrokenPipeError`; after, three runs, 200, 200, `503 busy` and both `413`
+read by the client. Over a slow link a body past 64 MiB can still be reset; upload.js refuses a set over 32 MiB before
+it sends.
+
+**Encryption at rest (`age`, W5; off by default).** `LANES_DOCS_AGE_RECIPIENT=<age recipient>` in lanes-docsd's
+drop-in makes the docs store keep each NEW document as `age -r <recipient>` output (`<name>.age`, meta.json `enc:
+{alg, file, bytes, recipient}`); the file in the workspace's `uploads/` stays plain (agents read it), and receipts stay
+the sha256 of the plaintext, computed before encryption (age output is randomised, so a hash of it would match nothing
+anyone holds). `lanes upload` runs over SSH, outside the unit, and reads the same drop-in files, so both paths follow
+one switch. For docsd to open encrypted documents, give it an identity file with `LANES_DOCS_AGE_IDENTITY=<path>`: raw
+downloads and artifacts are then decrypted on the fly (at most 32 MiB, one at a time) and checked against the receipt;
+without it they answer `409 encrypted` (a page that sends the person to `uploads/`) and a document page shows its facts
+only. Documents stored before the switch stay plain. Every server install refuses the setting where no `age` binary is
+on PATH (`host-install.sh` `check_docs_age` → `python3 libexec/docs_store.py check-age`, exit 1 with the reason; an
+update records it `refused`, nothing changed); install `age` first.
+
+```sh
+systemctl --user edit lanes-docsd.service   # [Service]
+                                            # Environment=LANES_DOCS_AGE_RECIPIENT=age1...
+                                            # Environment=LANES_DOCS_AGE_IDENTITY=/home/<you>/.config/lanes/docs-age.key
+python3 ~/.local/share/lanes/current/libexec/docs_store.py check-age && systemctl --user restart lanes-docsd.service
+```
+
+**docs.log** (`~/.local/state/lanes/docs.log`, 0600, append-only, DM-LANES-DOCS-LOG): `<at> <login> <event> <id> <lane>
+<bytes> <sha256> <outcome>` — docsd adds `denied` (outcome = the refusal word; the first refusal of a source and word,
+the login cut to 64 characters) and `denied-repeat` (one a minute while that source keeps being refused: the `bytes`
+field is how many refusals the line folds, the login the latest), `view`/`raw`/`artifact`/`receipt` (`ok`,
+`not-found`, `encrypted`, `busy`, and `view … rate-limited` once a window), `upload` (a refusal before any file
+reaches intake, `request-timeout` included) and `publish` (one per request the pick-up takes: `ok` or the refusal
+reason — the precise word, also where the receipt says `not-delivered`); each stored file is intake's own `intake`
+line; `lanes upload` adds `upload … no-owner`/`no-lane`/`too-many` lines with a file's size and sha256 when it lands
+without a document. Never content, a title or a file name. At 8 MiB the file is renamed `docs.log.1` (replacing the
+one before) and a new one begun, by whichever writer finds it full first (an exclusive `flock`; the others append to
+the new file), so the two files never hold much more than 16 MiB. Before the security review (2026-10-08) refusals
+from any tailnet device appended 269 B each without bound (DEF-1913).
+
+**Publish pick-up (W10 W4).** `lane publish <file>` and the agents' `lanes_publish` write a request in the container,
+`~/.lz/state/publish/<lane id>/<id>.json` (`{v: 1, path, title, kind, claimed_sha256, mime, bytes, for}`;
+DM-LANES-PUBLISH-REQUEST). A thread of `lanes-docsd` takes them every 5 s — for each container `containers.json` names
+whose init pid is alive (a pid whose `/proc/<pid>/root` is the host's own `/` is skipped, and so is one whose
+`/home/coder` is not the home volume `containers.json` records, when this account can see that volume), at most 16 per
+container per cycle and 30 per container per 10 minutes (more are refused `rate-limited`). It first surveys the
+container's publish directory and lane directories, at most 4,096 entries in all; a container that holds more is
+refused for the cycle (Limits above). It renames the request to `.<id>.taking` (a directory planted at that name is
+removed when empty, else moved aside to `.<name>.<random>.planted`; a request it still cannot rename is left alone, the
+next one is taken and the journal says why once), reads it, resolves the file inside
+the container to a regular file under `/home/coder` (never through a link, never a FIFO), streams it into the store and
+compares the sha256. The answer is written back beside the request as `<id>.receipt.json` (0644; DM-LANES-PUBLISH-RECEIPT):
+
+```json
+{"v": 1, "id": "<document id>", "request": "<id>", "sha256": "…", "bytes": 1234, "url": "/lanes-docs/d/<document id>", "at": "2026-10-08T12:00:00Z", "outcome": "ok"}
+{"v": 1, "id": null, "request": "<id>", "sha256": null, "bytes": null, "url": null, "at": "…", "outcome": "refused", "reason": "outside-home"}
+```
+
+then the claim is removed and the lane keeps its 16 newest receipts (a directory planted at the receipt's name is
+removed or moved aside first, so the answer is always written). A refused receipt carries the host's sha256 and size
+when it read the file (`sha256-mismatch`, `too-large`). Refusal reasons (the receipt's word):
+
+| Reason | Meaning |
+|---|---|
+| `unreadable-request` | the request is not a regular JSON object file of at most 16 KiB (a link, a FIFO, a directory, not JSON) |
+| `bad-version` · `bad-request` · `bad-kind` · `bad-title` | `v` is not 1; a field of the wrong type (`path` not absolute, `claimed_sha256` not 64 hex, `bytes` not a count); `kind` not `md`/`html`/`svg`/`file`; a title that is not one printable line of at most 200 characters |
+| `too-large` | the claimed or the real size is over 32 MiB |
+| `unknown-lane` | the registry places no lane of that id in this container |
+| `rate-limited` | over 30 requests from this container in 10 minutes |
+| `not-delivered` | `for` names a login that owns no member record, or — no `for`, nobody opened the lane — no member record grants its workspace. One word for both (security review 2026-10-08, DEF-1915): the two words told a container whether a login it named is a member. `docs.log`'s `publish` line keeps the precise one, `for-not-a-member` or `no-recipient`; a `for` that names a member still answers `ok` |
+| `outside-home` | the path, every link resolved inside the container, is not under `/home/coder` |
+| `not-a-file` | missing, a directory, a FIFO or device, or a link appeared on the way after it was resolved |
+| `sha256-mismatch` | the file's bytes are not the ones the request hashed (it changed): nothing is stored |
+| `invalid` | the store refused it (a name or login it cannot hold) |
+| `error` | anything else went wrong after the claim (the journal names it): the request is answered and removed, never dropped silently |
+
+Who it is for: `for` (stored in that member's store, for them alone); else the member whose profile last opened the lane
+(`users/<login>.json` `last_opened`); else every member whose record grants the lane's workspace (`for` empty). A busy
+store leaves the request for the next cycle, and without a `registry.json` nothing is taken (the requests wait). Each stored document sends one `published` push through notify (above;
+at most one per lane per minute). From inside a container the latest answer is `lanes_status`'s `published`, or:
+
+```sh
+ls -t ~/.lz/state/publish/<lane id>/ | head; cat ~/.lz/state/publish/<lane id>/<id>.receipt.json
+```
+
+A crash between the claim and the receipt leaves `.<id>.taking` without a receipt; publish again.
+
+**Caddy picks up the route** as for `/enrol/*` (section "Enrolment service"): a server install restarts a running
+`lanes-mobile`; after editing the Caddyfile in place, `systemctl --user restart lanes-mobile.service`. If
+`/lanes-docs/` answers with the Zellij page, `lanes-mobile` runs an older Caddyfile. Settings go in a drop-in:
+
+```sh
+systemctl --user edit lanes-docsd.service        # [Service] Environment=LANES_DOCS_DOMAINS=beyondwork.ai,example.com
+systemctl --user restart lanes-docsd.service
+```
+
+### Mermaid pin
+
+The docs page (plan W10, `docs/superpowers/plans/2026-10-08-lanes-docs-cockpit.md`) draws ```` ```mermaid ```` fences
+with Mermaid 11.17.2, pinned in `holders.lock` as an opt-in line: the npm tarball's sha256 and the sha256 of its member
+`package/dist/mermaid.min.js`, the classic-script build (3 572 661 B). The server installer's pinned-binaries loop
+skips it; `install/enable-docs.sh` installs it. As the workspace account, `sh
+~/.local/share/lanes/current/install/enable-docs.sh` downloads the tarball into a
+temporary directory, refuses unless both digests match, and installs `~/.local/share/lanes/vendor/mermaid-11.17.2.min.js`
+(0644; `$LANES_SHARE/vendor`) and the link `mermaid.min.js`; run again, it finds the pinned digest and downloads
+nothing. Exit status: 0 installed or present, 1 a prerequisite or the download failed, 2 usage, 3 refused (no valid
+pin, a digest mismatch, the member missing or not a regular file) — a refusal installs nothing.
+
+**The server install runs it (plan W8, LNS-109), never fatally.** The full `./install.sh --server` (or `npx
+@vibelord/lanes@<release> --server`) runs it right after `lanes-docsd`'s enable and restart, shows its own line, goes
+on whatever it exits, and ends its summary with one line: `Mermaid for the docs page: ok`, `… skipped (<its last
+line>) — diagrams show as source until sh <tree>/install/enable-docs.sh succeeds` (exit 1: a prerequisite or the
+network), `… refused (<its last line>) — nothing was installed; see RUNBOOK "Mermaid pin"` (exit 3), or `… failed (exit
+N: …)`; `--no-start` does not run it and says so. **An update (`--update-only`)** runs it as the post-commit step
+`enable-docs`, right after `try-restart lanes-docsd` (`libexec/update.py` `DOCS_STEP`; a release rolled back to that
+has no script gets no step): exit 0 is `ok`; exit 1, and a download stopped after the step's 300 s (`rc` 124), are
+recorded `"warning": true, "outcome": "skipped"`, exit 3 `"warning": true, "outcome": "refused"`, each with `reason`
+(the script's last line) — warnings, so the update stays `ok` and `lanes update` does not re-run the post-commit for
+them; any other status is a failed step (`"outcome": "failed"`, `partial`). The update's summary line names it:
+`…; every step ran; mermaid skipped: enable-docs: download failed: https://… — log …`. A re-run (every update, every
+install) finds the pinned file and downloads nothing. To install by hand after a skip, run the script; `lanes doctor`
+says which state the pin is in ("What `lanes doctor` says" below). Caddy serves the directory at `/lanes-assets/vendor/`
+(`lanes-mobile.service`; a new Caddyfile takes `systemctl --user try-restart lanes-mobile.service`, which the server
+installer does) as `immutable`, so `web/docs.js` names the versioned file and carries the member digest as its SRI
+(DEF-1870). Without the file, or on an integrity mismatch, every fence shows its source as a plain `<pre>`. Check:
+`curl -sI http://127.0.0.1:8083/lanes-assets/vendor/mermaid-11.17.2.min.js` answers 200 with `cache-control: public,
+max-age=31536000, immutable` (step 3 of "Operator verification" below; DEF-1871 stays open until that is seen on a
+server).
+
+The pin needs no `'unsafe-eval'` (MEASURED 2026-10-08): the member has no `new Function(`; its four
+`Function("return this")` (lodash's global lookup) sit behind `self`, which every page has, and its one `(0,eval)`
+(chevrotain) follows a `return`. In headless Chromium 153 under `default-src 'none'; script-src 'self'; style-src
+'self' 'unsafe-inline'`, docs.js drew a flowchart and a sequence diagram with no violation, while a control page's
+`eval` was refused and reported. Mermaid's SVG needs `style-src 'unsafe-inline'` (without it: unstyled, 88 violations).
+
+To bump the pin (12.x — npm's latest, 12.1.0 on 2026-10-08 — is a separate decision): download the tarball once
+(`curl -fsSLO https://registry.npmjs.org/mermaid/-/mermaid-<v>.tgz`) and compare its sha512 with `npm view
+mermaid@<v> dist.integrity`; take `sha256sum mermaid-<v>.tgz` and `tar -xzOf mermaid-<v>.tgz
+package/dist/mermaid.min.js | sha256sum`; check that the member is still a classic script (no `import`/`export`, ends
+by assigning `globalThis["mermaid"]`) and repeat the `'unsafe-eval'` check above. Then change, in one commit, the
+`mermaid` line of `holders.lock` (and its comment) and `SRC`/`SRI` in `web/docs.js` — the SRI is `sha256-` plus the
+base64 of the raw member digest: `python3 -c 'import base64,sys; print("sha256-" +
+base64.b64encode(bytes.fromhex(sys.argv[1])).decode())' <member-sha256>`. `test_docs_assets` and
+`tests/web/docs.test.mjs` are red while the lock and docs.js disagree. The install or update of that release runs
+`enable-docs.sh`, which downloads the new pin (a skip says why: run it again by hand); older `vendor/mermaid-*.min.js`
+files stay (harmless; remove them by hand).
+
+### What `lanes doctor` says
+
+Five lines (plan W8, LNS-109), after the browser/phone lines and before the release lines, read-only (one bounded
+`systemctl --user show`, one loopback connect that sends nothing — docsd answers nothing and writes no docs.log line
+for it — and file reads):
+
+| Line | Marks |
+|---|---|
+| `lanes-docsd.service active, answering on 127.0.0.1:8185` | `✓` enabled, active and the port (its drop-in's `LANES_DOCS_PORT`, else 8185) accepts a connection; `✗` `enabled but failed` (or any state but active), `active, but 127.0.0.1:8185 does not answer`, a `LANES_DOCS_PORT` that is no port, or systemctl silent — each with `journalctl --user -u lanes-docsd.service; systemctl --user restart lanes-docsd.service`; `⚠` `not enabled, so there is no docs page` (the full server install enables it; `--update-only` never does) or active but not enabled (a reboot loses it) |
+| `docs: pinned — lanes-docsd answers members through Tailscale Serve` | `✓` `enrol-mode` pins `request`, read as docsd reads it on every request; `⚠ docs: refuses until the Serve header check is pinned (unpinned: auto \| pinned invite only \| <why the pin cannot be read>)` with the pointer to "Enrolment service" (Operator verification) and this section — an operator gate, never a `✗` |
+| `docs store: N documents in M lanes (counts.json), <size> under ~/.local/state/lanes/docs; docs.log <size>` | information: the documents and lanes `docs/counts.json` counts, the bytes of the regular files under `docs/` (never through a link), docs.log's size (`no docs.log yet`) |
+| `docs: Mermaid 11.17.2 pinned (~/.local/share/lanes/vendor/mermaid-11.17.2.min.js, sha256 581ed7d74bd9…)` | `✓` a regular file whose sha256 is `holders.lock`'s member digest; `⚠ … not installed …, so diagrams show as source — run sh …/install/enable-docs.sh`; `✗ … refused — … is not the pinned build (sha256 …, holders.lock …)` or `… is not a regular file` (a link or a FIFO, never followed or waited on) — browsers refuse it by its integrity; the script replaces it from a verified download; `✗ docs: Mermaid not checked — …/holders.lock: …` without a valid opt-in pin |
+| `docs: age encryption off (LANES_DOCS_AGE_RECIPIENT unset; age at /usr/bin/age)` | information while the switch is off (and whether an `age` is on PATH); `✓ … on — new store copies are age output (age at …); lanes-docsd opens them with LANES_DOCS_AGE_IDENTITY` (or `no LANES_DOCS_AGE_IDENTITY, so their downloads answer 409 encrypted`); `✗` set without an `age` binary (every upload and publish fails `encrypt-failed`) or a value that is no recipient. The recipient is never printed. The `age` looked for is the one on doctor's PATH, which may not be the unit's |
+
+### Operator verification (docs plan gate 1, not yet run on ceobox)
+
+Unit-proven only so far: `tests/unit/test_docsd.py` runs a real docsd on a loopback port, `test_install.DocsRoute`
+models the shipped Caddyfile's routes and headers in front of it, `test_docs_assets.VendorRoute` models Caddy's route
+sort for the Mermaid route, and `tests/web/docs.test.mjs` and `tests/web/upload.test.mjs` drive the page scripts
+against fakes. Nothing below has been run on a server, a phone or a real browser. After the server install of the
+first release with the docs cockpit (1.3.0), run it once, in order, and record the date, the devices and each step's
+result here:
+
+1. **Install.** On the server, the full install: `npx @vibelord/lanes@1.3.0 --server` — it enables and restarts
+   `lanes-docsd`, restarts `lanes-mobile` on the new Caddyfile and runs `enable-docs.sh`; its last lines say
+   `Mermaid for the docs page: ok`. Then `lanes install-container <name>` for each container whose agents should
+   publish (the `lane publish` verb and the `lanes_publish` tool; new agent sessions load the tool).
+2. **Pin.** From another tailnet device signed in as yourself, run the Serve header check (section "Enrolment
+   service", Operator verification); on the server, `lanes enrol mode request`. `lanes doctor` then shows
+   `✓ lanes-docsd.service active, answering on 127.0.0.1:8185`, `✓ docs: pinned …` and
+   `✓ docs: Mermaid 11.17.2 pinned …`.
+3. **The Mermaid route (DEF-1871).** On the server, `curl -sI
+   http://127.0.0.1:8083/lanes-assets/vendor/mermaid-11.17.2.min.js` answers `200` with `cache-control: public,
+   max-age=31536000, immutable`. Seen once on the server, that closes DEF-1871 (the route proven on a running Caddy,
+   not only on a model of its sort).
+4. **Publish.** In a lane of a container from step 1, `~/.lz/bin/lane publish README.md` (a README with a
+   ```` ```mermaid ```` fence; add a small flowchart if it has none). The JSON says `"picked_up_by": "lanes-docsd"`;
+   within about 5 s `cat ~/.lz/state/publish/<lane id>/<id>.receipt.json` says `"outcome": "ok"` with a `url`.
+5. **Sidebar.** Within a few seconds that workspace's upload strip reads ` ↑ uploads · ▤ docs 1  (U)`. With the
+   cursor on the lane, `d` shows `https://<name>:8443/lanes-docs/?ws=<workspace>&lane=<lane id>` in the footer; a
+   ⌘-click or Ctrl-click on it (or on the strip) opens the page.
+6. **Phone.** **More → Docs** opens the index in a new tab, signed in as you; the README opens rendered and its
+   ```` ```mermaid ```` fence is drawn as a diagram, not shown as source.
+7. **Artifact sandbox (DEF-1853).** Publish an HTML file whose script tries to reach this site and writes what it
+   got into its own page: `fetch('/lanes-docs/')`, `fetch('/')`, `document.cookie`, and a WebSocket to the same
+   server's `/ws/` path that the terminal page itself opens (the browser's network panel on a view shows it). **Open
+   the HTML artifact**: the script runs (the page shows its writing), every one of those attempts fails or comes back
+   empty, and no lane receives a keystroke. Record the browser and what each attempt answered: that is DEF-1853's
+   measurement.
+8. **Upload.** On the Docs page pick a lane, drop a file on the dashed area, **Upload**: the receipt lists the name,
+   size, sha256 and `/home/coder/<repo>/uploads/<name>`; in that lane's shell, `sha256sum
+   /home/coder/<repo>/uploads/<name>` prints the receipt's sha256. The sidebar's count goes up by one.
+9. **Not a member.** From a tailnet login that owns no member record, `https://<name>:8443/lanes-docs/` answers 403
+   `not-a-member`; on the server, `curl -s http://127.0.0.1:8185/` answers `{"error": "not-through-serve"}`.
+10. **Forged header: the known DEF-1645 case.** A process in the host's network namespace can send Serve's headers
+    itself: list such containers with `docker ps --filter network=host` and record the answer. From one (or from the
+    host as the workspace account), `curl -s -H 'Tailscale-User-Login: <a member login>' -H 'Tailscale-User-Name: x'
+    -H 'X-Forwarded-For: 100.64.0.9' -H 'Sec-Fetch-Site: none' http://127.0.0.1:8083/lanes-docs/` is answered as that
+    member. That is expected and stays DEF-1645 (open): the pin gate and the Serve-only check are the controls against
+    every other client, not against a process on this host. If another account or a host-network container exists,
+    weigh `lanes enrol mode invite` (which also stops the Docs page) against it.
+
 ## Safety rules baked into the code (do not remove)
 
 - tmux is always called with `-N` (`attach-session`, `new-session` and `start-server` on a missing socket start