@vibelord/lanes 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibelord/lanes",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "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

@@ -139,16 +139,17 @@ The installer starts an empty catalog safely; it does not assume anyone's contai
 | Rename a lane | `R` in the sidebar (Enter saves, Esc cancels; arrows and Tab type nothing in the name, a click on the list cancels it first), or `lanes rename <lane-id> <name>` on the server; the lane id never changes, and your name wins over a `displayName` the repository's `terminals.json` declares |
 | Add a workspace (board) | `lanes workspaces add <id> --container <name> --repo /home/coder/<repo> [--title T]` on the server prints the catalog and manifest diff; add `--write` to apply, then `lanes sync` ([install](docs/INSTALL.md#2-configure-workspaces-and-editor-sync)) |
 | Onboard a user's container | `lanes onboard <login> --container <name> --workspace <id> --repo /home/coder/<repo>` on the server prints every step (board, contract, Claude and Codex hooks, Throttle attachment, canonical recipes, sync, doctor); add `--write` to apply them and keep a receipt ([install](docs/INSTALL.md#onboard-a-users-container)) |
-| Let an agent see and manage its lanes | The container's agents get the Lanes MCP server, `lane-mcp`, from `lanes install-container <name>` (on by default; `--no-mcp` leaves it out). `lanes_whoami`, `lanes_list`, `lanes_status` and `lanes_capture` read the lanes of that container. `lanes_register`, `lanes_rename`, `lanes_unregister` and `lanes_new` change a lane's declaration, shown on the boards within about 15 s. `lanes_send` types into a sibling lane, and `lanes_signal` reports the agent's own status. Ending, interrupting or attaching a lane stays yours ([architecture](docs/ARCHITECTURE.md#agent-api), [guide](docs/USERGUIDE.md#agent-tools-mcp)) |
+| Let an agent see and manage its lanes | The container's agents get the Lanes MCP server, `lane-mcp`, from `lanes install-container <name>` (on by default; `--no-mcp` leaves it out). `lanes_whoami`, `lanes_list`, `lanes_status` and `lanes_capture` read the lanes of that container. `lanes_register`, `lanes_rename`, `lanes_unregister` and `lanes_new` change a lane's declaration, shown on the boards within about 15 s. `lanes_send` types into a sibling lane, `lanes_signal` reports the agent's own status, and `lanes_publish` puts a file on the docs page (`lane publish <file>` in a shell). Ending, interrupting or attaching a lane stays yours ([architecture](docs/ARCHITECTURE.md#agent-api), [guide](docs/USERGUIDE.md#agent-tools-mcp)) |
 | 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). The queue holds still: each section keeps the order its lanes entered it, a lane moves up a section at once but down only after the new state has held 8 s (leaving Needs you) or 5 s (leaving Working or Done), so an agent that asks again within seconds of an answer does not jump; the Needs you and Working headers stay drawn, `(0)` included, and the cursor stays on its lane ([how](docs/ARCHITECTURE.md#attention-queue)) |
 | Read a sidebar row | `▌` cursor · agent glyph · `›` the lane this pane shows (`²`/`³`: shown in pane 2/3; `▲` pinned) · 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`: ` › close ‘name’ — y⏎ confirm · Esc cancel`; `y` arms (` — ⏎ confirm`), Enter closes; any other key cancels (typed text closes nothing unless it is `x`, `y`, Enter in a row) |
-| Every sidebar key | `?` replaces the list with the key sheet until the next key (that key only closes it): the short form of the [user guide's table](docs/USERGUIDE.md#the-sidebar), first `lanes <installed> · view <running>`, then companion keys on one line (`J K`, `Tab S-Tab`, `+ U`, `u z`, `p h`, `H o`, `r ?`), ending with Ctrl–Alt–L, the chord that brings the keyboard to the sidebar from a lane. The footer legend says ` ⏎ open · / find · x close · ? keys`; one prompt at a time, in one shape on the desktop and the phone (` › close ‘name’ — y⏎ confirm · Esc cancel`, ` › Rename: …█`, ` › Register as: …█` then ` › register ‘name’ — y⏎ confirm`) and a filter counts its matches (` /abc · 3 matches`). What an action says in the footer (` Closed sh`, ` Cancelled`, why it failed) stays 3 s or until your next action, not just until the next key. After an action — a close, rename, register, cancel, `Esc`, `r`, closing `?`, a click that opens no lane — the keyboard goes back to the lane, so what you type next reaches the lane, not the sidebar; a prompt, the filter and the armed upload strip keep it |
+| Every sidebar key | `?` replaces the list with the key sheet until the next key (that key only closes it): the short form of the [user guide's table](docs/USERGUIDE.md#the-sidebar), first `lanes <installed> · view <running>`, then companion keys on one line (`J K`, `Tab S-Tab`, `+ U d`, `u z`, `p h`, `H o`, `r ?`; `d` shows the cursor lane's docs link), ending with Ctrl–Alt–L, the chord that brings the keyboard to the sidebar from a lane. The footer legend says ` ⏎ open · / find · x close · ? keys`; one prompt at a time, in one shape on the desktop and the phone (` › close ‘name’ — y⏎ confirm · Esc cancel`, ` › Rename: …█`, ` › Register as: …█` then ` › register ‘name’ — y⏎ confirm`) and a filter counts its matches (` /abc · 3 matches`). What an action says in the footer (` Closed sh`, ` Cancelled`, why it failed) stays 3 s or until your next action, not just until the next key. After an action — a close, rename, register, cancel, `Esc`, `r`, closing `?`, a click that opens no lane — the keyboard goes back to the lane, so what you type next reaches the lane, not the sidebar; a prompt, the filter and the armed upload strip keep it |
 | Pin, hide | `p` pins the cursor lane (it leads its section, `▲`, and never falls below `⋮ N more`), `h` hides it, `o` shows the hidden lanes again (faint), `H` then `y` `Enter` hides the whole workspace — its tab closes, its lanes keep running. They are yours, not the device's: every device you own follows your profile on its next tick; a session under **Unregistered** is never hidden ([guide](docs/USERGUIDE.md#the-sidebar)) |
 | 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-launch <device> --notify 0` (or `lanes attach <device> --notify 0` on the server) silences it for that device, live; `LANES_NOTIFY=0` in the shell that creates a view session does the same for it, see the [user guide](docs/USERGUIDE.md#9-appearance)) |
 | 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)`), press `U` in the sidebar or Ctrl–Alt–U from anywhere in the tab, then drop anywhere on the window; or use `~/Lanes Uploads/<workspace>/`, or `lanes-upload <files>` |
+| See what an agent published, or upload from a phone | The Docs page, `https://<server>:8443/lanes-docs/`, open only to your own tailnet login: **More → Docs** on a phone or tablet, **Docs** in the laptop's Lanes bar, a ⌘/Ctrl-click on the sidebar's ` ↑ uploads · ▤ docs N` strip, or `d` on a lane for its own link. An agent publishes with `lanes_publish` (or `~/.lz/bin/lane publish <file>` in a lane's shell): Markdown with Mermaid diagrams rendered, HTML and SVG opened in a sandbox, any other file a download, each with a sha256 receipt; the page's drop area lands files in the workspace's `uploads/` with the same receipt. It answers nobody until the operator pins the Serve header check (`lanes enrol mode request`) ([user guide](docs/USERGUIDE.md#docs)) |
 | Phone view from a client | `lanes-launch web phone` in your own terminal: prepares `<your device>-phone` (phone layout), makes Tailscale Serve forward private HTTPS 8443 when the mapping is missing, prints the private URL with a QR code of it and a login token; scan the code or open the URL in Safari. `sh install/enable-phone.sh --host lanes` is the older one-shot for the device `phone` ([guide](docs/USERGUIDE.md#phone-safari-home-screen)) |
 | Laptop or tablet browser view | `lanes-launch web laptop` (`<your device>-web`, desktop layout) or `lanes-launch web <device> [--desktop\|--mobile]` from a client; on the server `lanes web <device> [--desktop\|--mobile] [--viewports N] [--token \| --print-only]` (prepares the view, enables the loopback web services, adds the Tailscale Serve `https:8443` mapping when missing, prints the private URL) ([guide](docs/INSTALL.md#laptop-and-tablet-browser)) |
 | Web login tokens | `lanes token list` (each token with the device it was created for), `lanes token revoke <device>`, `lanes token revoke-all --yes` ([runbook](docs/RUNBOOK.md#login-tokens)) |
@@ -190,7 +191,7 @@ long (agent since-time, or last output). Glyph then ASCII twin (`LANES_GLYPHS=as
 | --- | --- | --- | --- | --- |
 | `◆` `!` needs approval | `◇` `?` needs input | `●` `*` output in the last 20 s | `○` `o` quiet | `▌` `\|` cursor · `›` `=` viewing · `²` `2` / `³` `3` shown in viewport 2/3 · `▲` `^` pinned |
 | `▸` `>` working | `✓` `v` done (until viewed) | `–` `-` no session right now | `!` `!` pane dead | `·` `.` viewers · `…` `~` clipped (end of a name) or on its way — closing, registering, a new shell (column 3, dim) · `×` `x` close |
-| `✗` `X` errored | `_` `_` shell · `·` `.` idle | `✗` `x` container down | `?` `?` not observed · `·` `.` helper | `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now |
+| `✗` `X` errored | `_` `_` shell · `·` `.` idle | `✗` `x` container down | `?` `?` not observed · `·` `.` helper | `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now · `▤` `#` docs |
 
 Column 34 is one tail cell: `?` stale (last known state shown) > `⚠` `!` starving > `↓` `v` downgraded > `$` mostly
 paid. Colour is reinforcement, never the only signal; `LANES_COLOR=none` keeps every glyph. Full tables, tokens and

package/payload/lanes/VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

package/payload/lanes/bin/lanes

@@ -149,7 +149,14 @@
   lanes upload <ws> | --active <device> [--paste]
                                  read a tar stream on stdin into that board's uploads/ folder (the same folder Cursor
                                  users drop files into); prints the in-container paths. --paste also types the path(s)
-                                 into the lane that device is looking at. `lanes workspaces` lists board ids.
+                                 into the lane that device is looking at. `lanes workspaces` lists board ids. Each file
+                                 also goes to the docs store with a sha256 receipt (stderr `# docs:` lines), for the
+                                 login that owns the device; the Docs page's upload (POST /up) lands the same way.
+  lanes docs push <id>           the hook for pushing one docs-store document to the data service's publication surface
+                                 — NOT BUILT: it prints the document's receipt (receipt.json: id, sha256, bytes, url,
+                                 at; looked up by id in every login's store, for the operator), says `not configured`
+                                 on stderr and exits 2. It sends nothing and writes nothing. Exit 1: no document with
+                                 that id, an id that is not one, or another argument (this usage)
   lanes cursor-sync [ws…] [--write] [--diff] [--canonicalize] [--identity]
                                  make Cursor/VS Code terminals open exactly the board's lanes through `lane open`
                                  (dry-run by default: prints the git-style diff; --write applies with a backup).
@@ -170,7 +177,7 @@
                                  current ✓ · statusd runs 1.1.0 ✗ · enrold notify ✓` — this tree's VERSION and the npm
                                  stamp's commit, the tree, whether ~/.local/share/lanes/current names it (✗ with the
                                  tree it does name), then the tree each long-running process recorded at its last start
-                                 (~/.local/state/lanes/run/<name>.tree: statusd, enrold, notify, economy, studio_host,
+                                 (~/.local/state/lanes/run/<name>.tree: statusd, enrold, docsd, notify, economy, studio_host,
                                  the newest sidebar), ✗ for one that is not the current tree (`runs 1.1.0 ✗`) or that
                                  started before its tree's code (VERSION, bin/, libexec/) last changed — a checkout
                                  updated in place by `git pull` keeps its path (`started before its tree changed ✗`) —
@@ -269,6 +276,11 @@
                                  lanes-web / lanes-mobile units (⚠ not enabled, ✗ enabled but not running), the login-token
                                  database the running lanes-web reads (✗ when it is not the one `lanes token` uses) and the
                                  Tailscale Serve https:8443 mapping (⚠ not checked on a host without a Tailscale name);
+                                 the docs service: lanes-docsd enabled, active and answering on its loopback port (⚠
+                                 not enabled, ✗ enabled but not running or not answering), the pin gate (⚠ until `lanes
+                                 enrol mode request`), the store (documents, bytes, docs.log), the Mermaid pin (⚠ not
+                                 installed: install/enable-docs.sh; ✗ not the pinned build) and the age switch (✗ set
+                                 without an age binary);
                                  then the release that runs: ~/.local/share/lanes/current names a tree whose VERSION
                                  agrees with its pkg/<version> name and npm stamp and that this lanes runs (⚠ without the
                                  link: the rest compares with this tree); every lanes process that runs now has a run
@@ -777,9 +789,18 @@ def hold_sessions(stack, timeout, doing):
     return None
 
 
+# The web front's own path roots (web/Caddyfile): a view session is served at /<device>, so a device of one of these
+# names would sit on a route a service owns — the enrolment service (/enrol/*), the docs service (/lanes-docs/*) and
+# the shell's assets (/lanes-assets/*). Compared casefolded: Caddy's path matcher ignores case.
+RESERVED_DEVICES = ('enrol', 'lanes-assets', 'lanes-docs')
+
+
 def device_name(value):
     if not L.IDENT.match(value or '') or len(value) > 32:
         raise L.LanesError('Invalid device name')
+    if value.casefold() in RESERVED_DEVICES:
+        raise L.LanesError(f'Invalid device name: {value} is a path the web front reserves '
+                           f'({", ".join(RESERVED_DEVICES)})')
     return value
 
 
@@ -2129,8 +2150,12 @@ class UploadReader:
 
 
 def cmd_upload(args):
+    """`lanes upload <workspace> | --active <device> [--device D] [--paste] [--request R]`: a tar stream on stdin into
+    the workspace's `uploads/` AND the docs store (W10 W5, libexec/uploads.py receive_tar): each file lands as it always
+    did — same folder, `-1` collision suffix, `.git/info/exclude` line — and gets a sha256 receipt, `source` ssh, for
+    the login that owns the asking device (users.login_for; none: a docs.log `no-owner` line), under the lane its view
+    shows (uploads.upload_lane). stdout and `<request>.done` stay the landed in-container paths, one per line."""
     import shlex
-    import tarfile
     registry = L.load_registry()
     device = args[args.index('--active') + 1] if '--active' in args else None
     paste_device = args[args.index('--device') + 1] if '--device' in args else device
@@ -2151,34 +2176,20 @@ def cmd_upload(args):
             raise L.LanesError(f'unknown board: {names[0]} (see `lanes workspaces`)')
     else:
         raise L.LanesError('usage: lanes upload <workspace> | --active <device>  [--paste]   (tar stream on stdin)')
-    folder = next((lane.get('folder') for lane in workspace['lanes'] if lane.get('folder')), None) or workspace['cwd']
-    info = registry['containers'].get(workspace['container']) or {}
-    root = L.host_path(info, folder)
-    uploads = root / 'uploads'
-    uploads.mkdir(exist_ok=True)
-    # Keep uploads out of commits without touching a tracked .gitignore: the repository-local exclude file.
-    exclude = root / '.git' / 'info' / 'exclude'
-    # check-ignore: 0 = ignored, 1 = not ignored; an error or no answer (None) is not a reason to append.
-    if (root / '.git').is_dir() and L.run_bounded(['git', '-C', str(root), 'check-ignore', '-q', 'uploads/x'], 10)[0] == 1:
-        exclude.parent.mkdir(exist_ok=True)
-        with open(exclude, 'a') as handle:
-            handle.write('\n# lanes upload: local intake folder, never committed\nuploads/\n')
-    staging = uploads / f'.incoming-{os.getpid()}'
-    staging.mkdir()
-    landed = []
+    uploads_lib, users = libexec_module('uploads'), libexec_module('users')
+    folder, home, parts = uploads_lib.landing(registry, workspace)
+    # The view that asked (a suffixed view's sidecar, else the device named): whose upload it is, and whose lane.
+    view_device = paste_target(spool, request, paste_device) if spool else paste_device
+    login = users.login_for(view_device) if view_device else None
+    lane = uploads_lib.upload_lane(workspace, view_device)
+    uploads = uploads_lib.open_uploads(home, parts)
     try:
         stream = UploadReader(sys.stdin.buffer, spool / f'{request}.progress' if spool else None)
-        with tarfile.open(fileobj=stream, mode='r|') as archive:
-            archive.extractall(staging, filter='data')  # regular files/dirs only, no absolute paths, no links out
-        for entry in sorted(staging.iterdir()):
-            final, n = uploads / entry.name, 1
-            while final.exists():  # never overwrite an earlier upload
-                final = uploads / f'{entry.stem}-{n}{entry.suffix}'
-                n += 1
-            entry.rename(final)
-            landed.append(f"{folder}/uploads/{final.name}")
+        landed = [f'{folder}/uploads/{name}' for name in uploads_lib.receive_tar(
+            stream, uploads, login=login, ws=workspace['id'], lane=lane,
+            say=lambda line: print(line, file=sys.stderr, flush=True))]
     finally:
-        shutil.rmtree(staging, ignore_errors=True)
+        os.close(uploads)
     if not landed:
         # The helper reports the client-side cause (eg. macOS denied Downloads). Publishing a generic .err here
         # races that report: the sidebar consumes it and loses the useful error before the helper can send it.
@@ -2187,7 +2198,6 @@ def cmd_upload(args):
         print(path)
     if '--paste' in args and paste_device:
         # The result files (.done / .err) stay in the base spool, where the asking sidebar looks for them.
-        view_device = paste_target(spool, request, paste_device) if spool else paste_device
         shown = type_into_lane(registry, device_name(view_device), workspace, ' '.join(shlex.quote(p) for p in landed) + ' ')
         print(f'# typed into lane: {shown}' if shown else '# could not type into the lane (not a tmux lane?)', file=sys.stderr)
     if spool:
@@ -2195,6 +2205,32 @@ def cmd_upload(args):
     return 0
 
 
+DOCS_USAGE = 'usage: lanes docs push <id>'
+# What a publication target needs and does not have yet: the data service's token-authenticated publication surface
+# (plan W10 "Operator gates" 3 — decided once that surface is stable). Until then `lanes docs push` is the hook only.
+DOCS_PUSH_UNCONFIGURED = ('lanes docs push: not configured — no publication target exists yet (the data service\'s '
+                          'publication surface is not built; plan W10, operator gate 3): nothing was sent')
+
+
+def cmd_docs(args):
+    """`lanes docs push <id>` (docs cockpit W10 W9, LNS-110): the hook for the data service's publication surface — a
+    STUB, not built. It looks the document up in every login's docs store (docs_store.operator_receipt: the operator is
+    the account the store belongs to, so no login's visibility applies), prints its receipt.json on stdout
+    (DM-LANES-DOCS-RECEIPT, as stored: indent 2), says `not configured` on stderr and returns 2. Nothing is sent,
+    written or logged. No such document, an id that is not one (docs_store.ID_RE) or any other argument: LanesError,
+    exit 1."""
+    if len(args) != 2 or args[0] != 'push':
+        raise L.LanesError(DOCS_USAGE)
+    D = libexec_module('docs_store')
+    found = D.operator_receipt(args[1])
+    if found is None:
+        raise L.LanesError(f'docs push: no document {args[1]} in the docs store ({D.root()})')
+    _meta, receipt = found
+    print(json.dumps(receipt, indent=2, ensure_ascii=False))
+    print(DOCS_PUSH_UNCONFIGURED, file=sys.stderr)
+    return 2
+
+
 def resolve_device(name, args):
     """`coder-launch worlds` style: a board id given where a device is expected means "my default device"."""
     try:
@@ -2768,7 +2804,7 @@ def cmd_hello(args):
 
 # The record_tree names, in the order `lanes version` lists them: statusd first (every view's status comes from it),
 # then the services, then the newest sidebar. A name not listed (a newer tree's process) follows, sorted.
-RUN_ORDER = ('statusd', 'enrold', 'notify', 'economy', 'studio_host', 'sidebar')
+RUN_ORDER = ('statusd', 'enrold', 'docsd', 'notify', 'economy', 'studio_host', 'sidebar')
 VERSION_SCHEMA = 'lanes.version/1'
 COMMIT_RE = re.compile(r'([0-9a-f]{7})[0-9a-f]{0,33}(-dirty)?')   # scripts/build-payload.mjs: rev-parse HEAD [-dirty]
 # A tree's code, as far as a recorded process runs it: VERSION and the regular files directly in these folders (every
@@ -3919,6 +3955,25 @@ def cmd_device(args):
     return 0
 
 
+def unit_properties(units):
+    """One bounded `systemctl --user show` of `units` (Id, LoadState, ActiveState, UnitFileState, MainPID) ->
+    ({unit: {property: value}}, None), or (None, why) when systemctl did not answer or failed. Read-only."""
+    argv = ['systemctl', '--user', 'show', '-p', 'Id', '-p', 'LoadState', '-p', 'ActiveState', '-p', 'UnitFileState',
+            '-p', 'MainPID', *units]
+    rc, out, err = L.run_bounded(argv, 10, env=clean_env())
+    if rc != 0:
+        return None, 'did not answer in 10 s' if rc is None else err.strip() or f'exit {rc}'
+    found = {}
+    for block in out.strip().split('\n\n'):
+        props = dict(line.partition('=')[::2] for line in block.splitlines() if '=' in line)
+        found[props.get('Id', '')] = props
+    return found, None
+
+
+def unit_enabled(props):
+    return props.get('UnitFileState', '').startswith(('enabled', 'linked', 'alias'))
+
+
 def web_doctor():
     """`lanes doctor`'s browser/phone lines -> [(mark, text)], mark ✓ | ⚠ | ✗ (LNS-50). One bounded
     `systemctl --user show` for both web units, a read of the running lanes-web's environment, `tailscale status --json`
@@ -3932,20 +3987,14 @@ def web_doctor():
     if not shutil.which('systemctl'):
         lines.append(('⚠', 'web units not checked — no systemctl on this host (`lanes web` needs systemd user services)'))
     else:
-        argv = ['systemctl', '--user', 'show', '-p', 'Id', '-p', 'LoadState', '-p', 'ActiveState', '-p', 'UnitFileState',
-                '-p', 'MainPID', *WEB_UNITS]
-        rc, out, err = L.run_bounded(argv, 10, env=clean_env())
-        if rc != 0:
-            lines.append(('✗', f"web units NOT checked — systemctl --user {'did not answer in 10 s' if rc is None else err.strip() or f'exit {rc}'}"))
+        units, why = unit_properties(WEB_UNITS)
+        if units is None:
+            lines.append(('✗', f'web units NOT checked — systemctl --user {why}'))
         else:
-            units = {}
-            for block in out.strip().split('\n\n'):
-                props = dict(line.partition('=')[::2] for line in block.splitlines() if '=' in line)
-                units[props.get('Id', '')] = props
             for unit in WEB_UNITS:
                 props = units.get(unit, {})
                 active = props.get('ActiveState') or 'unknown'
-                enabled = props.get('UnitFileState', '').startswith(('enabled', 'linked', 'alias'))
+                enabled = unit_enabled(props)
                 enabled_any = enabled_any or enabled
                 if enabled and active == 'active':
                     lines.append(('✓', f'{unit} active'))
@@ -3990,6 +4039,207 @@ def web_doctor():
     return lines
 
 
+# ------------------------------------------------------------------ doctor: the docs service (W10 W8, LNS-109)
+DOCS_UNIT = 'lanes-docsd.service'
+DOCS_PROBE_S = 2                    # seconds the loopback connect to lanes-docsd may take
+ENABLE_DOCS = 'install/enable-docs.sh'
+
+
+def home_shown(path, home=None):
+    """`path` as `~/…` under the home, else as it is (plain)."""
+    try:
+        return plain(f'~/{Path(path).relative_to(Path(home) if home is not None else Path.home())}')
+    except (ValueError, KeyError, RuntimeError):
+        return plain(path)
+
+
+def byte_size(count):
+    """A size for a person: `812 B`, `3.4 KiB`, `17.0 MiB`, `1.2 GiB`."""
+    if count < 1024:
+        return f'{count} B'
+    for unit in ('KiB', 'MiB', 'GiB'):
+        count /= 1024
+        if count < 1024 or unit == 'GiB':
+            return f'{count:.1f} {unit}'
+
+
+def tree_bytes(root):
+    """(regular files, their bytes) under the directory `root`, never through a link (a link at `root` itself counts
+    nothing); (0, 0) when it does not exist. Unreadable entries are skipped."""
+    if os.path.islink(root):
+        return 0, 0
+    files = total = 0
+    stack = [os.fspath(root)]
+    while stack:
+        try:
+            with os.scandir(stack.pop()) as entries:
+                for entry in entries:
+                    try:
+                        if entry.is_dir(follow_symlinks=False):
+                            stack.append(entry.path)
+                        elif entry.is_file(follow_symlinks=False):
+                            files, total = files + 1, total + entry.stat(follow_symlinks=False).st_size
+                    except OSError:
+                        continue
+        except OSError:
+            continue
+    return files, total
+
+
+def docs_port():
+    """(port, None): the port lanes-docsd listens on — LANES_DOCS_PORT from its drop-in (docs_store.unit_environment,
+    the files `lanes upload` reads too), else docsd.DEFAULT_PORT — or (None, why) for a setting that is not a port."""
+    value = libexec_module('docs_store').unit_environment().get('LANES_DOCS_PORT') or ''
+    if not value:
+        return libexec_module('docsd').DEFAULT_PORT, None
+    if value.isdigit() and 0 < int(value) <= 65535:
+        return int(value), None
+    return None, f'LANES_DOCS_PORT={plain(value)[:20]} in its drop-in is not a port number'
+
+
+def port_answers(port, timeout=DOCS_PROBE_S):
+    """Whether 127.0.0.1:<port> accepts a TCP connection within `timeout` s. It connects and closes without sending a
+    byte, so lanes-docsd answers nothing and writes no docs.log line (its handler reads an empty request line)."""
+    import socket as sockets
+    try:
+        with sockets.create_connection(('127.0.0.1', port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def docs_unit_line(probe):
+    restart = f'journalctl --user -u {DOCS_UNIT}; systemctl --user restart {DOCS_UNIT}'
+    if not shutil.which('systemctl'):
+        return ('⚠', f'{DOCS_UNIT} not checked — no systemctl on this host')
+    units, why = unit_properties([DOCS_UNIT])
+    if units is None:
+        return ('✗', f'{DOCS_UNIT} NOT checked — systemctl --user {why}')
+    props = units.get(DOCS_UNIT, {})
+    active, enabled = props.get('ActiveState') or 'unknown', unit_enabled(props)
+    if active != 'active':
+        if enabled:
+            return ('✗', f'{DOCS_UNIT} enabled but {plain(active)} — {restart}')
+        return ('⚠', f'{DOCS_UNIT} not enabled, so there is no docs page — the full server install enables it (an '
+                     f'update with --update-only enables nothing): systemctl --user enable --now {DOCS_UNIT}')
+    port, why = docs_port()
+    if port is None:
+        return ('✗', f'{DOCS_UNIT} active, but {why} — fix it with systemctl --user edit {DOCS_UNIT}')
+    where = f'127.0.0.1:{port}'
+    if not probe(port):
+        return ('✗', f'{DOCS_UNIT} active, but {where} does not answer — {restart}')
+    if not enabled:
+        return ('⚠', f'{DOCS_UNIT} active on {where} but not enabled: a reboot loses it — systemctl --user enable '
+                     f'{DOCS_UNIT}')
+    return ('✓', f'{DOCS_UNIT} active, answering on {where}')
+
+
+def docs_pin_line():
+    """The pin gate as docsd reads it on every request (enrold.read_mode): an operator gate, so never a ✗."""
+    mode, problem = libexec_module('enrold').read_mode()
+    if mode == 'request':
+        return ('✓', 'docs: pinned — lanes-docsd answers members through Tailscale Serve (lanes enrol mode request)')
+    said = problem or ('pinned invite only' if mode == 'invite' else 'unpinned: auto')
+    return ('⚠', f'docs: refuses until the Serve header check is pinned ({plain(said)}): every request is 403 '
+                 'not-pinned — run the check (RUNBOOK "Enrolment service", Operator verification), then lanes enrol '
+                 'mode request (RUNBOOK "Docs service")')
+
+
+def docs_store_line(home=None):
+    D = libexec_module('docs_store')
+    counts = D.read_counts()
+    documents = sum(entry['n'] for entry in counts.values())
+    _files, size = tree_bytes(D.root())
+    try:
+        log = f'docs.log {byte_size(D.log_path().lstat().st_size)}'
+    except FileNotFoundError:
+        log = 'no docs.log yet'
+    except OSError as error:
+        log = f'docs.log not readable ({error.strerror or error})'
+    return ('', f"docs store: {documents} document{'' if documents == 1 else 's'} in {len(counts)} "
+                f"lane{'' if len(counts) == 1 else 's'} (counts.json), {byte_size(size)} under "
+                f'{home_shown(D.root(), home)}; {log}')
+
+
+def docs_mermaid_line(home=None):
+    """holders.lock's opt-in `mermaid` pin against the file install/enable-docs.sh installs: the member digest, read
+    without following a link or blocking on a FIFO."""
+    import hashlib
+    SH = libexec_module('studio_host')
+    script = f"sh {home_shown(L.CURRENT, home)}/{ENABLE_DOCS}"
+    try:
+        pin = SH.parse_lock((L.REPO / 'holders.lock').read_text()).get('mermaid')
+        why = 'no mermaid line' if pin is None else '' if pin.opt_in else 'the mermaid line is not an opt-in pin'
+    except (OSError, ValueError, SH.Refusal) as error:
+        pin, why = None, str(error)
+    if why:
+        return ('✗', f'docs: Mermaid not checked — {L.REPO / "holders.lock"}: {plain(why)}')
+    target = L.SHARE / 'vendor' / f'mermaid-{pin.version}.min.js'
+    shown, version = home_shown(target, home), plain(pin.version)
+    try:
+        fd = os.open(target, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, 'O_CLOEXEC', 0))
+    except FileNotFoundError:
+        return ('⚠', f'docs: Mermaid {version} not installed ({shown}), so diagrams show as source — run {script} '
+                     '(every server install and update runs it)')
+    except OSError as error:
+        return ('✗', f'docs: Mermaid {version} refused — {shown} is not a regular file '
+                     f'({error.strerror or error}) — {script} replaces it from a verified download')
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            return ('✗', f'docs: Mermaid {version} refused — {shown} is not a regular file — {script} replaces it '
+                         'from a verified download')
+        digest = hashlib.sha256()
+        for chunk in iter(lambda: os.read(fd, 1 << 20), b''):
+            digest.update(chunk)
+    finally:
+        os.close(fd)
+    actual = digest.hexdigest()
+    if actual != pin.binary_sha256:
+        return ('✗', f'docs: Mermaid {version} refused — {shown} is not the pinned build (sha256 {actual[:12]}…, '
+                     f'holders.lock {pin.binary_sha256[:12]}…): browsers refuse it by its integrity, so diagrams '
+                     f'show as source — {script} replaces it from a verified download')
+    return ('✓', f'docs: Mermaid {version} pinned ({shown}, sha256 {actual[:12]}…)')
+
+
+def docs_age_line():
+    """The store's encryption switch (docs_store.age_settings: this environment, else lanes-docsd's drop-in, as
+    `lanes upload` reads it) and the `age` on this PATH. The recipient is never printed."""
+    D = libexec_module('docs_store')
+    binary = D.age_binary()
+    has = f'age at {plain(binary)}' if binary else 'no age binary on PATH'
+    try:
+        recipient, identity = D.age_settings()
+    except D.DocsError as error:
+        return ('✗', f'docs: age encryption NOT usable — {error}: every upload and publish fails until it is fixed '
+                     f'({home_shown(D.dropin_dir())})')
+    if recipient is None:
+        return ('', f'docs: age encryption off (LANES_DOCS_AGE_RECIPIENT unset; {has})')
+    if binary is None:
+        return ('✗', 'docs: age encryption on (LANES_DOCS_AGE_RECIPIENT set) but there is no age binary on PATH: every '
+                     'upload and publish fails (encrypt-failed) — install age or remove the setting (the server '
+                     'install refuses it)')
+    opens = ('lanes-docsd opens them with LANES_DOCS_AGE_IDENTITY' if identity else
+             'no LANES_DOCS_AGE_IDENTITY, so their downloads answer 409 encrypted')
+    return ('✓', f'docs: age encryption on — new store copies are age output ({has}); {opens}')
+
+
+def docs_doctor(home=None, probe=None):
+    """`lanes doctor`'s docs lines (W10 W8, LNS-109) -> [(mark, text)], mark ✓ | ✗ | ⚠ | '' (information), in this
+    order; read-only (one bounded `systemctl --user show`, one loopback connect, file reads):
+      lanes-docsd.service — enabled, active and its loopback port (docs_port) accepting a connection ✓ · enabled but not
+        active, or active while its port refuses ✗ · active but not enabled ⚠ (a reboot loses it) · not enabled ⚠ (the
+        full server install enables it; an update with --update-only enables nothing) · systemctl silent ✗ · no
+        systemctl ⚠. `probe` (port -> bool) stands in for port_answers.
+      the pin gate — `request` ✓ `docs: pinned` · else ⚠ `docs: refuses until the Serve header check is pinned`
+      the store — information: documents and lanes from counts.json, the bytes under docs/, docs.log's size
+      the Mermaid pin — the pinned member digest ✓ · absent ⚠ (run install/enable-docs.sh) · another digest or not a
+        regular file ✗ (refused: browsers refuse it by its integrity) · no valid pin ✗
+      the `age` switch — unset: information · set with an `age` on PATH ✓ · set without one, or no recipient ✗"""
+    home = Path(home) if home is not None else Path.home()
+    return [docs_unit_line(port_answers if probe is None else probe), docs_pin_line(), docs_store_line(home),
+            docs_mermaid_line(home), docs_age_line()]
+
+
 # ------------------------------------------------------------------ doctor: the release that runs (W9 V3, LNS-85)
 # `lanes version` says which tree each process last started from; doctor judges it, with the reference `lanes version`
 # uses (the tree the `current` link names; this tree when there is none). A run record outlives its process, so only a
@@ -4004,8 +4254,8 @@ def web_doctor():
 # <tree>/libexec/sidebar.py …`. Anything else that names the file — an editor, a pager, a grep, the script run by
 # hand another way — and a one-shot that never records (RUN_ONESHOTS) is not that daemon (DEF-1785). studio_host
 # records a oneshot step (install/enable-studio-host.sh), never a running process.
-RUN_SCRIPTS = {'statusd': 'statusd.py', 'enrold': 'enrold.py', 'notify': 'notify.py', 'economy': 'economy_poll.py',
-               'sidebar': 'sidebar.py'}
+RUN_SCRIPTS = {'statusd': 'statusd.py', 'enrold': 'enrold.py', 'docsd': 'docsd.py', 'notify': 'notify.py',
+               'economy': 'economy_poll.py', 'sidebar': 'sidebar.py'}
 RUN_INTERPRETER = re.compile(r'python3(?:\.\d+)?')   # argv[0]'s name, by path or not: python3, a versioned python3.N
 RUN_FLAGS = ['-S', '-E']                             # the interpreter flags of every launch, in this order
 # The arguments that make a run a one-shot that never records, as each record_tree comment names them. statusd reads
@@ -4013,8 +4263,8 @@ RUN_FLAGS = ['-S', '-E']                             # the interpreter flags of
 # anywhere and by any prefix it can tell apart (`--dry`; none of these prefixes another option of its script).
 RUN_ONESHOTS = {'statusd': ('--once',), 'notify': ('--test',), 'economy': ('--once', '--dry-run')}
 RUN_FIRST_ARGUMENT = {'statusd'}
-RUN_UNITS = {'statusd': 'lanes-statusd.service', 'enrold': 'lanes-enrold.service', 'notify': 'lanes-notify.service',
-             'economy': 'lanes-economy.service'}   # what restarts each daemon; a sidebar restarts with its view
+RUN_UNITS = {'statusd': 'lanes-statusd.service', 'enrold': 'lanes-enrold.service', 'docsd': 'lanes-docsd.service',
+             'notify': 'lanes-notify.service', 'economy': 'lanes-economy.service'}   # what restarts each daemon; a sidebar restarts with its view
 LAYOUT_COMMAND = re.compile(r'command=("(?:[^"\\]|\\.)*")')     # q(): a JSON string
 LAYOUT_FILES = L.LAYOUT_FILES                                   # the tree files a generated layout runs
 UNIT_ENTRY = re.compile(r'"@REPO@/([^"]+)"')                    # a unit template's tree file (install/services.py)
@@ -4370,6 +4620,12 @@ def cmd_doctor(_args):
             print(f'⚠ {text}')
         else:
             check(mark == '✓', text)
+    # The docs service (W10 W8, LNS-109): lanes-docsd and its port, the pin gate, the store, the Mermaid pin, `age`.
+    for mark, text in docs_doctor():
+        if mark in ('⚠', ''):
+            print(f'{mark or " "} {text}')
+        else:
+            check(mark == '✓', text)
     # The release that runs (W9 V3): `current`, the run records against the one process-table sweep above, the
     # device layouts, the units.
     for mark, text in release_doctor(table if rc == 0 else None):
@@ -5053,7 +5309,7 @@ COMMANDS = {'rebuilt': cmd_rebuilt, 'hello': cmd_hello, 'client-config': cmd_cli
             'sidebar-key': cmd_sidebar_key, 'studio-host': cmd_studio_host,
             'keys': cmd_keys, 'invite': cmd_invite, 'enrol': cmd_enrol, 'offboard': cmd_offboard,
             'token': cmd_token, 'onboard': cmd_onboard, 'user': cmd_user, 'lane': cmd_lane, 'here': cmd_here,
-            'version': cmd_version, 'update': cmd_update}
+            'version': cmd_version, 'update': cmd_update, 'docs': cmd_docs}
 
 if __name__ == '__main__':
     if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:

package/payload/lanes/container/lane

@@ -23,6 +23,12 @@ a `holder: tmux` lane through its exact socket and session; any other id is a zm
                               hook sidecar says the agent is `working` unless --force
   lane gc --sockets           unlink this container's tmux socket files that tmux is refused on (ECONNREFUSED: no
                               server listens); prints each unlinked path. A live, empty or silent server keeps its file
+  lane publish <file> [--title T] [--for <login>] [--kind md|html|svg|file]
+                              put the file on the Lanes docs page from the lane this runs in ($LANE_ID, else the tmux
+                              pane): writes ~/.lz/state/publish/<lane>/<id>.json (the file's container path, hashed
+                              once) and prints {id, …, picked_up_by, expected_within_s} as JSON; the host's lanes-docsd
+                              takes it within ~5 s and writes <id>.receipt.json beside it (kind from the extension when
+                              --kind is left out; the file must be under /home/coder, at most 32 MiB)
   lane mcp install [--agent claude|codex|all] [--write]
                               add the Lanes MCP server (~/.lz/bin/lane-mcp) to ~/.claude.json (mcpServers.lanes) and
                               ~/.codex/config.toml ([mcp_servers.lanes], with env_vars passing LANE_ID, LANE_WS, TMUX
@@ -574,8 +580,43 @@ def cmd_mcp(args):
     sys.exit(1 if refused else 0)
 
 
+PUBLISH_USAGE = 'usage: lane publish <file> [--title T] [--for <login>] [--kind md|html|svg|file]'
+
+
+def cmd_publish(args):
+    """`lane publish` (plan W10 W4): lane_core.publish from the lane this process runs in (lane_core.whoami: $LANE_ID,
+    else the tmux pane) for the file named relative to the working directory. Prints the answer as JSON on stdout
+    (what lanes_publish answers) and one line for a person on stderr. A refusal is one stderr line, exit 1."""
+    options, rest, path = {}, list(args), None
+    while rest:
+        word = rest.pop(0)
+        if word in ('--title', '--for', '--kind'):
+            if not rest or word in options:
+                sys.exit(PUBLISH_USAGE)
+            options[word] = rest.pop(0)
+        elif word.startswith('--') or path is not None:
+            sys.exit(PUBLISH_USAGE)
+        else:
+            path = word
+    if path is None:
+        sys.exit(PUBLISH_USAGE)
+    found = C.whoami(ROOT, os.environ)
+    if not found['lane']:
+        sys.exit(f"lane publish: {found.get('why') or 'not inside a lane'}")
+    try:
+        out = C.publish(ROOT, Path(os.environ.get('HOME') or Path.home()), os.path.abspath(path), found['lane'],
+                        title=options.get('--title'), for_login=options.get('--for'), kind=options.get('--kind'))
+    except C.LaneError as error:
+        sys.exit(f'lane publish: {error}')
+    out.update(picked_up_by=C.PUBLISH_PICKUP, expected_within_s=C.PUBLISH_LATENCY_S)
+    print(json.dumps(out, ensure_ascii=False, indent=1))
+    sys.stderr.write(f"lane publish: {out['path']} ({out['kind']}, {out['bytes']} bytes) -> request {out['id']} of "
+                     f"{out['lane']}; {C.PUBLISH_PICKUP} takes it within ~{C.PUBLISH_LATENCY_S} s and answers in "
+                     f"{out['receipt']}\n")
+
+
 COMMANDS = {'new': cmd_new, 'open': cmd_open, 'attach': cmd_attach, 'send': cmd_send, 'capture': cmd_capture, 'ls': cmd_ls,
-            'status': cmd_status, 'kill': cmd_kill, 'gc': cmd_gc, 'mcp': cmd_mcp}
+            'status': cmd_status, 'kill': cmd_kill, 'gc': cmd_gc, 'mcp': cmd_mcp, 'publish': cmd_publish}
 
 if __name__ == '__main__':
     if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS: