@vibelord/lanes 1.0.3 → 1.1.0

package/payload/lanes/docs/INSTALL.md

@@ -3,6 +3,7 @@
 The same `lanes/` directory installs either a desktop client or the workspace server. A deployment needs
 one server and one client installation per desktop. Safari uses the optional web services on the server.
 Configuration identifies your server and workspaces; credentials and generated runtime state stay outside Git.
+For daily use after installation, see the [user guide](USERGUIDE.md).
 
 ## 1. Prepare a workspace host
 
@@ -13,6 +14,12 @@ Install missing packages using your distribution's package manager. The installe
 Run the server as an unprivileged workspace account with Docker access. Container homes must be mounted at
 `/home/coder` with UID 1000; the host account must be able to read the mounted files and reach those users'
 Unix sockets through `/proc`. This is the current container contract, including on a host provisioned without Coder.
+The host account must also have UID 1000, the container's. `lanes install-container`, `lanes hooks install` and
+`lanes onboard` write into the container homes as the host account, so a file they create belongs to the host
+account's UID. With any other UID the agent inside cannot read the private ones (`.claude/settings.json` is 0600)
+and cannot write into a directory the host account created. On such a host `lanes onboard` stops at its first check
+and writes nothing (exit 1), `lanes hooks install --write` into a container refuses with the reason, and
+`lanes doctor` warns about each container. Run them from a host account with UID 1000.
 Containers need Bash, Python 3 and tmux. Use compatible tmux versions on the host and containers (tested with
 tmux 3.4): the host client attaches directly to the container server. Zmx is installed as an optional holder,
 not a migration of existing lanes.
@@ -39,20 +46,31 @@ only if no configuration exists. Host protection, temporary-file deletion and we
 
 ## 2. Configure workspaces and editor sync
 
-Start from the included configuration, then edit container names and repository paths:
+Add one board per repository. `lanes workspaces add` writes the site catalog and the board's manifest for you:
+`catalog.json` gains `{id, title, manifest}` and a new `workspaces.<id>.json` names the container and the
+repository's `.vscode/terminals.json`. It prints the diff first and writes only with `--write`:
 
 ```sh
-mkdir -p ~/.config/lanes/workspaces
-cp -R workspaces.example/. ~/.config/lanes/workspaces/
-$EDITOR ~/.config/lanes/workspaces/catalog.json
-$EDITOR ~/.config/lanes/workspaces/workspaces.product.json
-$EDITOR ~/.config/lanes/workspaces/workspaces.research.json
+lanes workspaces add product --title Product --container my-workspace-container --repo /home/coder/product
+lanes workspaces add product --title Product --container my-workspace-container --repo /home/coder/product --write
 lanes install-container my-workspace-container
 lanes sync
 lanes doctor
 ```
 
-Remove unused example boards from the catalog. A complete terminal registry is provided in
+The catalog goes where the server reads it: `$LANES_WORKSPACES`, else `~/.config/lanes/workspaces/` (created on a
+fresh host), or a single-site checkout's own `workspaces/catalog.json`. The first write keeps a
+`catalog.json.bak-<UTC>Z` copy beside it. `--repo` is the repository folder as
+the container sees it, under `/home/coder`. The title defaults to the id, and every tab title must be unique.
+A repository belongs to one board: a container and folder that another board already declares is refused before
+anything is written, because `lanes cursor-sync` would rewrite that repository's `.vscode/terminals.json` for both
+boards.
+Running the command again for the same id changes nothing. If the catalog already describes that id differently,
+the command prints the differences, writes nothing and exits 1. Boards with several repositories, prefixes,
+`remoteShell`, a monitor tab or SSH workspaces are still edited by hand: start from
+[`workspaces.example/`](../workspaces.example/README.md) (`cp -R workspaces.example/. ~/.config/lanes/workspaces/`).
+
+A complete terminal registry is provided in
 [`workspaces.example/terminals.example.json`](../workspaces.example/terminals.example.json): adapt it to the
 repository's `.vscode/terminals.json` inside the container. Every terminal needs an explicit tmux socket/session
 binding; there is no guessed command parsing. See [the configuration reference](../workspaces.example/README.md).
