@vibelord/lanes 1.0.3 → 1.1.0

package/payload/lanes/docs/USERGUIDE.md

@@ -0,0 +1,1612 @@
+# Lanes user guide
+
+Lanes keeps long-running agent terminals on one Linux workspace host and lets every device you use look at the
+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.
+
+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) ·
+[DESIGN](DESIGN.md) (tokens, glyphs, budgets) · [SHARING](SHARING.md) (Throttle sharing and the Studio Host) ·
+[HOST-GUARD](HOST-GUARD.md) (root memory protection).
+
+Labels used below:
+
+- **Opt-in**: installed (the unit file or command exists) but enabled by nothing; you turn it on.
+- **Operator gate**: turning it on is a deliberate operator decision; the consequence is named next to it.
+- **Not yet verified on a device**: covered by unit tests in this tree, not yet checked on real hardware.
+
+## Contents
+
+1. [What Lanes is](#1-what-lanes-is)
+2. [Join a site](#2-join-a-site)
+3. [Desktop use](#3-desktop-use)
+4. [Phone, tablet and laptop browser](#4-phone-tablet-and-laptop-browser)
+5. [Uploads](#5-uploads)
+6. [Workspaces and registry](#6-workspaces-and-registry)
+7. [Agents in lanes](#7-agents-in-lanes)
+8. [Economy and notifications](#8-economy-and-notifications)
+9. [Appearance](#9-appearance)
+10. [Sharing and Studio](#10-sharing-and-studio)
+11. [Operations reference](#11-operations-reference)
+12. [Appendix A: environment variables](#appendix-a-environment-variables)
+13. [Appendix B: exit codes](#appendix-b-exit-codes)
+
+## 1. What Lanes is
+
+```text
+Mac / Linux terminal ──── SSH (alias "lanes") ─────┐
+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
+                                                   │  /proc/<container init pid>/root
+                                                   ▼
+  Workspace containers (home /home/coder, uid 1000)
+    tmux servers that hold the lanes; the agents run here
+    ~/.lz: the `lane` command, the registry projection, hook sidecars
+    Cursor / VS Code terminals reach the same lanes with `lane open <lane-id>`
+```
+
+| Layer | Owns | Lifetime |
+| --- | --- | --- |
+| Host | Views, the registry, status, uploads, 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 |
+
+**A lane** is one long-lived terminal, normally a tmux session on a socket inside a workspace container, with a
+stable id `<workspace>--<slug>`. Closing a window, losing the network or rebuilding a view never ends it. Lanes itself
+ends one only on an explicit close of an unregistered session (`×` / `x`) or `lane kill` inside the container; a
+Throttle Studio **Stop** or a `tmux kill-session` run in the container ends one too.
+
+**A workspace** (also called a board) is one tab of the view: the lanes of one or more repositories in one container.
+The server's catalog orders the tabs.
+
+**Registered and unregistered lanes**
+
+| 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 |
+| 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
+view:
+
+| Glyph | ASCII | Word | Meaning |
+| --- | --- | --- | --- |
+| `●` | `*` | active | Output in the last 20 s |
+| `○` | `o` | quiet | Alive, no recent output |
+| `–` | `-` | absent | The server answered and has no such session right now (for example a finished orchestrator turn) |
+| `!` | `!` | dead | The pane died |
+| `✗` | `x` | missing | The container is down |
+| `?` | `?` | unknown | Never observed yet |
+| `·` | `.` | helper | A tool view, not a lane |
+
+A lane whose tmux server did not answer in time keeps its last glyph, dimmed, with `?` in column 34: not observed
+right now, never "gone". A lane is dead only on a positive observation (`–`, `!`, `✗`).
+
+**The agent state** (sidebar column 2) comes from the agent running in the lane and sorts the sidebar into
+attention sections:
+
+| Section | Glyph | ASCII | Status | Meaning |
+| --- | --- | --- | --- | --- |
+| Needs you | `◆` | `!` | needs_approval | A permission prompt is blocking |
+| 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 |
+| (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 |
+
+**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
+co-located Studio Host (section 10) give read-only and browser access to registered lanes through Throttle SSO.
+
+## 2. Join a site
+
+A site is one Lanes server and the people who use it. Joining takes three things: the site's tailnet, the client, and
+this machine's key authorized on the server. With an invite, one command does the last two. The administrator's side
+(the server install, invites, approvals, updates) follows the client's.
+
+### What you need
+
+| Role | Requirements |
+| --- | --- |
+| Client (Mac or Linux desktop) | macOS or Linux, OpenSSH, a route to the server (Tailscale for the supplied profile; the installer checks it and opens its login, see "Tailscale" below). Node.js 18+ only for the npm path. Ghostty is recommended for a separate window (Linux falls back to Foot); `lanes-launch` works in any terminal |
+| Server (workspace host) | Linux x86_64, Python 3.9+, systemd user services, OpenSSH server, Docker, tmux (tested with 3.4), `curl`, `tar`, `sha256sum`, `infocmp`, `tic`, `install`, `systemctl`. Run as an unprivileged account with Docker access, never as root |
+| Containers | Homes mounted at `/home/coder` with uid 1000; Bash, Python 3 and tmux (compatible with the host's tmux) |
+| Browser access (optional) | Caddy and Tailscale (with HTTPS) on the server |
+
+### Join with an invite
+
+A member of the site sends you an invite: five lines from `lanes invite` ("Invite a user" below) with a one-time
+**invite code**. Then, on your Mac or Linux machine:
+
+1. **Join the tailnet**, on this machine and on your phone: open the Tailscale link in the invite (or ask the member
+   for one). Without Tailscale, install it first (macOS: `brew install --cask tailscale`; Linux:
+   [tailscale.com/download](https://tailscale.com/download)). Logging in can wait: the installer opens `tailscale login`
+   itself ("Tailscale" below).
+2. **Run the installer with the code:**
+
+   ```sh
+   npx @vibelord/lanes --invite LN-xxxx-xxxxxxxxxxxx   # the code's prefix picks the site (LN = beyondwork)
+   ```
+
+3. **Open Lanes**, in your own terminal (the two web commands show a login token there):
+
+   ```sh
+   lanes-launch                # your desktop view in this terminal (lanes-window: in its own window)
+   lanes-launch web phone      # your phone's view: a QR code of its private URL, then a login token
+   lanes-launch web laptop     # this laptop's browser view, the same way
+   ```
+
+| Step | The installer prints |
+| --- | --- |
+| Site | `site beyondwork, inferred from the invite code's prefix LN` (npm only; an explicit `--site` wins) |
+| 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>)` |
+| Server | `server: ok device=<device> version=<version> boards=<n>`, then `Ready.` and the commands of step 3 |
+
+`LANES_INVITE=<code>` works like `--invite`. The code stays secret until it is redeemed: the installer sends it in the
+request body (never on a command line) and never prints or stores it, and a code typed at the prompt below is read
+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.
+
+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
+machine is gone, a member can end it first with `lanes offboard <device> --yes`. `409 (key-taken)` means the server
+holds this key for another device: the installer names a key of its own (`--key ~/.ssh/lanes_ed25519`). Retrying
+with a valid code this way never pauses the machine: only wrong codes count toward the 10-minute limit.
+
+**Operator gate**: the server must run the enrolment service `lanes-enrold` behind its private HTTPS front (installed
+and enabled by `npx @vibelord/lanes --server`). **Not yet verified on a device**: no code has been redeemed from a
+second machine yet.
+
+### No code: ask for access
+
+Run the installer in your own terminal without a code (`npx @vibelord/lanes --site beyondwork`, or `./install.sh`
+from a checkout). When the server does not know this machine's key, it asks `Invite code (Enter = ask the members of
+this site for access instead):`. Press Enter: the installer files an access request — `request: filed as <id> for
+<device> — a member approves it on their phone (https://<server>:8443/enrol/pending) or on the server: lanes enrol
+approve <id>` — and counts down up to 10 minutes (`LANES_ENROL_WAIT`) while a member decides:
+
+| A member decides | Where |
+| --- | --- |
+| On a phone or laptop on the tailnet | `https://<server>:8443/enrol/pending`: **Approve** or **Deny** next to your login and device (open to a tailnet login that owns a member device) |
+| On the server or over `ssh lanes` | `lanes enrol list`, then `lanes enrol approve <id>` (or `lanes enrol deny <id>`) |
+| From a push | With the opt-in push notifier on, each new request arrives as one notification naming you, your device and that command (section 8) |
+
+Approved, the installer says `request: approved — this machine's key is now authorized for <login> (device <device>)`
+and goes on to the server check and `Ready.` If nobody answers in time, it exits 3 and the request stays open for 24
+hours: `npx @vibelord/lanes --resume` (or `./install.sh --resume`) waits again, and so does a plain re-run in a
+terminal. A site whose enrolment service cannot see tailnet logins admits by invite only: there Enter says `request:
+this site admits by invite only — ask a member for an invite, then ./install.sh --invite CODE`.
+
+### No enrolment service: the administrator authorizes the key
+
+A server without `lanes-enrold`, a refused, used or expired code, or an install with no code and no terminal (`--yes`,
+a pipe) ends with this machine's **public** key printed for the administrator (exit 3), as before enrolment existed.
+The administrator authorizes it on the server with `lanes keys add <device> <file.pub>` (or `lanes keys add <device> -`
+and paste the line), which writes it into the lanes-managed block of the server account's `~/.ssh/authorized_keys`
+(the client never edits that file). Then run `npx @vibelord/lanes --check` (or `./install.sh --check`) and
+`lanes-launch`.
+
+### Client from npm
+
+Without an invite code, name the site yourself; the same command updates an installed client. The package
+`@vibelord/lanes` is public — no npm login or token. It carries the committed `lanes/` tree and runs that
+tree's own `install.sh` with the same options and exit codes; its only site facts are the bundled profiles' public host
+keys and tailnet names and addresses.
+
+```sh
+npx @vibelord/lanes --site beyondwork    # install or update the client
+lanes-window                             # open the desktop view
+```
+
+| Wrapper option | Effect |
+| --- | --- |
+| `--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) |
+| `--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).
+
+### Client from a checkout
+
+For working on Lanes, or for a site without a bundled profile:
+
+```sh
+git clone https://github.com/bwllaming/bw-tools.git
+cd bw-tools/lanes
+./install.sh --site /path/to/site.conf        # Beyond Work: ./install.sh --site site/beyondwork/site.conf
+lanes-window
+```
+
+| `install.sh` option | Effect |
+| --- | --- |
+| (none) | Install or update the client on this machine |
+| `--check` | Verify the commands, SSH alias, key, upload helper and server; changes nothing |
+| `--uninstall` | Remove what the client installer added (your SSH key, the known_hosts entry and `~/Lanes Uploads` are kept) |
+| `--server [--check \| --no-start]` | Install or update the Linux server instead (must be the first argument; see below) |
+| `--site FILE` | Server profile; default the remembered one, else `site/site.conf`, else the installed `~/.config/lanes/client-site.conf` |
+| `--device NAME` | This machine's view session name (default `<user>-<hostname>`, lowercased, at most 32 characters) |
+| `--key PATH` | SSH private key (default: the one already configured, else `~/.ssh/id_ed25519`, else a new `~/.ssh/lanes_ed25519`) |
+| `--link` | Symlink the client into this checkout instead of copying it (for working on Lanes) |
+| `--coder-launch` / `--no-coder-launch` | Also provide the command name `coder-launch` (an existing one is kept as `coder-launch-legacy`) / take it away again (the kept one returns) |
+| `--no-desktop` / `--desktop` | No Lanes.app, `.desktop` entry or Hyprland bindings — an earlier install's are removed (Hyprland line with a backup) / back on |
+| `--no-uploads` / `--uploads` | No uploads watch-folder agent or upload helper service — an earlier install's are stopped and removed, `~/Lanes Uploads` and its files stay / back on |
+| `--palette` / `--no-palette` | Give the lanes window the cockpit's own Ghostty palette (section 9) / put your everyday look back |
+| `--invite CODE` | Join with an invite code when the server does not know this machine's key yet ("Join with an invite" above; also `LANES_INVITE`); not remembered |
+| `--resume` | Wait again for this machine's open access request (`~/.config/lanes/enrol-request`; "No code: ask for access" above); not remembered |
+| `--yes`, `-y` | Never prompt (a newly created key then has no passphrase; no invite prompt either) |
+| `-h`, `--help` | Print the option summary |
+
+**Remembered options.** Every install writes its choices — `--device`, `--key`, `--site`, `--coder-launch`,
+`--no-desktop`, `--no-uploads`, `--palette` and their opposites — to `~/.config/lanes/install-options` (plain
+`KEY=VALUE`, mode 0600, read without executing it). A re-run without flags, and so every update, repeats the last
+install; a flag given again overrides the remembered value and is remembered from then on. A profile bundled with
+the package (`--site beyondwork`) is remembered by its name, so an update reads the new package's copy and its pinned
+host key; your own profile file is remembered by its path (when that file is gone, the installed copy is used).
+`--check` only reads the file, `--uninstall` removes it. `--link` and `--yes` are per run. A client installed before
+the file existed (1.0.x) is read once from what it left behind: the palette include, the `coder-launch` link, and
+desktop or uploads as off only when nothing of them is left (no app, launcher entry, Hyprland line or bind file; no
+watch-folder README, agent or service) — a launcher entry you deleted by hand while keeping the key binding leaves the
+desktop on, so that first update takes nothing away. What is installed follows the remembered choice both ways: an
+option turned off takes away what an earlier install added for it — `--no-uploads` stops and removes the watch-folder
+agent and the upload helper service (on macOS the two launchd agents, Lanes Helper.app and the Lanes Upload droplet)
+and the agent hand-off block, keeping `~/Lanes Uploads` and its files; `--no-desktop` removes Lanes.app or the
+launcher entry and the Hyprland line (backup `.pre-lanes-off.<UTC>`) with its bind file; `--no-palette` and
+`--no-coder-launch` likewise. Nothing is touched on a machine that never had them, and `--check` reports the upload
+helper as off.
+
+What a client install changes: `lanes-launch`, `lanes-window` and `lanes-upload` in `~/.local/bin` (copied to
+`~/.local/share/lanes/client` unless `--link`); the SSH alias `lanes` in `~/.ssh/config.d/lanes.conf` plus one
+`Include` line at the top of `~/.ssh/config` (backup kept), with a `lanes-public` fallback when the site provides one —
+when this machine resolves the profile's MagicDNS name (`LANES_SERVER_NAME`), `lanes` names the server by it and a
+second alias `lanes-ip` holds the tailnet address (otherwise `lanes` holds the address, as before; both pin the same
+host key, keyed by the profile's alias);
+the server's host key pinned from the profile's `known_hosts`; a separate Ghostty configuration
+`~/.config/lanes/ghostty.conf` (your everyday Ghostty config is read, never written); `~/.config/lanes/install-options`;
+desktop integration (macOS `~/Applications/Lanes.app`; Linux a "Lanes" launcher entry and, on Omarchy/Hyprland,
+validated key bindings); and the uploads watch folder plus the upload helper service (section 5) — on Linux with a
+key that has a passphrase also one marked block in your login profile (section 5, "The upload helper and a
+passphrase").
+
+### Tailscale
+
+A profile whose server has a Tailscale name (`LANES_SERVER_NAME` ends in `.ts.net`, as the supplied
+`beyondwork` profile does) is reached only through the tailnet, so the installer looks at Tailscale before it tries
+the server (a profile without such a name skips this):
+
+| The installer prints | What happened | What you do |
+| --- | --- | --- |
+| `tailscale: not installed — macOS: brew install --cask tailscale · Linux: https://tailscale.com/download` | No `tailscale` command on `PATH` (on macOS also none inside `Tailscale.app` in `~/Applications` or `/Applications`). The client is installed; exit 4 | Install Tailscale, then run the installer again |
+| ``tailscale: needs login — opening `tailscale login`… (approve in the browser)`` | This machine is logged out of the tailnet; the installer runs `tailscale login` once (its login URL is printed where no browser opens) and waits up to 120 s, with a countdown, until the machine is `Running` and online | Approve the login in the browser |
+| `` tailscale: `tailscale login` failed `` | The login gave up at once — on Linux, an account without operator rights (`Access denied`) | `sudo tailscale up` once (`sudo tailscale set --operator=$USER` lets you log in without sudo), then run the installer again |
+| `tailscale: installed, but not running` / `switched off` / `waits for a tailnet admin` | `tailscaled` does not answer / Tailscale is switched off / the tailnet requires device approval | Start the app (Linux: `sudo systemctl enable --now tailscaled`) / switch it on / ask the admin; the installer keeps counting down meanwhile |
+| `tailscale: not on the tailnet after 120 s (state: …)` | The wait ran out; the client is installed and the server was not tried; exit 4 | Connect Tailscale, then run the installer again |
+| `tailscale: connected as <login> (<address>)` | This machine is in the tailnet | Nothing: the server check follows |
+
+`LANES_TAILSCALE_WAIT=<seconds>` changes the 120-second bound; Ctrl-C ends the wait and the login it opened.
+`--check` only looks: it never opens a login and never waits (a logged-out machine is exit 4 with the advice above).
+
+### Exit status
+
+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.
+
+### Server
+
+On the Linux host, as the workspace account:
+
+```sh
+sudo loginctl enable-linger <account>    # administrator, once: services stay up after logout
+./install.sh --server --check            # prerequisites only; changes nothing
+./install.sh --server                    # or: npx @vibelord/lanes --server
+```
+
+`./install.sh --server` runs `install/host-install.sh`, which takes:
+
+| Option | Effect |
+| --- | --- |
+| `--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 |
+| `-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
+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
+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).
+
+Then configure the workspaces (section 6) and install the container contract:
+
+```sh
+lanes install-container <container>   # once per workspace container
+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`;
+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).
+
+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
+board is written. Add `--write` to apply the steps in order: the board, `install-container`, the
+Claude and Codex hooks, `throttle setup --install-clients` inside the container when Throttle is installed and
+configured there (otherwise it prints the one-time setup to run on a terminal), `lanes sync`,
+`cursor-sync --canonicalize --write` when the repository has a
+`.vscode/terminals.json`, and `lanes doctor`. It ends with a table and a receipt under
+`~/.local/state/lanes/onboard/`. Running it again changes nothing that is already done
+([install guide](INSTALL.md#onboard-a-users-container); what the agents get: section 7).
+
+### Invite a user (administrator)
+
+Any member can invite a new person from the server, or over `ssh lanes`, **in their own terminal** — the code is
+shown once and only to a terminal (piped or redirected, `lanes invite` exits `2` and mints nothing):
+
+```text
+$ lanes invite anna --email anna@example.com --workspaces bw-tools,throttle
+Invite for anna — valid 7 d, one redemption
+ 1. Join the tailnet (laptop and phone):  ask your admin for the Tailscale invite
+ 2. On your Mac/Linux:  npx @vibelord/lanes --invite LN-7q4k-m2xpf9c3d8e2
+ 3. Then:  lanes-launch · lanes-launch web phone · lanes-launch web laptop
+Takes ~5 min.
+```
+
+Send those five lines to the person (`--md` prints them as Markdown to paste). The code `LN-<id>-<secret>` is
+case-insensitive and redeems **once**, within 7 days (`--expires 3d`, `--expires 12h`; 1 h to 30 d); the server keeps
+only its hash in `invites/<id>.json`. `--email` records who the invite is for — on a server whose enrolment service
+cannot see tailnet logins (invite-only) that address becomes the new member's owner, so give it — and, when
+`~/.config/lanes/resend.key` exists, mails the five lines — put a `from=Name <addr>` line on a domain verified in
+Resend under the key, or the kit goes from Resend's test sender, which delivers only to the Resend account's own
+address (anyone else: Resend answers 403, and the note names the missing line). Step 1's link is
+`--tailscale-link URL` (an invite from the Tailscale admin console), else one minted with
+`~/.config/lanes/tailscale-api.key`, else the person asks you for one.
+Both key files are Lanes' own and optional (RUNBOOK "Invite, approve, offboard"). Step 2 redeems the code at the
+enrolment service through the client's `--invite` (W8 B3, the same release). **Operator gate**: the server needs
+`lanes-enrold` installed (`npx @vibelord/lanes --server`). **Not yet verified on a device**: no code has been
+redeemed from a second machine yet.
+
+| Command | Does |
+| --- | --- |
+| `lanes invite list` | Every invite: `live`, `redeemed` (by which device), `revoked`, `expired` |
+| `lanes invite revoke <id>` | The code is refused from now on (a redeemed invite is not revoked: offboard the device) |
+| `lanes enrol list [--all]` | Requests filed by machines without a code; `--all` adds decided and expired ones |
+| `lanes enrol approve <id> [--as <device>]` / `deny <id>` | Decide one, as `/enrol/pending` does on the phone; `--as` names your own device ([install guide](INSTALL.md#approve-a-request)) |
+| `lanes enrol mode [request\|invite\|auto]` | Pin whether the server takes access requests, across restarts — `request` once the Serve header check passed, `invite` for invites only ([install guide](INSTALL.md#approve-a-request)) |
+| `lanes offboard <device> --yes` | In your own terminal: revoke its key, forget the device, sign its browsers and phones out (the login tokens of the device, its windows and its `lanes-launch web` views), end its view session; it names its windows (`<device>-2`) to offboard by name ([install guide](INSTALL.md#offboard-a-machine)) |
+
+### Update
+
+| 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 (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:
+
+- `systemctl --user restart lanes-statusd.service` (the status observer runs the old code until restarted).
+- 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).
+
+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.
+
+### Versions
+
+- `lanes/VERSION` is the release version; the npm package version equals it (`npx @vibelord/lanes --version`).
+- `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?".
+- The client installer prints `lanes client <version>` and copies `VERSION` into `~/.local/share/lanes/client/`.
+- `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.
+- `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
+  reach this machine` — the view and its login token still work. The client updates itself first (public npm), the
+  server when its operator runs `npx @vibelord/lanes@latest --server`, so this mixed window is expected.
+
+### Uninstall
+
+- 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
+  container lane data until you have decided which sessions to retain. See
+  [INSTALL §6](INSTALL.md#6-updates-optional-operations-and-removal).
+
+## 3. Desktop use
+
+### Open a view
+
+| Command | What it opens |
+| --- | --- |
+| `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) |
+| 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 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 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>`.
+
+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
+60 s; `Enter` reconnects now) and reattaches. After two quick transport failures it uses the next fallback the SSH
+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.
+
+### Devices and views
+
+- A **device** is the name of one view session on the server. The default is `<user>-<hostname>`, saved in
+  `~/.config/lanes/device`; `lanes-window 2` and `w2` derive suffixed devices from it.
+- 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`.
+- 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.
+
+### Panes and viewports
+
+A desktop workspace tab is the sidebar (36 columns) beside one to three viewports. `Enter` in the sidebar shows the
+cursor lane in the first viewport; in a wide view `2` and `3` show it in the second or third. The sidebar marks
+what the other viewports show with `²` and `³`. In a single-viewport view `2`/`3` do nothing; `3` in a two-viewport
+view says `this view has no such viewport (open a wide view: lanes-window w2)`.
+
+### Keybindings
+
+`lanes/zellij/config.kdl` clears Zellij's defaults and puts every Zellij action behind **Ctrl-Alt**, so ordinary keys
+reach the lane. `Ctrl-g` is never bound (Claude Code opens its editor on it) and plain `Ctrl-b` reaches the lane's own
+tmux.
+
+Keys in the `shared` block work in every mode, locked included:
+
+| Key | Action |
+| --- | --- |
+| `Ctrl-Alt-←` / `Ctrl-Alt-→` | Previous / next workspace tab |
+| `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-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.
+
+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-m` | Markdown preview of the focused lane (every mode except locked; see below) |
+| `Ctrl-Alt-p` | Pane mode |
+| `Ctrl-Alt-t` | Tab mode |
+| `Ctrl-Alt-n` | Resize mode |
+| `Ctrl-Alt-h` | Move mode |
+| `Ctrl-Alt-o` | Session mode (`d` detaches) |
+| `Ctrl-Alt-b` | tmux-style mode (Zellij's, not the lane's tmux) |
+| `Ctrl-Alt-f` | Scroll mode |
+
+Inside a mode (`Esc` returns to normal; `Enter` too, except while typing a search):
+
+| Mode | Keys |
+| --- | --- |
+| Pane | Arrows or `h j k l` move focus · `n` new pane · `d` / `r` / `s` new pane down / right / stacked · `x` close the focused pane · `f` fullscreen · `F` fullscreen without UI · `e` float/embed · `w` show floating panes · `z` frames · `i` pin · `c` rename · `p` / `;` switch / last pane |
+| Tab | `←` `↑` `h` `k` previous · `→` `↓` `l` `j` next · `1`–`9` go to tab · `Tab` toggle last tab · `n` new · `r` rename · `x` close · `s` sync input · `b` `[` `]` break the pane out |
+| Resize | Arrows or `h j k l` grow · `H J K L` shrink · `+` `=` grow · `-` shrink |
+| Move | Arrows or `h j k l` move the pane · `n` / `Tab` next · `p` previous |
+| Session | `d` detach · `w` session manager · `a` about · `c` configuration · `l` layout manager · `p` plugin manager · `s` share |
+| tmux-style | Arrows or `h j k l` focus · `"` / `%` split · `c` new tab · `n` / `p` tabs · `,` rename tab · `[` scroll · `z` fullscreen · `o` next pane · `space` next layout · `x` close pane · `d` detach · `Ctrl-b` sends `Ctrl-b` to the pane |
+| Scroll | `↑` `↓` `j` `k` line · `←` `→` `h` `l` `PageUp` `PageDown` page · `u` / `d` half page · `g` `G` `Home` `End` top / bottom · `s` search · `e` open the scrollback in `vi` · `c` copy the last command's output · `y` copy · `[` `]` previous / next prompt |
+| Search | `n` / `p` next / previous · `c` case · `w` wrap · `o` whole word |
+
+In every mode other than normal and locked, `Alt`-arrows or `Alt-h/j/k/l` move the focus (or the tab), `Alt-n` adds
+a pane, `Alt-f` toggles floating panes, `Ctrl-p/t/n/h/o/s/b` switch modes, and `Ctrl-q` quits the view session.
+
+Closing a pane, a tab or the session affects this view only: lanes keep running. `lanes rebuild <device>` restores
+the layout, and `lanes-ensure.timer` recreates a known device session that is missing within a minute. Tab titles
+belong to the catalog: `lanes sync` renames tabs to their catalog titles, so rename a workspace in the catalog
+(section 6), not with tab mode's `r`.
+
+To detach: close the window, or `Ctrl-Alt-o` then `d`.
+
+### The sidebar
+
+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)**
+   with its `+ New shell` row. A list longer than the pane ends in `⋮ N more`; moving onto that row or clicking it
+   scrolls instead of opening.
+3. **Upload strip** (panes of 14 rows or more): ` ↑ uploads · click, then drop  (U)` (section 5).
+4. **Strip row** (panes of 18 rows or more): the fleet economy line when the opt-in poller runs (section 8), otherwise
+   the other workspaces that need you, e.g. ` ◆1 Worlds · ◇2 Code`; blank when there is nothing to say.
+5. A rule, then the **footer**: one line, by priority.
+
+A workspace whose lanes live on another SSH host (`sshWorkspaces` with `layout: "lanes"`) is attach-only: it has no
+Unregistered section, no upload strip and no `+`, and its footer has no `x close`.
+
+**Row anatomy** (every row is 36 cells; column 36 is never written):
+
+| Column | Shows |
+| --- | --- |
+| 1 | `▌` the cursor |
+| 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 `…` |
+| 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) |
+| 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 ·
+`⚠` `!` 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):
+
+| Key | Action |
+| --- | --- |
+| `↑` `↓` `j` `k` | Move the cursor |
+| `PageUp` / `PageDown` | Move the cursor ten rows |
+| `Enter` `→` `Space` | Open the cursor lane (in this pane's viewport) |
+| `J` / `K` | Open the next / previous lane relative to the one shown |
+| `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 |
+| `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`) |
+| `R` | Rename the cursor lane |
+| `P` | Promote (register) the cursor session in the repository's `terminals.json` |
+| `U` | Arm the upload strip |
+| `r` | Reload and repaint |
+| `?` | 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.
+
+### Find, rename, add, 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
+  footer counts matches. `Enter` opens the match under the cursor (the top one unless you moved), `Backspace` edits,
+  `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).
+- **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.
+- **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
+  `view-…` viewer) has those viewers ended first; any other grouped session makes the close refuse and say why.
+
+### Markdown preview
+
+`Ctrl-Alt-m` opens a floating **Preview** pane over the focused lane. It reads the lane's last 300 lines, keeps the
+`.md` paths that exist in its container (relative ones resolved against the lane's working directory), and shows
+one at once; several give a numbered menu, newest first (`Enter` takes the newest, `q` closes). It renders with
+`glow` in the view's dark or light theme, else `less -R`; quitting the pager closes the pane. The server installer
+adds a pinned glow unless the view server's PATH already has one; `lanes doctor` names the renderer
+(`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`.
+
+### 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
+  lane's tmux copy mode); Zellij's scroll mode has little to show for it.
+- For a single lane with your terminal's native scrollback, use `lanes-launch lane <lane-id>`.
+- Selecting with the mouse copies to the system clipboard (`copy_on_select`); `Ctrl-Alt-c` copies explicitly.
+  Ghostty's own config for the window allows clipboard writes and asks before clipboard reads.
+- On Omarchy the window class `org.omarchy.lanes` makes `Super+C` / `Super+V` copy and paste.
+
+### 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,
+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.
+
+## 4. Phone, tablet and laptop browser
+
+From an installed client, in your own terminal (the login token is shown only there), one command per browser:
+
+```sh
+lanes-launch web phone      # your phone: the view <your device>-phone, phone layout
+lanes-launch web laptop     # this laptop's browser: the view <your device>-web, desktop layout
+lanes-launch web ipad       # any other name is that view (a new one gets the desktop layout)
+```
+
+Each prints the private URL with a QR code of it, then a fresh login token. Open the URL on the device (scan the code
+with a phone's camera), sign in with the token, and on a phone add it to the Home Screen. The server does the rest in
+the same step: it prepares the view, enables the web services and adds the Tailscale Serve mapping when it is
+missing. The device must be on the tailnet ("Join with an invite", step 1).
+
+### How it is served
+
+```text
+browser ── https://<host>.<tailnet>.ts.net:8443/<device> ── Tailscale Serve
+        ── lanes-mobile.service (Caddy, 127.0.0.1:8083: the Lanes frontend in web/)
+        ── lanes-web.service (Zellij web server, 127.0.0.1:8082: login, assets, WebSockets)
+```
+
+Everything listens on loopback; Tailscale Serve is the only way in. **There is no public fallback by design**: a
+browser needs Tailscale. Zellij's own token and cookie checks are the login; Lanes adds no second login system.
+A token grants terminal access as the server account.
+
+### One-time server setup (administrator)
+
+1. Install Caddy (2.5 or later: the `/enrol/*` route uses `trusted_proxies`) and Tailscale on the server and enable
+   Tailscale HTTPS for the tailnet. Reserve ports 8082, 8083, 8443 and 8184 (the enrolment service) for Lanes.
+2. Allow the workspace account to manage Tailscale Serve: `sudo sh sudo/one-time-root.sh --user <account>` (it changes
+   SSH daemon settings only with `--ssh-keepalive`).
+3. Nothing more: the first `lanes-launch web …` from a client (or `lanes web <device>` on the server) enables the
+   loopback web services and adds the Tailscale Serve mapping `https:8443 -> http://127.0.0.1:8083` when it is missing
+   ("Laptop and tablet" below has the rules). When Tailscale refuses the account it exits 64 and prints the step of
+   item 2. The same front carries the enrolment service's `/enrol/*` routes (section 2).
+
+### Phone (Safari, Home Screen)
+
+From an installed client, in your own terminal (the token is shown only there):
+
+```sh
+lanes-launch web phone      # this machine's phone view: <your device>-phone, phone layout
+```
+
+The server prepares the view `<your device>-phone` (for example `anna-mbp-phone`), enables the web services, makes
+Tailscale Serve forward private HTTPS 8443 to them (added when missing), prints the private URL with a QR code of it
+and then a fresh token. On the phone: connect Tailscale, scan the code with the camera (or open the printed
+`https://<server>.<tailnet>.ts.net:8443/<your device>-phone` in Safari), paste only the token value (Zellij prints
+`NAME: TOKEN`), then **Share → Add to Home Screen**.
+
+`lanes-launch web phone|laptop|<device> [--desktop|--mobile] [--no-qr]` runs `lanes web <view> <layout> --token
+--default-device <your device>` on the server over `ssh -t lanes`:
+
+| Target | View on the server | Layout |
+| --- | --- | --- |
+| `phone` | `<your device>-phone` | phone (`--mobile`) |
+| `laptop` | `<your device>-web` | desktop (`--desktop`) |
+| any other name | that device, as given | a known device keeps its layout; a new one is desktop |
+
+`--desktop` or `--mobile` overrides the layout. `phone` and `laptop` are named after this machine's device (from
+`~/.config/lanes/device`), so the server records this machine as the view's base, as `lanes attach` does for `mac-2`;
+a name over 32 characters is refused here (name the view yourself: `lanes-launch web <name>`). Any other option is
+refused before a connection (exit 64). The exit status is the server's: 64 when ssh got no terminal for the token,
+when a running view has the other layout (choose another name), or when the server could not make the Tailscale
+Serve mapping (it prints the operator's step). Before the token, the server draws a QR code of the
+URL (only the URL: the token does not exist yet) so the phone's camera opens it; `--no-qr` leaves it out. A device
+literally named `phone` or `laptop` (the `phone` view `enable-phone.sh`
+makes) is reached with `lanes web phone` on the server.
+
+`enable-phone.sh [--host SSH_ALIAS | --local] [--desktop|--mobile] [device]` is the older one-shot for the device
+`phone`: `--host` connects with the key the client installer chose (no password fallback, no agent forwarding);
+`--local` runs on the server, where it is a thin wrapper over `lanes web <device> <layout> --token`; `--mobile` (the
+default, device `phone`) or `--desktop` (device `browser`) picks the layout. On macOS `--host lanes` is assumed when
+neither is given. An SSH-only phone client can instead run `lanes attach phone --mobile`.
+
+### Laptop and tablet
+
+Give each browser its own device. From an installed client, in your own terminal:
+
+```sh
+lanes-launch web laptop             # this laptop's browser view: <your device>-web, desktop layout
+lanes-launch web ipad               # any other name is that device (a new one gets the desktop layout)
+lanes-launch web ipad --mobile      # the phone layout instead
+```
+
+On the server the same command is `lanes web`:
+
+```sh
+lanes web ipad --desktop            # desktop sidebar layout (a new device's default); prints the private URL
+lanes web ipad --desktop --token    # the same, then a fresh login token in this terminal
+lanes web ipad --print-only         # the exact prepare call, URL and Serve step; changes nothing
+```
+
+From a client: `lanes-launch web laptop` (the view `<your device>-web`), `lanes-launch web <device> --desktop`, or
+`sh install/enable-phone.sh --host lanes --desktop <device>` (without a name, `--desktop` uses the device `browser`).
+
+`lanes web <device> [--desktop|--mobile] [--viewports N] [--token | --print-only] [--default-device NAME] [--no-qr]`
+prepares the view (before it prints anything), enables the loopback services through `install/enable-web.sh`, makes
+Tailscale Serve forward `https:8443` to `http://127.0.0.1:8083`, and prints `key: value` lines (`device`, `layout`,
+`state`, `prepare`, `services`, `url`, then `note` / `next` / `serve` when they apply). Without `--desktop`/`--mobile`
+a known device keeps its recorded layout; only a new device defaults to desktop. A running view of the other layout
+is refused, never rebuilt: choose another device name. `--token` needs your own terminal (exit 64 otherwise); it then
+draws a QR code of the URL — `qrencode -t ANSIUTF8` when the server has it, else a built-in encoder for URLs up to
+106 bytes — and none for a loopback URL or with `--no-qr`; the token is never in it. The Serve step leaves a present
+mapping alone (`serve: present …`), adds a missing one (`serve: added …`), and never replaces a mapping of 8443 to
+anything else; when it cannot make the mapping it exits 64 and prints the operator's step (`sudo tailscale set
+--operator=<account>`, or the command that frees the port). `--default-device` (what `lanes-launch web` passes)
+records the view's base machine; `--print-only` records nothing. Without a Tailscale name the URL is
+`http://127.0.0.1:8083/<device>`, which opens only on the host itself, and Serve is not touched.
+
+On a captive-portal network (hotel, train, aircraft): complete the portal sign-in first, then connect Tailscale, then
+open the URL and paste the token.
+
+### Tokens
+
+| Task | Command |
+| --- | --- |
+| Create (shown once, in your terminal) | `lanes-launch web phone\|laptop\|<device>` on a client, `lanes web <device> --token` on the server, or `enable-phone.sh` |
+| List, with the device each was created for | `lanes token list` |
+| Sign one device out | `lanes token revoke <device>` (`--name token_N` for a token Lanes did not record) |
+| Sign a whole machine out when it leaves (its phone and browser views too) | `lanes offboard <device> --yes` |
+| Sign every browser and phone out | `lanes token revoke-all --yes` |
+
+Lanes never prints or logs a token itself. Existing tokens stay valid when you create a new one. Zellij 0.45.1
+names tokens `token_1`, `token_2`, … and cannot name them after a device, so Lanes records which device each
+`lanes web --token` was for (`~/.local/state/lanes/web-tokens.json`). Revoking any token but the newest would stop
+Zellij creating new ones; `lanes token revoke` refuses that case and names `revoke-all`
+([RUNBOOK](RUNBOOK.md#login-tokens)).
+
+The tokens live in `~/.local/share/zellij/tokens.db` on the server: `lanes-web.service` pins
+`XDG_DATA_HOME=%h/.local/share` and the token commands use the same root, whatever your shell exports. If the
+running server reads another database (one started before that pin, under a user manager with its own
+`XDG_DATA_HOME`), `lanes doctor` shows a `✗`, and `lanes web --token` (exit 64) and `lanes token` refuse: run
+`lanes web <device>`, then `systemctl --user restart lanes-web.service`, then mint the token again.
+
+### The three shell modes
+
+The frontend chooses once per page load, by capability:
+
+| Mode | Chosen when | What you get |
+| --- | --- | --- |
+| 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 |
+
+### 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 keyboard opens only when you tap **Type here** or another input. Swipes, live updates and reconnects leave it
+  closed.
+- 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.
+- On a lane's own tab a row of quick keys sits above the dock: `⏎ y n Esc ^C ↑ ↓`. A tap sends the key without opening
+  the keyboard; `n` and `^C` need a 400 ms hold (a short tap says "Hold to send").
+- The filter bar on the picker sends its text as UTF-8, so non-ASCII filters match.
+- `+` and `×` on picker rows add and close unregistered sessions, as on the desktop; tapping `+` then a workspace
+  needs no typing.
+
+### 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.
+- Not yet verified on a device: the quick keys on a real iPhone, 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
+  change needs `lanes rebuild <device>`; `lanes doctor` lists such devices), and an iPad Safari pass of the tablet mode
+  (top bar, left panel, whole-tab view). The mode choice itself is unit-tested.
+
+## 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.
+
+| Way | How |
+| --- | --- |
+| Upload strip | Click the strip above the footer (or press `U` in the sidebar, `Ctrl-Alt-u` from anywhere in the tab); it turns into ` ↓ DROP FILES NOW · anywhere · Esc`. Drop the files anywhere on the window. The file goes to that tab's workspace and its path is typed into the lane. While sending: ` ↑ sending 2 files · 12.4 MiB`; the result stays 8 s as ` ✓ name` or ` ✗ reason` |
+| Watch folder | `~/Lanes Uploads/` → the workspace your view shows; `~/Lanes Uploads/<workspace>/` → that workspace. Sent files move to `.sent/<date>/`; a failed upload stays for a retry |
+| 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 |
+| 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.
+
+**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.
+
+**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
+temp folders), asks on macOS once per new folder (**Deny**, **Allow once**, **Always allow**), and never reads from
+`~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.kube`, `~/.config`, `~/.docker`, keychains, `.git` or `/etc`.
+`lanes-upload --allow <dir>` adds a folder; `lanes-upload --allowed` lists them. The allowlist applies to drops served
+by the helper; a `lanes-upload <files>` you type sends what you name.
+
+The helper runs as one background service per machine (launchd `ai.beyondwork.lanes-helper` on macOS,
+`lanes-helper.service` on Linux), so it survives closing windows; while no service serves, an open window runs its
+own. On macOS the service runs as `~/Applications/Lanes Helper.app`: choose **Allow** when it asks for Downloads,
+Desktop or Documents, or enable it under System Settings → Privacy & Security → Files and Folders → Lanes Helper.
+Full Disk Access is not needed; the allowlist and macOS's folder permission are separate checks.
+
+Transfers have an idle timeout (two minutes without incoming data), not a total-duration limit. Logs:
+`~/.local/state/lanes-client/helper-service.log` (macOS) or `journalctl --user -u lanes-helper` (Linux).
+
+**The upload helper and a passphrase** (Linux). A systemd user service cannot ask for a passphrase, so with a
+protected key the helper logs in through your SSH agent — the one the systemd user manager holds, looked up again
+before every login. The service starts at boot (`default.target`), often before your desktop session hands its agent
+to the user manager (GNOME or KDE keyring, uwsm); it uses that agent from its next login attempt, at most a minute
+later, without a restart. The installer hands the agent of the terminal it runs in to
+the user manager (`systemctl --user import-environment SSH_AUTH_SOCK`) before it restarts the helper, and appends one
+block between `# >>> lanes agent hand-off >>>` and `# <<< lanes agent hand-off <<<` to the file your login shell reads
+(zsh `~/.zprofile`; bash the first of `~/.bash_profile`, `~/.bash_login`, `~/.profile` that exists; other shells
+`~/.profile`). At each local login the block hands that login's agent over and restarts the helper — only when the
+user manager does not already have that agent, and never from an SSH login (`SSH_CONNECTION`), whose forwarded agent
+disappears with it. A re-run adds nothing; `--uninstall` and `--no-uploads` remove the block (backup kept). Installed
+over SSH, nothing is handed over until your next local login. fish reads no POSIX profile: the installer names the
+line to add instead.
+A profile the installer cannot write (a read-only dotfiles checkout, a root-owned or immutable file, a full disk) is
+left exactly as it was — a write that stops part-way is put back from its backup — and the installer names the line
+to add, hands this terminal's agent over and finishes; `--uninstall` likewise leaves the block in such a file and says
+which lines to delete.
+The agent must hold the key (`AddKeysToAgent yes` in the `lanes` alias adds it on the first interactive login).
+
+| Strip says | Meaning | Do |
+| --- | --- | --- |
+| `✗ 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 |
+| `✗ upload timed out` | No progress for 120 s | Check the helper log |
+
+## 6. Workspaces and registry
+
+### The chain
+
+```text
+catalog.json ──► workspaces.<workspace>.json ──► <repo>/.vscode/terminals.json (in the container)
+ (tabs, order)    (container, repositories)       (the terminals = the lanes)
+                                     + registered-sessions.json (adopted sessions)
+            lanes sync ──► ~/.local/state/lanes/registry.json, resolve/, and ~/.lz/registry.json in each container
+```
+
+The site directory is `$LANES_WORKSPACES`, else `~/.config/lanes/workspaces/` when it holds a `catalog.json`, else
+`workspaces/` in the checkout. Start from `lanes/workspaces.example/` ([reference](../workspaces.example/README.md)).
+For a board with one repository, `lanes workspaces add <id> --container <name> --repo /home/coder/<repo> --write`
+writes both files below. Without `--write` it prints the diff only. An id already in the catalog is checked, never
+rewritten. A repository that another board already declares is refused. After any edit: `lanes sync && lanes doctor`.
+
+**`catalog.json`**: `version` (1), `workspaces`: `{id, title, manifest}` in tab order. The `id` is also the upload
+and watch-folder name; `title` is the tab. Changing a title renames the existing tab. Optional `sshWorkspaces` adds
+fixed terminals on another host ([README](../README.md#register-a-workspace-once)).
+
+**`workspaces.<workspace>.json`** (the manifest): `repositories[]`, each with `id`, `host` (the container),
+`registry` (the repository's `.vscode/terminals.json` path inside the container), and optionally `prefix` (prepended
+to lane titles), `displayNames` (display overrides keyed by terminal name), `bindingOverrides` (a tmux binding for a
+terminal that has none), and `cursor` (a second file to project the workspace into). `remoteShell.cwd` sets the
+working directory; `monitor` adds the Throttle monitor tab; `discoveryRoots` extends the directories that associate
+unregistered sessions with the workspace. A repository belongs to one board: `lanes cursor-sync` rewrites each
+`registry` (and `cursor` file) with the lane ids of the board that names it, so a file two boards name flips on every
+run.
+
+**`.vscode/terminals.json`** (in the repository, inside the container):
+
+```json
+{
+  "terminals": [
+    { "name": "Shell", "command": "exec /home/coder/.lz/bin/lane open product--shell", "focus": true }
+  ],
+  "lanes": {
+    "version": 1,
+    "terminals": {
+      "Shell": {
+        "holder": "tmux",
+        "tmux": { "socketName": "project", "sessionName": "shell" },
+        "create": "TMUX= tmux -L project new -ADs shell bash -l"
+      }
+    }
+  }
+}
+```
+
+| 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 |
+| `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.
+
+**`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.
+
+### Lane ids
+
+| Lane | Id |
+| --- | --- |
+| Repository lane | `<workspace>--<slug of prefix + declared terminal name>` |
+| Unregistered or adopted session | `<workspace>--x-<slug>-<digest>` (an adopted session keeps it) |
+| zmx lane | `<workspace>--z-<name>` |
+
+A lane id never changes on rename. `lanes ls [--json] [workspace]` lists registry lanes with their state;
+`lanes ls --unregistered [--json]` lists unregistered sessions; `lanes resolve <lane-id>` prints one lane's exact
+target as JSON.
+
+### Sync
+
+- `lanes-sync.timer` runs `lanes sync` every 2 minutes (30 s after boot). It is read-only toward repositories: it
+  rebuilds the registry, the resolve files and each container's `~/.lz/registry.json`, then reconciles the tabs of
+  every known live device (`lanes upgrade-session`). A sync with nothing new rewrites nothing.
+- **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.
+- 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.
+
+### Cursor and VS Code
+
+Cursor's Terminals Manager opens what `.vscode/terminals.json` lists. `lanes cursor-sync` normalizes how each terminal
+reaches its lane, so Cursor and Lanes attach to the same tmux session:
+
+| Command | Effect |
+| --- | --- |
+| `lanes cursor-sync [workspace…]` | Dry run: the summary and a short diff per file |
+| `lanes cursor-sync [workspace…] --diff` | Dry run with the full diff |
+| `lanes cursor-sync [workspace…] --write` | Apply: each `command` becomes `exec /home/coder/.lz/bin/lane open <lane-id>`, the original kept as the `create` recipe; backups under `~/.local/state/lanes/cursor-sync-backups/` |
+| `… --canonicalize` | Also replace a recipe that cannot create its lane (none, attach-only, the retired path, a missing script) with the canonical recipe (section 7) |
+| `… --identity` | Also add the identity `-e` flags to a working plain `tmux -L S new -ADs N [-c D] CMD` recipe, keeping CMD |
+| `lanes cursor-commit [workspace…]` | Dry run of committing the normalized file on top of each repository's remote branch tip |
+| `lanes cursor-commit [workspace…] --push` | Commit with git plumbing (no working tree or index touched) and push; a protected branch gets a `lanes/terminals-lane-open` branch and a pull request |
+
+`cursor-commit` reads `commit-targets.json` in the site directory. Neither command runs automatically.
+**Operator gate:** `--canonicalize --write` or `--identity --write` on a live workspace rewrites operator-declared
+recipes and produces the first `lanes/<ws>/<id>` trace; decide lane-level against per-session proxy fairness first
+(DEF-1560, [RUNBOOK](RUNBOOK.md#cursor--vs-code-terminals--the-same-lanes)). The rewrite changes the file only: a
+running lane gains its identity when it is next created.
+
+### Rename rules
+
+| 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 |
+| Registered session | Its record's `name` in `registered-sessions.json` |
+| Unregistered session | `~/.local/state/lanes/user-sessions/<id>.json` |
+
+Names must be non-empty and free of control characters. The id, resolve file and `lane open <id>` never change.
+
+### Register, promote, unregister
+
+- **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.
+- **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`.
+- If a repository later declares the same binding as a registered session, the repository declaration wins.
+
+### `lanes doctor`
+
+`lanes doctor` is the full health check (every external call bounded; exit 1 on any `✗`). It reports:
+
+- `✓`/`✗`: Zellij installed, registry present, clean and up to date (no `terminals.json` newer than the last sync),
+  each container running, the statusd heartbeat, all registry lanes observed and present (stale lanes counted as
+  "shown with their last known state"), the process table, no host-side tmux servers, coexistence mode, Zellij
+  reachable, phone picker panes current, and the host not under critical memory pressure.
+- Information: lanes per create-recipe class (`idempotent`, `attach-only`, `null`, `external`, `retired-path`), how many
+  create with their identity, where the `lane` contract is installed, zmx-held lanes, the preview renderer, the live
+  view sessions, and the pressure summary.
+- Warnings (`⚠`, never a `✗`): lanes that `lane open` cannot recreate (fix: `lanes cursor-sync --canonicalize`),
+  lanes bound to a numeric session name, more than 4 lanes on one container's tmux socket `default`, orphan tmux
+  socket files in a container (report only; inside the container `~/.lz/bin/lane gc --sockets` removes the ones tmux
+  is refused on), and records left in the retired `legacy-sessions/` directory.
+- Browser and phone views: `lanes-web` / `lanes-mobile` active (`✓`), not enabled (`⚠`: no browser view yet, or
+  running without being enabled), enabled but not running (`✗`); the login-token database the running `lanes-web`
+  reads, from its own environment: the one `lanes token` uses (`✓`), another one (`✗`, see
+  [Tokens](#tokens)), or not compared (`⚠`); the Tailscale Serve mapping `https:8443 -> http://127.0.0.1:8083`
+  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).
+
+## 7. Agents in lanes
+
+### How the agent state is derived
+
+`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.
+2. A **Claude Code session file** `~/.claude/sessions/<pid>.json` naming the pane, for a live pid (recycled pids are
+   rejected).
+3. The **Codex pane title**: `[ ! ] Action Required` is needs approval, a braille spinner is working, a task title is
+   idle.
+4. The **window bell**: an idle title plus a bell is done.
+
+A Codex title left on a bare shell with no child process is `shell` (the harness ended).
+
+### 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
+every diff and command and changes nothing:
+
+```sh
+lanes onboard anna --container ws-anna --workspace anna-tools --repo /home/coder/tools           # the plan
+lanes onboard anna --container ws-anna --workspace anna-tools --repo /home/coder/tools --write   # apply it
+```
+
+| 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`) |
+| 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
+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
+same Throttle pool over the tailnet once the operator shares it (`throttle remote share --tailnet`, unpublished). When
+the server's `~/.config/lanes/site.conf` names `LANES_THROTTLE_REMOTE_URL`, `lanes onboard` prints and records that
+step for the user: `throttle remote join <pairing code>` on the laptop
+([install guide](INSTALL.md#laptop-agents-on-the-throttle-pool-operator-gated)).
+
+### Hooks (opt-in, per container, dry run first)
+
+Hooks make the state event-driven. Nothing installs one unasked: `lanes onboard --write` (above) installs both, or
+install them one by one.
+
+```sh
+lanes install-container <name>                                  # puts lane-signal in ~/.lz/bin
+lanes hooks install --agent claude --container <name>            # prints the diff to ~/.claude/settings.json
+lanes hooks install --agent claude --container <name> --write    # applies it (backup settings.json.lanes-bak-<time>)
+lanes hooks install --agent codex --container <name> --write     # ~/.codex/hooks.json (+ notify in config.toml)
+```
+
+`lanes hooks install --agent claude|codex (--container <name> | --home <dir>) [--dry-run | --write]`: a dry run
+unless `--write`; your own hooks and keys stay, and an earlier lane-signal install is replaced, not duplicated. An
+install that is already current is left where it is, even when another tool (Throttle's `setup --install-clients`)
+has put its own group before or after it or re-sorted the file's keys, so running it again writes nothing. For
+Codex it also adds a top-level `notify` to `~/.codex/config.toml` only when none exists. Codex asks you to review and
+trust new hooks; Lanes never writes that trust. Expect hooks to reach agent sessions started after the install
+(inferred from how both harnesses read their configuration, not measured). Undo:
+restore the `.lanes-bak-*` file, or delete the groups whose command contains `lane-signal`.
+
+| Harness | Event | Status |
+| --- | --- | --- |
+| Claude Code | `UserPromptSubmit`, `PostToolUse` | working |
+| Claude Code | `Stop`, `Notification` (idle prompt) | needs_input |
+| Claude Code | `PermissionRequest`, `Notification` (permission prompt) | needs_approval |
+| Claude Code | `StopFailure` | errored |
+| Claude Code | `SessionEnd` | shell |
+| Codex | `SessionStart` | idle |
+| Codex | `UserPromptSubmit`, `PostToolUse` | working |
+| Codex | `PermissionRequest` | needs_approval |
+| Codex | `Stop`, `notify` (turn complete) | done |
+| 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".
+
+### The in-container `lane` command
+
+Installed at `/home/coder/.lz/bin/lane` by `lanes install-container`. Viewers, editors and scripts use only these
+verbs, so the holder stays swappable.
+
+| Verb | Effect |
+| --- | --- |
+| `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 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-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 identity and the canonical recipe
+
+A lane's identity is its environment: `LANE_ID` (`<ws>--<slug>`), `LANE_WS` (`<ws>`), and the Throttle trace
+`lanes/<ws>/<id>` as `THROTTLE_TRACE` and as `ANTHROPIC_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>'`. A tmux
+lane gets it only from the `-e` flags of its create recipe; `lane open` deliberately exports none (the client that
+starts a shared tmux server would hand its environment to every later session there). The canonical recipe is:
+
+```sh
+tmux -L <socket> new -ADs <session> -c <folder> -e LANE_ID=<id> -e LANE_WS=<ws> \
+  -e ANTHROPIC_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>' -e THROTTLE_TRACE=lanes/<ws>/<id> bash -l
+```
+
+`-A` attaches when the session exists, so the identity lands only on a real create. A running lane gains it when it is
+next created. A trace makes the whole lane one proxy fairness bucket (operator gate above, DEF-1560).
+
+### zmx
+
+zmx is an optional, separately pinned holder (`lane new`, `holders/zmx.sh`). Installing it migrates nothing: the
+registry's lanes stay on tmux. zmx lanes appear in their own `zmx lanes (N)` section; a hook sidecar does not reach a
+zmx lane's agent state yet (DEF-1573). Gate results: [ZMX-RING0.md](ZMX-RING0.md).
+
+## 8. Economy and notifications
+
+### Economy projection (opt-in, operator gate)
+
+`lanes-economy.service` polls the Throttle daemon's control port (`GET /status` and `/sessions`, default
+`http://127.0.0.1:19181`) every 10 s, folds today's `proxy.log`, and writes `~/.local/state/lanes/economy.json`. It is
+installed with the other units and enabled by nothing: it reads the production daemon, so turning it on is your call.
+It runs on the host, so check what it can reach first:
+
+```sh
+LANES_THROTTLE_CONTROL=none LANES_THROTTLE_CONTAINER=<container> lanes economy --once --dry-run   # writes nothing
+systemctl --user edit lanes-economy.service       # put the same settings in a drop-in ([Service] Environment=)
+systemctl --user enable --now lanes-economy.service
+```
+
+`lanes economy --once [--dry-run] [--status-file F --sessions-file F]` runs one poll; stderr names each source it
+could not read. Settings: `LANES_THROTTLE_CONTROL` (base URL, or `none` for no request), `LANES_THROTTLE_TOKEN_FILE`
+(a bearer in a file), `LANES_THROTTLE_CONTAINER` (read the log through that container's home volume),
+`LANES_THROTTLE_LOG_DIR` (where `proxy.log` lives). A daemon bound to loopback inside its container is not reachable
+from the host: use `LANES_THROTTLE_CONTROL=none` there (the log fold still works). Details:
+[RUNBOOK](RUNBOOK.md#economy-projection-opt-in).
+
+**The fleet strip** (the strip row, panes of 18 rows or more), parts in priority order, whole parts dropped to fit:
+
+| Part | Meaning |
+| --- | --- |
+| `$8.5k/16k 53%` | Overflow spend today against the daily cap; amber at or over the alert level |
+| `429 +4` | New upstream 429s since the last poll (only when above 0) |
+| `F2 S1` | This workspace's lanes by model tier: `F` fable, `O` opus, `S` sonnet, `H` haiku, `G` gpt |
+| `spill 76%` | The pool's spill fraction; amber unless the pressure phase is closed |
+| `free 3/19` | Effectively free accounts of all accounts |
+| `reset 2h` | The soonest 5 h reset |
+
+A leading `?` and an all-dim line mean the figures are frozen: `/status` failed, or the poller stopped (no rewrite for
+over 3 minutes). Without the poller, or with `LANES_THROTTLE_CONTROL=none`, the strip row shows fleet attention
+instead.
+
+**Per-lane cells** (column 34): `⚠` starving (the pane is producing output but the proxy saw no request from the lane
+for over 10 minutes, or a 429 is in its recent requests) · `↓` downgraded in the last 5 minutes · `$` more than half of
+its recent requests paid. A dim `⚠` or `↓` is a frozen last-known figure, not a live alarm. A lane the poller has not
+joined has a blank cell.
+
+### Desktop notifications (OSC 9)
+
+Covered in section 3: one notification per lane entering Needs you, from the sidebar itself, on desktop layouts.
+
+### 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.
+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
+request even across restarts. It sends lane names, task titles and requesters' names and device names to the server
+you configure, so enabling it is your decision. Not yet run against a real ntfy server or phone.
+
+`~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` at install time renders another path), `key=value` lines:
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `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 |
+
+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.
+
+```sh
+$EDITOR ~/.config/lanes/notify.conf
+python3 ~/.local/share/lanes/current/libexec/notify.py --test     # one test push; exit 1 = not sent
+systemctl --user enable --now lanes-notify.service
+```
+
+## 9. Appearance
+
+One token table, `libexec/tokens.py`, defines every colour and glyph. It generates marked blocks in
+`zellij/config.kdl` (the `lanes-dark` / `lanes-light` themes and the web client palette), `web/mobile.css`,
+`web/mobile.js`, `libexec/tokens.sh` (the viewer's status screens), `docs/DESIGN.md` and the optional Ghostty palette
+files. `python3 libexec/tokens.py --check` fails on drift; `--write` regenerates all blocks; `--kdl`, `--css`, `--sh`,
+`--md`, `--js`, `--ghostty-dark` and `--ghostty-light` print one block.
+
+| 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` |
+| 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.
+
+**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
+newer when your everyday config sets no colours explicitly, else the dark palette) and includes it last; the choice
+is remembered, and `--no-palette` removes it. Not yet verified on a real Ghostty: the window background should then
+be `#101318`.
+
+**Fonts**: no Nerd Font is needed. Any monospace font with Latin-1, Box Drawing, Geometric Shapes, Dingbats, Arrows and
+`⋮ ⏎ ⚠ …` renders the cockpit; `--ascii` is the remedy for any other font.
+
+The legend, token table, mockups and budgets: [DESIGN.md](DESIGN.md).
+
+## 10. Sharing and Studio
+
+**Shared lanes (read-only).** Throttle's **Shared lanes** console shows selected workspaces to people in your
+organization through Throttle SSO. An organization administrator chooses who may share; a workspace owner exposes a
+workspace and picks people or teams. Viewers see the workspace's registered lanes (names, observed activity, and for
+tmux lanes the latest 2,000 lines of a pane, capped at 256 KiB) as escaped plain text, refreshed every five seconds;
+there is no input, upload, start/stop, resize or terminal connection. Each workspace is private until enabled. It
+needs a platform and Studio Host built with Lanes sharing support. See [SHARING.md](SHARING.md).
+
+**Co-located Studio Host (opt-in).** One Throttle Studio Host can serve every workspace of a Lanes server from the
+workspace account, supervised as `lanes-studio-host.service` with the retry timer `lanes-studio-host-enrol.timer`.
+The server installer renders the units but never enables them or downloads the binary.
+
+```sh
+lanes studio-host install --from ./throttle-rc --sha256 <digest>     # select a sha256-verified binary
+sh install/enable-studio-host.sh --server https://throttle.example.com --dry-run
+sh install/enable-studio-host.sh --server https://throttle.example.com
+lanes studio-host status
+```
+
+| Command | Effect |
+| --- | --- |
+| `lanes studio-host status [--json] [--check]` | Binary digest, config mode, enrolment and units; exit 0 only when it runs enrolled |
+| `lanes studio-host install [--from PATH [--sha256 HEX]]` | Select the Host binary (the `holders.lock` opt-in pin, or a local build); restarts nothing |
+| `lanes studio-host re-key [--yes] [--dry-run]` | After the owner revoked this machine: stop the Host, remove the machine key and its dead enrolment, publish a new public key; nothing without `--yes` |
+| `sh install/enable-studio-host.sh [options]` | Write the Host config, publish the public key, adopt a deploy receipt or enrol with a registration key, enable the units (exit 0 running or waiting, 2 usage, 3 refused, 1 failure); `--help` lists the options |
+
+Throttle Studio is a second client of the same lanes. It reads the registry, the repositories' terminal lists and
+the live tmux servers and writes none of the registry files; on a workspace's tmux server it adds only its own
+browser viewer sessions (`view-…`, shown as `·` marks after a lane's name) and the lanes it starts
+(`st_<workspace>_<slug>`, listed under Unregistered until declared). Details:
+[SHARING.md](SHARING.md#co-located-studio-host-one-host-per-lanes-server) and
+[RUNBOOK](RUNBOOK.md#throttle-studio-as-a-client).
+
+## 11. Operations reference
+
+### systemd user units
+
+All units run in `lanes.slice` and are rendered by the server installer from `lanes/systemd/`.
+
+| Unit | Schedule | Enabled by | Does |
+| --- | --- | --- | --- |
+| `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-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-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 |
+| `lanes-studio-host-enrol.timer` / `.service` | Every 5 min | `enable-studio-host.sh` (opt-in) | Adopt a new receipt or key, then start the Host |
+| `lanes-economy.service` | Every 10 s | Nobody (opt-in, operator gate) | Economy projection `economy.json` |
+| `lanes-notify.service` | Every 3 s | Nobody (opt-in, operator gate) | ntfy push on needs-you transitions and new enrolment requests |
+| `lanes-tmpreap.timer` / `.service` | Hourly | Nobody (opt-in) | `lanes tmp reap`; a dry run until `~/.local/state/lanes/flags/tmpreap.armed` exists |
+| `lanes-guard.timer` / `.service` | Every 60 s | Nobody (opt-in) | `lanes guard --once`: raise `oom_score_adj` of builds in the containers |
+
+Clients also get `lanes-helper.service` and `lanes-upload.path`/`.service` (Linux) or the launchd agents
+`ai.beyondwork.lanes-helper` and `ai.beyondwork.lanes-upload` (macOS).
+
+### `lanes` commands (server)
+
+| Group | Command | Does |
+| --- | --- | --- |
+| Registry | `lanes sync` | Refresh the registry and reconcile workspaces on every known device |
+| Registry | `lanes ls [--json] [--unregistered] [workspace]` | Lanes with live status (`?` after a state = last known) |
+| 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 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 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 reattach` | Make every view re-attach its lane |
+| Views | `lanes device list` / `lanes device forget <name>` | The devices `ensure` keeps / stop keeping one |
+| Views | `lanes next\|prev --focused [--device D]` | What `Ctrl-Alt-↓` / `Ctrl-Alt-↑` run |
+| Views | `lanes preview --focused [--device D]` | What `Ctrl-Alt-m` runs |
+| 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 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 |
+| 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 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 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 |
+| Housekeeping | `lanes gc` | What the daily timer runs |
+| Housekeeping | `lanes tmp scan\|plan\|apply\|reap\|caches [container…] [--approve] [--home]` | What fills the containers' RAM-backed `/tmp`, and removing the dead part ([RUNBOOK](RUNBOOK.md#free-the-ram-lanes-tmp)) |
+| Housekeeping | `lanes guard [--dry-run] [container…]` | One OOM-guard pass by hand |
+| Throttle | `lanes economy --once [--dry-run] [--status-file F --sessions-file F]` | One economy poll (section 8) |
+| Throttle | `lanes studio-host status\|install\|re-key …` | Section 10 |
+
+The client helpers call three more verbs (`rebuilt`, `upload-requests`, `upload-result`); you do not run them.
+
+### Client commands
+
+| 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-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 --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) |
+| `npx @vibelord/lanes --invite <code>` / `--site NAME` / `--resume` | Join a site with an invite, install or update without one, wait again for an access request (section 2) |
+| `./install.sh …` | Install, check, update, uninstall (section 2) |
+
+### State files
+
+Server (`~/.local/state/lanes/`, `$LANES_STATE`):
+
+| Path | Holds |
+| --- | --- |
+| `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 |
+| `containers.json`, `containers/` | Container init pids and home volumes |
+| `devices/<device>.json` | Each known device: layout, viewports, base device, look |
+| `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` |
+| `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 |
+| `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 |
+| `flags/` | `coexist`, `readonly`, `tmpreap.armed`, `sockets-lost` |
+| `cursor-sync-backups/` | Backups taken by `cursor-sync --write` |
+| `invariant.json` | `lanes invariant save` |
+| `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 |
+| `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 |
+| `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) |
+
+Other server paths: `~/.config/lanes/` (`workspaces/`, `site.conf`, `notify.conf`, 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
+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).
+
+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/`.
+
+### NEVER
+
+From the [RUNBOOK](RUNBOOK.md#never):
+
+- Restart or stop a container, docker, or `user@<uid>.service`: every lane dies with its container, every view with
+  the user manager. No symptom in the runbook is fixed by a restart.
+- Touch `/tmp/tmux-1000` inside a container, by hand, by a cleaner, or by a "free space" one-liner: those are the
+  lanes' sockets.
+- `systemd-oomd` on docker scopes · `memory.oom.group=1` · `swapoff` under pressure · a `memory.max` below current
+  usage · tightening any limit before usage has dropped.
+- Live test suites, `docker exec`, `du` or a server rollout on the busy host.
+- Recreate a lane because the sidebar shows `?`, or because a window showed `[terminated]`.
+
+### Troubleshooting
+
+| You see | Likely cause | Do | Details |
+| --- | --- | --- | --- |
+| A lane's glyph dimmed with `?` | Its tmux server did not answer in time; last known state shown | Wait; `lanes invariant check`, `lanes doctor` | [RUNBOOK](RUNBOOK.md#a-dead-lane-or-a-blind-harness) |
+| Footer `⚠ host under memory pressure · status 3 m old` (or `host busy`) | statusd's health is busy/critical, or older than 30 s | `lanes pressure`; nothing is lost | [RUNBOOK](RUNBOOK.md#what-you-see-and-what-it-means) |
+| Footer `⚠ lane sockets deleted` | Someone emptied a container's `/tmp` | `lanes sockets repair` | [RUNBOOK](RUNBOOK.md#tmux-server--is-not-running-on-every-lane-at-once-deleted-sockets) |
+| Viewport: THIS VIEWER DISCONNECTED | The viewer's tmux client dropped; it retries | Wait; if it keeps saying `is not provisioned`, pick another lane | [RUNBOOK](RUNBOOK.md#what-you-see-and-what-it-means) |
+| A view session you do not recognise in `lanes doctor`'s `view sessions:` (an old device, a mistyped device name) | A device file keeps it alive | `lanes device list`, `lanes device forget <name>` | [RUNBOOK](RUNBOOK.md#server-as-the-workspace-account) |
+| A tablet shows the phone lane picker | The device was created with the phone layout | `lanes web <new-device> --desktop` | [RUNBOOK](RUNBOOK.md#web--phone) |
+| Phone keyboard does not open, or opens unexpectedly | The keyboard opens only from **Type here** or an input | Tap **Type here**; quick keys never open it | [RUNBOOK](RUNBOOK.md#web--phone) |
+| Phone shows no counts | Phone view laid out before the picker change | `lanes rebuild <device>` | [RUNBOOK](RUNBOOK.md#web--phone) |
+| `lanes web` printed a `127.0.0.1` URL | The host has no Tailscale name | Connect Tailscale on the host; there is no public fallback | [INSTALL](INSTALL.md#laptop-and-tablet-browser) |
+| `lanes web` exits 64 and prints `sudo tailscale set --operator=…` | The workspace account may not manage Tailscale Serve (or HTTPS is off for the tailnet) | Run the printed step as the server admin, then `lanes web` again | [RUNBOOK](RUNBOOK.md#tailscale-serve) |
+| `lanes doctor`: `✗ lanes-web.service reads login tokens from …`, or a fresh token is refused at sign-in | The running web server reads another token database than `lanes token` (started before the `XDG_DATA_HOME` pin) | `lanes web <device>`, `systemctl --user restart lanes-web.service`, then `lanes web <device> --token` | [RUNBOOK](RUNBOOK.md#login-tokens) |
+| `lanes web --token` says the next token name exists | Zellij 0.45.1 names tokens `token_<count + 1>`; an older token was revoked | `lanes token revoke-all --yes` (every browser signs in again) | [RUNBOOK](RUNBOOK.md#login-tokens) |
+| Upload `✗ not allowed on this machine` | Folder not on the helper's allowlist | `lanes-upload --allow <folder>` | [RUNBOOK](RUNBOOK.md#uploads-the-cursor-uploads-folder-without-cursor) |
+| Upload `✗ no upload helper` | Helper service not serving | `./install.sh --check` on the client | [RUNBOOK](RUNBOOK.md#what-you-see-and-what-it-means) |
+| Installer: `tailscale: not installed`, `needs login` or `not on the tailnet after 120 s`, exit 4 | This machine is not in the tailnet the profile's server lives in | Install or connect Tailscale (the installer opens `tailscale login` itself), then run the installer again | [Section 2](#tailscale) |
+| Installer: `invite: not redeemed — the server answered …` or `enrolment: no answer from …`, exit 3 | The code was refused (used, expired, revoked) or the server runs no enrolment service yet | Ask a member for a new invite, or send the printed public key to the administrator | [Section 2](#no-enrolment-service-the-administrator-authorizes-the-key) |
+| Installer: `request: no answer within 10:00 — it stays open`, exit 3 | No member has approved the access request yet | `npx @vibelord/lanes --resume` (or `./install.sh --resume`) waits again | [Section 2](#no-code-ask-for-access) |
+| A phone or browser of an offboarded machine still signs in | Its token is not attributed to the machine: minted before 1.1.0, outside `lanes web --token`, or `lanes offboard` warned or ended incomplete at step 3 | Read offboard's step 3 line; `lanes token list`, then `lanes token revoke --name token_N` (or `lanes token revoke-all --yes`) | [install guide](INSTALL.md#offboard-a-machine) |
+| Installer: `invite: not redeemed — the server answered 409 (device-taken)` (or `key-taken`), exit 3 | The server already has a device of that name (two machines with one hostname, or an earlier enrolment), or holds this key for another device | The installer names the re-run: the same command with `--device NAME` (the invite is still valid) or with a key of its own; if the old machine is gone, a member runs `lanes offboard <device> --yes` | [Section 2](#join-with-an-invite) |
+| `lanes-launch web`: "the server runs lanes 1.0.x, older than this client" | This client is newer than the server (a client updates itself first) | The view and its token work; there is no QR code and the view's upload box does not reach this machine until the server runs `npx @vibelord/lanes@latest --server` | [Versions](#versions) |
+| `/enrol/pending`: "Refused: the browser did not say where the form came from (no Sec-Fetch-Site)" | The Approve/Deny POST came without the browser's `Sec-Fetch-Site` header: curl or a script, or a browser that does not send it | Approve from a current browser, or on the server: `lanes enrol approve <id>` | [install guide](INSTALL.md#approve-a-request) |
+| Nobody can file an access request after the server restarted (`requests-disabled`), although it worked before | Request mode is unpinned and the first request through Serve after the restart carried no tailnet identity (a tagged device) | On the server: `lanes enrol mode request` (after the header check) | [install guide](INSTALL.md#approve-a-request) |
+| Installer: "an older server?" / `lane open`: "registry is newer than this lane" / "site file … newer schema" | Client, server or container contract at different versions | Update the server (`./install.sh --server`), re-run `lanes install-container <name>`, update the client checkout | Section 2 |
+| Client window holds with a countdown | Connection lost or refused | Leave it open; `Enter` retries now | [RUNBOOK](RUNBOOK.md#what-you-see-and-what-it-means) |
+| Wrong colours in Codex's input box | Codex sampled another client's background at start | Use the same light/dark choice on every client | [RUNBOOK](RUNBOOK.md#tuis-and-the-terminals-colours-codexs-dark-box-the-stars) |
+
+## Appendix A: environment variables
+
+Server and views:
+
+| Variable | Read by | Default | Effect |
+| --- | --- | --- | --- |
+| `LANES_STATE` | `bin/lanes`, `libexec/*`, `holders/*`, `host-install.sh`, `services.py` | `~/.local/state/lanes` | State directory; rendered into every unit |
+| `LANES_SHARE` | `libexec/lanes_lib.py`, `host-install.sh`, `services.py`, `enable-phone.sh` | `~/.local/share/lanes` | Pinned binaries and installed files |
+| `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 |
+| `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 |
+| `LANES_THROTTLE_CONTAINER` | `libexec/economy_poll.py` | unset | Read the daemon log through this container's home volume |
+| `LANES_THROTTLE_LOG_DIR` | `libexec/economy_poll.py` | `~/.local/share/throttle` | Where `proxy.log` is read; wins over the container |
+| `LANES_NOTIFY_CONF` | `libexec/notify.py` | `~/.config/lanes/notify.conf` | Push notifier config path |
+| `LANES_HOST_GUARD_CONF` | `sudo/host-guard.sh` | `/etc/lanes-host-guard.conf` | Root guard config |
+| `LANES_PROC_ROOT`, `LANES_CGROUP_ROOT` | `bin/lanes`, `libexec/guard.py`, `libexec/view.sh` (the first); `libexec/guard.py` (the second) | `/proc`, `/sys/fs/cgroup` | Test injection only |
+| `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_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_REPO`, `LANES_ZELLIJ` and `LANES_WS` are set by Lanes itself for its units and panes.
+
+Client:
+
+| Variable | Read by | Default | Effect |
+| --- | --- | --- | --- |
+| `LANES_HOST` | `lanes-launch`, `lanes-upload` | `lanes` | SSH alias of the server |
+| `LANES_FALLBACK_HOST` | `lanes-launch` | `lanes-ip lanes-public` | Fallback SSH aliases, tried in order (each only when the SSH config defines it) |
+| `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME` | `install.sh`, client scripts | `~/.config`, `~/.local/share`, `~/.local/state` | Where client files go |
+| `LANES_TAILSCALE_WAIT` | `install.sh` | `120` | Seconds an install waits for this machine to join the tailnet (a `.ts.net` profile) |
+| `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_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:
+
+| Variable | Read by | Default | Effect |
+| --- | --- | --- | --- |
+| `LANE_ROOT` | `lane`, `lane-run` | `/home/coder/.lz` | Root of the in-container contract |
+| `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_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 |
+
+## 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 |
+| `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 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 |
+| `lanes offboard <device> --yes` | `0` · `2` without `--yes` or not on a terminal (the plan printed, nothing changed) · `1` stopped at the key or device step, a key line left outside the block, the web login tokens could not be revoked, or the view could not be ended |
+| `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 |
+| `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-upload` | `64` usage · `66` no such file or empty clipboard · otherwise the transfer's status |
+| `lane status` | `1` when the lane is not running |
+| Live test suites (`tests/*.py`) | `75` host busy, not started |