@vibelord/lanes 1.0.4 → 1.1.0

package/payload/lanes/docs/USERGUIDE.md

@@ -20,7 +20,7 @@ Labels used below:
 ## Contents
 
 1. [What Lanes is](#1-what-lanes-is)
-2. [Install and update](#2-install-and-update)
+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)
@@ -107,24 +107,105 @@ fleet economy strip (overflow spend against the daily cap, new 429s, model tiers
 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. Install and update
+## 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). 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 |
+| 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
 
-The package `@vibelord/lanes` is restricted to the `@vibelord` npm organization. It carries the committed `lanes/`
-tree and runs that tree's own `install.sh` with the same options and exit codes.
+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
-npm login --scope=@vibelord              # once per machine (or a read-only token in ~/.npmrc)
 npx @vibelord/lanes --site beyondwork    # install or update the client
 lanes-window                             # open the desktop view
 ```
@@ -134,6 +215,7 @@ lanes-window                             # open the desktop view
 | `--site NAME` | A bundled profile (`beyondwork`); a value containing `/` or ending in `.conf` is your own file |
 | `--stage-only` | Copy the bundled tree to `~/.local/share/lanes/pkg/<version>/` and print the path; run nothing |
 | `--version` | Print the package version |
+| `--invite CODE` | Hand the code to the installer; without `--site`, the code's prefix picks the bundled profile ("Join with an invite" above) |
 | `--wrapper-help` | Wrapper help only |
 
 Every other option goes to `install.sh`. The wrapper stages the tree under `~/.local/share/lanes/pkg/<version>/`
@@ -142,6 +224,8 @@ version a server unit still runs from. See [`npm/lanes/README.md`](../../npm/lan
 
 ### 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
@@ -155,32 +239,73 @@ lanes-window
 | `--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 `site/site.conf`, else the remembered `~/.config/lanes/client-site.conf` |
-| `--device NAME` | This machine's view session name (default `<user>-<hostname>`, lowercased, at most 32 characters; kept on re-install) |
+| `--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` | Also provide the command name `coder-launch` (an existing one is kept as `coder-launch-legacy`) |
-| `--no-desktop` | Skip Lanes.app, the `.desktop` entry and Hyprland bindings |
-| `--no-uploads` | Skip the uploads watch folder and the upload helper service |
-| `--palette` | Give the lanes window the cockpit's own Ghostty palette (section 9); a re-run without it puts your everyday look back |
-| `--yes`, `-y` | Never prompt (a newly created key then has no passphrase) |
+| `--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;
+`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); 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).
+`~/.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
 
-Exit status (same for `npx @vibelord/lanes`): `0` ready · `3` installed, but this machine's key is not yet
-authorized on the server · `4` installed, but the server is unreachable (Tailscale?) or did not answer in time ·
-`1` error.
+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 |
 
-**Authorize the machine.** On exit 3 the installer prints this machine's **public** key. The administrator appends
-that line to the server account's `~/.ssh/authorized_keys` (the client never edits that file). Then run
-`./install.sh --check` (or `npx @vibelord/lanes --check`) and `lanes-window`.
+`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
 
@@ -205,7 +330,9 @@ glow 3.0.0 unless a glow is already on the view server's PATH) into `~/.local/sh
 `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` and `lanes-gc.timer`. Web access, the Studio Host, the economy poller, push notifications,
+`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:
@@ -223,12 +350,59 @@ it creates `~/.tmp` and appends one marker-guarded line (`# lanes-env`) to the l
 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) | `npx @vibelord/lanes@latest` with the same options | `npx @vibelord/lanes --check` |
-| Client (checkout) | `git pull`, then `./install.sh` | `./install.sh --check` |
+| 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 |
 
@@ -253,6 +427,17 @@ before a server update. To roll back, restore those files; do not rebuild device
   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
 
@@ -281,11 +466,16 @@ before a server update. To roll back, restore those files; do not rebuild device
 | `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 `lanes-public` fallback
-when the site defines one. Exits 64–78 are server refusals and retry after 60 s. Its log is
+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.
 
@@ -298,7 +488,9 @@ away.
   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, running or not);
+- 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
@@ -490,6 +682,19 @@ 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
@@ -504,47 +709,88 @@ A token grants terminal access as the server account.
 
 ### One-time server setup (administrator)
 
-1. Install Caddy and Tailscale on the server and enable Tailscale HTTPS for the tailnet. Reserve ports 8082, 8083 and
-   8443 for Lanes.
+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
-sh install/enable-phone.sh --host lanes     # or on the server: sh install/enable-phone.sh --local
+lanes-launch web phone      # this machine's phone view: <your device>-phone, phone layout
 ```
 
-It enables the web services, prepares the `phone` view (phone layout), starts private Tailscale Serve and prints a
-fresh token. On the phone: connect Tailscale, open `https://<server>.<tailnet>.ts.net:8443/phone` in Safari, paste
-only the token value (the last line is `NAME: TOKEN`), then **Share → Add to Home Screen**.
+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`:
 
-`enable-phone.sh [--host SSH_ALIAS | --local] [--desktop|--mobile] [device]`: `--host` connects with the key the
-client installer chose (no password fallback, no agent forwarding); `--local` runs on the server; `--mobile` (the
+| 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. On the server:
+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 and URL; changes nothing
+lanes web ipad --print-only         # the exact prepare call, URL and Serve step; changes nothing
 ```
 
