@vibelord/lanes 1.2.0 → 1.5.0

package/payload/lanes/bin/lanes

@@ -82,12 +82,19 @@
                                  is gone, its board is hidden). Asked for, never automatic: `lanes-launch here` runs it
                                  for the client's own device
   lanes onboard <login> --container <name> [--workspace <id> --repo <path> [--title T]]
-                [--write] [--no-mcp]
+                [--write] [--no-mcp] [--step kimi-notify|grok-build]...
                                  provision a user's container and agents in one verb. Dry-run by default (every diff and
                                  command it would run). It first checks the container (read-only docker inspect: an
                                  unknown one stops the run before anything is written); --write then applies, in order:
                                  the board (`workspaces add`, when --workspace is given), install-container,
-                                 `hooks install --write` for claude and codex, `throttle setup --install-clients`
+                                 (--step grok-build first: see below) `hooks install --write` for claude and codex,
+                                 then for kimi, grok (Grok Build) and
+                                 grok-cli where that harness's home (~/.kimi-code, ~/.grok-build, ~/.grok) is in the
+                                 container (else `skipped`); two steps run only when named: --step kimi-notify (Kimi's
+                                 tui.toml notification_condition = "always": the bell on every turn end) and --step
+                                 grok-build (Grok Build installed under GROK_HOME=~/.grok-build by the stable-channel
+                                 recipe, never ~/.grok; the channel publishes no checksum, so the receipt records the
+                                 download's size and sha256 as unverified), `throttle setup --install-clients`
                                  inside the container as uid 1000 when it has a CONFIGURED throttle (else the manual
                                  step is printed: a first setup needs a person on a terminal; the laptop-pool step too
                                  when site.conf names LANES_THROTTLE_REMOTE_URL), sync,
@@ -149,7 +156,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 +184,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 ✗`) —
@@ -185,15 +199,34 @@
                                  (additive; installs no agent hook and no editor: lane-edit runs $LANES_EDITOR or the
                                  first of micro hx nvim vim vi there) and add the Lanes MCP server to the agents'
                                  configs: mcpServers.lanes in ~/.claude.json and [mcp_servers.lanes] in
-                                 ~/.codex/config.toml, both starting /home/coder/.lz/bin/lane-mcp — only where missing,
+                                 ~/.codex/config.toml, and where Kimi Code, Grok Build or grok-cli is installed
+                                 ~/.kimi-code/mcp.json, ~/.grok-build/config.toml (a `# >>> lanes mcp >>>` block) or
+                                 ~/.grok/user-settings.json (mcp.servers id lanes), all starting
+                                 /home/coder/.lz/bin/lane-mcp — only where missing,
                                  the file kept as <file>.bak-<UTC> first, atomic (a `lanes` entry that starts something
                                  else is left alone, exit 1; on a uid split nothing is written there, exit 1). --no-mcp
                                  leaves out lane-mcp and the entries (lane-edit and its vimrc still ship) and removes
-                                 nothing an earlier install wrote. In the container: lane mcp install
-  lanes hooks install --agent claude|codex (--container <name> | --home <dir>) [--dry-run | --write]
+                                 nothing an earlier install wrote. In the container: lane mcp install. The Throttle
+                                 pulse (throttle-pulse) ships to every container; in the daemon's container only
+                                 (site.conf LANES_THROTTLE_CONTAINER, else the registry's Throttle Monitor container)
+                                 its loop is started, once: `docker exec -d -u 1000 -e HOME=/home/coder <name> tmux -L
+                                 lanes-pulse new -d -s pulse ~/.lz/bin/throttle-pulse --loop` (nothing when that
+                                 session already runs; exit 1 when docker refused the start)
+  lanes throttle adopt-token <container>
+                                 the operator's opt-in to the pulse's burn and money lines: copy env.ANTHROPIC_API_KEY
+                                 of the container's own ~/.claude/settings.json — the LOCAL Throttle client bearer, it
+                                 must start `throttle_` — into its ~/.lz/throttle-token (0600, by rename), read and
+                                 written through /proc/<init>/root without following a link. Prints `adopted` or the
+                                 refusal, never the value. Exit 1 when refused
+  lanes hooks install --agent claude|codex|kimi|grok|grok-cli (--container <name> | --home <dir>) [--dry-run | --write]
                                  merge the lane-signal hooks into that home's ~/.claude/settings.json or ~/.codex/hooks.json
-                                 (+ a top-level Codex notify when none is set); prints the diff, writes only with --write
-                                 (backup kept). Opt-in, per container; Codex still asks you to trust new hooks.
+                                 (+ a top-level Codex notify when none is set), ~/.kimi-code/config.toml (a `# >>> lanes
+                                 hooks >>>` block of [[hooks]]), Grok Build's ~/.grok-build/hooks/lanes.json and
+                                 ~/.grok-build/config.toml (blocks: [compat.claude] hooks/mcps = false, [ui.notifications]
+                                 bel always, [model."grok-4.6"/"grok-4.5"] env_http_headers from LANES_TRACE) or
+                                 grok-cli's ~/.grok/user-settings.json `hooks`; prints the diff (credential values shown
+                                 as …), writes only with --write (backup kept; nothing outside a block is rewritten).
+                                 Opt-in, per container; Codex still asks you to trust new hooks.
                                  --write into a --container whose home the agent could not read from this account (uid
                                  not 1000, or a home volume not owned by 1000) is refused with the reason
   lanes invariant save|check     snapshot / verify every live pane's pid and window size
@@ -269,6 +302,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
@@ -348,6 +386,7 @@
 """
 import contextlib
 import json
+import math
 import os
 import posixpath
 import pwd
@@ -777,9 +816,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
 
 
@@ -1164,7 +1212,15 @@ def hook_env(home):
 
 INSTALL_CONTAINER_USAGE = 'usage: lanes install-container <name> [--no-mcp]'
 # lane_core.py first: `lane` imports it, so no moment has a new `lane` beside an old (or no) lane_core.py.
-CONTRACT_FILES = ('lane_core.py', 'lane-mcp', 'lane', 'lane-run', 'lane-signal', 'lane-edit')
+CONTRACT_FILES = ('lane_core.py', 'lane-mcp', 'lane', 'lane-run', 'lane-signal', 'lane-edit', 'throttle-pulse')
+# The Throttle pulse (W11): installed everywhere, its loop started only in the daemon's container. As uid 1000 with
+# the container home as HOME, whatever user the image defaults to: it writes ~/.lz/state/throttle.json, which
+# lanes-statusd reads, and reads ~/.lz/throttle-token, which only the container's own user may read (0600).
+PULSE_BIN = L.CONTAINER_HOME + '/.lz/bin/throttle-pulse'
+PULSE_TMUX = ('tmux', '-L', 'lanes-pulse')
+PULSE_SESSION = 'pulse'
+PULSE_DOCKER_S = 20
+THROTTLE_MONITOR = 'tools--throttle-monitor'
 
 
 def lane_core():
@@ -1264,8 +1320,8 @@ def cmd_install_container(args):
     # user (0700), never here.
     install_file(L.REPO / 'container/vimrc', root / 'vimrc')
     # The hook DEFINITIONS travel with the contract for reference; no hook is installed here — that is the opt-in,
-    # per-container `lanes hooks install --agent claude|codex --container <name> --write` (RUNBOOK).
-    for source in sorted((L.REPO / 'container/hooks').glob('*.json')):
+    # per-container `lanes hooks install --agent claude|codex|kimi|grok|grok-cli --container <name> --write` (RUNBOOK).
+    for source in sorted([*(L.REPO / 'container/hooks').glob('*.json'), *(L.REPO / 'container/hooks').glob('*.toml')]):
         install_file(source, root / 'hooks' / source.name)
     env_file = L.REPO / 'container/env.sh'   # TMPDIR off the RAM-backed /tmp; only NEW shells and agents read it
     if env_file.exists():
@@ -1280,21 +1336,142 @@ def cmd_install_container(args):
     if link.is_symlink() or link.exists():
         link.unlink()
     link.symlink_to(root)
-    print(f"installed {root}/bin/{{lane,lane_core.py,lane-run,lane-signal,lane-edit{'' if no_mcp else ',lane-mcp'},zmx-*}}, "
+    print(f"installed {root}/bin/{{lane,lane_core.py,lane-run,lane-signal,lane-edit,throttle-pulse"
+          f"{'' if no_mcp else ',lane-mcp'},zmx-*}}, "
           f'{root}/VERSION, {root}/vimrc, {root}/hooks/' + (f' and {root}/env.sh' if env_file.exists() else '')
           + f'; host link {link} -> {root}')
+    pulse = start_pulse(container)
     if no_mcp:
         print('--no-mcp: lane-mcp and the agents\' MCP entries left out (anything an earlier install wrote is kept)')
+        return pulse
+    return install_mcp_entries(home) or pulse
+
+
+def throttle_container():
+    """(container, where it was named) of the Throttle daemon's container, or (None, None): site.conf's
+    LANES_THROTTLE_CONTAINER, else the container of the registry's Throttle Monitor tool (`lanes sync` names the one
+    that hosts most boards' monitor)."""
+    named = site_profile().get('LANES_THROTTLE_CONTAINER')
+    if named and L.IDENT.match(named):
+        return named, 'site.conf LANES_THROTTLE_CONTAINER'
+    registry = L.read_json(L.STATE / 'registry.json', {})
+    for tool in (registry.get('tools') if isinstance(registry, dict) else None) or []:
+        if isinstance(tool, dict) and tool.get('id') == THROTTLE_MONITOR and L.IDENT.match(str(tool.get('container'))):
+            return tool['container'], f'the registry\'s {THROTTLE_MONITOR}'
+    return None, None
+
+
+def pulse_argv(container, *tmux):
+    """`docker exec` of the pulse's tmux server in `container` as uid 1000, argv only (no shell anywhere)."""
+    detach = ['-d'] if tmux[:1] == ('new',) else []
+    return ['docker', 'exec', *detach, '-u', str(L.CONTAINER_UID), '-e', f'HOME={L.CONTAINER_HOME}', container,
+            *PULSE_TMUX, *tmux]
+
+
+def start_pulse(container):
+    """Start the Throttle pulse's loop in `container` when it is the daemon's container (throttle_container) and no
+    `pulse` session runs on the `lanes-pulse` tmux socket there -> exit code (1 only when docker refused the start).
+    Any other container gets the file only."""
+    daemon, named_by = throttle_container()
+    if container != daemon:
+        why = f'the daemon runs in {daemon} ({named_by})' if daemon else \
+            'no daemon container is known (site.conf LANES_THROTTLE_CONTAINER, or a board with a Throttle monitor)'
+        print(f'throttle pulse: installed, not started here — {why}')
+        return 0
+    rc, _out, _err = L.run_bounded(pulse_argv(container, 'has-session', '-t', f'={PULSE_SESSION}'), PULSE_DOCKER_S)
+    if rc == 0:
+        print(f'throttle pulse: already running in {container} (tmux -L lanes-pulse, session {PULSE_SESSION})')
         return 0
-    return install_mcp_entries(home)
+    rc, _out, err = L.run_bounded(pulse_argv(container, 'new', '-d', '-s', PULSE_SESSION, PULSE_BIN, '--loop'),
+                                  PULSE_DOCKER_S)
+    if rc != 0:
+        last = next((line.strip() for line in reversed(err.splitlines()) if line.strip()), '')
+        why = f'no answer within {PULSE_DOCKER_S} s' if rc is None else f'exit {rc}'
+        print(f'! throttle pulse: not started in {container} ({why}' + (f': {last[:160]}' if last else '') + ')')
+        return 1
+    print(f'throttle pulse: started in {container} ({named_by}): tmux -L lanes-pulse, session {PULSE_SESSION}; '
+          'it writes ~/.lz/state/throttle.json every 10 s')
+    return 0
+
+
+THROTTLE_USAGE = 'usage: lanes throttle adopt-token <container>'
+THROTTLE_TOKEN = re.compile(r'throttle_[A-Za-z0-9_-]{8,512}')
+SETTINGS_MAX = 1 << 20
+
+
+def cmd_throttle(args):
+    """`lanes throttle adopt-token <container>`: the operator's opt-in to the pulse's tokened reads. Copies
+    env.ANTHROPIC_API_KEY of the container's own ~/.claude/settings.json — the local Throttle client bearer
+    `throttle setup --install-clients` put there, never a provider credential: it must look like `throttle_…` — into
+    ~/.lz/throttle-token (0600, by rename), both read and written through /proc/<container init>/root without
+    following a link. Never prints the value, not even in a refusal."""
+    if len(args) != 2 or args[0] != 'adopt-token' or args[1].startswith('-'):
+        raise L.LanesError(THROTTLE_USAGE)
+    container = args[1]
+    if not L.IDENT.match(container):
+        raise L.LanesError(f'Invalid container name: {container!r}')
+    info = L.container_info(container)
+    if not info.get('running') or not info.get('pid'):
+        raise L.LanesError(f'{container} is not running: nothing adopted')
+    split = uid_split(info['home']) if info.get('home') else None
+    if split:
+        raise L.LanesError(f'{split}: the pulse (uid {L.CONTAINER_UID}) could not read a token this account writes — '
+                           'nothing adopted')
+    root = f"{L.proc_root()}/{int(info['pid'])}/root"
+    home = L.CONTAINER_HOME.strip('/').split('/')
+    try:
+        fd = L.open_real_dir(root, [*home, '.claude'])
+    except OSError:
+        raise L.LanesError(f'{container}: no ~/.claude directory (a real one, not a link): nothing adopted') from None
+    try:
+        data = L.read_regular_at(fd, 'settings.json', SETTINGS_MAX)
+    finally:
+        os.close(fd)
+    if data is None:
+        raise L.LanesError(f'{container}: ~/.claude/settings.json is not a regular file of at most 1 MiB: '
+                           'nothing adopted')
+    try:
+        settings = json.loads(data)
+    except ValueError:
+        raise L.LanesError(f'{container}: ~/.claude/settings.json is not JSON: nothing adopted') from None
+    env = settings.get('env') if isinstance(settings, dict) else None
+    value = env.get('ANTHROPIC_API_KEY') if isinstance(env, dict) else None
+    if not isinstance(value, str) or not THROTTLE_TOKEN.fullmatch(value):
+        raise L.LanesError(f'{container}: env.ANTHROPIC_API_KEY in ~/.claude/settings.json is not a local Throttle '
+                           'client token (throttle_…): nothing adopted — run `throttle setup --install-clients` in '
+                           'the container first')
+    try:
+        fd = L.open_real_dir(root, [*home, '.lz'])
+    except OSError:
+        raise L.LanesError(f'{container}: no ~/.lz directory (a real one): run `lanes install-container '
+                           f'{container}` first — nothing adopted') from None
+    try:
+        changed = L.atomic_write_if_changed_at(fd, 'throttle-token', value + '\n', 0o600)
+    finally:
+        os.close(fd)
+    print(f'adopted: {container} ~/.lz/throttle-token (0600)' + ('' if changed else ', unchanged')
+          + '; the pulse reads it on its next cycle')
+    return 0
 
 
 HOOK_TARGETS = {'claude': ('claude-settings.json', '.claude/settings.json'),
-                'codex': ('codex-hooks.json', '.codex/hooks.json')}
-HOOKS_USAGE = ('usage: lanes hooks install --agent claude|codex (--container <name> | --home <dir>) '
+                'codex': ('codex-hooks.json', '.codex/hooks.json'),
+                'kimi': ('kimi-hooks.toml', '.kimi-code/config.toml'),
+                'grok': ('grok-hooks.json', '.grok-build/hooks/lanes.json'),
+                'grok-cli': ('grok-cli-hooks.json', '.grok/user-settings.json')}
+# The other file an install changes: Codex's top-level notify; Grok Build's config.toml blocks (W12).
+HOOK_EXTRA = {'codex': ('.codex/config.toml',), 'grok': ('.grok-build/config.toml',)}
+# W12: a harness whose home is not a directory in the container is not installed there; `lanes onboard` skips it.
+HOOK_HOMES = {'kimi': '.kimi-code', 'grok': '.grok-build', 'grok-cli': '.grok'}
+HOOKS_USAGE = ('usage: lanes hooks install --agent claude|codex|kimi|grok|grok-cli (--container <name> | --home <dir>) '
                '[--dry-run | --write]')
 
 
+def hook_files(agent):
+    """The container-home-relative files `lanes hooks install --agent <agent>` may change."""
+    return (HOOK_TARGETS[agent][1],) + HOOK_EXTRA.get(agent, ())
+
+
 def render_hooks(agent):
     """The shipped hook definitions with `~/` spelled as the container home: the command reaches lane-signal whether
     or not the harness runs it through a shell that expands `~`."""
@@ -1356,16 +1533,236 @@ def codex_notify(text):
             + json.dumps(argv) + '\n' + text)
 
 
