@vibelord/lanes 1.0.3 → 1.0.4

package/README.md

@@ -6,6 +6,9 @@ registry sync, uploads and a phone interface. The package carries the committed
 
 The package is **restricted** to the `@vibelord` npm organization.
 
+How to use Lanes once installed (desktop, phone and browser views, keys, uploads, operations): the
+[Lanes user guide](../../lanes/docs/USERGUIDE.md).
+
 ## Install on a new Mac or Linux machine
 
 Requirements: Node.js 18+ (for npm only), OpenSSH, and a route to the server (Tailscale for the Beyond Work profile).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibelord/lanes",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Installer for Lanes: shared agent terminals over SSH with Zellij views, registry sync, uploads and a phone interface.",
   "license": "MIT",
   "type": "module",

package/payload/lanes/README.md

@@ -1,17 +1,47 @@
 # Lanes
 
-One setup for shared agent terminals: Zellij panes and workspace tabs, live lane status, registry sync,
-Cursor / VS Code integration, uploads, desktop launchers, and a phone interface. The complete implementation
-and its tests live in this folder.
-
-Each device gets its own view of the same long-running terminals. Closing a view or losing a connection
-leaves those terminals running in their workspace containers.
+Lanes is the shared terminal setup for long-running coding agents. The agents run in tmux sessions inside workspace
+containers on one Linux host; every device you use gets its own live view of the same terminals: Zellij workspace
+tabs with a lane sidebar that sorts the agents that need you to the top, registry sync from the repositories'
+terminal lists, Cursor / VS Code integration, file uploads, desktop launchers, and a phone, tablet and laptop browser
+interface. The complete implementation and its tests live in this folder.
+
+**Start here: the [Lanes user guide](docs/USERGUIDE.md)** covers daily use on every surface, every key, sidebar
+glyph and command, installation and updates, and the operations reference.
+
+Closing a view or losing a connection leaves the terminals running in their workspace containers: a lane ends only
+when someone closes it explicitly.
+
+**Who uses it.** Operators and teammates who run several Claude Code or Codex agents at once use Lanes daily to see
+which lane needs them, switch to it, answer, and move on, from a desk or from a phone. An administrator installs the
+server once on the workspace host and authorizes each person's SSH key; each person installs the client on their own
+Mac or Linux machine.
+
+**Three surfaces, one set of lanes:**
+
+| Surface | How you reach it | Typical use |
+| --- | --- | --- |
+| Desktop terminal | `lanes-window` (own Ghostty window) or `lanes-launch` in any terminal, over SSH | Daily work: workspace tabs, the sidebar, one to three lanes side by side |
+| Browser | `/phone` in Safari (Add to Home Screen), or a laptop or tablet browser view from `lanes web`, private over Tailscale | Checking and answering agents away from the desk |
+| Editor | Cursor / VS Code terminals that run `lane open <lane-id>` inside the container | Opening the same lane next to the code |
+
+**How it relates to the rest of the repository.**
+
+- **Throttle**: Lanes runs without it. With the opt-in economy poller, the sidebar shows what the fleet spends and
+  which lanes are starving, downgraded or mostly paid, read from the Throttle daemon. A lane created with the
+  canonical recipe sends a `lanes/<workspace>/<lane>` trace to the Throttle proxy (enabling that on a live workspace is
+  an operator decision).
+- **Throttle Studio**: a second client of the same lanes. Its **Shared lanes** console gives teammates a read-only,
+  SSO-protected view of selected workspaces, and one co-located Studio Host can serve every workspace of a Lanes server
+  ([sharing](docs/SHARING.md)).
+- **Cursor / VS Code**: each repository's `.vscode/terminals.json` is the source of truth for its lanes;
+  `lanes cursor-sync` points the editor's terminals at the same tmux sessions the views show.
 
 ```text
-Mac / Linux terminal ── SSH ───────┐
-                                 ├─ Linux workspace host ── container tmux sessions
-Safari / Home Screen ── HTTPS ────┘      Zellij views            agent lanes
-                                       registry + status
+Mac / Linux terminal ──── SSH ───────┐
+                                     ├─ Linux workspace host ── container tmux sessions ── Cursor / VS Code
+Phone / tablet / laptop ── HTTPS ────┘      Zellij views            agent lanes            `lane open <id>`
+  browser (Tailscale)                      registry + status
 ```
 
 ## Quick start
