@vibelord/lanes 1.1.1 → 1.3.0

package/payload/lanes/docs/USERGUIDE.md

@@ -4,7 +4,7 @@ Lanes keeps long-running agent terminals on one Linux workspace host and lets ev
 same terminals: a terminal window on a Mac or Linux desktop, Safari on a phone, a browser on a laptop or tablet, and
 the Cursor / VS Code terminals inside the workspace containers. This guide is the day-to-day reference for operators
 and teammates, and the install and update path for the administrator. It describes the tree it ships in; run
-`cat lanes/VERSION` (or `lanes hello` on the server) for the version.
+`cat lanes/VERSION` (or `lanes version` on the server) for the version.
 
 Companion documents: [README](../README.md) (overview and quick start) · [INSTALL](INSTALL.md) (full setup) ·
 [RUNBOOK](RUNBOOK.md) (operations and incidents) · [ARCHITECTURE](ARCHITECTURE.md) (how the parts fit) ·
@@ -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 |
 
@@ -69,7 +69,7 @@ The server's catalog orders the tabs.
 | Kind | Comes from | In the sidebar |
 | --- | --- | --- |
 | Repository lane | A terminal declared in a repository's `.vscode/terminals.json` | The workspace's list; no close control |
-| Registered session | An observed session adopted with **Add to workspace** or `lanes register` (saved in `registered-sessions.json`) | The workspace's list; no close control |
+| Registered session | An observed session adopted with **Add to workspace** or `lanes register` (saved in `registered-sessions.json`) | The workspace's list; no close control; `u` (or `lanes unregister`) moves it back to Unregistered |
 | Unregistered session | Any other tmux session observed in the workspace's container: a **New shell**, a session you started by hand, a Throttle Studio `st_…` session | **Unregistered (N)**; can be opened, renamed, added, promoted or closed |
 
 **The terminal status** (sidebar column 33) is one of six words `lanes-statusd` publishes, plus `helper` for a tool
@@ -97,11 +97,17 @@ attention sections:
 | Needs you | `✗` | `X` | errored | The turn failed |
 | Needs you | `◇` | `?` | needs_input | The turn finished; waiting for your prompt |
 | Working | `▸` | `>` | working | The agent is working |
-| Done | `✓` | `v` | done | The turn finished; stays until you open the lane from this device |
+| Done | `✓` | `v` | done | The turn finished; stays until you open the lane — from any device of yours when the device has an owner, else from this one |
 | (rest) | `_` | `_` | shell | The harness ended into a shell |
 | (rest) | `·` | `.` | idle | The harness is up, no turn |
 | (rest) | blank | blank | — | A plain shell, no agent signal |
 
+A lane moves up into a section (Needs you above Working above Done) at once, and down only after the agent has
+been doing the less urgent thing for 8 s (leaving Needs you) or 5 s (leaving Working or Done), so a lane whose
+agent flickers between two states stays where it is. A lane whose agent signal disappears keeps its glyph for 5 s.
+Inside a section lanes keep the order in which they entered it, and the list does not scroll under your cursor
+(section 3, "The sidebar").
+
 **What Throttle adds.** Lanes runs without Throttle. With the opt-in economy poller (section 8) the sidebar shows a
 fleet economy strip (overflow spend against the daily cap, new 429s, model tiers, spill, free accounts) and one
 economy cell per lane (`⚠` starving, `↓` downgraded, `$` mostly paid). Throttle's **Shared lanes** console and the