+SECRET_LINE = re.compile(r'^(\s*"?[A-Za-z0-9_.-]*(?:key|token|secret|password|credential)[A-Za-z0-9_.-]*"?\s*[:=]\s*)'
+                         r'(.+?)(,?)$', re.I)
+
+
+def redact_line(line):
+    """A diff line whose key names a key, token, secret, password or credential, with its value shown as `…`: the
+    agents' files hold credentials (grok-cli's `apiKey`, Claude's `env.ANTHROPIC_API_KEY`), and a dry run's diff is
+    printed — and the onboarding printout pasted into tickets."""
+    body = line.rstrip('\n')
+    found = SECRET_LINE.match(body[1:]) if body[:1] in (' ', '+', '-') else None
+    if not found:
+        return line
+    return body[0] + found.group(1) + '"…"' + found.group(3) + line[len(body):]
+
+
 def show_change(path, before, after):
     import difflib
     if before == after:
         print(f'{path}: no change')
         return False
-    sys.stdout.writelines(difflib.unified_diff(before.splitlines(True), after.splitlines(True),
-                                               f'{path} (now)', f'{path} (with lanes hooks)'))
+    sys.stdout.writelines(redact_line(line) for line in difflib.unified_diff(
+        before.splitlines(True), after.splitlines(True), f'{path} (now)', f'{path} (with lanes hooks)'))
     return True
 
 