@@ -69,6 +87,80 @@ A lane that has not started is shown as absent. Open its terminal in Cursor / VS
 The viewer itself only attaches. `lanes cursor-commit --push` is a separate, explicit publishing action;
 it is not run by installation or automatic sync.
 
+### Onboard a user's container
+
+`lanes onboard` does every server-side step for one user's workspace container in one command. Without `--write` it
+prints each diff and each command it would run, and changes nothing:
+
+```sh
+lanes onboard anna --container ws-anna --workspace anna-tools --repo /home/coder/tools
+lanes onboard anna --container ws-anna --workspace anna-tools --repo /home/coder/tools --write
+```
+
+Both forms first check the container with `docker inspect` (the `inspect` step), which only reads. An unknown
+container, for example a mistyped `--container`, stops the run before anything is written, so no board names a
+container that does not exist. The same step compares the host account's UID and the home volume's owner with the
+container's UID 1000 ([section 1](#1-prepare-a-workspace-host)). On a mismatch the step fails and the run stops
+there, in a dry run too: no board, no contract, no hooks, no Throttle step and no other write. Every later step is
+listed as `not-run` with the reason, and the exit code is 1, as for an unknown container. Run it again from a host
+account with UID 1000. With `--write` it then applies these steps in order:
+
+1. **Board.** Runs `lanes workspaces add`, when `--workspace` and `--repo` are given. `--title` defaults to the id
+   or to the title the board already has. A board that already disagrees stops the run before the container is
+   touched.
+2. **Contract.** Runs `lanes install-container`.
+3. **Agent hooks.** Runs `lanes hooks install --write`, first for Claude and then for Codex. Your own hooks and
+   keys are kept, with a backup of each changed file. A Lanes hook group that is already installed stays where
+   it is, even when Throttle's setup has added its own group around it.
+4. **Throttle.** Asks the container, as UID 1000, whether it has a `throttle` and whether Throttle is configured
+   there (`~/.config/throttle/config.toml` exists). Only a configured Throttle gets `throttle setup
+   --install-clients`, which then runs without a person. A first setup needs one: it signs in to claude.ai with a
+   code pasted on a terminal, or adopts the container's own Claude login as a pool account. So when Throttle is
+   missing or not configured, the command prints the step to run once on a terminal,
+   `docker exec -it -u 1000 <container> sh -lc 'throttle setup --install-clients'`, records it as `manual` and
+   continues, because Lanes runs without Throttle. The setup output is not shown: it names accounts and credential
+   sources. When the server's
+   `~/.config/lanes/site.conf` sets `LANES_THROTTLE_REMOTE_URL`, the command also prints a laptop step: `throttle remote join` with a
+   pairing code from the operator.
+5. **Sync.** Runs `lanes sync`, so the registry knows the board.
+6. **Recipes.** Runs `lanes cursor-sync <id> --canonicalize --write` when `<repo>/.vscode/terminals.json` exists
+   in the container. When the file is missing, the command points at
+   [`terminals.example.json`](../workspaces.example/terminals.example.json) instead. When this step rewrote the
+   file, a second `lanes sync` copies the new recipes into the container's `~/.lz/registry.json`, which
+   `lane open` reads.
+7. **Doctor.** Runs `lanes doctor`. Its result is reported but does not stop onboarding.
+
+The run ends with a `key: value` table and a receipt in `~/.local/state/lanes/onboard/<login>-<UTC>.json`:
+`{version, login, container, workspace, at, steps: [{name, status, detail}]}`. A status is one of `planned`,
+`changed`, `unchanged`, `ok`, `skipped`, `manual` (a step left for a person, with its command), `warn`, `failed` or
+`not-run`. When a step stops the run, every step after it is still listed, as `not-run`, in the table and the receipt.
+The exit code is 1 only when a step failed. 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. Until it does, the
+receipt records that step as skipped.
+Each user's board still shows on every device's view. A per-device subset of boards is a separate follow-up.
+
+### Laptop agents on the Throttle pool (operator-gated)
+
+Lanes agents run in the containers and reach Throttle there. Agents a user runs on their own laptop can use the same
+pool over the tailnet, without a public relay: Throttle's `throttle remote share --tailnet` and `throttle remote join`
+(source-current, unpublished; the Throttle user guide's "Remote clients over Tailscale" section, which lands with that
+change, in [docs/throttle-userguide.md](../../docs/throttle-userguide.md)). Lanes only prints the laptop step; every
+operator step stays with the operator, because each one changes the production daemon:
+
+1. Decide to share. The remote key is also the daemon's control-plane admin credential: hand it only to people you
+   would give operator access.
+2. Where the daemon's configuration lives, run `throttle remote share --tailnet` (the key from `--key-file` or stdin,
+   never an argument). It sets only `server.remote_key` and prints the rest.
+3. Do the printed steps: `throttle setup --install-clients` (loopback clients need the managed token once a remote key
+   is set), `server.host` for a containerised daemon, `throttle restart`, and on the host `tailscale serve --bg
+   --https=10000 http://<address>:<data port>`. Lanes' own front keeps 8443.
+4. Put the resulting URL in the server's `~/.config/lanes/site.conf` as
+   `LANES_THROTTLE_REMOTE_URL=https://<host>.<tailnet>.ts.net:10000`.
+
+From then on `lanes onboard` prints, and records as a `manual` step in its receipt, `on the user's laptop: throttle
+remote join <pairing code>`; the pairing code comes from the operator's share. Without that line in `site.conf`,
+onboarding says nothing about laptops. No Lanes command shares the pool or touches the daemon.
+
 ## 3. Give clients a site profile
 
 Copy [`site/site.example.conf`](../site/site.example.conf) and fill in the server's reachable hostname,