@@ -148,6 +154,7 @@ A member of the site sends you an invite: five lines from `lanes invite` ("Invit
 | Step | The installer prints |
 | --- | --- |
 | Site | `site beyondwork, inferred from the invite code's prefix LN` (npm only; an explicit `--site` wins) |
+| Release | Only when the server runs a newer release than the package you ran (npm only; see below): `server runs 1.2.0: fetching that installer first (this one is 1.1.0; nothing is installed yet, and the invite is kept for it)`, then `lanes-install: the server runs 1.2.0: npx --yes @vibelord/lanes@1.2.0, with the same options` — the server's release then prints every row below and redeems the code |
 | Tailscale | `tailscale: connected as <login> (<address>)`, after opening the login when needed ("Tailscale" below) |
 | SSH alias | `ssh: host alias 'lanes' -> dev@<MagicDNS name> (fallback lanes-ip -> <tailnet address>), key …` |
 | Invite | `invite: redeemed — this machine's key is now authorized for <login> (device <device>)` |
@@ -158,6 +165,19 @@ request body (never on a command line) and never prints or stores it, and a code
 with echo off. A code whose prefix belongs to another site is refused before anything is installed. Phone and
 browser views: section 4. Uploads: section 5.
 
+The code is redeemed by the server's own release (W9 K3). With an invite, the npm installer first asks the site's
+enrolment service which release the server runs (`GET /enrol/site`, one call of at most 15 s; on a tailnet site only
+when this machine is already connected, so join the tailnet first, step 1 — it never opens the Tailscale login for
+this). When the server runs a newer release than the package, that run ends before anything is installed, sent or
+redeemed, and the wrapper runs `npx --yes @vibelord/lanes@<release>` with your options instead — the code passes
+through the environment, not a command line — once: that installer never asks again. When it cannot, the wrapper says
+why in one line and the package you ran installs and redeems the code as before: no npx with its npm on the PATH, npm
+not answering, or a release npm does not have yet (`lanes-install: the server runs 1.2.0, which npm does not have
+(yet): installing 1.1.0 from this package instead` — a server run from a checkout names its `VERSION` before the
+release is published). A window then updates that client by itself once npm has the release ([Versions](#versions)).
+`LANES_NO_SELF_UPDATE=1` (or `LANES_NO_AUTOUPDATE=1`) installs exactly the package you ran. A checkout's `./install.sh`
+only says `server runs 1.2.0; this installer is 1.1.0 — going on with 1.1.0`.
+
 When the server already has a device of this machine's name — two laptops with one hostname, or a replaced laptop
 whose old enrolment is still there — it answers `409 (device-taken)` and uses nothing up: the installer says so and
 names the re-run, `npx @vibelord/lanes --invite <code> --device <another name>` (it remembers the name). If the old
@@ -215,12 +235,15 @@ lanes-window                             # open the desktop view
 | `--site NAME` | A bundled profile (`beyondwork`); a value containing `/` or ending in `.conf` is your own file |
 | `--stage-only` | Copy the bundled tree to `~/.local/share/lanes/pkg/<version>/` and print the path; run nothing |
 | `--version` | Print the package version |
-| `--invite CODE` | Hand the code to the installer; without `--site`, the code's prefix picks the bundled profile ("Join with an invite" above) |
+| `--invite CODE` | Hand the code to the installer; without `--site`, the code's prefix picks the bundled profile ("Join with an invite" above). When the server runs a newer release, its installer runs instead and redeems the code (`LANES_NO_SELF_UPDATE=1`: this package) |
 | `--wrapper-help` | Wrapper help only |
 
 Every other option goes to `install.sh`. The wrapper stages the tree under `~/.local/share/lanes/pkg/<version>/`
-(`$LANES_PKG_ROOT` overrides the parent), reuses an identical tree, and keeps the newest three versions plus any
-version a server unit still runs from. See [`npm/lanes/README.md`](../../npm/lanes/README.md).
+(`$LANES_PKG_ROOT` overrides the parent, under any name: the wrapper's `.lanes-package.json` stamp in the tree is what
+marks it as staged, so its views follow `~/.local/share/lanes/current` like any other), reuses an identical tree, and
+on a client (no `~/.local/share/lanes/current`) keeps the newest three versions. A server's trees are pruned by `lanes
+gc` instead, which also keeps every older tree still in use ([systemd user units](#systemd-user-units)). See
+[`npm/lanes/README.md`](../../npm/lanes/README.md).
 
 ### Client from a checkout
 
@@ -305,7 +328,9 @@ the server (a profile without such a name skips this):
 
 The same for `./install.sh` and `npx @vibelord/lanes`: `0` ready · `3` installed, but this machine's key is not yet
 authorized on the server · `4` installed, but this machine is not in the tailnet, or the server is unreachable or
-did not answer in time · `1` error.
+did not answer in time · `1` error. `install.sh` also ends with `5` — nothing installed, the server runs a newer
+release — but only when the npm wrapper asks for that (`LANES_WRAPPER_REPLY`, [Join with an
+invite](#join-with-an-invite)); the wrapper then runs that release, and `npx @vibelord/lanes` ends with its status.
 
 ### Server
 
@@ -323,14 +348,21 @@ sudo loginctl enable-linger <account>    # administrator, once: services stay up
 | --- | --- |
 | `--check` | Check prerequisites, the user manager and Docker; print `Server prerequisites: ready`; change nothing |
 | `--no-start` | Install files and units without contacting Docker or starting services |
+| `--update-only` | An update (W9 U2) of a server a full install set up (refused when none is installed): install this release, then restart what runs it — every step after the switch runs even when one before it failed — and record the run in `~/.local/state/lanes/update/last.json` ([Update](#update)) |
 | `-h`, `--help` | Usage |
 
 A normal server install verifies and installs the pinned binaries from `holders.lock` (Zellij 0.45.1, zmx 0.8.1, and
 glow 3.0.0 unless a glow is already on the view server's PATH) into `~/.local/share/lanes/bin`, adds the
 `xterm-lanesview` terminfo alias, renders every unit in `lanes/systemd/` into the user manager's unit directory,
-links `~/.local/share/lanes/current` and `~/.local/bin/lanes` to this checkout, creates an empty catalog only when no
+links `~/.local/share/lanes/current` to this checkout (moving it last, in one step: the units, `~/.local/bin/lanes` and
+the view layouts name that link, never the checkout path, and `current.previous` keeps the tree it named before; only
+this installer moves the link — `lanes web` and `install/enable-studio-host.sh` re-render the units of the release it
+names),
+creates an empty catalog only when no
 configuration exists, runs `lanes sync`, and enables `lanes-statusd.service`, `lanes-sync.timer`,
-`lanes-ensure.timer`, `lanes-gc.timer` and the enrolment service `lanes-enrold.service` (restarted by every install, so
+`lanes-ensure.timer`, `lanes-gc.timer`, the update timer `lanes-update.timer` (an npm-installed server then installs
+each newer release itself, [Update](#update); a checkout is left alone) and the enrolment service
+`lanes-enrold.service` (restarted by every install, so
 it runs the installed code; it restarts a running `lanes-mobile` too, so Caddy reads the new `/enrol/*` route). Web
 access, the Studio Host, the economy poller, push notifications,
 the `/tmp` reaper and the OOM guards stay off (section 11 lists each unit).
@@ -343,12 +375,14 @@ lanes sync
 lanes doctor
 ```
 
-`lanes install-container <name>` is additive. In that container's home it copies `lane`, `lane-run` and
-`lane-signal` into `~/.lz/bin/`, the agent hook definitions into `~/.lz/hooks/`, and `env.sh` into `~/.lz/env.sh`;
+`lanes install-container <name>` is additive. In that container's home it copies `lane`, `lane-run`, `lane-signal`
+and `lane-edit` into `~/.lz/bin/`, the quick-edit `vimrc` into `~/.lz/vimrc`, the agent hook definitions into
+`~/.lz/hooks/`, and `env.sh` into `~/.lz/env.sh`;
 it creates `~/.tmp` and appends one marker-guarded line (`# lanes-env`) to the login files (`.bash_profile` or
 `.profile`, `.bashrc`, and `.zshrc` when it exists) so new shells keep temp files off the RAM-backed `/tmp`; it copies
 the pinned zmx binaries without overwriting a running one; and it links `~/.lz/<container>` on the host. It installs
-no agent hook (section 7).
+no agent hook (section 7) and no editor: `Ctrl-Alt-e` uses one the container already has, and vi is the floor
+([section 7](#the-in-container-lane-command)).
 
 For a new user's container, `lanes onboard <login> --container <name> --workspace <id> --repo /home/coder/<repo>`
 prints every step and changes nothing. It checks the container first, so an unknown container stops it before the
@@ -401,38 +435,179 @@ redeemed from a second machine yet.
 
 | Where | Update | Then |
 | --- | --- | --- |
-| Client (npm) | `lanes-launch update`, which runs `npx --yes @vibelord/lanes@latest` with every choice in `~/.config/lanes/install-options` given again as its flag (the command is printed first; flags you add follow them and win, e.g. `lanes-launch update --no-palette`); or `npx @vibelord/lanes@latest` yourself (your remembered options are repeated; add a flag only to change one) | `npx @vibelord/lanes --check` |
+| Client (npm) | Nothing, usually: a window updates its client itself when the server is newer and npm has the server's release, at most every 6 h ([Versions](#versions); `LANES_NO_AUTOUPDATE=1` turns that off). By hand: `lanes-launch update`, which runs `npx --yes @vibelord/lanes@latest` with every choice in `~/.config/lanes/install-options` given again as its flag (the command is printed first; flags you add follow them and win, e.g. `lanes-launch update --no-palette`); or `npx @vibelord/lanes@latest` yourself (your remembered options are repeated; add a flag only to change one) | `npx @vibelord/lanes --check` |
 | Client (checkout) | `git pull`, then `./install.sh` (`lanes-launch update` refuses a client that runs from a checkout: npm would replace it with a copy) | `./install.sh --check` |
-| Server (npm) | `npx @vibelord/lanes@latest --server` (runs from `~/.local/share/lanes/pkg/<version>/`; older trees a service still uses are kept) | the restarts below |
-| Server (checkout) | `git pull` in the installed checkout, then `./install.sh --server` (configured workspaces and agent sessions are preserved) | the restarts below |
-
-After a server update:
+| Server (npm) | Nothing, usually: `lanes-update.timer` installs each newer release within about 30 min of its publish (below) — once it is enabled: the full `--server` install enables it, an update with `--update-only` never does, so a server set up before 1.2.0 needs `npx @vibelord/lanes@latest --server` once, or `systemctl --user enable --now lanes-update.timer`. By hand: `lanes update --now`, or `npx @vibelord/lanes@latest --server --update-only` (runs from `~/.local/share/lanes/pkg/<version>/`; older trees a service still uses are kept), which makes the restarts below itself; without `--update-only` the full install runs | `lanes version`; `lanes update --status`; `lanes doctor` |
+| Server (checkout) | `git pull` in the installed checkout, then `./install.sh --server --update-only` (or the full `./install.sh --server`; configured workspaces and agent sessions are preserved) | the restarts below |
+
+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, 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
+previous lanes sync keeps — is reported as `WARN` and leaves the result `ok`: fix the board, not the update. The run
+ends `ok`, `partial` (installed; a step after the switch failed — run it by hand), `refused` (nothing changed: a
+prerequisite said no, no release is installed yet — run the full `--server` install first, it enables what an update
+restarts — or another install or update is running, in which case nothing is recorded either) or `failed` (nothing was
+installed); `~/.local/state/lanes/update/last.json` keeps the result and each step's exit status, `update/last.log`
+every step's output. One install or update runs at a time. After a full install, or for a step `--update-only`
+reports as `FAIL`:
 
 - `systemctl --user restart lanes-statusd.service` (the status observer runs the old code until restarted).
+  `lanes version` then lists statusd among the names before its `✓`; each name it still marks `✗` started before
+  the update: `runs 1.1.0 ✗` after an npm update (it runs the previous `pkg/<version>` tree), `started before its tree
+  changed ✗` after a checkout update (the checkout keeps its path; `git pull` gave the code a newer time than that
+  start).
 - When web unit definitions or the pinned Zellij changed: `systemctl --user restart lanes-web.service
   lanes-mobile.service`; browsers reconnect.
 - When the Studio Host is enabled: re-run `sh install/enable-studio-host.sh` (it checks, then restarts the Host).
 - Re-run `lanes install-container <container>` to update the in-container `lane` contract; an older `lane` refuses a
   newer registry with exactly that hint.
 - Existing view sessions keep their layout. `lanes upgrade-session` (also run by every `lanes sync`) adds new tabs and
-  renames titles without a rebuild; a changed pane layout needs `lanes rebuild <device>` (agents are never touched).
+  renames titles without a rebuild, and closes the tab of a workspace your profile hides; a changed pane layout needs
+  a rebuild (agents are never touched). The update's last step, `lanes ensure --if-layout-changed`, makes it where it
+  can: a view whose tabs the new release lays out differently is rebuilt when no client is attached to it; one you are
+  looking at keeps running and its sidebar footer says `update ready · reload (r)` — press `r` in the sidebar (or run
+  `lanes rebuild <device>`) when it suits you: the window reconnects. Close the window instead and
+  `lanes-ensure.timer` rebuilds it within a minute. A full `--server` install does not run that step: run `lanes
+  ensure --if-layout-changed` yourself afterwards.
+  A layout built by 1.2.0 or later names its sidebar and viewports through `~/.local/share/lanes/current`, so running
+  views move onto the new release by themselves: each sidebar notices the new version within 30 s and, as soon as
+  nothing is open on it (no prompt, filter being typed, armed upload strip, picker, key sheet, action, undo offer,
+  upload or `r` rebuild on its way), saves its cursor, scroll, opened-lane marks and filter and restarts from the new
+  tree (a ~100 ms repaint). The update's `lanes reload-views` tells each viewport (`view.sh`) that can take it to
+  re-execute itself from `current` the next time its lane's viewer ends by itself — a detach, a switch to another
+  lane, the end of a status screen — never by cutting an attached lane (by hand: `kill -USR2 <pid>`, its pid in
+  `~/.local/state/lanes/views/<device>/<workspace>.<slot>.pid`; only a viewport of 1.2.0 or later — an older one ends
+  on that signal, so `lanes reload-views` names it and leaves it alone). A layout built before names its
+  `pkg/<version>` tree and stays on it until `lanes rebuild <device>` (`lanes doctor` warns; its footer says ` server …
+  · view … — ?`). Either kind keeps its tabs: `lanes sync` recognises them by the file they run.
+- `lanes doctor` then names whatever still runs the previous code, each with its fix: a process that runs with an
+  older run record, or with none at all (it was started by a release before the records, such as a statusd or a
+  sidebar still running from 1.1.0), a device layout that runs the old tree (`lanes rebuild <device>`),
+  a unit whose `ExecStart` does (re-run the server installer). See [`lanes doctor`](#lanes-doctor).
 
 Back up the catalog (`~/.config/lanes/workspaces/`, including `registered-sessions.json`) and the running checkout
-before a server update. To roll back, restore those files; do not rebuild device sessions as a rollback shortcut.
+before a server update. An npm-installed server rolls back with `lanes update --rollback` (below); a checkout, by
+checking out the previous commit and running `./install.sh --server --update-only`. Do not rebuild device sessions as a
+rollback shortcut.
+
+**Automatic server updates (W9 U3).** A full `--server` install enables `lanes-update.timer`: 15 minutes after a boot,
+then every 30 minutes (each time up to 5 minutes later, at random), it runs `lanes update --timer`. On a server the npm
+installer set up (`~/.local/share/lanes/current` names a staged `pkg/<version>` tree), that:
+
+1. runs the post-commit of the installed release again when the last update ended `partial` (from the timer once per
+   release, since a cause that stays would restart every service every 30 minutes; by hand every time);
+2. asks the npm registry which release the dist-tag `latest` names — or `lanes-stable`, with the line `channel=stable`
+   in `~/.config/lanes/update.conf` (`#` comment lines; any other channel is refused and nothing is asked) — unless a
+   check answered less than 20 minutes ago (`lanes update --now` asks anyway);
+3. installs it when it is newer than the installed release (major.minor.patch as numbers: never a downgrade) and not
+   the release a rollback left (`bad`), with the npx the npm installer recorded when it installed the server
+   (`~/.local/state/lanes/update/npx`; a unit's PATH has no Node.js): `npx --yes @vibelord/lanes@<release> --server
+   --update-only`, the update described above. The economy poller's, the notifier's and `LANES_WORKSPACES` settings
+   the installed units carry are given to it again, so the units it renders keep them.
+
+Only the full install enables the timer: an update (`--update-only`) enables nothing, the timer included. A server set
+up before 1.2.0, the first release with `lanes update`, and updated since with `npx @vibelord/lanes@latest --server
+--update-only` therefore has the timer off and installs nothing by itself — run the full `npx @vibelord/lanes@latest
+--server` once, or `systemctl --user enable --now lanes-update.timer`. Until then `lanes doctor` says `⚠ updates: …
+lanes-update.timer is not enabled`.
+
+`lanes update` by hand does the same; one runs at a time. Each check is recorded in `update/last.json` as `check`
+(when, which channel and tag, what the registry named, what came of it), beside the install's own record; `lanes
+update --status` prints that file, and `lanes doctor` says how long ago the last check was and how the last update
+ended. A registry that does not answer, a recorded npx that is gone (Node.js moved or upgraded: install once by hand
+with `npx @vibelord/lanes --server --update-only` from a shell whose npx works, which records it again) or an install
+that fails changes nothing and exits 1 (the timer's unit then shows as failed); a release older than the installed
+one, or the one marked bad, is not installed (exit 0). A server run from a checkout is left alone (`git pull`).
+
+`lanes update --rollback` installs the release `~/.local/share/lanes/current.previous` names again, in place: this
+release's `install/services.py` renders that tree's units and moves `current` back to it (no network, no npx), the
+release left is marked `bad` in the record — no update installs it again; the next newer release is installed as
+usual — and its post-commit runs. The mark is written the moment `current` moves, with the result `partial`: a rollback
+stopped during its post-commit (Ctrl-C, a dropped SSH session) keeps the mark, and the next timer tick runs the
+post-commit again (Ctrl-C and hangups wait for that moment and its record, then end the run). A second rollback, which
+would put the bad release back, is refused (install it by hand with `npx @vibelord/lanes@<release> --server
+--update-only` if you mean to).
 
 ### Versions
 
 - `lanes/VERSION` is the release version; the npm package version equals it (`npx @vibelord/lanes --version`).
+- The sidebar: `?` shows `lanes <installed> · view <running>` on the key sheet's first row. A server update installs a
+  new tree and points `~/.local/share/lanes/current` at it, while each running sidebar keeps the tree it started from;
+  until it runs the new one its footer says ` server 1.2.0 · view 1.1.0 — press ?` (below the health banner; at 36
+  columns ` — ?`). The installed version is read every 30 s, so the note appears within half a minute. A checkout
+  install is its own tree and never shows it.
 - `lanes hello [device]` on the server prints `ok device=<device> version=<version> boards=<n>`. The client
   installer calls it to prove the SSH path, the key and the server version; an answer without that greeting is
-  reported as "an older server?".
+  reported as "an older server?". A client that adds its own release, `lanes hello --client-version 1.1.0`, gets
+  ` update=<version>` at the end of the line when it is older than the server (`ok device=- version=1.2.0 boards=0
+  update=1.2.0`): the exact release to update to, compared as `lanes attach` compares (major.minor.patch, as numbers:
+  `1.9.3` is older than `1.10.0`). An equal or newer client, `dev` on either side, or no flag gets the plain line.
+- `lanes version` on the server says which release runs there and what still runs an older one, in one line:
+  `lanes 1.2.0 (39998ed) · tree pkg/1.2.0 · current ✓ · statusd runs 1.1.0 ✗ · enrold notify ✓`. In order: this
+  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, 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
+  newest file of the tree's `VERSION`, `bin/` and `libexec/`; docs and web files do not count). Restart it (a stopped
+  service keeps its last record, so its `✗` stays until it starts again). `lanes version --json` prints the same
+  facts as one `lanes.version/1` document: `{schema, version, commit, tree, current, running: {<name>: {tree,
+  version, started, current, changed}}, client_min}` — `started` is the record's time (UTC), `changed` the time of the
+  tree's newest code when it is later than `started` (else null; `current` is false then), `client_min` the release
+  from which `lanes attach` stops telling a `lanes-launch` to update (the server's major.minor.patch; none on a `dev`
+  tree).
 - 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 **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
   dim line before the view opens, and again after it detaches: `lanes client 1.0.4 is older than the server (1.1.0) —
   run lanes-launch update`. A `lanes-launch` from before the flag (1.0.4 or earlier; it has no `update` verb) is told
   `update it: npx @vibelord/lanes@latest` only by a server newer than 1.0.4 — a 1.0.4 server says nothing to it.
   Only major.minor.patch is compared (`1.1.0-rc.1` counts as `1.1.0`); a `dev` version on either side, and your own
   `lanes attach` on the server, get no line.
+- A window updates its own client (W9 K2). Before `lanes-launch` connects a window (a device, a workspace or
+  `lanes-launch lane <id>`), and at most once every 6 h per machine, it asks the server `lanes hello --client-version
+  <its release>` over the same SSH path (`BatchMode`, 5 s to connect, 10 s in all; the dim line `lanes 1.2.0: asking
+  lanes for a newer client…` shows meanwhile). When the answer ends ` update=<version>`, it first asks npm whether it
+  has exactly that release (`npm view @vibelord/lanes@<version> version --fetch-retries=0`, at most 15 s; the dim line
+  `lanes 1.1.0: the server runs 1.2.0; asking npm for it…` shows meanwhile), then runs `npx --yes
+  @vibelord/lanes@<version>` — exactly the server's release, never `@latest` — with the choices in
+  `~/.config/lanes/install-options` given again as flags (as `lanes-launch update` does, without your window's
+  options), then starts again as the new client with the same command line, which connects as usual. That restart
+  carries `LANES_AUTOUPDATED=1` and never updates again, so a window updates at most once. Each question touches
+  `~/.local/state/lanes-client/checked`, answered or not; windows that open at the same moment ask once between
+  them. It never runs for `--helper`, `ls`, `web`, `update` or `--version`, for a client run from a checkout (`git
+  pull` updates that one), or for one without a release. `LANES_NO_AUTOUPDATE=1` in the window's environment turns
+  it off.
+  A release npm does not have yet installs nothing and shows nothing: a server run from a checkout names its
+  `VERSION` as soon as it is pulled, which can be before the release is published, and no client can change that.
+  The window logs it (`self-update: the server runs 1.2.0, which npm does not have (yet): not installed`) and the
+  next question, 6 h later, asks npm again, so the clients follow the publish by themselves. Until then `lanes
+  attach` still says the client is older than the server.
+  When it cannot update, it says so in one dim line and the window goes on with the client it has:
+  `lanes: the update to 1.2.0 did not finish (exit 1) — this window goes on with 1.1.0; windows try again in 6 h, or
+  now: npx @vibelord/lanes@1.2.0`; also when npm cannot be asked (`asking npm for it failed (exit 1, ENOTFOUND)`),
+  when no npx with its npm is found (on the window's PATH, nor through your login shell's profile — a window a
+  desktop app opened has the system's minimal PATH), and when `install-options` was written by a newer installer
+  (`lanes-launch update` then decides). The install gets 10 minutes. When that runs out, or you close the window or
+  press Ctrl-C while it runs, the window ends every process of it — npx, npm, the npm wrapper, `install.sh` and what
+  that started — before it goes on or closes, so nothing of the install keeps writing into the window or swaps the
+  client folder afterwards. A question without an answer (no server, a busy one, or a server from before
+  1.2.0, which takes the flag for a device name) is only logged (`self-update:` lines in `launch-<target>.log`): the
+  connection that follows says what is wrong with the path.
+- A first install with an invite is the server's release too (W9 K3): the npm installer asks the enrolment service's
+  `/enrol/site` for the server's release before it installs anything and, when that is newer, runs `npx --yes
+  @vibelord/lanes@<release>` instead, which redeems the code ([Join with an invite](#join-with-an-invite)). The phone's
+  **Lanes v1.2.0** row reads the same `version`.
 - `lanes-launch web` asks the server's `lanes hello` first, on the same connection. A 1.0.x server does not know the
   options a 1.1.0 client adds (`--default-device`, `--no-qr`), so the client leaves them out there and says so in one
   line: `the server runs lanes 1.0.4, older than this client: no QR code, and the upload box of this view does not
@@ -443,8 +618,9 @@ before a server update. To roll back, restore those files; do not rebuild device
 
 - Client: `./install.sh --uninstall` or `npx @vibelord/lanes --uninstall`. Your view session on the server stays until
   an administrator removes it; it holds no agents.
-- Server: disable `lanes-statusd.service`, `lanes-sync.timer`, `lanes-ensure.timer`, `lanes-gc.timer` and any
-  opt-in units you enabled; for the web endpoint also run `tailscale serve --https=8443 off`. Keep the state and the
+- Server: disable `lanes-statusd.service`, `lanes-sync.timer`, `lanes-ensure.timer`, `lanes-gc.timer`,
+  `lanes-update.timer` and any opt-in units you enabled; for the web endpoint also run `tailscale serve --https=8443
+  off`. Keep the state and the
   container lane data until you have decided which sessions to retain. See
   [INSTALL §6](INSTALL.md#6-updates-optional-operations-and-removal).
 
@@ -457,19 +633,20 @@ before a server update. To roll back, restore those files; do not rebuild device
 | `lanes-window` | Your device's view in its own Ghostty instance (Linux: Ghostty, else Foot with the same window class) |
 | `lanes-window 2` | An independent second view, device `<device>-2` (another monitor) |
 | `lanes-window w2` / `lanes-window w3` | A wide view, device `<device>-w2` / `-w3`, with two or three viewports per workspace |
-| `lanes-window --ascii` / `--light` / `--dark` [suffix] | The same, with that look recorded for the device (section 9) |
+| `lanes-window --ascii` / `--light` / `--dark` [`--device-only`] [suffix] | The same, with that look recorded as `lanes attach` records it: in the owner's profile on a device with an owner, in the device file with `--device-only` or on a device without one (section 9) |
 | macOS **Lanes** app | `~/Applications/Lanes.app` (Spotlight: Lanes) runs `lanes-window` |
 | Omarchy | `Super+Shift+L` opens or focuses the window; `Super+Shift+Alt+L` opens the `w2` wide view |
 | `lanes-launch` | Your device's view inside the current terminal |
 | `lanes-launch <workspace>` | Your device's view with that workspace's tab in front |
 | `lanes-launch <device> --viewports N` | A view with N (2–3) viewports per workspace |
-| `lanes-launch <device> [--ascii] [--theme dark\|light\|auto] [--glyphs M] [--color C]` | The view with a recorded look |
+| `lanes-launch <device> [--ascii] [--theme dark\|light\|auto] [--glyphs M] [--color C] [--notify 1\|0] [--dim 90\|2] [--editor E]` | The view with a recorded look (and desktop notifications on or off); `--editor` is the editor of [quick edit](#quick-edit) |
 | `lanes-launch lane <lane-id>` | One lane straight in this terminal, no multiplexer (native terminal scrollback) |
 | `lanes-launch ls` | List the lanes with live status (`lanes ls` on the server) |
+| `lanes-launch here [device]` | Show here the lane you opened last on another of your devices (`lanes here` on the server; default: this machine's device). An open window shows it at once with its tab in front; a closed one shows it when it next attaches. Asked for, never automatic |
 | `lanes-launch web phone` / `laptop` / `<device>` | Not a terminal view: a browser view's private URL and a login token (section 4) |
 
-`web`, `update`, `lane` and `ls` are verbs: a device or workspace with one of those names is not reached through
-`lanes-launch <name>`.
+`web`, `update`, `lane`, `ls` and `here` are verbs: a device or workspace with one of those names is not reached
+through `lanes-launch <name>`.
 
 Closing the window detaches; nothing on the server stops. `lanes-launch` never ends by itself: when the connection
 drops, the server drops a slow client, or the server refuses, it says so, waits with a countdown (backing off up to
@@ -477,7 +654,7 @@ drops, the server drops a slow client, or the server refuses, it says so, waits
 configuration defines, first `lanes-ip` (the server's tailnet address, when `lanes` names it by its MagicDNS name), then
 `lanes-public` (when the site defines one), and after the last it goes back to `lanes`. Exits 64–78 are server refusals and retry after 60 s. Its log is
 `~/.local/state/lanes-client/launch-<target>.log`. When the server rebuilt the view, the client reconnects straight
-away.
+away. Before it connects, a window may first update its own client from npm ([Versions](#versions)).
 
 ### Devices and views
 
@@ -486,12 +663,69 @@ away.
 - Each view has one tab per workspace in catalog order, then SSH split workspaces and tool tabs (the **Throttle**
   monitor when a manifest configures `monitor`), then **Host** (a login shell on the server). An `sshWorkspaces`
   entry with `layout: "lanes"` sits just before Host unless its `position` is `workspace`.
+- On a device with an owner the workspace tabs are that person's: the profile's `workspaces.hidden` boards have no tab
+  on any of their devices, and `workspaces.order` puts the boards it names first, in its order (the others follow in
+  catalog order; an id no board has is ignored). Every `lanes sync` and `lanes ensure` brings running views in line
+  — a hidden board's tab is closed (only its sidebar and view panes: the lanes keep running in their containers), a
+  board shown again comes back as a new tab. A profile that hides every board hides none. A device nobody owns keeps
+  the catalog order.
 - Phones and browsers are separate devices (`phone`, `browser`, or a name you choose); a device keeps the layout
   (desktop or phone) it was created with.
 - On the server: `lanes device list` shows each device (phone or desktop with its viewports, the owner's login once
   the machine was enrolled through an invite or a request — the current member's, so a handed-over machine shows its
   new owner — running or not);
   `lanes device forget <name>` stops `lanes ensure` recreating it; `lanes rebuild <device>` recreates a stuck view.
+- A device from before enrolment has no owner (`lanes doctor` names it), so it keeps its look and opened-lane marks to
+  itself. `lanes device claim <device> --login <login> [--name N]` names one: it records the owner on the device and its
+  windows and folds their look (a `--device-only` key stays the device's) and marks into that person's profile; run
+  again (with or without `--name`) it keeps the
+  name it recorded unless `--name` gives a new one. Its running sidebars follow the profile from their next tick: the
+  person's look, and a Done lane opened on any of their devices leaves Done on all of them. On a device enrolled
+  before profiles existed the profile already wins wherever it sets a key; a claim naming the login its member record
+  names folds the look the device recorded then into the profile. A member record decides
+  whenever one exists — a claim that disagrees with it is refused and names `lanes keys owner`. `lanes user list` shows
+  the people lanes knows with their devices, `lanes user show <login>` one profile (what it holds: [Your
+  profile](#your-profile)).
+
+### Your profile
+
+Once a device has an owner — its member record from an invite or a request, or one `lanes keys owner` or `lanes
+device claim` named for a device from before enrolment — Lanes keeps what you choose per person, not per device: one
+file on the server, `users/<login>.json`, shared by every device you own (the Mac, its `mac-2` window, `mac-phone`, a
+browser view). `lanes user show <login>` prints it.
+
+| Kept in your profile (every device you own) | Kept per device (`devices/<device>.json`, `clients/`) |
+| --- | --- |
+| The look: theme, colour mode, glyphs (`lanes attach --theme\|--color\|--glyphs\|--ascii`, `lanes-window --light\|--dark\|--ascii`) | A look key set with `--device-only`, and `--notify` and `--dim` (always per device) |
+| The lanes you opened, so a Done lane opened on the phone leaves Done on the Mac, and the last lane you opened | The device's own record of what it opened (`clients/<device>.seen.json`: an older release reads it) |
+| Board order and hidden boards (`lanes workspaces order\|hide\|show`) | The layout (desktop or phone), viewports, the machine a window belongs to, its owner |
+| Pinned and hidden lanes (`lanes lane pin\|unpin\|hide\|show`) | |
+| Your own quiet window for pushes, `notify.quiet_s` (section 8; no verb sets it yet) | |
+
+- **Per user or per device.** A look flag on a device with an owner goes to your profile, and every sidebar of every
+  device you own repaints within a tick. Add `--device-only` to keep it on that device alone (`lanes-window --light
+  --device-only`); the same flag without `--device-only` hands the key back to the profile. A device nobody owns keeps
+  everything in its own file, exactly as before profiles (section 9 has the order a sidebar paints in).
+- **Claim and adopt.** A device from before enrolment follows no profile: `lanes doctor` names it, and `lanes device
+  claim <device> --login <login>` gives it an owner and folds its look (never a `--device-only` key) and opened-lane
+  marks into that person's profile, with its windows. `lanes keys adopt --login <login>` and `lanes keys owner <device>
+  <login>` fold the devices whose keys they move in or name the same way. A device whose member record already names
+  you folds a look it recorded before profiles existed with the same claim.
+- **Arrange boards and lanes**, on the server, for the owner of `--device <device>` (else of `$LANES_DEVICE`) or for
+  `--login <login>`: `lanes workspaces hide <id…>` / `show <id…>` takes boards off your tabs and puts them back (hiding
+  the last visible board is refused); `lanes workspaces order <id…>` puts those boards first, in that order, the rest
+  in catalog order. `lanes lane pin <lane-id>` lists a lane first in its section; `lanes lane hide <lane-id>` leaves a
+  registered lane out of your lists (a running unregistered session is always listed); `unpin` and `show` undo them.
+  The sidebar keys do the same where you are looking: `p` pins or unpins the cursor lane, `h` hides it, `H` hides
+  this board (after `y` and Enter) and `o` shows what you hid, faint, until you press it again. Every sidebar of yours
+  follows within a tick (pinned lanes first, hidden ones out); the tabs take the board order and close a hidden
+  board's tab at the next `lanes upgrade-session` — `H` starts one at once, and every `lanes sync` (2-minute timer) and
+  `lanes ensure` (1-minute timer) runs one.
+- **Pick up elsewhere.** `lanes-launch here` (on the server `lanes here <device>`) shows in this machine's view the lane
+  you opened last on any of your devices and brings its tab to the front; it is asked for, never automatic. It says
+  why when it cannot: nothing opened yet, the lane is gone, or its board is one you hide.
+- **Safe to delete.** Without the file the look falls back to the device files and the environment, Done lanes show
+  again until opened, and the arrangement resets.
 
 ### Panes and viewports
 
@@ -514,20 +748,28 @@ Keys in the `shared` block work in every mode, locked included:
 | `Ctrl-Alt-↓` / `Ctrl-Alt-↑` | Point the focused viewport (the first one when the sidebar has the focus) at the next / previous lane of its workspace in registry order, wrapping. Runs `lanes next\|prev --focused` in a floating pane that closes at once; nothing is typed and the focus stays. Does nothing on Host or tool tabs |
 | `Ctrl-Alt-/` | Find: moves the focus to the sidebar and starts its filter |
 | `Ctrl-Alt-u` | Arm the sidebar's upload strip, then drop files anywhere on the window |
+| `Ctrl-Alt-l` | Move the focus to the sidebar, nothing else: browse it with its keys, `Esc` gives the keyboard back to the lane |
 | `Ctrl-Alt-c` | Copy the selection |
 | `Ctrl-Alt-PageUp` / `Ctrl-Alt-PageDown` | Page up / down and enter scroll mode |
 | `Ctrl-Alt-End` | Scroll to the bottom and return to normal mode |
 | `Ctrl-Alt-s` | Zellij's session manager (floating) |
 
-`Ctrl-Alt-/` and `Ctrl-Alt-u` walk the focus left to the sidebar first; on a tab without a sidebar (Host, Throttle,
-the phone's view tab) the character goes to that tab's pane.
+`Ctrl-Alt-/`, `Ctrl-Alt-u` and `Ctrl-Alt-l` walk the focus left to the sidebar (three steps, enough from the third
+viewport of a wide view). `Ctrl-Alt-/` and `Ctrl-Alt-u` then type nothing: they run `lanes sidebar-key filter|upload
+--focused` in a floating pane that closes at once, which tells that sidebar to start its filter or arm its strip
+(cockpit v3 S4; until then they typed `/` or `U`, which on a tab without a sidebar went into the lane). On a tab
+without a sidebar (Host, Throttle, the phone's view tab) they do nothing. The first keys after the chord already
+reach the filter; keys typed while the floating pane is still open (a fraction of a second) go to it, not to the
+sidebar. Zellij 0.45.1 matches `Ctrl-Alt-/` in the kitty keyboard protocol and xterm `modifyOtherKeys` encodings
+(measured); the legacy `Esc` + `Ctrl-_` byte pair is not read as `Ctrl-Alt-/` and reaches the focused pane as is.
 
 Normal mode:
 
 | Key | Action |
 | --- | --- |
-| `Ctrl-Alt-g` | Lock the view; press again to unlock. The mode ribbon shows LOCKED in the urgent accent. While locked, the mode keys below and `Ctrl-Alt-m` reach the lane; the `shared` keys above stay active |
+| `Ctrl-Alt-g` | Lock the view; press again to unlock. The mode ribbon shows LOCKED in the urgent accent. While locked, the mode keys below, `Ctrl-Alt-m` and `Ctrl-Alt-e` reach the lane; the `shared` keys above stay active |
 | `Ctrl-Alt-m` | Markdown preview of the focused lane (every mode except locked; see below) |
+| `Ctrl-Alt-e` | [Quick edit](#quick-edit) of the focused lane's AGENTS.md, CLAUDE.md or .env.local: a one-key picker (`1`–`5`, `Enter` when one file is there, `q`/`Esc` closes), then an editor inside its container ([which one](#the-in-container-lane-command); Lanes installs none, vi is the floor), in a floating **Edit** pane that closes when the editor exits (every mode except locked). One Edit pane per view: pressing it again while one is open goes back to that editor (in another tab it names the tab instead) and opens no second one |
 | `Ctrl-Alt-p` | Pane mode |
 | `Ctrl-Alt-t` | Tab mode |
 | `Ctrl-Alt-n` | Resize mode |
@@ -566,12 +808,29 @@ Top to bottom, a desktop sidebar is:
 1. **Header**: the workspace title, then the attention counts in the column-2 glyphs, e.g. ` Sakio  ◆1 ◇2 ▸6 ✓1`
    (needs approval, needs input, working, done; zeros left out; a `done` you have opened is not counted). Without
    agents it says `N lanes`. The counts are dimmed while the footer warns that status is old.
-2. **Body**: **Needs you** (`◆` `✗` `◇`, most urgent then oldest first), **Working** (oldest first), **Done** (newest
-   first), then the workspace's other lanes under its own title (`── Sakio (25) ──`). The sections appear only when at
-   least one lane needs you, is working or is done. Then `zmx lanes (N)` when any exist, then **Unregistered (N)**
+2. **Body**: **Needs you** (`◆` `✗` `◇`, most urgent first, then in the order the lanes started needing you),
+   **Working** (in the order they started working), **Done** (the newest first), then the workspace's other lanes
+   under its own title (`── Sakio (25) ──`). Once any lane runs an agent, the **Needs you** and **Working** headers
+   stay on screen even when empty (`── ▸ Working (0)`, glyph dimmed; a header with lanes says its name in its section's
+   colour in truecolor and 256 colours), so a lane moving between them never pushes the
+   rows below it around; **Done** appears only when a lane is in it. A pending approval or an error sorts to the top
+   of Needs you while it lasts; after that (a question, an approval prompt, the question again) the lane is back in
+   the place it entered at. A lane moves up a section at once (a question or an approval is never delayed) and down
+   only after the new state has held: 8 s to leave Needs you, 5 s to leave Working or Done (the status daemon looks
+   every 3 s, so in practice 9 s and 6 s). An agent that asks, works for a few seconds and asks again stays in Needs
+   you, a working lane whose signal blinks for a cycle stays in Working, and the rows below them stay put. When a lane changes section above
+   your cursor, the list stays where it is and the cursor moves with its lane; the list scrolls only when that lane
+   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.
@@ -583,29 +842,39 @@ Unregistered section, no upload strip and no `+`, and its footer has no `x close
 
 | Column | Shows |
 | --- | --- |
-| 1 | `▌` the cursor |
+| 1 | `▌` the cursor; in truecolor and 256 colours the whole cursor row (to column 35) also sits on a soft background |
 | 2 | The agent glyph (table in section 1); dimmed while the lane is stale |
-| 3 | `›` the lane this pane shows (not on the cursor row, where the bold name says it) · `²` / `³` shown in viewport 2 / 3 |
-| 4–27 | The name in its identity colour, bold while shown; up to three `·` when other sessions view the lane; a clipped name ends in `…` |
+| 3 | `›` the lane this pane shows (not on the cursor row, where the bold name says it) · `²` / `³` shown in viewport 2 / 3 · `…` (dim; ASCII `~`) an action on its way: a session `x` is closing, a session `P` is registering (until its lane is listed), a shell being created (on the New shell row) · `▲` (ASCII `^`) a lane you pinned (`p`), the lowest of these marks |
+| 4–27 | The name in its identity colour (else the theme's ink in truecolor and 256 colours), bold while shown, faint for a lane you hid while `o` shows it; up to three `·` when other sessions view the lane; a clipped name ends in `…` |
 | 28 | `+` on an unregistered tmux session that can be added to a workspace |
-| 29–31 | Age: the agent's `since`, else the last output: `45s`, ` 3m`, ` 2h`, ` 4d` (at most `99d`); blank when unknown; amber inside **Needs you** |
-| 33 | The terminal status glyph (section 1); dimmed when an agent glyph is in column 2 (`▸` with `○` is a long tool call, not a stuck lane) |
+| 29–31 | Age: the agent's `since`, else the last output: `45s`, ` 3m`, ` 2h`, ` 4d` (at most `99d`); blank when unknown; amber inside **Needs you**, and in truecolor and 256 colours blue in **Working** and green in **Done** |
+| 33 | The terminal status glyph (section 1); dimmed when the lane is stale, and in 16 colours also when an agent glyph is in column 2 (`▸` with `○` is a long tool call, not a stuck lane) |
 | 34 | One tail cell by priority: `?` not observed right now > `⚠` starving > `↓` downgraded > `$` mostly paid (section 8) |
 | 35 | `×` close, on unregistered sessions only |
 
-Marks and their ASCII twins: `▌` `|` cursor · `›` `=` viewing · `²` `2` / `³` `3` other viewport · `·` `.` viewer ·
-`…` `~` clipped · `×` `x` close · `+` `+` new / add · `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now ·
+Marks and their ASCII twins: `▌` `|` cursor · `›` `=` viewing · `²` `2` / `³` `3` other viewport · `▲` `^` pinned · `·` `.` viewer ·
+`…` `~` 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).
 
-**Footer**, highest priority first: the close prompt ` › close ‘name’? y/n` · the rename prompt ` › Rename: …█` ·
-the promote prompt ` › Register ‘name’? y/n` · the Add to workspace prompt ` Choose a workspace · Esc cancels` · the
-filter ` /abc · 3 matches` · the health banner (` ⚠ host under memory pressure · status 3 m old`, or
-` ⚠ lane sockets deleted · lanes run; on the server: lanes sockets repair`) · ` ⚠ registry: …` · the last message ·
-the legend ` ⏎ open · / find · x close · ? keys`. An empty workspace shows `no lanes declared · + New shell` on its
-New shell row.
-
-**Sidebar keys** (`?` shows this sheet in place of the list until the next key; that key only closes the sheet):
+**Footer**, highest priority first: the open prompt — the sidebar asks one thing at a time, in one of two shapes. A
+name field: ` › Rename: …█`, or ` › Register as: …█` for promote (a name longer than the field shows its end, `…` first,
+so what you type stays in view). A confirmation: ` › close ‘name’ — y⏎ confirm · Esc cancel` or
+` › register ‘name’ — y⏎ confirm · Esc cancel` (promote), `⏎ confirm` once `y` armed it; at 36 columns ` cancel`
+gives way first, then ` · Esc`, then the name is clipped, so the keys always show. Then the Add to workspace prompt
+` Choose a workspace · Esc cancels` · the filter ` /abc · 3 matches` · the health banner
+(` ⚠ host under memory pressure · status 3 m old`, or ` ⚠ lane sockets deleted · lanes run; on the server: lanes
+sockets repair`) · the version note ` server 1.2.0 · view 1.1.0 — press ?` while this sidebar runs another tree than
+the installed one (at 36 columns ` — ?`; section [Versions](#versions)) · ` ⚠ registry: …` · the last message · the undo offer ` Unregistered ‘name’ · z undo` (10 s after
+`u`) · the legend ` ⏎ open · / find · x close · ? keys`. The phone
+draws the same footer (its picker says ` Choose a workspace · Tap Cancel`, and ` Swipe to scroll · Tap to open` when
+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 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):
 
 | Key | Action |
 | --- | --- |
@@ -616,22 +885,64 @@ New shell row.
 | `Tab` / `Shift-Tab` | Open the next / previous lane that needs you, cycling from the lane shown (` nothing needs you` when the section is empty) |
 | `2` / `3` | Show the cursor lane in viewport 2 / 3 (wide views) |
 | `/` | Find a lane |
-| `Esc` | Clear the filter; cancel a prompt, a rename, Add to workspace or an armed upload strip |
+| `Esc` | Clear the filter; cancel a prompt, a rename, Add to workspace or an armed upload strip; the keyboard goes back to the lane |
 | `g` / `G` | First / last row |
 | `+` | New persistent shell in this workspace |
 | `a` | Add the cursor session to a workspace |
-| `x` | Close the cursor session (asks `y/n`) |
+| `x` | Close the cursor session: `y` arms, `Enter` closes, any other key cancels (on a registered lane: ` registered: u to unregister first`) |
+| `u` | Unregister the cursor session added with `a`: it moves back to **Unregistered**, still running, and the cursor goes with it; on a lane a repository's `terminals.json` declares, take its terminal out of that file |
+| `z` | Undo that unregister (within 10 s) |
 | `R` | Rename the cursor lane |
-| `P` | Promote (register) the cursor session in the repository's `terminals.json` |
+| `P` | Promote (register) the cursor session in the repository's `terminals.json`: the name first (`Enter` accepts), then `y` and `Enter` |
+| `p` | Pin / unpin the cursor lane: on every device you own it leads its section, marked `▲` (`^` in ASCII), and never falls below `⋮ N more` |
+| `h` | Hide the cursor lane on every device you own (` Hid ‘name’ · o shows it`); on a hidden lane `o` shows, show it again |
+| `H` | Hide this workspace on every device you own: `y` arms, `Enter` hides — its tab closes, its lanes keep running (the last workspace shown stays) |
+| `o` | Show / hide again the lanes you hid (shown faint) |
 | `U` | Arm the upload strip |
-| `r` | Reload and repaint |
+| `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 |
 
-Mouse: a click opens a lane; the wheel moves the cursor three rows; a click on `×` asks to close, on `+` starts Add to
-workspace, on the upload strip arms it. The cursor follows the lane, not the row: when a lane changes section the
-cursor and scroll position go with it.
+**Pins and hidden lanes** (`p`, `h`, `H`, `o`) are yours, not the device's: they live in your profile
+(`users/<login>.json`, section [Devices and views](#devices-and-views)) and every device you own follows them on its next
+tick. A hidden lane leaves the list, the header counts, the fleet strip and the desktop notifications; a session under
+**Unregistered** is never hidden (nothing alive is), and `/` finds only the lanes shown — `o` first to search hidden
+ones. The filter keeps its match order; pins lead their section everywhere else. A hidden workspace's tab closes on
+every view of yours (`lanes upgrade-session`, which `H` starts); `lanes workspaces show <id>` (cockpit v3 R6) brings it
+back. On a device nobody owns there is no profile: `p`, `h` and `H` say ` no owner: lanes device claim`.
 
-### Find, rename, add, promote, new, close
+Mouse: a click opens a lane; the wheel moves the cursor three rows; a click on `×` asks to close, on `+` starts Add to
+workspace, on the upload strip arms it. Under an open prompt the wheel does nothing and a click ends the prompt first
+(` Cancelled`), then does what it does (a click on a row opens that lane); a click on the upload strip beside a Rename
+or Register-as field arms the strip and leaves the field. The cursor follows the lane, not the row: when a lane changes
+section the cursor and scroll position go with it.
+
+**The keyboard goes back to the lane.** The sidebar and the lane share one keyboard: whichever pane has the focus gets
+what you type. So every sidebar action that ends hands the focus back to the pane's viewport — opening a lane, a
+close, a rename (`Enter`), a register (`a` → workspace, or `P` → `y` → `Enter`), an unregister (`u`) and its undo
+(`z`), a cancel (`n`, `Esc` or any other key at a prompt), `r`, the key that closes the `?` sheet, a drop on the upload strip, and a click that opens nothing
+(a section header, `⋮ N more`, an empty row). Anything else typed in the same burst was meant for the lane and is
+dropped, never read as sidebar keys. A prompt, the filter and the armed upload strip keep the keyboard until you
+answer them, and so does a refused key (`x` on a lane that cannot be closed, `u` on a declared lane), so the `y` you
+type next lands in the
+sidebar, not in an agent's approval prompt. The wheel and a mouse release never move the focus. On the phone the
+picker tab keeps it; only opening a lane leaves it.
+
+**The footer says when the keyboard is on the sidebar.** While it is, the legend line reads
+` ▌ keys go to sidebar · Esc → lane` in the accent colour (` | keys go to sidebar - Esc -> lane` in ASCII) instead of
+` ⏎ open · / find · x close · ? keys` — no extra row; a prompt, the filter, a banner or a message still take the line
+first. The sidebar asks Zellij for focus reports and follows them (Zellij 0.45.1 sends them); a Zellij that never
+sends one leaves the legend up for 3 s after each key you type in the sidebar. Every action that hands the keyboard
+back clears it at once. On the phone the picker is a whole tab and has no such legend.
+
+**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`, `?`, `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.
+
+### Find, rename, add, unregister, promote, new, close
 
 - **Find** (`/` or `Ctrl-Alt-/`): type a few letters. Matching is fuzzy (the letters in order; whole-substring and
   prefix matches rank first, word starts score higher). The list flattens (sections drop, column 2 stays) and the
@@ -639,19 +950,74 @@ cursor and scroll position go with it.
   `Esc` clears. No hits:
   ` no lane matches ‘abc’ · Esc`.
 - **Rename** (`R`, or `lanes rename <lane-id> <new-name>` on the server): edit in the footer, `Enter` saves, `Esc`
-  cancels. The lane id never changes, so view targets and Cursor's `lane open <id>` keep working. Where the name is
-  stored depends on the lane kind (section 6).
+  cancels. While you type, the keyboard is the field's: `Space`, `j`, `k`, `J`, `K` are letters, and the arrows,
+  `Tab`, `Shift-Tab`, `PageUp` and `PageDown` type nothing — none of them opens a lane, moves the cursor or throws the
+  name away. A click on the list cancels the field before it opens anything, so a name never stays open in the footer
+  after the keyboard has gone to a lane. The lane id never changes, so view targets and Cursor's `lane open <id>`
+  keep working. Where the name is stored depends on the lane kind (section 6). `Enter` on an emptied name, or on the
+  name the lane already has, writes nothing and says ` name unchanged`.
 - **Add to workspace** (click `+` on the row, or `a`): choose a workspace that uses the session's container (the
   current one first), or **Cancel** / `Esc`. The session keeps its id, name, programs, scrollback and views, moves to
-  that workspace's list, loses its `×`, and survives sync and reconnects.
-- **Promote** (`P`): asks ` › Register ‘name’? y/n`. `y` declares the unregistered tmux session in the workspace's
-  repository `terminals.json` (only when the workspace has exactly one repository registry) and syncs; the lane then
-  gets a repository id `<workspace>--<slug>`. Refused on a lane that is already registered.
+  that workspace's list, loses its `×`, and survives sync and reconnects. The cursor goes with it into the list;
+  **Cancel** / `Esc` puts it back on the session (added to another workspace, the session leaves this list and the
+  cursor keeps its row).
+- **Unregister** (`u` on a session added that way, or `lanes unregister <lane-id>` on the server): takes it out of the
+  workspace again at once. Nothing stops: a running session moves back to **Unregistered** with the same id and name,
+  in the same workspace even if its directory now belongs to another one, its views stay attached, and the cursor goes
+  with it; a session that no longer runs leaves the list. The footer
+  offers ` Unregistered ‘name’ · z undo`, and `z` within 10 seconds adds it back exactly as it was — unless the session
+  was closed and started again under the same name meanwhile, which the undo refuses (`a` adds the new one). `u` hands
+  the keyboard back to the lane like every action, so press `z` on the sidebar (`Ctrl-Alt-l` first; the phone's picker
+  keeps the keyboard). On a busy host where tmux cannot be asked about the session, `u` changes nothing and says
+  ` Session could not be checked; nothing was unregistered`; press it again in a moment. If the record was saved but the
+  workspace list could not be published (a full disk), it says ` Unregistered; run lanes sync to finish publishing: …`
+  and `z` still undoes it. On a lane a repository's `terminals.json` declares, `u` takes its terminal out of that file
+  (the same editor the agents' `lanes_unregister` tool uses: the terminal and its `lanes.terminals` entry go, nothing
+  else in the file moves, a `.bak-<UTC>` copy is kept the first time), starts `lanes sync` and says ` Unregistered
+  name`; the session keeps running and is listed under **Unregistered** after the sync. There is no `z` for it. The
+  editor refuses, in its own words, the file's last terminal, a symbolic link in the container's home and a file that
+  is gone. A lane of an SSH workspace says ` declared in catalog.json — edit the file`; an unregistered session says
+  ` not registered — a adds it to a workspace`. `x` on any registered lane says ` registered: u to unregister first`.
+- **Promote** (`P`): asks the name first, ` › Register as: name█` (prefilled with the session's; edit it, `Enter`
+  accepts, an emptied name cancels; the field takes keys and clicks as Rename's does), then
+  ` › register ‘name’ — y⏎ confirm`. `y` arms it (` › register ‘name’ — ⏎
+  confirm`) and `Enter` declares the unregistered tmux session under that name in the workspace's repository
+  `terminals.json` (only when the workspace has exactly one repository registry) and syncs; the lane then gets a
+  repository id `<workspace>--<slug>` (the slug of the repository's prefix + the name). Any other key cancels.
+  Refused on a lane that is already registered, and on a session that `terminals.json` already declares under any
+  name — a `P` on another device, or one whose row has let go before the sync listed it: ` Already declared as
+  'name'; lanes sync lists it`, nothing written. Until the sync lists the lane (a few seconds) the row stays where it
+  is, under the new name, with a dim `…` in column 3 (ASCII `~`) and no `+` or `×`; the footer says
+  ` Registering ‘name’` — from the `Enter` on, before the write itself has answered; if the write refuses, the row
+  goes back to its own name and the footer says why. Then the row moves into the workspace's list and the cursor, if
+  it was on the row, moves with it. Meanwhile `x`, `a`, `R`, `P` and `u` on that row say ` registering ‘name’ — a moment`; opening it works.
+  If no sync has listed the lane 80 s later — the longest one can still take when docker answers slowly — and the
+  sync the sidebar started has ended, the mark goes and the footer says ` ‘name’ not listed yet — lanes
+  sync` (run `lanes sync` on the server; a broken `terminals.json` shows as ` ⚠ registry: …`).
 - **New shell** (`+`, or the `+ New shell` row): starts a persistent shell in the workspace container on the socket
-  `lanes-shells-<workspace>` and shows it. Reopening it attaches to the same shell.
-- **Close** (`x`, or a click on `×`): unregistered sessions only. ` › close ‘name’? y/n`: `y` ends the session and its
-  jobs and clears views showing it; any other key cancels. A session others are grouped onto (a Studio browser
+  `lanes-shells-<workspace>` and shows it. Reopening it attaches to the same shell. While it is being created (up to
+  15 s on a busy host) the sidebar keeps working: the New shell row has a dim `…` (ASCII `~`) after its `+`, the footer
+  says ` Creating a shell`, and a second `+` says ` creating a shell — a moment` instead of making another. The keyboard
+  stays on the sidebar meanwhile; the shell opens in the viewport and takes the keyboard when it is ready — unless you
+  have moved on (the keyboard went elsewhere, you opened another lane there, or a prompt is open), in which case it is
+  only listed under **Unregistered** and the cursor, if it was still on the New shell row, moves onto it (`Enter` opens
+  it). Either way it is listed once, even when the status update has already found it.
+- **Close** (`x`, or a click on `×`): unregistered sessions only. ` › close ‘name’ — y⏎ confirm · Esc cancel`: `y` arms
+  it (` › close ‘name’ — ⏎ confirm`; a long name is clipped so the keys fit) and `Enter` ends the session and its jobs and
+  clears views showing it; any other key cancels, at either step, so typed text closes nothing unless it is `x`,
+  `y`, `Enter` in a row. The keyboard goes back to the lane at the `Enter`; the close itself runs in the background
+  (a busy registry lock or a slow tmux can take seconds): the row stays with a dim `…` in column 3 (ASCII `~`), no `+`
+  or `×`, and the footer says ` Closing ‘name’`, then ` Closed name` — or why nothing was closed, with the row back as
+  it was. A viewport of this window that shows the session is cleared at the `Enter`, before the keyboard moves, so
+  what you type next lands on its **No lane selected** screen (which ignores keys), never in the shell being ended;
+  if nothing was closed, a viewport still cleared gets the session back (one you pointed elsewhere meanwhile keeps
+  your choice). A view that cannot be cleared (a full disk) closes nothing: the footer says why and the keyboard
+  stays. Meanwhile every key on that row — `x`, `a`, `R`, `P`, `u`, `Enter` — says ` closing ‘name’ — a moment`; the
+  rest of the sidebar answers as usual. A session others are grouped onto (a Studio browser
   `view-…` viewer) has those viewers ended first; any other grouped session makes the close refuse and say why.
+- **Paste into a prompt**: a paste into ` › Rename: `, ` › Register as: ` or the filter is typed there, after what is
+  already in the field. Line breaks and tabs become one space, so a copied line never acts as `Enter`; the prompt waits
+  for yours. Only the armed upload strip, or a sidebar with no prompt open, takes a paste as a file drop.
 
 ### Markdown preview
 
@@ -663,6 +1029,41 @@ adds a pinned glow unless the view server's PATH already has one; `lanes doctor`
 (`preview renderer:`). Preview reads tmux lanes only; on a Host or tool tab, or a lane that named no existing `.md`
 file, it says so and closes on `Enter`.
 
+### Quick edit
+
+`Ctrl-Alt-e` opens a floating **Edit** pane over the focused lane with the files that steer its agent:
+
+| Key | File | Offered when |
+| --- | --- | --- |
+| `1` / `2` | `AGENTS.md` / `CLAUDE.md` of the lane's checkout | always |
+| `3` / `4` | `AGENTS.md` / `CLAUDE.md` of the main checkout | the lane works in a linked git worktree |
+| `3` (`5` in a worktree) | `.env.local` of the main checkout | always |
+
+The checkout is the git checkout the lane's working directory is in (else its repository folder), found inside the
+container: a worktree's `.git` file leads to its main checkout. A file is offered only as a regular file inside its
+checkout; a symbolic link is never offered, and a missing file is shown dim, `not present` (quick edit creates no
+file). One key picks, without `Enter`, even one typed while the pane was still opening; `Enter` alone takes the file
+when only one is there; `q` or `Esc` closes. The editor then runs inside the lane's container as uid 1000, in that
+checkout: `docker exec -it -u coder … lane-edit <file>` with no shell between, so a save is the container's own write
+(owner and mode kept). Quitting the editor closes the pane.
+
+Which editor: the one `lanes attach <device> --editor micro|hx|nvim|vim` recorded for the device (`--editor auto`
+takes the choice back; from your machine, `lanes-launch <device> --editor E` passes the same flag), else the first of
+micro, hx, nvim, vim and vi in the container ([lane-edit](#the-in-container-lane-command)). `LANES_EDITOR` counts
+only for a `lanes edit --focused` you run by hand: the `Ctrl-Alt-e` pane has the view server's clean environment,
+which does not carry it.
+
+Quick edit reads tmux lanes only. It is refused with the reason, and closes on `Enter`, when the container is not
+running, when it has no `lane-edit` (`lanes install-container <name>`) or when no git checkout holds the lane's
+directory. `.env.local` is named by its label only, never by its path, in anything quick edit prints.
+
+**What quick edit can reach, and what leaves the container.** The server side (`lanes edit`) only looks: through
+`/proc/<container init>/root` it resolves the checkout and checks that each file is a regular file inside it, and it
+never opens one. The file is opened, edited and saved by the editor inside the container, as uid 1000 (`coder`, the
+agents' own user), so it can reach nothing the lane's agent could not, and the save is that user's write. Nothing is
+copied out of the container: no temporary copy on the server, no upload, no log of the contents. What you see on
+screen travels the way the lane's own output does — the terminal stream of your view — and nothing else.
+
 ### Scroll, mouse and copy
 
 - A tmux lane keeps its own history and draws on the alternate screen, so scroll inside the lane (mouse wheel or the
@@ -675,10 +1076,13 @@ file, it says so and closes on `Enter`.
 ### Pane title and desktop notifications
 
 The sidebar pane's title is `WORKSPACE · ◆1 ◇2` (the header counts, rewritten only when they change). A lane that
-starts needing you (`◆` `✗` `◇`) raises one desktop notification `name: task` through OSC 9: once per transition,
+starts needing you (`◆` `✗` `◇`) raises one desktop notification `name: task` through OSC 9: once each time it
+enters Needs you (an approval prompt after a question, while it is still waiting on you, is not a second one),
 never for the lane this pane shows, never on a phone layout. A sidebar that starts while lanes already need you
 announces each once. Ghostty shows OSC 9 only while the lanes window is not focused (`desktop-notifications = true`
-in the window's config). Not yet verified on a Mac.
+in the window's config). Not yet verified on a Mac. To silence them for one device, live:
+`lanes-launch <device> --notify 0` from the client (or `lanes attach <device> --notify 0` on the server); `--notify 1`
+turns them back on, also over a `LANES_NOTIFY=0` in the view's environment (section 9).
 
 ## 4. Phone, tablet and laptop browser
 
@@ -825,21 +1229,24 @@ 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). The light/dark toggle repaints the
-  whole terminal.
+  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
   keyboard. A suggestion you tap arrives as the whole word; long-press the field and choose **Paste** to paste.
 - The lane picker shows three rows per lane: the viewing mark, agent glyph and name; then what the agent needs, since
   when and the harness (`Needs you · 25m · claude`; a shell says `Quiet · 2h`); then the agent's task. Its first line
   counts the lanes that need you (`◆1 need approval · ◇2 need you · ▸6 working`). The footer says
-  `Swipe to scroll · Tap to open`. The picker has no upload strip.
+  `Swipe to scroll · Tap to open`, and otherwise exactly what the desktop footer says: every prompt (Rename,
+  Register as, the close and register confirmations), the filter and its match count, a banner, the last message.
+  The picker has no upload strip.
 - On a lane's own tab a row of quick keys sits above the dock: `⏎ y n Esc ^C ↑ ↓`. A tap sends the key to the lane
   without opening the keyboard; `n` and `^C` need a 400 ms hold (a short tap says "Hold to send" in the header for
   about a second and a half).
@@ -851,16 +1258,121 @@ The frontend chooses once per page load, by capability:
 - **More** opens the client's menu; tap it again to close the menu.
 - The filter bar on the picker filters the lane list as you type, non-ASCII letters included: it sends each change
   (a typed letter, a backspace) once, and clearing the field or pressing Esc closes the filter. On a picker tab the dock
-  shows the filter in place of **Panes**. Leaving the picker forgets the filter.
-- `+` and `×` on picker rows add and close unregistered sessions, as on the desktop; tapping `+` then a workspace
-  needs no typing.
+  shows the filter in place of **Panes**. Leaving the picker with a filter typed (a tap on a match opens that lane)
+  sends nothing to the lane and forgets the filter; that picker's list is shown whole again the next time you are on
+  it. Moving to another workspace's picker from the Workspaces sheet leaves the filter behind too: that picker's bar
+  starts empty.
+- `+` and `×` on picker rows add and close unregistered sessions, at the same columns as on the desktop; tapping `+`
+  then a workspace needs no typing. While the picker asks (` › close ‘sh’ — y⏎ confirm`, ` › register ‘sh’ — y⏎
+  confirm`, or Add to workspace), a short row `⏎ y Esc` sits above the dock: `y` then `⏎` closes, `Esc` cancels — no keyboard needed.
+  While you type a name (Rename, Register as) the row stays away, so a `y` meant as yes is never typed into it. A tap
+  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
@@ -870,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 |
 | --- | --- |
@@ -879,16 +1394,46 @@ 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
-file.
+file. Once the drop lands the sidebar gives the keyboard back to the lane straight away; the end of the upload never
+moves the focus (you may be typing somewhere else by then).
 
 **The upload helper and its allowlist.** The helper is the security boundary for drops. It reads only from folders
 listed in `~/.config/lanes/upload-allow` (created with Desktop, Downloads, Pictures, Documents, Lanes Uploads and the
@@ -930,7 +1475,7 @@ The agent must hold the key (`AddKeysToAgent yes` in the `lanes` alias adds it o
 | `✗ not allowed on this machine: … - run: lanes-upload --allow FOLDER` | The file's folder is not on the allowlist (or you chose Deny) | `lanes-upload --allow <folder>`, then drop again |
 | `✗ macOS denied folder access: allow Lanes Helper in System Settings > …` | macOS refused the helper | Allow Lanes Helper in Files and Folders |
 | `✗ no upload helper on this device (reopen lanes-launch)` | No helper heartbeat for this device | `./install.sh --check`; reopen the window |
-| `✗ that was not a file drop` | The paste was not a list of absolute paths | Drop files, not text |
+| `✗ that was not a file drop` | The paste was not a list of absolute paths (a paste into an open Rename, Register-as or filter prompt is typed there instead) | Drop files, not text |
 | `✗ upload timed out` | No progress for 120 s | Check the helper log |
 
 ## 6. Workspaces and registry
@@ -986,14 +1531,30 @@ run.
 | Key | Meaning |
 | --- | --- |
 | `terminals[]` | The terminals the editor extension opens and Lanes turns into lanes: `name` (the lane title; the id is its slug), `command`, optional `focus`, `color` (`terminal.ansi<Colour>` / `terminal.ansiBright<Colour>`), `icon` (a codicon name) |
-| `lanes.terminals[<name>]` | The exact binding Lanes uses: `holder`, `tmux: {socketName, sessionName}`, `id` (added by `cursor-sync`), and `create` (the recipe `lane open` runs when the lane does not exist; `createPrevious` keeps an earlier one after `cursor-sync --canonicalize`/`--identity`). Written by `lanes cursor-sync`; ignored by the editor extension |
+| `lanes.terminals[<name>]` | The exact binding Lanes uses: `holder`, `tmux: {socketName, sessionName}`, `id` (added by `cursor-sync`), and `create` (the recipe `lane open` runs when the lane does not exist; `createPrevious` keeps an earlier one after `cursor-sync --canonicalize`/`--identity`). Optional `displayName`: the name Lanes shows for the lane (see below). Written by `lanes cursor-sync`, which carries `displayName` as is; ignored by the editor extension |
 | `throttle.terminals[<name>].tmux` | A binding Lanes also accepts (Throttle Studio's), used when `lanes.terminals` has none |
 
-Every terminal needs an explicit tmux binding; there is no guessed command parsing. Display names are not set in
-`terminals.json`: the manifest's `displayNames` holds them.
+Every terminal needs an explicit tmux binding; there is no guessed command parsing.
+
+A repository lane's shown name has two layers, both keyed by the terminal's `name`, neither of which changes the id:
+
+1. `repositories[i].displayNames` in the manifest (host) — the operator's override, written by `R` and
+   `lanes rename`. It wins.
+2. `lanes.terminals[<name>].displayName` in `terminals.json` (container) — the repository's own name for the lane.
+   A value that is not a usable name (not a string, blank or invisible characters only, not valid Unicode text,
+   or with a control character) is ignored. So is a name another lane on the same board already answers to — its
+   title, its `displayNames` override, or its own `displayName` (then neither lane keeps it): the repository names
+   only its own lane and never makes two rows read the same. Names are compared as a row reads them, so extra
+   spaces, a zero-width character or a full-width form do not make a second `main`. No board error is raised; the
+   lane shows its override, else its title.
+
+Without either, the lane shows its prefix plus the terminal's `name`.
 
 **`registered-sessions.json`** (site directory, version 1): `sessions[]` of `{id, workspace, name, container,
-tmux: {socket, session}, folder}`, written by Add to workspace and `lanes register`. Back it up with the catalog.
+tmux: {socket, session}, folder}`, written by Add to workspace and `lanes register`; `u` in the sidebar or
+`lanes unregister <lane-id>` removes a record (`z` puts it back within 10 s). `lanes unregister <id>` also removes a
+record no workspace lists any more (its workspace left the catalog, uses another container, or a repository declares
+the session). Back it up with the catalog.
 
 ### Lane ids
 
@@ -1015,7 +1576,10 @@ target as JSON.
 - **Hot-sync**: `lanes-statusd` starts one `lanes sync` when a referenced `terminals.json` changes, at most one per
   10 s.
 - `lanes-ensure.timer` runs `lanes ensure` every minute: it recreates any known device session that is missing, and
-  never when Zellij did not answer.
+  never when Zellij did not answer. A view an update left running because a client was attached
+  (`clients/<device>.update-ready`) is rebuilt by the first tick that finds no client attached. While another
+  `lanes ensure`, `lanes rebuild` or the create of a view runs, a tick waits 10 s for it and then skips (`ensure:
+  skipped: …`); the next tick follows a minute later.
 - A repository whose registry is temporarily invalid keeps its previous lanes; the sidebar footer and `lanes doctor`
   say why. `lanes sync` exits 1 then (the timer treats that as informational).
 - A device with no attached client gets new tabs on its next connection and the next ensure tick.
@@ -1045,7 +1609,7 @@ running lane gains its identity when it is next created.
 
 | Lane kind | `R` / `lanes rename <lane-id> <name>` writes |
 | --- | --- |
-| Repository lane | `repositories[i].displayNames` in `workspaces.<workspace>.json` (a `.bak-<UTC>` copy on the first write), then syncs. Renaming back to the terminal's own title removes the override |
+| Repository lane | `repositories[i].displayNames` in `workspaces.<workspace>.json` (a `.bak-<UTC>` copy on the first write), then syncs. Never `terminals.json`. Renaming back to the lane's default (its `terminals.json` `displayName` when it has one, else the terminal's own title) removes the override |
 | Registered session | Its record's `name` in `registered-sessions.json` |
 | Unregistered session | `~/.local/state/lanes/user-sessions/<id>.json` |
 
@@ -1056,12 +1620,18 @@ Names must be non-empty and free of control characters. The id, resolve file and
 - **Register** (Add to workspace, or `lanes register <lane-id> [workspace]` with the id from
   `lanes ls --unregistered`): saves the session's existing id, name and binding in `registered-sessions.json`. It
   has no create recipe and does not edit any editor terminal list; an ended registered session stays absent until
-  someone starts it. Only workspaces using the session's container are offered.
+  someone starts it. Only workspaces using the session's container are offered. If that container refuses its own
+  copy of the registry (`~/.lz` is no real directory), the registration is still saved and listed, and Lanes says so
+  at once: `Registration saved; run lanes sync to finish publishing: container <name>: …` (a rename of a registered
+  lane says `Rename saved; …` the same way); `lane open` in that container sees the change only after the fix
+  ([RUNBOOK](RUNBOOK.md)).
 - **Promote** (`P`): declares the session in the workspace's single repository `terminals.json` (a terminal entry
   and its `lanes.terminals` binding), so it gets a repository id, editor integration and a saved recipe when one was
   known.
-- **Unregister** a registered session: remove its record from `sessions` and run `lanes sync`; the terminal keeps
-  running and returns to Unregistered. Remove a repository lane by deleting its terminal from `terminals.json`.
+- **Unregister** a registered session: `u` in the sidebar, or `lanes unregister <lane-id>` (which also clears a record
+  `lanes sync` ignores); the terminal keeps running and returns to Unregistered with the same id and name. Removing the
+  record from `sessions` by hand and running `lanes sync` works too, without the name hand-back. Remove a repository
+  lane by deleting its terminal from `terminals.json`.
 - If a repository later declares the same binding as a registered session, the repository declaration wins.
 
 ### `lanes doctor`
@@ -1086,6 +1656,32 @@ 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, 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
+  `systemctl --user restart …` or `lanes rebuild <device>`); a record whose process is not running is a line of
+  information, never a `✗`. Every device's layout runs the current tree (`✗ … mac runs 1.1.0 — lanes rebuild mac`;
+  `⚠` when it names that tree by another path than `lanes rebuild` writes now: the next update would leave that view
+  behind). Every installed lanes unit's `ExecStart` runs it (`✗ … 12 units run 1.1.0 (…) — re-run the server installer`; `⚠` when no unit is found under
+  `~/.config/systemd/user` or `$XDG_CONFIG_HOME/systemd/user`).
+- The updates ([Update](#update)), from `update/last.json`: `updates: checked 12 min ago: latest names 1.2.0: installed ·
+  last update ok: 1.1.0 → 1.2.0`. `✗` when the last update ended `partial` (with the steps that failed, the log, and
+  that `lanes update` runs its post-commit again) or `failed`, or when the last check found a release it could not
+  install (no recorded npx); `⚠` when the registry gave no release, the last update was refused, no update is recorded
+  yet, `lanes-update.timer` is not enabled (no `timers.target.wants/lanes-update.timer` link in
+  `~/.config/systemd/user` or `$XDG_CONFIG_HOME/systemd/user`: said at once, with `systemctl --user enable --now
+  lanes-update.timer` — an update with `--update-only` never enables it), or the last check is more than 2 hours old
+  (is `lanes-update.timer` on?); a release a rollback marked bad is named. A checkout server gets one line of
+  information; without an installed release there is no line.
 
 ## 7. Agents in lanes
 
@@ -1094,8 +1690,12 @@ Names must be non-empty and free of control characters. The id, resolve file and
 `lanes-statusd` reads each container through `/proc/<init pid>/root` every cycle (3 s) and, without starting
 anything, picks the first signal that applies:
 
-1. A **hook sidecar** `~/.lz/state/hooks/<lane id>.json` written by `lane-signal` (when hooks are installed), while
-   its agent process is alive and its last event is under an hour old.
+1. A **hook sidecar** `~/.lz/state/hooks/<lane id>.json` written by `lane-signal` (when hooks are installed, or when
+   the agent reports itself with `lanes_signal`), while its agent process is alive and its last event is under an
+   hour old. Its `name`, when there is one, is the agent's own note: the lane's task line. A `lanes_signal` report
+   stands against the agent's own hooks until the agent does something new (its next tool call, a new prompt, a
+   permission prompt, a failed turn, the session's end); the hook of the report's own tool call and the end of the
+   turn keep it, unless the report was `working`.
 2. A **Claude Code session file** `~/.claude/sessions/<pid>.json` naming the pane, for a live pid (recycled pids are
    rejected).
 3. The **Codex pane title**: `[ ! ] Action Required` is needs approval, a braille spinner is working, a task title is
@@ -1104,6 +1704,17 @@ anything, picks the first signal that applies:
 
 A Codex title left on a bare shell with no child process is `shell` (the harness ended).
 
+What the sidebar shows is not that word itself but a debounced one. The sections rank Needs you > Working > Done > the
+workspace's other lanes: a status that moves the lane up is shown at once, one that moves it down only after it has
+held for 8 s (leaving Needs you) or 5 s (leaving Working or Done), and a lane whose agent signal disappears keeps its
+glyph 5 s. `status.json` carries both:
+`agent.status` (debounced) and `agent.raw_status` (this cycle's word), with `agent.stable_since`, when the lane
+entered its section — the sidebar orders each section by it. With the Claude hooks installed, every tool call that
+starts signals Working (`PreToolUse`); that hook fires before the permission dialog, so a call you approve still shows
+`◆` while it runs and for the 8 s dwell after it ends (`PostToolUse`; DEF-1571, open — [RUNBOOK](RUNBOOK.md#installing-agent-hooks-opt-in-per-container-dry-run-first)).
+A Codex approval read from its pane title (a lane without hooks) keeps the same 8 s dwell once approved. The full rules:
+[Attention queue](ARCHITECTURE.md#attention-queue).
+
 ### A user's agents in one step: `lanes onboard`
 
 On the server, one command gives a new user's workspace container what its agents need. Without `--write` it prints
@@ -1117,14 +1728,15 @@ lanes onboard anna --container ws-anna --workspace anna-tools --repo /home/coder
 | Step | What the agents get |
 | --- | --- |
 | Board | A workspace tab for the repository (`lanes workspaces add`, section 6) on every device's view |
-| Contract | `lane`, `lane-run`, `lane-signal` and the hook definitions in the container's `~/.lz` (`lanes install-container`) |
+| Contract | `lane`, `lane-run`, `lane-signal`, `lane-edit`, the quick-edit `vimrc`, `lane-mcp` and the hook definitions in the container's `~/.lz` (`lanes install-container`) |
+| Agent tools | The Lanes MCP server in Claude Code's and Codex's configuration, so an agent can see the lanes around it ("Agent tools (MCP)" below) |
 | Hooks | The lane-signal hooks for Claude Code and Codex ("Hooks" below), so the sidebar's agent glyphs are event-driven |
 | Throttle | `throttle setup --install-clients` inside the container when Throttle is installed and configured there, so the agents' requests go through the pool; otherwise the one-time setup to run on a terminal is printed (a first setup signs in, which needs a person; Lanes runs without Throttle) |
 | Recipes | `lanes cursor-sync <id> --canonicalize --write` when the repository has a `.vscode/terminals.json`: each lane's create recipe gives it its identity and trace ("Lane identity" below) |
 | Sync and doctor | The registry knows the new lanes; `lanes doctor`'s result is reported, never fatal |
 
 The receipt is `~/.local/state/lanes/onboard/<login>-<UTC>.json`, and running the command again changes nothing that
-is already done. `--no-mcp` leaves out `lane-mcp`, the in-container MCP server, which has not shipped yet. Every step
+is already done. `--no-mcp` leaves out `lane-mcp` and its entries in the agents' configuration. Every step
 and status: [install guide](INSTALL.md#onboard-a-users-container).
 
 **Laptop agents on the pool (operator-gated).** Agents a user runs on their own laptop, outside any lane, can use the
@@ -1156,7 +1768,7 @@ restore the `.lanes-bak-*` file, or delete the groups whose command contains `la
 
 | Harness | Event | Status |
 | --- | --- | --- |
-| Claude Code | `UserPromptSubmit`, `PostToolUse` | working |
+| Claude Code | `UserPromptSubmit`, `PreToolUse`, `PostToolUse` | working |
 | Claude Code | `Stop`, `Notification` (idle prompt) | needs_input |
 | Claude Code | `PermissionRequest`, `Notification` (permission prompt) | needs_approval |
 | Claude Code | `StopFailure` | errored |
@@ -1168,7 +1780,8 @@ restore the `.lanes-bak-*` file, or delete the groups whose command contains `la
 | Codex | `SessionEnd` | shell |
 
 Known limit: after you approve a permission prompt the lane reads needs approval until the approved tool call
-returns, because neither harness signals "approved".
+returns, because neither harness signals "approved". With Claude Code, after a denied prompt or a failed approved
+call the lane reads working again as soon as the agent starts its next tool call (`PreToolUse`).
 
 ### The in-container `lane` command
 
@@ -1179,19 +1792,135 @@ verbs, so the holder stays swappable.
 | --- | --- |
 | `lane open <lane-id>` | The editor entry point: attach to the lane; if it does not exist, run its recorded create recipe. Refuses to nest inside tmux; attaches with `ignore-size` while a lanes view shows the lane |
 | `lane attach <id>` | Attach this terminal; never creates; refuses to nest |
-| `lane send <id> [--no-enter] <text…>` | Type into the lane: tmux literally, then Enter unless `--no-enter`; zmx sends the bytes as given |
+| `lane send <id> [--no-enter] <text…>` | Type into the lane: tmux literally, then Enter half a second later unless `--no-enter` (an agent's prompt takes text and Enter that arrive together as a paste and never submits it); zmx sends the bytes as given |
 | `lane capture <id> [--lines N] [--vt]` | Print the scrollback (plain, or with escapes under `--vt`) |
 | `lane ls [--json] [--all]` | zmx lanes; `--all` adds the registry's tmux lanes with `alive` |
 | `lane status <id>` | JSON: alive, the hook agent, metadata; exit 1 when not running |
 | `lane kill <id> --yes [--force]` | End the lane (the only verb that ends an agent); refuses while the hook sidecar says `working` unless `--force` |
 | `lane new <id> [--ws W] [--title T] [--cwd DIR] [--icon I] [--color C] -- <command…>` | Create a zmx-held lane |
 | `lane gc --sockets` | Unlink this container's tmux socket files that tmux is refused on (no server listens); a live, empty or silent server keeps its file |
+| `lane mcp install [--agent claude\|codex\|all] [--write]` | Add the Lanes MCP server to `~/.claude.json` and `~/.codex/config.toml` ("Agent tools (MCP)" below); a dry run until `--write` |
+| `lane 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.
 
 `lane-run` is the root process of a zmx lane: it runs the agent command, then a login shell in the same directory,
 forever ("lanes never die on agent exit"). `~/.lz/env.sh`, sourced by new shells, points `TMPDIR` and
 `CLAUDE_CODE_TMPDIR` at `/home/coder/.tmp` (`LANES_TMP_DIR` names another; `LANES_TMP_OPTOUT` opts out); tmux sockets
 stay in `/tmp/tmux-<uid>`.
 
+`lane-edit <file>` is the editor `Ctrl-Alt-e` opens in the container, as uid 1000 in the checkout's root. It prints
+one line, `editing <file> · <checkout> · :wq to finish` (micro: `Ctrl-s, Ctrl-q to finish`), then runs
+`$LANES_EDITOR` when that names a program on the container's PATH (one word, a name or an absolute path, no
+arguments; `lanes edit` sets it from the device's `lanes attach --editor`), else the first of `micro`, `hx`, `nvim`,
+`vim` and `vi` it finds. **Lanes installs no editor**: a
+container with none of them gets `lane-edit: no editor on PATH` (exit 127) and nothing opens, so vi (or vim) is the
+floor. vim and nvim, and a `vi` that is vim behind a link, start with `-u ~/.lz/vimrc` instead of your own vimrc: the
+file is written in place (it keeps its mode and owner), swap and backup files go to `~/.lz/tmp/` (0700) rather than
+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
+configuration, and it lets the agent in a lane see the lanes around it and, within limits, change them. Four tools
+only read:
+
+| Tool | Answers |
+| --- | --- |
+| `lanes_whoami` | Which lane the agent runs in: id, board, name, kind (declared, registered or unregistered), tmux socket and session. It comes from `LANE_ID`, else from the agent's own tmux pane. Outside a lane the answer is `lane: null` with the reason |
+| `lanes_list` | Every lane in this container with its state and its agent (harness, status, task). Filters: `workspace`, `needs_you: true` (needs approval, errored or needs input, the sidebar's "Needs you" section) and `agent` (`any`, `none`, `claude`, `codex`). `status.fresh` is false once the host's observation is more than 60 s old |
+| `lanes_status` | One lane in full: what the registry says, the observed state and agent, whether its tmux session is alive now (`null` when tmux does not answer in 5 s) and its hook sidecar |
+| `lanes_capture` | The last `lines` (1 to 500, default 100) non-blank lines of a lane's screen and scrollback, as plain text. Any lane of the container can be read |
+
+Where the answers come from: `~/.lz/registry.json`, which `lanes sync` writes, and `~/.lz/status.json`, which the
+status daemon writes. A container that has neither yet answers with empty lists and says why.
+
+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 |
+| --- | --- | --- |
+| `lanes_register` | `name`, optional `session` and `repo`. Declares an unregistered tmux session — the one the agent runs in, or the one `session` names — as a lane: one terminal appended to its board's `.vscode/terminals.json` (command `lane open <id>`, the exact tmux binding, the canonical create recipe). Nothing is started, stopped or renamed. Answers the id the lane will have, `<workspace>--<slug of prefix + name>` | after the next `lanes sync`, within about 15 s |
+| `lanes_unregister` | Removes a declared lane's terminal (its `terminals[]` item and its `lanes.terminals` entry). The session keeps running and shows as an unregistered session again | same |
+| `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
+do instead, and nothing was changed. `lanes_register` refuses a session that is a lane already (`already_declared`,
+or `adopted_lane` for a session added with `lanes register` on the host), a name or display name another lane of the
+board shows (`duplicate_name`), a name whose id another lane holds or is made from (`slug_collision`), a name without
+a letter or digit A–Z/0–9 (`invalid_name`), a binding the file declares already (`duplicate_binding`), a session that
+is not running (`session_gone`) and a board with more than one repository in the container unless `repo` names one
+(`ambiguous_source`). `lanes_unregister` never removes the last terminal of a file (`last_terminal`), an adopted
+session or a lane whose declaration is not in a file the container holds (`not_declared_here`). `lanes_rename`
+refuses an unregistered session (register it first) and a name with a control character. `lanes_new` refuses a
+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`). `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.
+
+Left to people, on purpose (no tool exists for them): ending or closing a lane, interrupting one, opening or
+attaching one, uploads, the host's `lanes sync`/`gc`/`ensure`, renaming a tmux session, and any change to a session
+added with `lanes register` (its name and membership live on the host, in `registered-sessions.json`).
+
+`lanes install-container` (and so `lanes onboard`) adds the server to both agents by default:
+`"mcpServers": {"lanes": {"command": "/home/coder/.lz/bin/lane-mcp"}}` in `~/.claude.json` and
+
+```toml
+[mcp_servers.lanes]
+command = "/home/coder/.lz/bin/lane-mcp"
+env_vars = ["LANE_ID", "LANE_WS", "TMUX", "TMUX_PANE"]
+```
+
+in `~/.codex/config.toml`. Codex starts an MCP server with a cleared environment (only `HOME`, `PATH`, `USER` and a
+few more of its own), so `env_vars` passes the server what `lanes_whoami` reads; without it a Codex agent could see
+every lane but its own. Claude Code's servers inherit the agent's environment. An entry is written only where it is
+missing, and nothing else in either file changes. A Codex table that starts `lane-mcp` but does not pass all four
+names (the one `codex mcp add` writes, for instance) gains the `env_vars` line, or the names it lacks. The old file
+is kept as `<file>.bak-<UTC time>` first. `--no-mcp` leaves out `lane-mcp` and both entries, and removes nothing an
+earlier install wrote. Inside the container the same change is one command:
+
+```sh
+~/.lz/bin/lane mcp install                       # prints the diff to both files
+~/.lz/bin/lane mcp install --agent claude --write   # applies it for Claude Code only
+```
+
+An entry named `lanes` that starts something other than `lane-mcp` is never replaced. A file that is not strict
+JSON or valid TOML is left alone too, and so is a Codex `env_vars` written other than as one line of plain names.
+All of these are reported and exit 1. New agent sessions load the server; a
+running session keeps the tools it started with. Undo: restore the `.bak-*` file, or delete the `lanes` entry. The
+server logs one line per request (the tool, the lane, the outcome and a refusal's code; never a capture's text, a
+sent text or a note) to `~/.lz/s/logs/lane-mcp.log`. It speaks MCP protocol
+versions 2025-06-18, 2025-03-26 and 2024-11-05 over stdio.
+
+More on it: the wire contract, the latency of each write and what stays with people, in
+[ARCHITECTURE "Agent API"](ARCHITECTURE.md#agent-api). Uninstall, troubleshooting and a two-frame protocol smoke
+are in the [runbook](RUNBOOK.md#install-check-uninstall). What to tell your agents is in the
+[`lanes-agent-tools` skill](../../skills/lanes-agent-tools/SKILL.md).
+
 ### Lane identity and the canonical recipe
 
 A lane's identity is its environment: `LANE_ID` (`<ws>--<slug>`), `LANE_WS` (`<ws>`), and the Throttle trace
@@ -1262,7 +1991,8 @@ Covered in section 3: one notification per lane entering Needs you, from the sid
 ### Push notifications (opt-in, operator gate)
 
 `lanes-notify.service` sends one push to an [ntfy](https://ntfy.sh) topic when a lane's agent enters needs you
-(`Needs you`, `Needs approval`, `Error`). It reads only `status.json`, the registry and `enrol-requests/`, every 3 s.
+(`Needs you`, `Needs approval`, `Error`). It reads only `status.json`, the registry and `enrol-requests/`, every 3 s,
+and on such a transition the files that say who was at a desk (below).
 A push says
 `<lane name>: <agent task> — <status>` and `lanes-launch lane <id>`. It also pushes once per new enrolment request
 (`Enrol request`: `<name or login> · <device>` and `lanes enrol approve <id>`), never muted by presence, once per
@@ -1276,12 +2006,17 @@ you configure, so enabling it is your decision. Not yet run against a real ntfy
 | `url` | required | The ntfy server, `https://…` |
 | `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 |
-| `action_url` | unset | A URL template over `{lane}`; becomes the tap target and an **Open lane** button |
+| `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. `{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
-device's sidebar. Opening a lane from the phone never mutes pushes. A failed send is one journal line, not retried.
+device's sidebar (its seen file, or your profile when that desk device wrote it). Opening a lane from the phone
+never mutes pushes, and neither does an admin verb run on the command line for you (`lanes workspaces …`, `lanes
+lane …`, `lanes device claim`, `lanes keys adopt --login`): it writes your profile as `cli:<command>`, not as your
+device. The window is yours when only you were present and your profile sets `notify.quiet_s` (`0`:
+never mute your pushes; no verb sets it yet, see the [runbook](RUNBOOK.md#push-notifications-opt-in)); when several
+people were, the host's `quiet_when_device_active_s` decides. A failed send is one journal line, not retried.
 
 ```sh
 $EDITOR ~/.config/lanes/notify.conf
@@ -1299,20 +2034,48 @@ files. `python3 libexec/tokens.py --check` fails on drift; `--write` regenerates
 
 | Switch | Values | Default |
 | --- | --- | --- |
-| Colour (`--color`, `LANES_COLOR`) | `truecolor` · `16` · `none` | `truecolor` when `COLORTERM` is `truecolor`/`24bit` (the view's config sets it for every pane), else `16`; `NO_COLOR` set means `none` |
+| Colour (`--color`, `LANES_COLOR`) | `truecolor` · `256` · `16` · `none` | `truecolor` when `COLORTERM` is `truecolor`/`24bit` (the view's config sets it for every pane, so inside a view this is always `truecolor`; see below), else `256` when `TERM` contains `256color`, else `16`; `NO_COLOR` set means `none`. `truecolor` and `256` colour the section words, names and ages and lay the cursor row on a soft background; `16` (your terminal's palette) and `none` keep the quieter look. A viewport's status screens ("THIS VIEWER DISCONNECTED", "retrying in …") follow the same choice and theme: an amber lead and a readable dim line in `truecolor` and `256` |
 | Theme (`--theme`, `LANES_THEME`) | `dark` · `light` · `auto` | `auto`: the sidebar asks the terminal's background once (OSC 11) and paints dark without an answer in 0.3 s |
 | Glyphs (`--glyphs`, `--ascii`, `LANES_GLYPHS`) | `unicode` · `ascii` · `emoji` | `unicode`; `ascii` when no locale variable names UTF-8. `emoji` adds an icon column from the lane's `icon` |
-| Dim (`LANES_DIM`) | `90` · `2` | `90`; 16-colour mode only: `2` for palettes whose colour 8 is near the background |
-
-**Set the look per device**, live: `lanes attach <device> --ascii` (or `--glyphs M`, `--theme T`, `--color C`) records
-it in `~/.local/state/lanes/devices/<device>.json` for a device that already has that file; every running sidebar of
-the device picks it up within a tick, and the choice survives `lanes ensure` and `lanes rebuild`. From a client,
-`lanes-window --ascii|--light|--dark [suffix]` and `lanes-launch <device> --ascii|--theme T|--glyphs M|--color C`
-pass the same flags. The device file wins over the environment.
-
-The environment variables reach a sidebar only through the view server's environment when its session is created,
-and `bin/lanes` starts view sessions from a clean environment that does not forward them. On a standard server use
-the per-device flags; the variables matter when you run the sidebar by hand.
+| Dim (`--dim`, `LANES_DIM`) | `90` · `2` | `90`; 16-colour mode only: `2` for palettes whose colour 8 is near the background |
+| Notifications (`--notify`, `LANES_NOTIFY`) | `1` · `0` | `1` on desktop layouts; `0` silences the OSC 9 desktop notifications (section 3). A phone never gets them |
+
+**Set the look**, live: `lanes attach <device> --ascii` (or `--glyphs M`, `--theme T`, `--color C`, `--notify N`,
+`--dim D`, and `--editor E`, the editor of [quick edit](#quick-edit)) records it for a device that already has a view (`~/.local/state/lanes/devices/<device>.json`). On a device
+with an owner — its member record's, its machine's for a window such as `mac-2`, or one `lanes device claim` named —
+`--theme`, `--color`, `--glyphs` and `--ascii` go to that person's profile, `users/<login>.json`, which every device they
+own shares, and leave the device file; add `--device-only` to keep them in the device file for that device alone,
+marked as its own (the file's `device_only` list), where they win over the profile; the same flag without
+`--device-only` hands the key back to the profile. `--notify`, `--dim` and `--editor` always stay per device, and a device without
+an owner records every flag in its device file. Every running sidebar of the device picks a device-file change up
+within a tick, and every sidebar of every device the person owns picks a profile change up within a tick too (`lanes
+attach phone --theme light` repaints the Mac); the choice survives `lanes ensure` and `lanes rebuild`. A sidebar
+paints, per key, the device file's `--device-only` value, else the profile's, else the environment's, else the default.
+A look a device recorded before it had a profile — a device enrolled before profiles existed that ran `lanes-window
+--dark` then — is not the device's own: it paints only where the profile sets no such key, so recording that key from
+any device of the person repaints this one too. `lanes user show <login>` names each look a device of that person
+keeps in its own file, and why; `lanes device claim <device> --login <login>` folds such a look into the profile (the
+profile's own keys win) and out of the device file — also on a device whose member record already names that login.
+Lanes never folds it by itself: a device handed to another person still holds its previous owner's look. From a
+client,
+`lanes-window --ascii|--light|--dark [--device-only]
+[suffix]` and `lanes-launch <device> --ascii|--theme T|--glyphs M|--color C|--notify N|--dim D|--editor E|--device-only`
+pass the same flags (`lanes-window --light --device-only`: light on this device alone). The device file and the profile win
+over the environment. `lanes user show <login>` prints a profile and the devices' own looks.
+
+The environment variables `LANES_COLOR`, `LANES_THEME`, `LANES_GLYPHS`, `LANES_DIM` and `LANES_NOTIFY` reach a
+sidebar through the view server's environment: `bin/lanes` forwards them, when set, from the shell that creates a
+view session (`lanes attach` of a device whose session is not running, `lanes ensure`, `lanes rebuild`) into that
+session, so every sidebar it starts inherits them. A running session keeps the environment it was created with, and
+SSH does not pass them from your client's shell; for a device, the flags above are the live path.
+
+**256 colours inside a view** are something you choose; Lanes never detects them there. The view's
+`zellij/config.kdl` gives every pane `COLORTERM=truecolor`, which the sidebar reads before `TERM`, so the
+`256color` rule (and `NO_COLOR`, which is not forwarded) applies only outside Zellij, to a sidebar started by hand. If
+your terminal cannot show 24-bit colour, run `lanes attach <device> --color 256` (live, kept by `lanes ensure` and
+`lanes rebuild`) or create the session with `LANES_COLOR=256 lanes rebuild <device>`. The 256 set uses the fixed xterm
+colours 16–255 (the `256 dark` / `256 light` columns of [`docs/DESIGN.md`](DESIGN.md)), so your own palette never
+changes it; `--color none` is the glyphs-only look.
 
 **Ghostty palette** (opt-in): by default the lanes window inherits your everyday Ghostty look. `./install.sh --palette`
 installs `~/.config/lanes/ghostty-palette.conf` generated from the tokens (a light/dark theme pair on Ghostty 1.1 or
@@ -1370,9 +2133,11 @@ All units run in `lanes.slice` and are rendered by the server installer from `la
 | `lanes.slice` | — | (used by every unit) | High CPU weight and `MemoryLow` for the harness, so it stays scheduled on a thrashing host |
 | `lanes-statusd.service` | Always on | Server install | Observes every lane (never touches one); writes `status.json` and `health`; hot-sync |
 | `lanes-sync.timer` / `.service` | Every 2 min | Server install | `lanes sync` |
-| `lanes-ensure.timer` / `.service` | Every 1 min | Server install | `lanes ensure`: recreate missing device view sessions |
-| `lanes-gc.timer` / `.service` | Daily | Server install | `lanes gc`: truncate zmx logs over 5 MB, drop stale dynamic resolve files |
+| `lanes-ensure.timer` / `.service` | Every 1 min | Server install | `lanes ensure`: recreate missing device view sessions; rebuild a view an update left once no client is attached |
+| `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 |
@@ -1394,38 +2159,50 @@ Clients also get `lanes-helper.service` and `lanes-upload.path`/`.service` (Linu
 | Registry | `lanes resolve <lane-id>` | One lane's exact target as JSON |
 | Registry | `lanes status` | One line per workspace: state counts and the `status.json` age |
 | Registry | `lanes register <lane-id> [workspace]` | Add an unregistered session to a workspace without restarting it |
+| Registry | `lanes unregister <lane-id>` | Take a session added that way out of its workspace again (the sidebar's `u`): nothing stops, a running one is listed under Unregistered with the same id and name; refused while tmux cannot check it, and for a lane a repository's `terminals.json` declares (the file to edit is named) |
 | Registry | `lanes rename <lane-id> <new-name>` | Change a lane's display name (not in the usage text) |
 | Registry | `lanes workspaces` | Print the workspace ids (used by the client installer) |
 | Registry | `lanes workspaces add <id> --container <name> --repo <path> [--title T] [--session S] [--write]` | Add a one-repository board to the site catalog (a dry run until `--write`; section 6) |
-| Views | `lanes attach <device> [--client ID] [--mobile] [--viewports N] [--ascii] [--glyphs …] [--theme …] [--color …]` | Attach this terminal to the device's view (create it if needed); record the look |
+| Views | `lanes attach <device> [--client ID] [--mobile] [--viewports N] [--ascii] [--glyphs …] [--theme …] [--color …] [--editor …] [--device-only]` | Attach this terminal to the device's view (create it if needed); record the look — in the owner's profile on a device with an owner, on the device with `--device-only` or without one (section 9) — and the quick-edit editor (always per device) |
 | Views | `lanes prepare <device> [--mobile\|--desktop] [--viewports N]` | Create a view without attaching; a different explicit layout is refused |
 | Views | `lanes web <device> [--desktop\|--mobile] [--viewports N] [--token \| --print-only]` | Browser view in one step, Tailscale Serve included (section 4) |
 | Views | `lanes token list` / `revoke <device>` / `revoke --name NAME` / `revoke-all [--yes]` | Web login tokens and their devices (section 4) |
 | Views | `lanes open <lane-id>` | Attach this terminal straight to one lane |
 | Views | `lanes layout <device> [--mobile]` | Print the generated Zellij layout |
-| Views | `lanes rebuild <device>` | Recreate a device's view (agents never touched) |
-| Views | `lanes upgrade-session [device…]` | Sync catalog tabs and titles into live views without a rebuild |
-| Views | `lanes ensure` | Recreate known device sessions that are missing |
+| Views | `lanes rebuild <device>` | Recreate a device's view (agents never touched); waits up to 120 s while another `ensure`, `rebuild` or view create runs (the view-session lock), then names it and exits 1 |
+| Views | `lanes upgrade-session [device…]` | Sync catalog tabs and titles into live views without a rebuild; close the tabs of workspaces the owner's profile hides |
+| Views | `lanes ensure [--if-layout-changed]` | Recreate known device sessions that are missing; with the flag (the update's last step) also rebuild each view the installed release lays out differently that has no client attached, and mark the others `update ready · reload (r)`. One run at a time with every rebuild and view create: with the flag it waits up to 120 s for another, without it 10 s and then skips the run |
 | Views | `lanes reattach` | Make every view re-attach its lane |
+| Views | `lanes reload-views` | Ask every running viewport to start again from the installed release at its next lane switch (a viewport of an older release, which the signal would end, is left alone and named: `lanes rebuild <device>`); the server update runs it |
 | Views | `lanes device list` / `lanes device forget <name>` | The devices `ensure` keeps / stop keeping one |
+| Views | `lanes device claim <device> --login L [--name N]` | Name the owner of a device no member record speaks for (one from before enrolment) and fold it and its windows into that person's profile (all but `--device-only` keys); with the login its member record names it only folds (a look from before the profile); refused when a member record names someone else or nobody |
+| Views | `lanes user list` / `lanes user show <login> [--json]` | The people lanes knows with their devices / one person's profile and every look one of their devices keeps in its own file (`--device-only`, or from before the profile) (read-only) |
+| Views | `lanes workspaces hide\|show\|order <id…> [--device D \| --login L]` | Arrange one person's boards on every device they own, in their profile: hide or show boards (a hide that would leave no board is refused), or name the order of the first boards (the rest follow in catalog order). The person is the owner of `--device D`, else of `$LANES_DEVICE`, or `--login L`. Stored in the profile, which the tabs (cockpit v3 R4) and the sidebars (R5, and their keys `p h H o`) of every device of that person follow |
+| Views | `lanes lane pin\|unpin\|hide\|show <lane-id> [--device D \| --login L]` | The same person's pinned lanes (listed first) and hidden lanes (left out of their lists); hide takes a registered lane only |
+| Views | `lanes here <device>` | Show on that device the lane its owner opened last on any of their devices; says why when it cannot (`lanes-launch here` runs it for your own device) |
 | Views | `lanes next\|prev --focused [--device D]` | What `Ctrl-Alt-↓` / `Ctrl-Alt-↑` run |
 | Views | `lanes preview --focused [--device D]` | What `Ctrl-Alt-m` runs |
+| Views | `lanes sidebar-key filter\|upload --focused [--device D]` | What `Ctrl-Alt-/` / `Ctrl-Alt-u` run after moving the focus to the sidebar |
+| Views | `lanes edit --focused [--device D]` | What `Ctrl-Alt-e` runs: the focused lane's AGENTS.md, CLAUDE.md or .env.local in a one-key picker, then the editor in its container ([quick edit](#quick-edit)); with another Edit pane open it focuses or names that one and opens nothing |
 | Editor | `lanes cursor-sync [ws…] [--write] [--diff] [--canonicalize] [--identity]` | Section 6 |
 | Editor | `lanes cursor-commit [ws…] [--push]` | Section 6 |
-| Containers | `lanes install-container <name> [--no-mcp]` | Install the `lane` contract (section 2); `--no-mcp` is for the future `lane-mcp` and changes nothing today |
+| Containers | `lanes install-container <name> [--no-mcp]` | Install the `lane` contract (section 2) and the agents' MCP entries for `lane-mcp` (section 7, "Agent tools (MCP)"); `--no-mcp` leaves both out |
 | Containers | `lanes onboard <login> --container <name> [--workspace <id> --repo <path> [--title T]] [--write] [--no-mcp]` | One user's container in one command: board, contract, Claude and Codex hooks, Throttle attachment, canonical recipes, sync, doctor, and a receipt (a dry run until `--write`; section 2) |
 | Containers | `lanes hooks install --agent claude\|codex (--container <name> \| --home <dir>) [--dry-run \| --write]` | Section 7 |
 | Uploads | `lanes upload <ws> \| --active <device> [--paste]` | Read a tar stream into that workspace's `uploads/` |
-| Client | `lanes hello [device]` | Prove path, key and server version |
+| 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]` | Who may log in: the lanes-managed block of `~/.ssh/authorized_keys`, projected from `members/` |
-| Access | `lanes keys owner <device> <login> [--name NAME] [--email ADDR]` | Name the person behind a member; a key added by hand has none, and `/enrol/pending` lets in only a login a member names ([RUNBOOK](RUNBOOK.md#enrolment-service-lanes-enrold-w8-a3)) |
+| 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 |
+| Access | `lanes keys owner <device> <login> [--name NAME] [--email ADDR]` | Name the person behind a member; a key added by hand has none, and `/enrol/pending` lets in only a login a member names ([RUNBOOK](RUNBOOK.md#enrolment-service-lanes-enrold-w8-a3)); the device's view and its windows fold into that person's profile |
 | Access | `lanes invite <name> [--email ADDR] [--expires 7d] [--workspaces a,b] [--tailscale-link URL] [--md]` | Mint a one-time code and print the welcome kit, on a terminal only (section 2, "Invite a user") |
 | Access | `lanes invite list \| revoke <id>` | The invites and their state; refuse a code from now on |
 | Access | `lanes enrol list [--all] \| approve <id> [--as <device>] \| deny <id> [--as <device>]` | The enrolment requests; decide one as `/enrol/pending` does |
 | Access | `lanes enrol mode [request\|invite\|auto]` | Pin request mode across restarts (or say what is pinned) |
 | Access | `lanes offboard <device> --yes` | Revoke the key, forget the device, sign out the web login tokens of the machine and its views, end its view (own terminal only) |
 | Health | `lanes doctor` | Full health check (section 6) |
+| Health | `lanes version [--json]` | The release and tree this server runs, whether `current` names it, and each process still on older code (`✗`: another tree, or started before a checkout's `git pull`) |
+| Health | `lanes update [--now \| --timer \| --status \| --rollback]` | Install the newest npm release when it is newer (what `lanes-update.timer` runs as `--timer`; `--now` asks the registry even within 20 min of the last check), print the record (`--status`), or install the previous release again and mark the one left bad (`--rollback`) — [Update](#update) |
 | Health | `lanes pressure` | Memory / io / cpu pressure, swap, per-container memory and `/tmp`; plain files only; exit 1 unless ok |
 | Health | `lanes invariant save\|check` | Snapshot / verify every live pane's pid and window size |
 | Health | `lanes sockets [check\|repair]` | tmux servers whose socket file was deleted; `repair` sends tmux's SIGUSR1, nothing restarts |
@@ -1441,10 +2218,11 @@ The client helpers call three more verbs (`rebuilt`, `upload-requests`, `upload-
 
 | Command | Does |
 | --- | --- |
-| `lanes-window [--ascii] [--light\|--dark] [suffix]` | Open the lanes window (section 3) |
-| `lanes-launch [device \| workspace \| lane <id> \| ls]` | The reconnecting client (section 3) |
+| `lanes-window [--ascii] [--light\|--dark] [--device-only] [suffix]` | Open the lanes window (section 3; the look: section 9) |
+| `lanes-launch [device \| workspace \| lane <id> \| ls \| here [device]]` | The reconnecting client (section 3); `here` shows the lane you opened last on another of your devices |
 | `lanes-launch web phone\|laptop\|<device> [--desktop\|--mobile] [--no-qr]` | A browser view plus a login token, in this terminal (section 4) |
-| `lanes-launch update [install.sh options]` | The newest client from npm with your remembered install options (section 2) |
+| `lanes-launch update [install.sh options]` | The newest client from npm with your remembered install options (section 2); a window also updates itself to the server's release, at most every 6 h ([Versions](#versions)) |
+| `lanes-launch --version` | This client's release (`lanes-launch 1.2.0`; [Versions](#versions)) |
 | `lanes-launch --helper <device> [--service \| --while-pid PID]` | Run only the upload helper (the service form is what the installer sets up) |
 | `lanes-upload …` | Uploads (section 5) |
 | `sh install/enable-phone.sh …` | Phone or browser view plus token; on the server a wrapper over `lanes web … --token` (section 4) |
@@ -1459,13 +2237,15 @@ 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`, `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, look |
+| `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 |
-| `views/<device>/` | Per-viewport target, pid and error files |
-| `clients/` | Client pids, `.ready`, `.rebuilt`, `<device>.seen.json` (opened `done` lanes), `.theme`, `.glyphs` |
+| `views/<device>/` | Per-viewport target, pid and error files; `<workspace>.sidebar.cmd`, the key `Ctrl-Alt-/` or `Ctrl-Alt-u` handed to that workspace's sidebar (`{"cmd": "filter"\|"upload", "at": …}`, ignored once 10 s old); `<workspace>.<slot>.sidebar.state`, what a sidebar that swapped itself onto a new tree hands its successor (cursor lane, scroll, opened-lane marks, filter; taken and deleted at once, ignored once 60 s old) |
+| `clients/` | Client pids, `.ready`, `.rebuilt`, `<device>.seen.json` (the `done` lanes opened on that device; a device with an owner also marks them in the profile), `.theme`, `.glyphs`, `.color`, `<device>.update-ready` (an update changed that view's layout while it was attached: its sidebar offers the reload) |
 | `defaults/<workspace>` | The lane a workspace's first viewport shows by default (its `focus` lane, else the first) |
 | `user-sessions/<id>.json` | Names of unregistered sessions |
+| `handback/<digest>.json` | The workspace and id a session unregistered while it ran keeps (`u`, `lanes unregister`): statusd lists it there under that id; it applies to that one tmux session only |
 | `upload-requests/<device>/` | Upload hand-off between sidebar and helper |
 | `economy.json`, `economy.cursor.json` | The opt-in economy projection and its log cursor |
 | `notify.enrol-seen.json` | The enrolment requests the opt-in push notifier already announced (0600, pruned to the requests on disk); deleting it announces the ones still pending once more |
@@ -1475,25 +2255,42 @@ Server (`~/.local/state/lanes/`, `$LANES_STATE`):
 | `tmpscan/` | `lanes tmp` plans and `deleted.log` |
 | `studio-host/` | Optional Studio Host: public key, receipt, enrolment record |
 | `members/<device>.json`, `members.lock` | Who each enrolled machine key belongs to (`lanes keys`; the managed block of `~/.ssh/authorized_keys` is its projection) and the lock every writer of it holds |
+| `users/<login>.json`, `users/<login>.lock` | One profile per person, named by the percent-encoded login (`anna%40example.com.json`) and shared by every device that person owns: look, opened-lane marks, workspace order and hidden boards, pinned and hidden lanes, the last lane opened; and the lock each writer holds for at most a second (0600). Written by `lanes attach`'s look flags on a device with an owner, `lanes device claim`, `lanes keys adopt --login`, `lanes keys owner`, by `lanes workspaces hide\|show\|order`, `lanes lane pin\|unpin\|hide\|show` and the sidebar keys `p`, `h`, `H` (the arrangement), and by the sidebars, `lanes next\|prev` and `lanes here` when a lane is opened (its mark and the last lane opened); read by `lanes user list\|show`, by `lanes here` (the last lane opened), by the push notifier (a desk device's write is presence — never a command-line verb's, stamped `cli:<command>`; `notify.quiet_s` is your own quiet window) by the view's tabs (`create_session`, `lanes upgrade-session`: board order and hidden boards) and by every sidebar of a device with an owner, which paints its look beneath the device file's own keys, lists its pins first and leaves its hidden lanes out, and re-reads it within a tick of a change |
 | `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 |
+| `locks/sessions.lock` | The view-session lock: `lanes ensure`, `lanes rebuild` (and the sidebar's `r`), the create of `attach`/`prepare`/`web`, `lanes offboard`'s end of a view and `lanes device forget` hold it from their session list to their last Zellij call, so two of them never create or end one view at once; `{pid, doing, since}` of the holder while held, empty after (DEF-1792) |
+| `update/npx`, `locks/update.lock` | The npx the npm installer ran a `--server` install with (one absolute path; `lanes update` installs with it); the lock one `lanes update` at a time holds (`{pid, started}`) |
 
-Other server paths: `~/.config/lanes/` (`workspaces/`, `site.conf`, `notify.conf`, and the optional invite key files
+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` checkout link, npm-staged `pkg/<version>/`), and `~/.lz/<container>` (links to each
+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
 container's `.lz`).
 
-In each container (`/home/coder/.lz/`): `bin/` (`lane`, `lane-run`, `lane-signal`, `zmx-*`), `hooks/` (hook
-definitions), `env.sh`, `registry.json` (the projection `lanes sync` writes), `state/hooks/` (hook sidecars),
-`state/<zmx name>.json` (`lane-run` phase records), `meta/` and `s/` (zmx metadata and sockets).
+In each container (`/home/coder/.lz/`): `bin/` (`lane`, `lane_core.py`, `lane-run`, `lane-signal`, `lane-edit`,
+`lane-mcp`, `zmx-*`), `VERSION` (the Lanes version that installed them), `s/logs/lane-mcp.log`, `hooks/` (hook
+definitions), `env.sh`, `vimrc` (what `lane-edit` gives vim and nvim), `tmp/` (their swap files while an edit is open;
+created by `lane-edit`, 0700), `registry.json` (the projection `lanes sync` writes), `status.json` (this container's
+lane states, which the status daemon writes), `state/hooks/` (hook sidecars), `state/<zmx name>.json` (`lane-run` phase
+records), `meta/` and `s/` (zmx metadata and sockets). In the container home itself, the agents' entries for
+`lane-mcp`: `mcpServers.lanes` in `~/.claude.json` and `[mcp_servers.lanes]` in `~/.codex/config.toml`, with the
+`.bak-<UTC time>` copies their first write kept.
 
 Client: `~/.config/lanes/` (`device`, `install-options`, `ghostty.conf`, `client-site.conf`, `client-known-hosts`,
 `site.cache`, `upload-allow`, `uploads-dir`, and `enrol-request` while an access request is open),
-`~/.local/state/lanes-client/` (`launch-<target>.log`, `helper.alive`, `helper-service.log`), `~/.local/share/lanes/client/`.
+`~/.local/state/lanes-client/` (`launch-<target>.log`, `helper.alive`, `helper-service.log`, `checked` — the time of a
+window's last update question — and `checking/` while one asks), `~/.local/share/lanes/client/`.
 
 ### NEVER
 
@@ -1549,9 +2346,9 @@ Server and views:
 | `LANES_WORKSPACES` | `libexec/lanes_lib.py`, `host-install.sh`, `services.py` | unset | Site directory; unset means `~/.config/lanes/workspaces` (if it has a catalog), else the checkout's `workspaces/` |
 | `LANES_STATUS_INTERVAL` | `libexec/statusd.py` | `3` | Seconds between statusd cycles |
 | `LANES_CONTAINER_UID` | `holders/tmux.sh`, `libexec/view.sh` | `1000` | The containers' tmux uid in socket paths |
-| `LANES_COLOR`, `LANES_THEME`, `LANES_GLYPHS` | `libexec/sidebar.py` | see section 9 | Sidebar look; the device file wins; not forwarded into view sessions by `bin/lanes` |
-| `LANES_DIM` | `libexec/tokens.py` (in the sidebar) | `90` | `2` uses SGR 2 for dim text in 16-colour mode; not forwarded into view sessions |
-| `LANES_NOTIFY` | `libexec/sidebar.py` | unset (on) | `0` silences OSC 9; not forwarded into view sessions |
+| `LANES_COLOR`, `LANES_THEME`, `LANES_GLYPHS` | `libexec/sidebar.py` | see section 9 | Sidebar look; the device file wins; forwarded by `bin/lanes` into the view sessions it creates |
+| `LANES_DIM` | `libexec/sidebar.py` (`libexec/tokens.py` outside it) | `90` | `2` uses SGR 2 for dim text in 16-colour mode; the device file's `dim` wins; forwarded into the view sessions `bin/lanes` creates |
+| `LANES_NOTIFY` | `libexec/sidebar.py` | unset (on) | `0` silences OSC 9; the device file's `notify` wins; forwarded into the view sessions `bin/lanes` creates |
 | `NO_COLOR`, `COLORTERM`, `LC_ALL`, `LC_CTYPE`, `LANG` | `libexec/sidebar.py` | — | Colour and glyph defaults |
 | `LANES_THROTTLE_CONTROL` | `libexec/economy_poll.py` | `http://127.0.0.1:19181` | Throttle control URL; `none` sends no request |
 | `LANES_THROTTLE_TOKEN_FILE` | `libexec/economy_poll.py` | unset | File holding a bearer token |
@@ -1563,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:
@@ -1582,7 +2385,11 @@ Client:
 | `LANES_INVITE` | `install.sh`, `npm/lanes` wrapper | unset | An invite code, as `--invite` (the wrapper picks the site from its prefix) |
 | `LANES_ENROL_WAIT`, `LANES_ENROL_POLL` | `install.sh` | `600`, `5` | Seconds an install waits for an access request's approval, and between two looks |
 | `LANES_ENROL_URL` | `install.sh` | `https://<LANES_SERVER_NAME>:8443` | The enrolment service's base URL (development and tests) |
-| `LANES_PKG_ROOT` | `npm/lanes` wrapper | `~/.local/share/lanes/pkg` | Where npm-staged trees go |
+| `LANES_NO_AUTOUPDATE` | `lanes-launch`, `npm/lanes` wrapper | unset | Any value: a window never updates its client by itself ([Versions](#versions)), and the wrapper never hands an invite to the server's newer release |
+| `LANES_AUTOUPDATED` | `lanes-launch` | unset | Set by a window that has just updated itself, for the client it starts again: that one never updates again (one update per window) |
+| `LANES_NO_SELF_UPDATE` | `npm/lanes` wrapper, `install.sh` | unset | Any value: an invite is redeemed by the package you ran, without asking `/enrol/site` for the server's release |
+| `LANES_WRAPPER_REPLY` | `install.sh` | unset | Set by the npm wrapper only: the file into which `install.sh` writes `update-to=<release>` before it exits 5 (Appendix B) |
+| `LANES_PKG_ROOT` | `npm/lanes` wrapper | `~/.local/share/lanes/pkg` | Where npm-staged trees go (any directory name: a staged tree is known by the wrapper's stamp, `lanes_lib.staged_tree`) |
 | `LANES_NPM_ENV_FILE`, `LANES_NPM_TOKEN_KEY` | `npm/lanes/scripts/publish.sh` | `.env.local`, `NPMJS2` | Maintainers only: the publish token's file and key |
 
 Container:
@@ -1593,22 +2400,29 @@ Container:
 | `LANE_ZMX_VERSION` | `lane` | `0.8.1` | zmx binary version |
 | `LANES_TMP_DIR` | `env.sh` | `/home/coder/.tmp` | Temp directory for new shells |
 | `LANES_TMP_OPTOUT` | `env.sh` | unset | Set (any value) to keep `/tmp` |
-| `LANE_ID`, `LANE_WS`, `THROTTLE_TRACE`, `ANTHROPIC_CUSTOM_HEADERS` | Set by the canonical recipe; `lane-signal` reads `LANE_ID`; `lane` strips them | — | Lane identity (section 7) |
+| `LANE_ID`, `LANE_WS`, `THROTTLE_TRACE`, `ANTHROPIC_CUSTOM_HEADERS` | Set by the canonical recipe; `lane-signal` reads `LANE_ID`; `lane-mcp` reads `LANE_ID` (Codex passes it `LANE_ID`, `LANE_WS`, `TMUX` and `TMUX_PANE` through its entry's `env_vars`); `lane` strips them | — | Lane identity (section 7) |
 | `LANE_HARNESS`, `CLAUDE_SESSION_ID`, `CODEX_THREAD_ID` | `lane-signal` | — | Fallbacks for the harness name and session id |
 | `TMUX_TMPDIR` | `lane gc --sockets` | `/tmp` | Where tmux socket files are looked for |
+| `LANES_EDITOR` | `lane-edit`; `lanes edit` | unset | The editor quick edit runs: one program on the container's PATH, by name or absolute path, without arguments. Unset, empty or not found: the first of `micro`, `hx`, `nvim`, `vim`, `vi` (one that is not found is named on stderr). `lanes edit` sets it for `lane-edit` from the device's `lanes attach --editor`, else passes on its own `LANES_EDITOR` (a value with a control character is dropped; the `Ctrl-Alt-e` pane's clean environment has none, so there the device's choice is the one that counts) |
+| `LANES_EDIT_LABEL` | `lane-edit` | the file's name | What the `editing …` line names |
 
 ## Appendix B: exit codes
 
 | Command | Codes |
 | --- | --- |
-| `install.sh`, `npx @vibelord/lanes` | `0` ready · `3` key not yet authorized (no enrolment service, a refused invite, or an unanswered request) · `4` not in the tailnet, server unreachable or too slow · `1` error (also: a malformed invite code, or one for another site) |
-| `install.sh --server` (`host-install.sh`) | `0` · `1` missing prerequisite, not Linux x86_64, or run as root · `2` unknown option |
+| `install.sh`, `npx @vibelord/lanes` | `0` ready · `3` key not yet authorized (no enrolment service, a refused invite, or an unanswered request) · `4` not in the tailnet, server unreachable or too slow · `5` (`install.sh` only, and only for the npm wrapper's `LANES_WRAPPER_REPLY`) nothing installed: the server runs a newer release, which the wrapper then runs, ending with its status · `1` error (also: a malformed invite code, or one for another site) |
+| `install.sh --server` (`host-install.sh`) | `0` · `1` missing prerequisite, not Linux x86_64, or run as root · `2` unknown option · `3` the install was refused before anything changed (another install or update is running — it holds `~/.local/state/lanes/update/.lock` — or another install holds `~/.local/share/lanes/.install.lock`, or `current`, `current.previous` or `~/.local/bin/lanes` is no symlink) |
+| `install.sh --server --update-only` | `0` ok (a `lanes sync` warning included) · `4` partial: installed, a step after the switch failed · `3` refused: a prerequisite, no installed release or another install said no, nothing changed · `1` failed: nothing was installed · `2` usage (also with `--check` or `--no-start`) — the same result is in `update/last.json`, except for a run refused because another install or update was running, which records nothing |
 | `lanes <verb>` | `0` · `1` error (message `lanes: …`) or unknown verb (usage printed) |
 | `lanes sync` | `1` when any workspace's registry had errors (previous lanes kept) |
 | `lanes doctor`, `lanes pressure`, `lanes invariant check`, `lanes sockets` | `1` when something needs attention |
 | `lanes attach <workspace-id>` without a default device, `lanes web --token` without a terminal or while the running `lanes-web.service` reads another token database, `lanes web` when Tailscale Serve cannot be set (operator step printed) | `64` |
 | `lanes token revoke-all` without `--yes` | `2` (nothing changed) |
-| `lanes preview` / `next` / `prev` without `--focused` | `2` |
+| `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 |
 | `lanes invite revoke <id>` | `0` revoked or already revoked · `1` already redeemed (offboard the device) or no such invite |
@@ -1616,8 +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 · `69` no Ghostty (macOS) or neither Ghostty nor Foot (Linux) |
+| `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 |