+# ------------------------------------------------------------------- W12: Kimi Code, Grok Build and grok-cli hooks
+# Each file is changed through lane_core.edit_file: re-read before the write, `<file>.bak-<UTC>` first, atomic, never
+# through a symbolic link below the container home. A TOML file gets ONE marker block (lane_core.toml_block); nothing
+# outside it is rewritten. A refusal is raised to the operator as LanesError before anything is written.
+
+GROK_CONFIG_BODY = ('[compat.claude]\n'
+                    "# Claude Code's hooks (lane-signal --harness claude) and MCP entry must not run inside Grok Build\n"
+                    'hooks = false\n'
+                    'mcps = false\n'
+                    '\n'
+                    '[ui.notifications]\n'
+                    "# a BEL on every turn end, approval and error, focused or not: the pane's window_bell_flag\n"
+                    'condition = "always"\n'
+                    'method = "bel"\n'
+                    'events = ["turn_complete", "approval_required", "task_complete", "agent_error"]\n')
+GROK_CONFIG_VALUES = {'compat': {'claude': {'hooks': False, 'mcps': False}},
+                      'ui': {'notifications': {'condition': 'always', 'method': 'bel',
+                                               'events': ['turn_complete', 'approval_required', 'task_complete',
+                                                          'agent_error']}}}
+# The lanes trace on Grok Build's inference requests: each built-in model gains an env-sourced header (an override of a
+# built-in keeps its other fields; the value is read from $LANES_TRACE when the client is built, never stored).
+GROK_TRACE_MODELS = ('grok-4.6', 'grok-4.5')
+GROK_TRACE_HEADERS = {'x-throttle-trace': 'LANES_TRACE'}
+
+
+def _lane_error(error):
+    return L.LanesError(str(error))
+
+
+def kimi_hooks_block():
+    """The body of the shipped kimi-hooks.toml (between its marker lines), `~/` spelled as the container home."""
+    rows = (L.REPO / 'container/hooks/kimi-hooks.toml').read_text().splitlines(True)
+    return ''.join(rows[1:-1]).replace('"~/', f'"{L.CONTAINER_HOME}/')
+
+
+def _ours_hook(item):
+    return isinstance(item, dict) and '/.lz/bin/lane-signal' in str(item.get('command') or '')
+
+
+def _toml_multiset(items):
+    return sorted(json.dumps(item, sort_keys=True) for item in items)
+
+
+def kimi_config(text):
+    """~/.kimi-code/config.toml with the lanes `[[hooks]]` block (kimi-hooks.toml) — Kimi Code reads hooks only from
+    $KIMI_CODE_HOME/config.toml (`[[hooks]]` {event, matcher?, command, timeout?}, a strict schema; MEASURED in the
+    2.1.1 binary, 2026-10-15). The `.kimi-code` no-touch doctrine of the session registry concerns the device identity
+    files, not this block. A `hooks` that is not an array of tables refuses; another writer's `[[hooks]]` stay."""
+    core, what = lane_core(), '~/.kimi-code/config.toml'
+    try:
+        before = core._toml_loads(text or '', what)
+        rest_text = core.without_block(text, 'hooks')
+        after = core.toml_block(text, 'hooks', kimi_hooks_block(), core._lanes_command)
+    except core.LaneError as error:
+        raise _lane_error(f'{what}: {error}') from None
+    if before is None:   # no tomllib: the forms a textual rule can read
+        if re.search(r'(?m)^[ \t]*hooks[ \t]*[=.]|^[ \t]*\[[ \t]*hooks[ \t]*\]', rest_text):
+            raise L.LanesError(f'{what} defines `hooks` other than as [[hooks]] tables — left alone; fix it by hand')
+        return after
+    hooks = before.get('hooks', [])
+    if not isinstance(hooks, list) or not all(isinstance(item, dict) for item in hooks):
+        raise L.LanesError(f'{what}: "hooks" is not an array of tables ([[hooks]]) — left alone; fix it by hand')
+    try:
+        parsed = core._toml_loads(after, what)
+    except core.LaneError:
+        parsed = None
+    expected = [item for item in hooks if not _ours_hook(item)] + core._toml_loads(kimi_hooks_block(), what)['hooks']
+    if parsed is None or {k: v for k, v in parsed.items() if k != 'hooks'} != \
+            {k: v for k, v in before.items() if k != 'hooks'} or \
+            _toml_multiset(parsed.get('hooks', [])) != _toml_multiset(expected):
+        raise L.LanesError(f'{what}: the hooks block could not be written without changing anything else — add it by '
+                           'hand from ~/.lz/hooks/kimi-hooks.toml')
+    return after
+
+
+def grok_hooks_file(_text):
+    """$GROK_HOME/hooks/lanes.json: the whole file is Lanes' (grok-hooks.json, Claude Code's JSON shape, which Grok
+    Build reads from every $GROK_HOME/hooks/*.json)."""
+    return json.dumps(render_hooks('grok'), indent=2, ensure_ascii=False) + '\n'
+
+
+def _deep(doc, *keys):
+    for key in keys:
+        doc = doc.get(key) if isinstance(doc, dict) else None
+    return doc
+
+
+def grok_config(text):
+    """$GROK_HOME/config.toml with the lanes `hooks` block (GROK_CONFIG_BODY: `[compat.claude] hooks = false, mcps =
+    false` — Grok Build otherwise also runs Claude Code's hooks and MCP servers from ~/.claude*, which say `--harness
+    claude` — and `[ui.notifications]`: a BEL on every listed event, focused or not) and the `trace` block (each
+    GROK_TRACE_MODELS `[model."<id>"] env_http_headers`, except a model the file configures outside the block, which
+    is the person's: named instead). A `[compat.claude]` or `[ui.notifications]` of the person's refuses (TOML defines
+    a table once): set those keys there by hand."""
+    core, what = lane_core(), '~/.grok-build/config.toml'
+    try:
+        before = core._toml_loads(text or '', what)
+        rest_text = core.without_block(core.without_block(text, 'hooks'), 'trace')
+        rest = core._toml_loads(rest_text, what)
+    except core.LaneError as error:
+        raise _lane_error(f'{what}: {error}') from None
+    if rest is not None:
+        mine = [name for name, keys in (('[compat.claude]', ('compat', 'claude')),
+                                        ('[ui.notifications]', ('ui', 'notifications')))
+                if _deep(rest, *keys) is not None]
+        free = [model for model in GROK_TRACE_MODELS if _deep(rest, 'model', model) is None]
+    else:   # no tomllib: what a textual rule can see
+        mine = [name for name, word in (('[compat.claude]', 'compat'), ('[ui.notifications]', 'notifications'))
+                if re.search(rf'(?m)^[ \t]*[^#\n]*\b{word}\b', rest_text)]
+        free = [model for model in GROK_TRACE_MODELS if model not in rest_text]
+    if mine:
+        raise L.LanesError(f'{what} already has {" and ".join(mine)} of its own — left alone; set `[compat.claude] '
+                           'hooks = false, mcps = false` and `[ui.notifications] condition = "always", method = "bel"` '
+                           'there by hand')
+    for model in GROK_TRACE_MODELS:
+        if model not in free:
+            print(f'! {what}: [model."{model}"] is configured outside the lanes block — add env_http_headers = '
+                  '{ "x-throttle-trace" = "LANES_TRACE" } to it by hand for the lanes trace')
+    trace = ''.join(f'[model."{model}"]\nenv_http_headers = {{ "x-throttle-trace" = "LANES_TRACE" }}\n'
+                    for model in free)
+    tables = ('[compat.claude]', '[ui.notifications]', *(f'[model."{model}"]' for model in GROK_TRACE_MODELS))
+
+    def ours(table):
+        return table.split('\n', 1)[0].strip() in tables
+    try:
+        after = core.toml_block(text, 'hooks', GROK_CONFIG_BODY, ours)
+        if trace:
+            after = core.toml_block(after, 'trace', trace, ours)
+        else:
+            after = core.without_block(after, 'trace')
+    except core.LaneError as error:
+        raise _lane_error(f'{what}: {error}') from None
+    if before is not None:
+        expected = json.loads(json.dumps(rest))
+        for key, value in GROK_CONFIG_VALUES.items():
+            expected[key] = dict(expected.get(key) or {}, **value)
+        for model in free:
+            expected['model'] = dict(expected.get('model') or {}, **{model: {'env_http_headers': dict(GROK_TRACE_HEADERS)}})
+        try:
+            ok = core._toml_loads(after, what) == expected
+        except core.LaneError:
+            ok = False
+        if not ok:
+            raise L.LanesError(f'{what}: the lanes blocks could not be written without changing anything else — set '
+                               'the keys by hand (RUNBOOK "Agent hooks")')
+    return after
+
+
+def grok_cli_settings(text):
+    """grok-cli's ~/.grok/user-settings.json with the lane-signal groups merged into its top-level `hooks` (Claude
+    Code's shape; grok-cli matches a `matcher` as an exact string and runs every command through `sh -c` with its own
+    environment, MEASURED in the 1.1.7 binary's source, 2026-10-15) — that one member edited, every other byte kept (the
+    file holds grok-cli's apiKey); the result must parse back to the input with that member."""
+    core, what = lane_core(), '~/.grok/user-settings.json'
+    ours = render_hooks('grok-cli')
+    if text is None or not text.strip():
+        return json.dumps(ours, indent=2, ensure_ascii=False) + '\n'
+    try:
+        doc = core.strict_json(text, what)
+    except core.LaneError as error:
+        raise _lane_error(error) from None
+    if not isinstance(doc, dict):
+        raise L.LanesError(f'{what}: not a JSON object — refusing to rewrite it')
+    merged = merge_hooks(doc, ours)['hooks']
+    if merged == doc.get('hooks'):
+        return text
+    after = core.set_member(text, [], 'hooks', merged)
+    if core.strict_json(after, what) != dict(doc, hooks=merged):
+        raise L.LanesError(f'{what}: the hooks could not be merged without changing anything else — add them by hand')
+    return after
+
+
+HOOK_EDITORS = {'kimi': (('.kimi-code/config.toml', kimi_config),),
+                'grok': (('.grok-build/hooks/lanes.json', grok_hooks_file), ('.grok-build/config.toml', grok_config)),
+                'grok-cli': (('.grok/user-settings.json', grok_cli_settings),)}
+
+
+def install_edits(home, edits, write):
+    """Show each file's change (a diff, or `no change`) and, with `write`, apply them through lane_core.edit_file ->
+    the changed paths. A refusal of any file (LanesError) is raised before anything is written."""
+    core, planned = lane_core(), []
+    for rel, transform in edits:
+        path = home / rel
+        try:
+            _ident, before = core._snapshot(path, home)
+        except core.LaneError as error:
+            raise _lane_error(error) from None
+        after = transform(before)
+        if show_change(path, before or '', after):
+            planned.append((path, transform))
+    if not write:
+        return []
+    changed = []
+    for path, transform in planned:
+        try:
+            _before, _after, saved = core.edit_file(path, transform, new_mode=0o600, backup=True, root=home)
+        except core.LaneError as error:
+            raise _lane_error(error) from None
+        if saved:
+            print(f'backup {saved}')
+        print(f'wrote {path}')
+        changed.append(path)
+    return changed
+
+
 def write_with_backup(path, before, after):
     """Atomic replace, the previous bytes kept beside it first. `before` is what the diff was computed from."""
     if path.exists():