-From a client: `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]` prepares the view, enables the
-loopback services through `install/enable-web.sh`, and prints `key: value` lines (`device`, `layout`, `state`,
-`prepare`, `services`, `url`, and `note` / `next` 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). Without a
-Tailscale name the URL is `http://127.0.0.1:8083/<device>`, which opens only on the host itself.
+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.
@@ -553,10 +799,23 @@ open the URL and paste the token.
 
 | Task | Command |
 | --- | --- |
-| Create (shown once, in your terminal) | `lanes web <device> --token`, or `enable-phone.sh` |
-| Revoke a named token | `~/.local/share/lanes/bin/zellij-0.45.1 web --revoke-token NAME` |
-
-Lanes never prints or logs a token itself. Existing tokens stay valid when you create a new one.
+| 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
 
@@ -636,6 +895,25 @@ Full Disk Access is not needed; the allowlist and macOS's folder permission are
 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 |
@@ -657,7 +935,9 @@ catalog.json ──► workspaces.<workspace>.json ──► <repo>/.vscode/term
 
 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)).
-After any edit: `lanes sync && lanes doctor`.
+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
@@ -668,7 +948,9 @@ fixed terminals on another host ([README](../README.md#register-a-workspace-once
 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.
+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):
 
@@ -786,6 +1068,13 @@ Names must be non-empty and free of control characters. The id, resolve file and
   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
 
@@ -804,9 +1093,39 @@ anything, picks the first signal that applies:
 
 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 for you.
+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
@@ -816,7 +1135,9 @@ lanes hooks install --agent codex --container <name> --write     # ~/.codex/hook
 ```
 
 `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. For
+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:
@@ -930,8 +1251,11 @@ Covered in section 3: one notification per lane entering Needs you, from the sid
 ### Push notifications (opt-in, operator gate)
 
 `lanes-notify.service` sends one push to an [ntfy](https://ntfy.sh) topic when a lane's agent enters needs you
-(`Needs you`, `Needs approval`, `Error`). It reads only `status.json` and the registry, every 3 s. A push says
-`<lane name>: <agent task> — <status>` and `lanes-launch lane <id>`. It sends lane names and task titles to the server
+(`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:
@@ -940,7 +1264,7 @@ you configure, so enabling it is your decision. Not yet run against a real ntfy
 | --- | --- | --- |
 | `url` | required | The ntfy server, `https://…` |
 | `topic` | required | `[A-Za-z0-9_-]{1,64}`; on a public server the topic name is the only secret |
-| `token_file` | unset | A file holding an ntfy access token (an unreadable file disables sending) |
+| `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 |
 
@@ -981,8 +1305,9 @@ 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; a plain
-re-run removes it. Not yet verified on a real Ghostty: the window background should then be `#101318`.
+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.
@@ -1036,12 +1361,13 @@ All units run in `lanes.slice` and are rendered by the server installer from `la
 | `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-web.service` | Always on | `enable-web.sh` (via `enable-phone.sh` / `lanes web`) | Zellij web server on `127.0.0.1:8082` |
+| `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 |
+| `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 |
 
@@ -1059,9 +1385,11 @@ Clients also get `lanes-helper.service` and `lanes-upload.path`/`.service` (Linu
 | 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 (section 4) |
+| 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) |
@@ -1073,11 +1401,19 @@ Clients also get `lanes-helper.service` and `lanes-upload.path`/`.service` (Linu
 | 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>` | Install the `lane` contract (section 2) |
+| 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 |
@@ -1096,9 +1432,12 @@ The client helpers call three more verbs (`rebuilt`, `upload-requests`, `upload-
 | --- | --- |
 | `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 (section 4) |
+| `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
@@ -1118,13 +1457,22 @@ Server (`~/.local/state/lanes/`, `$LANES_STATE`):
 | `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 |
-
-Other server paths: `~/.config/lanes/` (`workspaces/`, `site.conf`, `notify.conf`), `~/.local/share/lanes/` (pinned
+| `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`).
 
@@ -1132,9 +1480,9 @@ In each container (`/home/coder/.lz/`): `bin/` (`lane`, `lane-run`, `lane-signal
 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`, `ghostty.conf`, `client-site.conf`, `client-known-hosts`, `site.cache`,
-`upload-allow`, `uploads-dir`), `~/.local/state/lanes-client/` (`launch-<target>.log`, `helper.alive`,
-`helper-service.log`), `~/.local/share/lanes/client/`.
+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
 
@@ -1162,8 +1510,19 @@ From the [RUNBOOK](RUNBOOK.md#never):
 | 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) |
@@ -1190,9 +1549,15 @@ Server and views:
 | `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.
+`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:
@@ -1200,8 +1565,12 @@ Client:
 | Variable | Read by | Default | Effect |
 | --- | --- | --- | --- |
 | `LANES_HOST` | `lanes-launch`, `lanes-upload` | `lanes` | SSH alias of the server |
-| `LANES_FALLBACK_HOST` | `lanes-launch` | `lanes-public` | Fallback SSH alias |
+| `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 |
 
@@ -1221,16 +1590,20 @@ Container:
 
 | Command | Codes |
 | --- | --- |
-| `install.sh`, `npx @vibelord/lanes` | `0` ready · `3` key not yet authorized · `4` server unreachable or too slow · `1` error |
+| `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 | `64` |
+| `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 · `1` missing Tailscale or Serve permission |
+| `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) |