@@ -83,10 +175,9 @@ The actual known_hosts line has three fields: alias, `ssh-ed25519`, and the base
 `ssh_host_ed25519_key` (the private key). [Site instructions](../site/README.md) cover profiles and updates.
 The supplied `site/beyondwork/` profile is an explicit choice for the existing team server, not a default.
 
-On each Mac or Linux desktop, install from npm (members of the `@vibelord` npm organization; Node.js 18+):
+On each Mac or Linux desktop, install from npm (public package, no npm login; Node.js 18+):
 
 ```sh
-npm login                                   # once per machine, or a read-only token in ~/.npmrc
 npx @vibelord/lanes --site beyondwork       # bundled team profile; or --site /path/to/site.conf
 ```
 
@@ -101,57 +192,202 @@ cd bw-tools/lanes
 
 OpenSSH is required. Install Ghostty for a dedicated window, or run `lanes-launch` in your existing terminal.
 Linux also supports Foot, plus optional Omarchy/Hyprland shortcuts. Tailscale is required when your profile uses
-a tailnet address. The installer installs its own configuration; your normal terminal remains usable.
-
-Authorize the printed public key in the server account's `~/.ssh/authorized_keys`. The client never edits that
-file remotely. Then `./install.sh --check` and `lanes-window`. Useful options:
+a tailnet address. When the profile's `LANES_SERVER_NAME` ends in `.ts.net`, the installer checks Tailscale before
+the server: without it, it prints `tailscale: not installed — macOS: brew install --cask tailscale · Linux:
+https://tailscale.com/download` and exits 4 (the client is installed); on a logged-out machine it prints
+``tailscale: needs login — opening `tailscale login`… (approve in the browser)``, runs `tailscale login` and waits up
+to 120 s (`LANES_TAILSCALE_WAIT`) with a countdown until the machine is online, then prints `tailscale: connected as
+<login> (<address>)`. On Linux an account without Tailscale operator rights is told to run `sudo tailscale up` once.
+`--check` only looks. The installer installs its own configuration; your normal terminal remains usable.
+
+When this machine resolves the profile's MagicDNS name, the SSH alias `lanes` names the server by it (a server that
+gets a new tailnet address keeps working), and a second alias, `lanes-ip`, holds the address. `lanes-launch` falls
+back to `lanes-ip` after two immediate connect failures, then to `lanes-public` when the site has one. A machine
+without MagicDNS keeps the address in `lanes`. Every alias pins the same host key under the profile's alias.
+
+### Join with an invite or a request
+
+On a server that runs the enrolment service `lanes-enrold` (every server install enables it), a new machine
+authorizes itself. The user's side, step by step, is the user guide's
+[Join a site](USERGUIDE.md#2-join-a-site): join the tailnet, run the installer with the code, then `lanes-launch`,
+`lanes-launch web phone` and `lanes-launch web laptop`. With an invite code, `npx @vibelord/lanes --invite
+LN-xxxx-xxxxxxxxxxxx` (the code's prefix picks the bundled profile whose `site.conf` says `LANES_SITE_CODE=LN`; an
+explicit `--site` wins) installs the client, redeems the code and prints `invite: redeemed — this machine's key is now
+authorized for <login> (device <device>)`. Without a code, the installer asks on a terminal; Enter files an access
+request that a member approves (the installer waits up to 10 minutes; `--resume` waits again). The installer calls
+`GET /enrol/site`, then `POST /enrol/redeem` or `POST /enrol/request` plus `GET /enrol/request/<id>`, on
+`https://<LANES_SERVER_NAME>:8443` (with curl, or python3 without it; `--resolve` to the tailnet address when MagicDNS is
+off). What the client reads of lanes-enrold's wire contract is in [the architecture](ARCHITECTURE.md#joining-a-site).
+The code is never shown, stored, or put on a command line. A malformed code, or one with another site's prefix, is refused before anything is installed
+(exit 1).
+
+Without the service, after a refused code, or with no code and no terminal, authorize the printed public key on the
+server, as the workspace account: `lanes keys add <device> <file.pub>` (or `lanes keys add <device> -` and paste the
+line) writes it into the lanes-managed block of `~/.ssh/authorized_keys` (ed25519 only; every line outside the block
+is kept; see the runbook's "Who may log in"). The client never edits that file; on the server the enrolment service
+and `lanes keys` write it. Then `./install.sh --check` and `lanes-window`.
+
+### Client options
+
+Useful options:
 
 - `--device NAME`: independent view name; a stable per-machine name is the default.
-- `--key PATH`: choose an existing SSH private key; the key stays on the client.
-- `--no-desktop` / `--no-uploads`: omit those integrations.
+- `--key PATH`: choose an existing SSH private key; the key stays on the client (enrolment takes an ed25519 key).
+- `--invite CODE` / `--resume`: join with an invite code, or wait again for an open access request (per run).
+- `--no-desktop` / `--no-uploads`: omit those integrations; on a machine where an earlier install added them they are
+  taken away (the upload agents stopped and removed, the launcher entry and key binding removed; `~/Lanes Uploads`
+  and its files stay). `--desktop` / `--uploads` put them back.
+- `--palette` / `--no-palette`, `--coder-launch` / `--no-coder-launch`: the cockpit's Ghostty palette and the
+  `coder-launch` command name, on or off.
 - `--link`: develop against the checkout instead of installing a client copy.
 - `--yes`: noninteractive installation; a newly created dedicated key has no passphrase.
 
-The site selection is saved in `~/.config/lanes/client-site.conf`. Subsequent installs and checks can omit `--site`.
+Every choice except `--invite`, `--resume`, `--link` and `--yes` is remembered in `~/.config/lanes/install-options`
+(plain `KEY=VALUE`, mode 0600, never executed; the runbook's
+[Remembered install options](RUNBOOK.md#remembered-install-options) lists the keys): subsequent installs, updates and checks can omit them, and a flag given again overrides
+the remembered value. A bundled profile is remembered by name (an update reads the new package's copy), your own
+profile file by path; the selected profile is also copied to `~/.config/lanes/client-site.conf`. `--uninstall`
+removes both. On Linux with a key that has a passphrase, the upload helper service logs in through the SSH agent your
+systemd user manager holds, looked up again before every login (so an agent your desktop session hands over after
+the service started is used from its next login on, at most a minute later); the installer hands your terminal's
+agent over and adds one marked block (`# >>> lanes agent hand-off >>>`) to your login profile that repeats this at
+each local login (`--no-uploads` and `--uninstall` remove it); a profile it cannot write (a read-only dotfiles
+checkout, a full disk) is left as it was, the installer prints the line to add and finishes the install; see [the
+user guide](USERGUIDE.md#5-uploads).
 On macOS, the signed Lanes Helper app requests access to protected folders. Allow Downloads/Desktop/Documents
 as needed. The allowlist is separate from macOS permission; inspect it with `lanes-upload --allowed`.
 
-## 4. Optional Safari / Home Screen access
+### Invite a user
 
-Install Caddy and Tailscale on the server and enable Tailscale HTTPS for its tailnet. The web services use
-loopback ports **8082** (native Zellij) and **8083** (Lanes frontend); private HTTPS uses **8443**.
-Reserve those ports for Lanes on this host. Caddy runs as a separate user service with its admin API disabled.
+Instead of hand-adding each key, a member mints an invite on the server (or over `ssh lanes`), in their own terminal:
 
-Once, a server administrator allows the workspace account to manage Tailscale Serve:
+```sh
+lanes invite anna --email anna@example.com --workspaces bw-tools,throttle     # prints the five-line welcome kit
+lanes invite list                                                            # live / redeemed / revoked / expired
+lanes invite revoke <id>                                                     # refuse that code from now on
+```
+
+The kit carries a one-time code `LN-<id>-<secret>` (case-insensitive, valid 7 days; `--expires 1h`…`30d`) that the
+new machine redeems at the enrolment service (`lanes-enrold`, RUNBOOK "Enrolment service") through the client's
+`--invite` (W8 B3): its key enters the
+lanes-managed block of `~/.ssh/authorized_keys` without anyone editing it. Only the code's hash is stored; the code is
+printed once, and only to a terminal (`lanes invite` refuses with exit `2` when piped). Give `--email` on an
+invite-only server: it becomes the new member's owner login. Two optional, Lanes-owned key files add to it —
+`~/.config/lanes/resend.key` (a Resend API key on its first line) mails the kit to `--email`; to reach anyone but
+you, add a `from=Name <addr>` line on a domain verified in Resend, because without it the kit goes from Resend's test
+sender, which delivers only to the Resend account's own address (Resend answers 403 and the note says so). The
+other, `~/.config/lanes/tailscale-api.key` (a user-owned Tailscale API access token), mints step 1's tailnet invite
+link; `--tailscale-link URL` pastes one from the Tailscale admin console instead. Keep both files `0600`.
+
+A machine that comes without a code asks instead: `lanes enrol list`, then `lanes enrol approve <id>` ("Approve a
+request" below). A machine leaves with `lanes offboard <device> --yes` ("Offboard a machine" below).
+
+### Approve a request
+
+A machine that comes without a code files an access request when its user presses Enter at the installer's prompt
+(the user guide's [No code: ask for access](USERGUIDE.md#no-code-ask-for-access)); the installer waits up to 10
+minutes, and the request stays open for 24 hours. Any member decides it:
 
 ```sh
-sudo sh sudo/one-time-root.sh --user workspace
+lanes enrol list                              # the open requests: id, device, login, the key's fingerprint
+lanes enrol approve <id> [--as <your-device>] # writes the member and its key line, exactly as the web page does
+lanes enrol deny <id>
+lanes enrol list --all                        # also the approved, denied and expired ones
 ```
 
-This does not change SSH daemon settings unless `--ssh-keepalive` is explicitly supplied. Then, in your own
-interactive terminal, either run on the server:
+On a phone or laptop on the tailnet, `https://<server>:8443/enrol/pending` lists the same requests with **Approve**
+and **Deny**. It admits a tailnet login that owns a member record, and keys added by hand (`lanes keys add`, `lanes
+keys adopt`) record no owner, so name yourself once on one of your own devices: `lanes keys owner <your-device>
+<your tailnet login>`. With the opt-in push notifier (`lanes-notify.service`), each new request arrives as one push
+naming the requester, the device and the approve command. The CLI records where a decision came from
+(`cli[:<device>]@<address>`), not who made it (everyone over SSH is the one workspace account); the web page records
+the real tailnet login. Requests need request mode, which needs Tailscale Serve to hand the service a tailnet
+identity. Run the runbook's [operator verification](RUNBOOK.md#enrolment-service-lanes-enrold-w8-a3) once after the
+first server install, then pin the result, so it holds across every restart and reinstall:
 
 ```sh
-sh install/enable-phone.sh --local
+lanes enrol mode request    # the header check passed: take access requests
+lanes enrol mode invite     # it did not (or other accounts share this host): invites only
+lanes enrol mode            # what is pinned; `auto` unpins it
 ```
 
-or run from an installed Mac/Linux client:
+Unpinned (`auto`), the first request that comes through Tailscale Serve after each start decides, so a tagged device
+or a forged header at the wrong moment can turn requests off — or on — until the next restart. `LANES_ENROL_DOMAINS`
+(default `beyondwork.ai`) limits which logins may file a request, and which may approve one on the web page.
+
+### Offboard a machine
+
+In your own terminal (without `--yes`, or piped, it prints the plan, changes nothing and exits 2):
 
 ```sh
-sh install/enable-phone.sh --host lanes
+lanes offboard anna-mbp --yes          # its key, its device record, its browsers and phones, its view session
+lanes offboard anna-mbp-2 --yes        # each window it names: forget the device, end that view
 ```
 
-The remote path uses the installed checkout shortcut and the SSH key selected by the client installer;
-there is no password fallback or agent forwarding. It enables the services, prepares a separate `phone` view,
-starts private Tailscale Serve and prints a fresh token. Existing tokens remain valid.
+`lanes offboard <device> --yes` takes the key out of the lanes-managed block of `~/.ssh/authorized_keys` and removes
+`members/<device>.json`, forgets the device so `lanes ensure` does not bring its view back, signs the machine's
+browsers and phones out, and ends its view session. No lane, agent or container is touched, and an SSH session
+already open with the key keeps running until it ends. Signing out revokes every web login token `lanes web --token`
+recorded for the machine: its own, its windows' (`<device>-2` from `lanes-window 2`), and those of the views
+`lanes-launch web phone|laptop` opened for it (`<device>-phone`, `<device>-web`) — never another machine's. It
+revokes them even when that leaves Zellij 0.45.1 unable to create the next token, and then names `lanes token
+revoke-all --yes`, which repairs that (and signs every browser and phone out); a token nobody can attribute (minted
+before 1.1.0, or outside `lanes web --token`) is listed with `lanes token revoke --name NAME`
+([runbook](RUNBOOK.md#login-tokens)). A step that fails (Zellij does not answer, the web server reads another token
+database) leaves the offboard incomplete, exit 1: run it again. The windows share the revoked key; offboard names them
+and leaves their views running, so offboard each by name to end it. A redeemed invite is not revoked by `lanes invite
+revoke`: offboarding its device is how access ends.
+
+## 4. Optional Safari / Home Screen access
+
+Install Caddy (2.5 or later: the `/enrol/*` route uses `reverse_proxy { trusted_proxies … }`, which older versions
+refuse; the Debian 12 and Ubuntu 24.04 packages are 2.6) and Tailscale on the server and enable Tailscale HTTPS for
+its tailnet. The web services use
+loopback ports **8082** (native Zellij) and **8083** (Lanes frontend); private HTTPS uses **8443**. The enrolment
+service every server install runs (`lanes-enrold`) listens on loopback **8184** and is reached as `/enrol/*` through
+the frontend.
+Reserve those ports for Lanes on this host. Caddy runs as a separate user service with its admin API disabled.
+
+Once, a server administrator allows the workspace account to manage Tailscale Serve:
+
+```sh
+sudo sh sudo/one-time-root.sh --user workspace
+```
+
+This does not change SSH daemon settings unless `--ssh-keepalive` is explicitly supplied. That is the whole server
+setup: each user then runs, from their installed Mac/Linux client, in their own interactive terminal:
+
+```sh
+lanes-launch web phone    # their phone's view, <device>-phone (phone layout)
+lanes-launch web laptop   # their laptop's browser view, <device>-web (desktop layout)
+```
+
+`lanes-launch web` runs `lanes web <view> --token --default-device <device>` on the server over `ssh -t lanes`, with
+the SSH key the client installer selected (no password fallback, no agent forwarding). On the server itself the same
+step is `lanes web phone --mobile --token`; `sh install/enable-phone.sh --host lanes` from a client is the older
+one-shot for the device `phone`. `lanes web` prepares the view, enables the loopback services, makes Tailscale Serve
+forward private HTTPS 8443 to the frontend, prints the URL with a QR code of it and shows a fresh token in your
+terminal. The Serve step reads `tailscale serve status --json` first: a mapping of `https:8443` to
+`http://127.0.0.1:8083` is left alone, a missing one is added with
+`tailscale serve --bg --https=8443 http://127.0.0.1:8083`, and a mapping of 8443 to anything else is never replaced
+(exit 64, with the command that frees the port). When Tailscale refuses the account, `lanes web` exits 64 and prints
+the `sudo tailscale set --operator=<account>` step above. Existing tokens remain valid.
 
 Connect Tailscale on the phone, open the printed URL in Safari, paste only the token value, then
-**Share → Add to Home Screen**. A token grants terminal access as the server account. Revoke a named token with:
+**Share → Add to Home Screen**. A token grants terminal access as the server account. Manage tokens with:
 
 ```sh
-~/.local/share/lanes/bin/zellij-0.45.1 web --revoke-token NAME
+lanes token list                  # every token, with the device it was created for
+lanes token revoke phone          # sign that device's token out
+lanes token revoke --name token_1 # a token created before Lanes recorded devices, or outside it
+lanes token revoke-all --yes      # every token: each browser and phone signs in again
 ```
 
+Zellij 0.45.1 cannot name a token: it calls each new one `token_<number of tokens + 1>`, so Lanes records which
+device `lanes web --token` created it for. Because of that naming rule, revoking any token but the newest would leave
+Zellij unable to create the next one; `lanes token revoke` refuses such a revocation and names `revoke-all` instead.
+Revoking a token also deletes its sign-in sessions, so that browser has to sign in again.
+
 `sh install/enable-web.sh` starts only the loopback services and prints no token. The frontend and services
 run on the workspace host; a Mac does not need to stay awake for the phone to work.
 
@@ -167,21 +403,35 @@ The same private frontend serves every browser and chooses its controls once, wh
   whole tab, so a desktop view's lane sidebar sits beside its lanes (**More → Single pane** shows one pane).
 - **Phone**: the phone shell described above.
 
-Give each browser its own view. On the server, one command prepares it, enables the loopback web services and
-prints its private URL:
+Give each browser its own view. From an installed client, in your own terminal, one command does it all on the
+server — prepares the view, enables the loopback web services, prints its private URL with a QR code of it (for a
+phone camera; `--no-qr` leaves it out) and a fresh login token:
+
+```sh
+lanes-launch web phone             # <your device>-phone with the phone layout
+lanes-launch web laptop            # <your device>-web with the desktop layout
+lanes-launch web ipad --desktop    # any other name is that device as given; --desktop / --mobile picks the layout
+```
+
+On the server the same command is `lanes web` (what `lanes-launch web` runs, with `--token` and
+`--default-device <your device>`):
 
 ```sh
 lanes web ipad --desktop           # desktop sidebar layout (a new device's default); --mobile: phone lane pickers
-lanes web ipad --desktop --token   # the same, then a fresh login token in this terminal
-lanes web ipad --print-only        # shows the exact prepare call and URL; changes nothing
+lanes web ipad --desktop --token   # the same, then a QR code of the URL and a fresh login token in this terminal
+lanes web ipad --print-only        # shows the exact prepare call, URL and Serve step; changes nothing
 ```
 
-From an installed client, `sh install/enable-phone.sh --host lanes --desktop ipad` does the same over the
-selected SSH key; without a name, `--desktop` uses the device `browser`. The server needs this version of Lanes
-for `--desktop`. A device keeps the layout it was created with: `lanes web <device>` without a flag reuses it
-(so `lanes web phone` reuses the phone's view), and an explicit request for the other layout is refused; choose
-another device name. `lanes web` reads the node's Tailscale name. Tailscale Serve itself is set up once
-by `enable-phone.sh`, as described above.
+From an installed client, `lanes-launch web <device> --desktop` or `sh install/enable-phone.sh --host lanes
+--desktop ipad` does the same over the selected SSH key; without a name, `--desktop` uses the device `browser`. The
+server needs this version of Lanes for `--desktop`. A device keeps the layout it was created with: `lanes web
+<device>` without a flag reuses it (so `lanes web phone` reuses the phone's view), and an explicit request for the
+other layout is refused; choose another device name. `lanes web` reads the node's Tailscale name and ensures the
+Tailscale Serve mapping itself, as described above (its `serve:` line says `present` or `added`), so neither
+`lanes-launch web` nor `enable-phone.sh` has a Serve step of its own. `lanes doctor` checks the same mapping (only
+when the host has a Tailscale name, as `lanes web` does), the two web units, and that the running `lanes-web` reads
+the login tokens from `~/.local/share/zellij/tokens.db`, the database `lanes web --token` and `lanes token` use (both
+sides pin `XDG_DATA_HOME=%h/.local/share`; see the [runbook](RUNBOOK.md#login-tokens)).
 
 On a network with a captive portal (hotel, train or aircraft Wi-Fi), connect in this order:
 
@@ -235,6 +485,10 @@ use the same overrides when reinstalling. `LANES_WORKSPACES` is also carried int
 when supplied; the standard configuration directory is the simplest default.
 
 After updating server code, restart the status observer with `systemctl --user restart lanes-statusd.service`.
+The installer itself restarts the enrolment service (`lanes-enrold`) and a running web frontend (`lanes-mobile`, so
+Caddy reads the new tree's Caddyfile; browser clients reconnect). On the first server install with enrolment, run the
+runbook's operator verification and pin its result with `lanes enrol mode request` (or `invite`) — see
+[Approve a request](#approve-a-request); a pinned mode survives this restart and every later one.
 If you enabled the Studio Host and selected a new `throttle-rc` or edited its config, restart
 `lanes-studio-host` (re-running `install/enable-studio-host.sh` does that, after `studio host --check`).
 If web service definitions or the pinned Zellij binary changed, restart `lanes-web` and `lanes-mobile` too;
@@ -247,7 +501,7 @@ Normal paths:
 | --- | --- |
 | `~/.config/lanes/` | Site profile, client settings and server workspace configuration |
 | `~/.local/share/lanes/` | Client copy, pinned binaries, download cache, installed checkout link and npm-staged trees (`pkg/<version>/`) |
-| `~/.local/state/lanes/` | Host registry, device selections, status, upload handoff and housekeeping projections |
+| `~/.local/state/lanes/` | Host registry, device selections, status, upload handoff and housekeeping projections; `members/`, `invites/`, `enrol-requests/` and the append-only `enrol.log` of the enrolment service |
 | `~/.local/state/lanes/studio-host/` | Optional Studio Host: published public key, deploy receipt, enrolment record, migrated unit text (`lanes studio-host re-key --yes` clears the key half after a revoke) |
 | `~/.config/throttle-rc/`, `~/.local/share/throttle-rc/` | Optional Studio Host config, machine key and enrolment receipt (throttle-rc's own files) |
 | `~/.local/state/lanes-client/` | Client helper heartbeat and logs |