@@ -1381,6 +1778,9 @@ def write_with_backup(path, before, after):
 def cmd_hooks(args):
     """`lanes hooks install`: merge the lane-signal hook definitions into ONE container home's agent config. Dry run
     (the printed diff) unless --write; never touches Codex's hook trust (`[hooks.state]` is Codex's own decision).
+    W12: kimi (a block in ~/.kimi-code/config.toml), grok (Grok Build: $GROK_HOME/hooks/lanes.json and blocks in
+    $GROK_HOME/config.toml, GROK_HOME = ~/.grok-build) and grok-cli (`hooks` in ~/.grok/user-settings.json), through
+    HOOK_EDITORS (`.bak-<UTC>` backups, no symbolic link followed).
     A --container target on a uid split (`uid_split`: this account or the home volume's owner is not the container
     uid) is refused with --write — the agent could not read the 0600 file this account would create — and warned in a
     dry run (DEF-1727). `--home <dir>` is for trying the merge on a copy, not an agent's home, and is not checked."""
@@ -1412,6 +1812,18 @@ def cmd_hooks(args):
     if split and opts.get('--write'):
         raise L.LanesError(f"{split}: the agent (uid {L.CONTAINER_UID}) could not read what this account would write "
                            f"into {home} — nothing written; run it from a host account with uid {L.CONTAINER_UID}")