@@ -78,25 +108,28 @@ The installer starts an empty catalog safely; it does not assume anyone's contai
 | Switch workspace | Ctrl–Alt–Left / Right |
 | Next or previous lane | Ctrl–Alt–Down / Up (the focused pane moves to the next / previous lane of its workspace; nothing is typed, the focus stays), or tap the sidebar |
 | Plain-ASCII glyphs, light or dark tokens | `lanes-window --ascii`, `lanes-window --light` / `--dark` (remembered per device in `devices/<device>.json`; a running sidebar picks it up within one tick) |
-| Lock the view (every key reaches the lane) | Ctrl–Alt–G, again to unlock; the bar shows LOCKED in red. Ctrl–G itself always reaches the lane (Claude Code's editor key) |
-| Search lanes | Ctrl–Alt–/ |
+| Lock the view (plain keys and Zellij's mode keys reach the lane) | Ctrl–Alt–G, again to unlock; the bar shows LOCKED in red. The Ctrl–Alt keys of `zellij/config.kdl`'s `shared` block (←/→/↓/↑, `/`, U, C, S, PageUp/PageDown/End) stay active while locked. Ctrl–G itself always reaches the lane (Claude Code's editor key) |
+| Zellij modes | Ctrl–Alt–P pane · Ctrl–Alt–T tab · Ctrl–Alt–N resize · Ctrl–Alt–H move · Ctrl–Alt–F scroll · Ctrl–Alt–O session (`d` detaches) · Ctrl–Alt–B tmux-style; Esc returns to normal. Every key: [user guide](docs/USERGUIDE.md#keybindings) |
+| Search lanes | Ctrl–Alt–/, or `/` in the sidebar: fuzzy (the letters in order, substring and prefix matches first); Enter opens the match under the cursor, Esc clears |
 | Select a lane for pane 2 or 3 | `2` / `3` in the sidebar of a wide view |
 | Open one lane directly | `lanes-launch lane <lane-id>`; find IDs with `lanes-launch ls` |
 | Read a markdown file a lane mentioned | Ctrl–Alt–M opens a floating **Preview** pane over the focused lane: the `.md` paths it printed in its last 300 lines that exist in its container (relative ones resolved against its working directory). One is shown at once; several give a numbered menu, newest first (Enter = the newest, `q` closes). Rendered by `glow` in the view's dark/light theme (the server installer adds a pinned glow unless the view server's PATH — `~/.local/share/lanes/bin`, the checkout's `bin`, `/usr/local/bin`, `/usr/bin`, `/bin` — already has one; a glow only in `~/.local/bin` or `~/go/bin` does not count), else `less -R`; `lanes doctor` names which (`preview renderer:`); quitting the pager closes the pane |
-| Create a persistent workspace shell | **+ New shell** under **Unregistered** (**New +** on the phone), or `+` in the sidebar |
-| Register an existing session | **+** beside an unregistered session, or select it and press `a`; choose a workspace |
+| Create a persistent workspace shell | The **+ New shell** row under **Unregistered** (desktop sidebar and phone picker), or `+` in the sidebar |
+| Register an existing session | **+** beside an unregistered session, or select it and press `a`; choose a workspace (`lanes register <lane-id> [workspace]` on the server) |
+| Declare a session in the repository | `P` in the sidebar, then `y`: writes the session's binding into the workspace's one repository `terminals.json`, so it becomes a repository lane `<workspace>--<slug>` |
+| Rename a lane | `R` in the sidebar (Enter saves, Esc cancels), or `lanes rename <lane-id> <name>` on the server; the lane id never changes |
 | See which agents need you | The sidebar sorts **Needs you** (◆ approval, ✗ error, ◇ waiting for a prompt), **Working** (▸) and **Done** (✓, until you open the lane) above the rest; the header counts them in the same glyphs (`◆1 ◇2 ▸6 ✓1`, zeros left out; `N lanes` when no lane runs an agent) |
 | Read a sidebar row | `▌` cursor · agent glyph · `›` the lane this pane shows (`²`/`³`: shown in pane 2/3) · the name (`·` per other viewer, `…` when clipped) · an **age column** on every row (agent turn, else last output: `45s`, ` 3m`, ` 2h`, ` 4d`; amber in **Needs you**) · stream glyph · one tail cell by priority (`?` not observed right now > `⚠` starving: producing output but no request for over 10 min, or a 429 > `↓` downgraded > `$` mostly paid — the economy cells need the opt-in economy poller; a dim `⚠`/`↓` is a frozen last-known figure, not a live alarm) · `×` close. `⋮ N more` ends a list that continues below |
 | End an unregistered session and its jobs | **×** beside the session, or select it and press `x`; confirm with `y` (any other key cancels) |
 | Every sidebar key | `?` replaces the list with the key sheet until the next key (that key only closes it). The footer legend says ` ⏎ open · / find · x close · ? keys`; prompts share one shape (` › close ‘name’? y/n`, ` › Rename: …█`, ` › Register ‘name’? y/n`) and a filter counts its matches (` /abc · 3 matches`) |
-| Jump to the next lane that needs you | `Tab` / `Shift-Tab` in the sidebar (cycles **Needs you** from the lane the pane shows; the pane title carries the counts and a lane that starts needing you raises one OSC 9 desktop notification — `LANES_NOTIFY=0` silences it) |
+| Jump to the next lane that needs you | `Tab` / `Shift-Tab` in the sidebar (cycles **Needs you** from the lane the pane shows; the pane title carries the counts and a lane that starts needing you raises one OSC 9 desktop notification on desktop layouts — `LANES_NOTIFY=0` in the sidebar's environment silences it, see the [user guide](docs/USERGUIDE.md#9-appearance) for how environment variables reach a sidebar) |
 | Other workspaces that need you | The row above the footer rule: ` ◆1 Worlds · ◇2 Code` (blank and absent when none; panes of 18 rows or more) |
 | What the fleet spends | With the opt-in economy poller ([RUNBOOK](docs/RUNBOOK.md#economy-projection-opt-in)) the same row is the fleet economy strip instead: ` $8.5k/16k 53% · F2 S1 · spill 76% · free 3/19` — overflow spend against the daily cap (amber at the alert level), new upstream 429s, this workspace's lanes by model tier (`F` fable, `O` opus, `S` sonnet, `H` haiku, `G` gpt), the pool's spill fraction, free accounts and the next 5 h reset, whole parts dropped from the end to fit; a leading `?` means the figures are frozen — the poller could not reach the daemon, or it stopped (no rewrite for over 3 min) |
 | Upload | Click the one-row upload strip above the footer (` ↑ uploads · click, then drop  (U)`) or press `U`, then drop anywhere on the window; or use `~/Lanes Uploads/<workspace>/`, or `lanes-upload <files>` |
-| Phone setup from a client | `sh install/enable-phone.sh --host lanes` |
-| Laptop or tablet browser view | `lanes web <device> --desktop [--token]` on the server, or `sh install/enable-phone.sh --host lanes --desktop <device>` ([guide](docs/INSTALL.md#laptop-and-tablet-browser)) |
+| Phone setup from a client | `sh install/enable-phone.sh --host lanes` (prepares the `phone` view; open `https://<server>:8443/phone` in Safari) |
+| Laptop or tablet browser view | `lanes web <device> [--desktop\|--mobile] [--viewports N] [--token \| --print-only]` on the server (prepares the view, enables the loopback web services, prints the private URL), or `sh install/enable-phone.sh --host lanes --desktop <device>` ([guide](docs/INSTALL.md#laptop-and-tablet-browser)) |
 | Switch workspace or lane in a laptop browser | The **Lanes** chip (top right) opens the workspace and lane pickers |
-| Detach | Close the window; the agents keep running |
+| Detach | Close the window, or Ctrl–Alt–O then `d`; the agents keep running |
 
 Unregistered sessions also appear when they use shared or previously unlisted tmux servers. Reopening a
 session reuses it; closing a view leaves it running. Registered lanes have no **×** control. See the
@@ -180,13 +213,17 @@ See [workspace configuration](workspaces.example/README.md) and the [architectur
 | `site/`, `workspaces.example/` | Deployment profiles and editable configuration examples |
 | `sudo/` | Optional administrator setup and host protection, applied explicitly |
 | `tests/` | Unit tests plus isolated host/container integration suites |
-| `docs/` | [Install](docs/INSTALL.md), [architecture](docs/ARCHITECTURE.md), [operations](docs/RUNBOOK.md), [host guard](docs/HOST-GUARD.md) |
+| `docs/` | [User guide](docs/USERGUIDE.md), [install](docs/INSTALL.md), [architecture](docs/ARCHITECTURE.md), [operations](docs/RUNBOOK.md), [design](docs/DESIGN.md), [sharing](docs/SHARING.md), [host guard](docs/HOST-GUARD.md) |
 
 ## Update and verify
 
 After `git pull`, clients re-run `./install.sh`; servers re-run `./install.sh --server` from their installed
-checkout. The server installer resolves the checkout's actual path, including `bw-tools/lanes`; no `~/lanes`
-clone is required. It preserves configured workspaces and existing agent sessions.
+checkout. npm installations update with `npx @vibelord/lanes@latest` (add `--server` on the host). After a server
+update, restart `lanes-statusd.service` (and `lanes-web`/`lanes-mobile` when their units or the pinned Zellij
+changed); existing views keep their layout until `lanes rebuild <device>`. `lanes hello` prints the server's
+version ([user guide](docs/USERGUIDE.md#update)). The server installer resolves the checkout's actual path,
+including `bw-tools/lanes`; no `~/lanes` clone is required. It preserves configured workspaces and existing agent
+sessions.
 
 ```sh
 ./install.sh --check                       # client connectivity

package/payload/lanes/VERSION

@@ -1 +1 @@
-1.0.3
+1.0.4

package/payload/lanes/docs/ARCHITECTURE.md

@@ -2,7 +2,8 @@
 
 Lanes has three parts: a Linux workspace host, long-running terminal sessions inside its containers, and
 views on desktop or phone. The host owns views and derived registries. The container owns each agent's
-terminal. Installing or closing a view does not end a lane.
+terminal. Installing or closing a view does not end a lane. For how to use it, see the [user guide](USERGUIDE.md);
+for operations, the [runbook](RUNBOOK.md).
 
 ## Source of truth and sync
 

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
 

package/payload/lanes/docs/RUNBOOK.md

@@ -1,9 +1,10 @@
 # lanes — runbook
 
 `lanes` is the host-level workspace server for a deployment's container terminals. The canonical source is
-`bw-tools/lanes`; [INSTALL.md](INSTALL.md) covers the full setup and [ARCHITECTURE.md](ARCHITECTURE.md) explains
-its parts. Run host commands as the workspace account. Deployment-specific incidents below retain their
-original names and measurements; substitute your account, containers and paths in operational commands.
+`bw-tools/lanes`; [INSTALL.md](INSTALL.md) covers the full setup, [ARCHITECTURE.md](ARCHITECTURE.md) explains
+its parts, and the [user guide](USERGUIDE.md) is the day-to-day reference for every surface, key and command.
+Run host commands as the workspace account. Deployment-specific incidents below retain their original names and
+measurements; substitute your account, containers and paths in operational commands.
 
 ## Daily use (client)
 
@@ -15,7 +16,7 @@ original names and measurements; substitute your account, containers and paths i
 | One lane, no multiplexer, native Ghostty scrollback | `lanes-launch lane <lane-id>` (ids: `lanes-launch ls`) |
 | Switch workspace | `Ctrl-Alt-←/→` (zellij tabs) |
 | Next / previous lane | `Ctrl-Alt-↓` / `Ctrl-Alt-↑` (works from inside the lane: `lanes next\|prev --focused` in a floating pane that closes at once points the FOCUSED viewport — the first one when the sidebar has the focus — at the next / previous lane of its workspace in registry order, wrapping; nothing is typed and the focus stays where it was; on a tab without a workspace, e.g. Host, it does nothing). In the sidebar `J` / `K` still step through the list as it is drawn |
-| Lock the view | `Ctrl-Alt-g` locks (every key reaches the lane; the mode ribbon shows LOCKED in on-accent-urgent) and unlocks. `Ctrl-g` is never bound: it always reaches the lane |
+| Lock the view | `Ctrl-Alt-g` locks (the lane gets every key except the `shared` chords that stay live while locked — the Ctrl-Alt arrows, `/`, `u`, `c`, `s`, PageUp/PageDown/End; the mode ribbon shows LOCKED in on-accent-urgent) and unlocks. `Ctrl-g` is never bound: it always reaches the lane |
 | Find a lane by name | `Ctrl-Alt-/`, type a few letters, `Enter` |
 | Browse the sidebar | click it (or `Ctrl-Alt-p` then `←`), `↑/↓` or `j/k`, `Enter`; selecting a lane focuses it again |
 | Go to the next lane that needs you | `Tab` in the sidebar opens the next lane in **Needs you** (`Shift-Tab` the previous), cycling from the lane this pane shows — or from the cursor lane when the shown one does not need you; ` nothing needs you` when the section is empty |