+    if agent in HOOK_EDITORS:
+        install_edits(home, HOOK_EDITORS[agent], bool(opts.get('--write')))
+        if not opts.get('--write'):
+            if split:
+                print(f'⚠ {split}: --write refuses here (run it from a host account with uid {L.CONTAINER_UID})')
+            print('dry run: nothing written (add --write to apply)')
+        return 0
+    for rel in hook_files(agent):   # DEF-1998: the host never reads or writes through a link the container planted
+        try:
+            lane_core().no_links(home, home / rel)
+        except lane_core().LaneError as error:
+            raise _lane_error(f'{error}: nothing written') from None
     target = home / HOOK_TARGETS[agent][1]
     before = target.read_text() if target.exists() else ''
     try:
@@ -2129,8 +2541,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 +2567,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 +2589,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 +2596,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:
@@ -2315,7 +2742,9 @@ def cmd_workspaces(args):
 # ------------------------------------------------------------------- onboard
 
 ONBOARD_USAGE = ('usage: lanes onboard <login> --container <name> [--workspace <id> --repo <path> [--title T]] '
-                 '[--write] [--no-mcp]')
+                 '[--write] [--no-mcp] [--step kimi-notify|grok-build]...')
+ONBOARD_OPTIONAL = ('kimi-notify', 'grok-build')   # steps that run only when named with --step (W12)
+HARNESS_NAMES = {'kimi': 'Kimi Code', 'grok': 'Grok Build', 'grok-cli': 'grok-cli'}
 # The receipt's status vocabulary. A dry run reports planned, unchanged, skipped, manual or failed, and `ok` for the
 # read-only `inspect` of the container; `manual` names a step a person still has to take (printed with the exact command);
 # `warn` is a step that ran and reported a problem that does not stop onboarding (the doctor's verdict, a board with
@@ -2336,7 +2765,7 @@ THROTTLE_PROBE = ('if ! command -v throttle >/dev/null; then echo absent; '
 THROTTLE_SETUP = 'throttle setup --install-clients'
 THROTTLE_PROBE_TIMEOUT = 20
 THROTTLE_TIMEOUT = 120
-SITE_LINE = re.compile(r'^(LANES_[A-Z_]+)=([A-Za-z0-9_.:@/-]*)$')   # also what `lanes client-config` hands out
+SITE_LINE = L.SITE_LINE   # also what `lanes client-config` hands out
 
 
 def onboard_step(name, status, detail=''):
@@ -2358,13 +2787,10 @@ def uid_split(home):
     return None
 
 
-def site_profile():
-    """This server's site facts: the LANES_* KEY=VALUE lines of ~/.config/lanes/site.conf (read, never executed)."""
-    try:
-        text = (Path.home() / '.config/lanes/site.conf').read_text()
-    except OSError:
-        return {}
-    return dict(match.groups() for match in map(SITE_LINE.match, text.splitlines()) if match)
+def site_profile(home=None):
+    """This server's site facts: the LANES_* KEY=VALUE lines of ~/.config/lanes/site.conf (read, never executed;
+    L.site_conf, `home` for a test's)."""
+    return L.site_conf(home)
 
 
 def provision_throttle(container, site, write=True):
@@ -2429,13 +2855,134 @@ def provision_laptop(steps, site):
     return steps
 
 
+# ------------------------------------------------------------------- W12 optional onboard steps
+
+KIMI_NOTIFY_LINE = 'notification_condition = "always"'
+KIMI_NOTIFY_TABLE = re.compile(r'^[ \t]*\[[ \t]*notifications[ \t]*\][ \t]*(?:#.*)?$')
+KIMI_NOTIFY_KEY = re.compile(r'^([ \t]*)notification_condition[ \t]*=[ \t]*("[^"\\]*"|\'[^\']*\')[ \t]*(#.*)?$')
+
+
+def kimi_notify(text):
+    """~/.kimi-code/tui.toml with `[notifications] notification_condition = "always"` (operator-approved per container,
+    `lanes onboard --step kimi-notify`): Kimi Code then rings the terminal bell on every turn end, focused or not, and
+    tmux sets the pane's window_bell_flag. Kimi Code's own default tui.toml already HAS a `[notifications]` table
+    (`enabled = true`, `notification_condition = "unfocused"`; MEASURED in the 2.1.1 binary, 2026-10-15), and TOML defines
+    a table once, so that table's key is edited in place (its old value kept in a comment); only a file without the
+    table gets the marker block `notify`."""
+    core, what = lane_core(), '~/.kimi-code/tui.toml'
+    body = '[notifications]\n' + KIMI_NOTIFY_LINE + '\n'
+    if text is None or not text.strip():
+        return core.toml_block(None, 'notify', body)
+    try:
+        before = core._toml_loads(text, what)
+        rest = core.without_block(text, 'notify')
+        rows = text.splitlines(True)
+        _rows, first, last = core._block_rows(text, 'notify')
+    except core.LaneError as error:
+        raise _lane_error(f'{what}: {error}') from None
+    headers = [i for i, row in enumerate(rows) if KIMI_NOTIFY_TABLE.match(row.rstrip('\r\n'))
+               and (first is None or not first < i < last)]
+    if first is not None and not headers:
+        after = core.toml_block(text, 'notify', body)
+    elif len(headers) == 1:
+        start = headers[0] + 1
+        end = next((i for i in range(start, len(rows)) if rows[i].lstrip().startswith('[')), len(rows))
+        keys = [i for i in range(start, end) if KIMI_NOTIFY_KEY.match(rows[i].rstrip('\r\n'))]
+        if len(keys) > 1 or any(re.match(r'[ \t]*notification_condition[ \t]*=', rows[i]) and i not in keys
+                                for i in range(start, end)):
+            raise L.LanesError(f'{what}: [notifications] has a notification_condition this edit cannot read — set it '
+                               'to "always" by hand')
+        if keys:
+            row = rows[keys[0]]
+            found = KIMI_NOTIFY_KEY.match(row.rstrip('\r\n'))
+            if found.group(2).strip('"\'') == 'always':
+                return text
+            ending = row[len(row.rstrip('\r\n')):] or '\n'
+            rows[keys[0]] = (f'{found.group(1)}{KIMI_NOTIFY_LINE}  # lanes onboard --step kimi-notify (was '
+                             f'{found.group(2)})' + ending)
+        else:
+            rows.insert(start, KIMI_NOTIFY_LINE + '  # lanes onboard --step kimi-notify\n')
+        after = ''.join(rows)
+    elif headers:
+        raise L.LanesError(f'{what}: [notifications] appears {len(headers)} times — fix the file by hand')
+    elif re.search(r'(?m)^[ \t]*notifications[ \t]*[=.]', rest):
+        raise L.LanesError(f'{what}: notifications is not written as a [notifications] table — set '
+                           'notification_condition = "always" by hand')
+    else:
+        after = core.toml_block(text, 'notify', body)
+    if before is not None:
+        expected = json.loads(json.dumps(before))
+        expected['notifications'] = dict(expected.get('notifications') or {}, notification_condition='always')
+        try:
+            ok = core._toml_loads(after, what) == expected
+        except core.LaneError:
+            ok = False
+        if not ok:
+            raise L.LanesError(f'{what}: notification_condition could not be set without changing anything else — '
+                               'set it to "always" by hand')
+    return after
+
+
+# `lanes onboard --step grok-build`: Grok Build installed under GROK_HOME=~/.grok-build inside the container, as uid
+# 1000, by the measured recipe (evidence 2026-10-15 "Container install recipe", derived from x.ai's install.sh): the
+# stable channel's version, the zstd artifact (else the plain one), the binary at downloads/grok-linux-x86_64 and the
+# relative link bin/grok (so the pane's command and comm stay `grok`), `[cli] installer = "internal"`. It never writes
+# ~/.grok (grok-cli's: Grok Build's own installer would replace grok-cli's bin/grok there), edits no shell rc file and
+# links nothing into ~/.local/bin. The channel publishes no checksum (no GitHub release assets; MEASURED 2026-10-15), so
+# the download cannot be verified: the step prints and records its size and sha256 as UNVERIFIED, and it runs only
+# when the operator names it (`--step grok-build`).
+GROK_BUILD_TIMEOUT = 900
+GROK_BUILD_RECIPE = (
+    'set -eu; G="$HOME/.grok-build"; '
+    '[ "$(uname -m)" = x86_64 ] || { echo "grok-build: only linux x86_64 builds exist, this is $(uname -m)" >&2; exit 3; }; '
+    'V=$(curl -fsSL https://x.ai/cli/stable); '
+    'case "$V" in ""|*[!0-9.]*) echo "grok-build: the stable channel answered no version" >&2; exit 3;; esac; '
+    'mkdir -p "$G/downloads" "$G/bin"; P="$G/downloads/.grok-linux-x86_64.part"; rm -f "$P" "$P.zst"; '
+    'if command -v zstd >/dev/null 2>&1 && curl -fsSL -o "$P.zst" "https://x.ai/cli/grok-$V-linux-x86_64.zst"; '
+    'then zstd -q -dc "$P.zst" > "$P"; rm -f "$P.zst"; '
+    'else rm -f "$P.zst"; curl -fsSL -o "$P" "https://x.ai/cli/grok-$V-linux-x86_64"; fi; '
+    'chmod 755 "$P"; mv -f "$P" "$G/downloads/grok-linux-x86_64"; '
+    'ln -sfn ../downloads/grok-linux-x86_64 "$G/bin/grok"; '
+    '[ -e "$G/config.toml" ] || printf \'[cli]\\ninstaller = "internal"\\n\' > "$G/config.toml"; '
+    'R=$(GROK_HOME="$G" "$G/bin/grok" --version 2>/dev/null | head -n 1); '
+    'echo "grok-build version=$V bytes=$(wc -c < "$G/downloads/grok-linux-x86_64") '
+    'sha256=$(sha256sum "$G/downloads/grok-linux-x86_64" | cut -d" " -f1) runs=$R"')
+GROK_BUILD_LINE = re.compile(r'^grok-build version=([0-9.]+) bytes=(\d+) sha256=([0-9a-f]{64}) runs=(.*)$')
+
+
+def provision_grok_build(container, write):
+    """The `grok-build` onboard step -> (status, detail). A dry run prints the command; --write runs it (bounded,
+    GROK_BUILD_TIMEOUT) and reports the installed version with the download's size and sha256, marked unverified."""
+    uid = str(L.CONTAINER_UID)
+    argv = ['docker', 'exec', '-u', uid, container, 'sh', '-lc', GROK_BUILD_RECIPE]
+    shown = f"docker exec -u {uid} {container} sh -lc '<GROK_BUILD_RECIPE>' (GROK_HOME=~/.grok-build)"
+    if not write:
+        print(f'would run: {shown}')
+        return 'planned', 'Grok Build into ~/.grok-build (stable channel; the download is unverified: no checksum)'
+    rc, out, err = L.run_bounded(argv, GROK_BUILD_TIMEOUT)
+    found = next((GROK_BUILD_LINE.match(line.strip()) for line in reversed(out.splitlines())
+                  if GROK_BUILD_LINE.match(line.strip())), None)
+    if rc != 0 or not found:
+        last = next((line.strip() for line in reversed((err or '').splitlines()) if line.strip()), '')
+        reason = f'no answer within {GROK_BUILD_TIMEOUT} s' if rc is None else f'exit {rc}'
+        print(f'✗ grok-build: {reason}' + (f' ({last[:160]})' if last else ''))
+        return 'failed', f'{reason}: Grok Build not installed in {container}' + (f' ({last[:160]})' if last else '')
+    version, size, digest, runs = found.groups()
+    detail = (f'Grok Build {version} in ~/.grok-build (bin/grok -> downloads/grok-linux-x86_64; {runs or "no --version"}'
+              f') — download UNVERIFIED (the stable channel publishes no checksum): {size} bytes, sha256 {digest}')
+    print(f'⚠ grok-build: {detail}')
+    return 'warn', detail
+
+
 def onboard_args(args):
     if not args or args[0].startswith('-'):
         raise L.LanesError(ONBOARD_USAGE)
     opts, rest = {}, list(args[1:])
     while rest:
         word = rest.pop(0)
-        if word in ('--container', '--workspace', '--repo', '--title') and rest and word not in opts:
+        if word == '--step' and rest and rest[0] in ONBOARD_OPTIONAL:
+            opts.setdefault('--step', []).append(rest.pop(0))
+        elif word in ('--container', '--workspace', '--repo', '--title') and rest and word not in opts:
             opts[word] = rest.pop(0)
         elif word in ('--write', '--no-mcp'):
             opts[word] = True
@@ -2577,10 +3124,20 @@ def cmd_onboard(args):
                    if lane_core().read_regular(path, lane_core().EDIT_MAX) != mcp_before.get(path)]
         return ('changed', ', '.join(changed)) if changed else ('unchanged', files)
 
+    def installed(agent):
+        """None when `agent` is installed in the container (its home is a real directory), else why not."""
+        rel = HOOK_HOMES.get(agent)
+        if rel is None or (home() / rel).is_dir() and not (home() / rel).is_symlink():
+            return None
+        return f'no ~/{rel} in the container: {HARNESS_NAMES[agent]} is not installed there'
+
     def hooks_step(agent):
         def step():
             target = home()
-            files = [target / HOOK_TARGETS[agent][1]] + ([target / '.codex/config.toml'] if agent == 'codex' else [])
+            missing = installed(agent)
+            if missing:
+                return 'skipped', missing + (' (--step grok-build installs it)' if agent == 'grok' else '')
+            files = [target / rel for rel in hook_files(agent)]
             before = [path.read_bytes() if path.exists() else None for path in files]
             cmd_hooks(['install', '--agent', agent, '--container', container, '--write' if write else '--dry-run'])
             if not write:
@@ -2590,6 +3147,24 @@ def cmd_onboard(args):
             return ('changed', ', '.join(changed)) if changed else ('unchanged', str(files[0]))
         return step
 
+    def kimi_notify_step():
+        if 'kimi-notify' not in opts.get('--step', []):
+            return 'skipped', 'optional: --step kimi-notify (Kimi Code rings the bell on every turn end, focused or not)'
+        missing = installed('kimi')
+        if missing:
+            return 'skipped', missing
+        path = home() / '.kimi-code/tui.toml'
+        before = path.read_bytes() if path.exists() else None
+        install_edits(home(), (('.kimi-code/tui.toml', kimi_notify),), write)
+        if not write:
+            return 'planned', str(path)
+        return ('changed' if (path.read_bytes() if path.exists() else None) != before else 'unchanged'), str(path)
+
+    def grok_build_step():
+        if 'grok-build' not in opts.get('--step', []):
+            return 'skipped', 'optional: --step grok-build (installs Grok Build into ~/.grok-build)'
+        return provision_grok_build(container, write)
+
     def sync_step():
         if not write:
             print('would run: lanes sync')
@@ -2643,9 +3218,13 @@ def cmd_onboard(args):
 
     print(f"lanes onboard {login} -> container {container}" + (f', board {board}' if board else '')
           + ('' if write else ' (dry run)'))
-    plan = [('inspect', inspect_step, True), ('board', board_step, True), ('contract', contract_step, True),
+    # grok-build (opt-in) runs before the contract, so install-container's MCP entries and hooks-grok find its home in
+    # the same run.
+    plan = [('inspect', inspect_step, True), ('board', board_step, True), ('grok-build', grok_build_step, False),
+            ('contract', contract_step, True),
             ('lane-mcp', mcp_step, False), ('hooks-claude', hooks_step('claude'), False),
-            ('hooks-codex', hooks_step('codex'), False),
+            ('hooks-codex', hooks_step('codex'), False), ('hooks-kimi', hooks_step('kimi'), False),
+            ('kimi-notify', kimi_notify_step, False), ('hooks-grok', hooks_step('grok'), False), ('hooks-grok-cli', hooks_step('grok-cli'), False),
             ('throttle', lambda: provision_throttle(container, site, write), False),
             ('sync', sync_step, False), ('cursor-sync', cursor_step, False), ('resync', resync_step, False),
             ('doctor', doctor_step, False)]
@@ -2661,7 +3240,8 @@ def cmd_onboard(args):
     for key, value in (('login', login), ('container', container), ('workspace', board or '-')):
         print(f'{key + ":":<14}{value}')
     for step in steps:
-        print(f"{step['name'] + ':':<14}{step['status']:<10} {step['detail']}")
+        print(f"{step['name'] + ':':<14}" + ('' if len(step['name']) < 13 else ' ')   # hooks-grok-cli: 15 wide
+              + f"{step['status']:<10} {step['detail']}")
     if write:
         print(f"{'receipt:':<14}{onboard_receipt(login, container, board, steps)}")
     else:
@@ -2768,7 +3348,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 +4499,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 +4531,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 +4583,414 @@ 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 fleet and the Throttle pulse (W11)
+# Four lines (W12 added the pools line) from what statusd published (spec
+# docs/superpowers/specs/2026-10-11-lanes-fleet-dashboard-design.md §2, §4): status.json's `throttle` (the
+# container-side pulse's ~/.lz/state/throttle.json as statusd copied it, with `stale`) and `fleet` (host and top
+# containers, OTel names as keys), and site.conf's LANES_FLEET_DASHBOARD_URL. doctor reads files only: it never asks the
+# daemon, never starts the pulse and never runs docker. A missing pulse, a daemon that does not answer and a stale fleet
+# are warnings (⚠), never a ✗: Lanes runs without Throttle and without them. The pulse rewrites its file at least every
+# 60 s, but on a 10 s loop with `at` truncated to the second a healthy one is routinely read 60–84 s after its `at`:
+# statusd calls it stale past 90 s (statusd.PULSE_STALE_S, DEF-1941), and doctor's own clock uses the same bound, so the
+# two never disagree about a healthy pulse.
+PULSE_FRESH_S = 90
+# The pulse's pools in its order (statusd.PULSE_POOLS, the throttle-pulse POOLS; W12 added kimi), named by the
+# `throttle pools:` line. A pool the pulse did not report says `?`: a pulse from before 1.5.0, or a daemon from before
+# its Kimi pool (`/pools/kimi/ready` answers 404 there).
+PULSE_POOLS = ('claude', 'codex', 'kimi')
+FLEET_FRESH_S = 60          # statusd republishes `fleet` every FLEET_INTERVAL (10 s) unless the host is critical
+THROTTLE_MONITOR = 'tools--throttle-monitor'
+FLEET_DASHBOARD_KEY = 'LANES_FLEET_DASHBOARD_URL'
+# The dashboard link (spec §1, §3): https only, a DNS host name, an optional port and a plain path — what an OSC 8 link
+# and a browser may be handed without escaping. No user part (no credential in a URL), no query or fragment (site.conf
+# lines carry neither: SITE_LINE refuses `?`, `#`, `=` and `&`). Accepted when an operator writes it into the server's
+# ~/.config/lanes/site.conf; no Lanes code path ever writes it (test_server_cli.FleetDashboardUrl pins both).
+FLEET_DASHBOARD_URL = re.compile(r'https://(?=[^/:]{1,253}(?::|/|\Z))[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?'
+                                 r'(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*'
+                                 r'(?::(?P<port>[0-9]{1,5}))?(?:/[A-Za-z0-9._~/-]*)?\Z', re.ASCII)
+
+
+def fleet_dashboard_url(home=None):
+    """site.conf's LANES_FLEET_DASHBOARD_URL -> (url, problem). (None, None): unset — the state until an authenticated
+    Grafana deployment exists; (url, None): accepted; (None, why): written but refused (not https, a user part, a port
+    out of range, a character outside the plain set), so nothing links to it. The last line naming the key wins, as in
+    site_profile; a line SITE_LINE does not admit (a `?` in it, a space) is judged here too rather than read as unset."""
+    try:
+        text = ((Path(home) if home is not None else Path.home()) / '.config/lanes/site.conf').read_text()
+    except (OSError, UnicodeDecodeError):
+        return None, None
+    values = [line.split('=', 1)[1].strip() for line in text.splitlines()
+              if line.startswith(FLEET_DASHBOARD_KEY + '=')]
+    if not values or not values[-1]:
+        return None, None
+    value = values[-1]
+    if not value.startswith('https://'):
+        return None, 'not an https URL'
+    match = FLEET_DASHBOARD_URL.match(value)
+    if not match:
+        return None, 'not a plain https://host[:port][/path] URL (no user part, query, fragment or space)'
+    if match.group('port') is not None and not 0 < int(match.group('port')) < 65536:
+        return None, 'port out of range'
+    return value, None
+
+
+def throttle_container(registry=None, home=None):
+    """(container, where it was named) of the Throttle daemon's container (and so the pulse's, spec §2.1), or (None,
+    None): site.conf's LANES_THROTTLE_CONTAINER (site_profile, `home` for a test's), else the container of the
+    registry's Throttle Monitor tab (`tools--throttle-monitor`; `registry` None reads <state>/registry.json). A name
+    that is not an identifier names nothing. install-container (which starts the pulse), doctor and the update's
+    re-ship (update.daemon_container) all read the setting from site.conf, so they name the same container."""
+    named = site_profile(home).get('LANES_THROTTLE_CONTAINER')
+    if named and L.IDENT.fullmatch(named):
+        return named, 'site.conf LANES_THROTTLE_CONTAINER'
+    if registry is None:
+        registry = L.read_json(L.STATE / 'registry.json', {})
+    for tool in (registry.get('tools') if isinstance(registry, dict) else None) or ():
+        if isinstance(tool, dict) and tool.get('id') == THROTTLE_MONITOR and isinstance(tool.get('container'), str) \
+                and L.IDENT.fullmatch(tool['container']):
+            return tool['container'], f"the registry's {THROTTLE_MONITOR}"
+    return None, None
+
+
+def age_shown(seconds):
+    seconds = max(0, int(seconds))
+    if seconds < 120:
+        return f'{seconds} s'
+    return f'{seconds // 60} min' if seconds < 7200 else f'{seconds // 3600} h'
+
+
+def number(value):
+    """A finite JSON number, else None (a bool, a string, NaN or an infinity a hand-edited file could hold)."""
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) else None
+
+
+def pulse_line(throttle, container, now):
+    """The pulse: its age by `at`, the container it runs in, whether the daemon answered and whether it holds the
+    opt-in bearer (money and burn lines need it; `lanes throttle adopt-token <c>` is the operator's step)."""
+    where = (f'container {container}' if container else
+             'no daemon container: site.conf LANES_THROTTLE_CONTAINER unset and no Throttle tab')
+    adopt = f'lanes throttle adopt-token {container}' if container else 'lanes throttle adopt-token <container>'
+    at = number((throttle or {}).get('at')) if isinstance(throttle, dict) else None
+    if at is None:
+        start = (f'lanes install-container {container} starts it in the daemon\'s container' if container else
+                 'name the daemon\'s container with LANES_THROTTLE_CONTAINER in ~/.config/lanes/site.conf, then lanes '
+                 'install-container <container>')
+        return '⚠', f'throttle pulse: none in status.json ({where}) — {start}'
+    age = now - at
+    up = throttle.get('up') is True
+    error = throttle.get('error')
+    daemon = 'daemon up' if up else 'daemon down' + (f' ({plain(error)[:80]})' if isinstance(error, str) and error else '')
+    tokened = throttle.get('tokened') is True
+    text = (f'throttle pulse: {age_shown(age)} old ({where}), {daemon}, tokened: {"yes" if tokened else "no"}'
+            + ('' if tokened else f' — {adopt}'))
+    if throttle.get('stale') is True or age > PULSE_FRESH_S:
+        rearm = f'lanes install-container {container}' if container else 'lanes install-container <container>'
+        return '⚠', text + f'; stale: the pulse stopped (statusd re-arms it at most every 10 min, or {rearm})'
+    return ('✓' if up else '⚠'), text
+
+
+def pools_line(throttle):
+    """The pools the pulse reports, usable of configured: `throttle pools: claude 12/19 · codex 3/5 · kimi 5/8 usable`.
+    A pool with nothing configured is `0/0` (a daemon with no Kimi account), one the pulse did not report `?`. A `⚠`
+    when a configured pool has no usable account (the sidebar's attention tone); otherwise information. The pulse
+    line above says how old these figures are."""
+    pools = throttle.get('pools') if isinstance(throttle, dict) else None
+    if not isinstance(pools, dict) or number(throttle.get('at')) is None:
+        return '', 'throttle pools: none in status.json'
+
+    def count(value):
+        return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else None
+    parts, empty = [], []
+    for pool in PULSE_POOLS:
+        row = pools.get(pool) if isinstance(pools.get(pool), dict) else {}
+        configured, usable = count(row.get('configured')), count(row.get('usable'))
+        if configured is None:
+            parts.append(f'{pool} ?')
+            continue
+        usable = min(usable or 0, configured)
+        parts.append(f'{pool} {usable}/{configured}')
+        if configured and not usable:
+            empty.append(pool)
+    text = 'throttle pools: ' + ' · '.join(parts) + ' usable'
+    if empty:
+        return '⚠', text + f" — no usable account in {', '.join(empty)}"
+    return '', text
+
+
+def fleet_line(fleet, containers, now):
+    """The host: cpu and memory utilization, the highest PSI avg10, and how many workspace containers run."""
+    containers = containers if isinstance(containers, dict) else {}
+    running = sum(1 for info in containers.values() if isinstance(info, dict) and info.get('running'))
+    if not isinstance(fleet, dict) or number(fleet.get('at')) is None:
+        return '⚠', (f'fleet: not in status.json (containers {running}) — a statusd from before 1.4.0 '
+                     '(systemctl --user restart lanes-statusd.service)')
+
+    def percent(value):
+        value = number(value)
+        return '?' if value is None else f'{round(value * 100)}%'
+    pressure = fleet.get('system.pressure') if isinstance(fleet.get('system.pressure'), dict) else {}
+    psi = [value for value in map(number, pressure.values()) if value is not None]
+    text = (f"fleet: cpu {percent(fleet.get('system.cpu.utilization'))} · "
+            f"mem {percent(fleet.get('system.memory.utilization'))} · "
+            f"psi {f'{round(max(psi))}%' if psi else '?'} · containers {running}")
+    age = now - fleet['at']
+    if fleet.get('stale') is True or age > FLEET_FRESH_S:
+        return '⚠', text + f' — stale ({age_shown(age)} old: statusd skips it while the host is critical)'
+    return '', text
+
+
+def dashboard_line(home=None):
+    url, problem = fleet_dashboard_url(home)
+    if problem:
+        return '⚠', f'fleet dashboard: {FLEET_DASHBOARD_KEY} ignored — {problem}; nothing links to it'
+    if url is None:
+        return '', f'fleet dashboard: {FLEET_DASHBOARD_KEY} unset'
+    return '', f'fleet dashboard: {url}'
+
+
+def fleet_doctor(status, registry, home=None, now=None):
+    """`lanes doctor`'s W11 lines -> [(mark, text)] (✓ | ⚠ | '' information; never ✗), in this order: the Throttle
+    pulse, its pools (W12: claude, codex, kimi), the fleet, the dashboard link. Read-only: status.json (already
+    read), the registry, site.conf."""
+    now = time.time() if now is None else now
+    status = status if isinstance(status, dict) else {}
+    container, _named_by = throttle_container(registry, home)
+    return [pulse_line(status.get('throttle'), container, now),
+            pools_line(status.get('throttle')),
+            fleet_line(status.get('fleet'), status.get('containers'), now),
+            dashboard_line(home)]
+
+
+# ------------------------------------------------------------------ doctor: the harness mix (W12)
+# `agent.harness` is an observed fact since W12 (spec
+# docs/superpowers/specs/2026-10-15-lanes-harness-observers-design.md §2): statusd reads it from the pane's process
+# tree. doctor counts what status.json carries — every lane row with an `agent` object, by its harness — and names each
+# value of the spec's enum, `unknown` (and any value outside the enum, such as an empty harness from a statusd before
+# W12) only when some lane has it. A row without `agent` (no signal names an agent there) is not counted. Information
+# only, never a ✗.
+HARNESSES = ('claude', 'codex', 'kimi', 'grok', 'grok-cli', 'shell')
+
+
+def harness_line(status):
+    """`lanes: claude 50 · codex 20 · kimi 3 · grok 0 · grok-cli 0 · shell 0` from status.json's lane rows. `shell`
+    counts an agent{} that names it, which statusd's merge never writes (a pane whose harness ended is published under
+    that harness's name with status `shell`, DM-LANES-STATUS): the slot reads 0 unless a foreign sidecar says so."""
+    counts, unknown = dict.fromkeys(HARNESSES, 0), 0
+    lanes = status.get('lanes') if isinstance(status, dict) else None
+    for row in lanes.values() if isinstance(lanes, dict) else ():
+        agent = row.get('agent') if isinstance(row, dict) else None
+        if not isinstance(agent, dict):
+            continue
+        harness = agent.get('harness')
+        if isinstance(harness, str) and harness in counts:
+            counts[harness] += 1
+        else:
+            unknown += 1
+    return '', ('lanes: ' + ' · '.join(f'{name} {n}' for name, n in counts.items())
+                + (f' · unknown {unknown}' if unknown else ''))
+
+
 # ------------------------------------------------------------------ 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 +5005,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 +5014,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)
@@ -4319,6 +5320,8 @@ def cmd_doctor(_args):
     # 'unknown' / stale = statusd could not OBSERVE the lane (its tmux server did not answer): not the same as gone.
     check(not states.get('missing') and not states.get('unknown') and not stale, 'all registry lanes observed and present',
           str(states) + (f'; {stale} shown with their last known state (tmux server did not answer)' if stale else ''))
+    # The harness mix (W12): which agent each lane runs, as statusd observed it; information only.
+    print(f'  {harness_line(status)[1]}')
     # One bounded process-table sweep serves both checks; the cgroup of the few tmux servers is a plain file read.
     rc, table, _err = L.run_bounded(['ps', '-eo', 'pid=,comm=,args='], 10)
     coexist = (L.STATE / 'flags/coexist').exists()
@@ -4370,6 +5373,18 @@ 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 fleet and the Throttle pulse (W11): what statusd published and site.conf's dashboard link; never a ✗.
+    for mark, text in fleet_doctor(status, registry):
+        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):
@@ -5048,12 +6063,12 @@ COMMANDS = {'rebuilt': cmd_rebuilt, 'hello': cmd_hello, 'client-config': cmd_cli
             'prepare': cmd_prepare, 'web': cmd_web, 'attach': cmd_attach, 'rebuild': cmd_rebuild, 'ensure': cmd_ensure, 'invariant': cmd_invariant,
             'doctor': cmd_doctor, 'pressure': cmd_pressure, 'sockets': cmd_sockets, 'tmp': cmd_tmp,
             'guard': cmd_guard, 'rename': cmd_rename, 'register': cmd_register, 'unregister': cmd_unregister,
-            'hooks': cmd_hooks, 'economy': cmd_economy,
+            'hooks': cmd_hooks, 'economy': cmd_economy, 'throttle': cmd_throttle,
             'preview': cmd_preview, 'edit': cmd_edit, 'device': cmd_device, 'next': cmd_next, 'prev': cmd_prev,
             '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: