@vibelord/lanes 1.2.0 → 1.3.0

package/payload/lanes/libexec/notify.py

@@ -31,10 +31,17 @@ NEEDS_YOU set. The six-word `state` is never read: the agent status is the only
     device_active).
   * Payload: `<lane name>: <agent task> — <status>` and, on a second line, the client command that opens the lane
     (`lanes-launch lane <id>`). No client registers a URL scheme for it, so the push carries a tappable action only
-    when `action_url` (a template over `{lane}`) is configured.
+    when `action_url` (a template over `{lane}`, and `{doc}` for a `published` event — `action_url()`) is configured.
   * A failed send is one journal line (lane id and the failure class — never the topic or the bearer) and is not
     retried; it never stops the service.
 
+Published documents (plan W10 W4): the docs service's publish pick-up (`lanes-docsd`, docsd.Pickup), not this
+service, calls `notify_published` once a document an agent published from a lane is stored — the same config, the
+same desk-presence rule (device_active) and the same `send`, at most one push per lane per minute (docsd's
+PUBLISHED_PUSH_S), best effort. Its payload is `{title: 'Published', message: '<lane name> published a document (<kind>,
+<size>)\n/lanes-docs/d/<id>', priority: 2}` and, when `action_url` is set, the tap target with `{doc}` resolved —
+never the document's title, name or content: the topic is the host's, and the document may be for one login only.
+
 Enrolment requests (W8 A5, LNS-44): the same service also watches `STATE/enrol-requests/` (lanes-enrold's store;
 read through `enrold.load_requests`, so a request announced is one `lanes enrol list` shows). A request that is
 pending — not approved, denied or past `expires_at` — and has not been announced yet yields ONE push:
@@ -55,7 +62,9 @@ Config `~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` overrides the path), `
 `url` (ntfy server, http/https, required), `topic` (`[A-Za-z0-9_-]{1,64}`, required), `token_file` (a file holding
 an ntfy access token, optional — sent as a bearer, never logged; an unreadable one disables sending rather than
 sending unauthenticated), `quiet_when_device_active_s` (default 120; 0 never suppresses), `action_url` (optional
-template, e.g. `https://lanes.example/?lane={lane}`). Without a valid `url` and `topic` the service only tracks
+template, e.g. `https://lanes.example/?lane={lane}`; plan W10 W7 adds `{doc}`, the page `/lanes-docs/d/<id>` of the
+document a `published` push names — empty for a needs-you push; the docs service sends those, W4). Without a valid
+`url` and `topic` the service only tracks
 transitions and sends nothing. The config is re-read when notify.conf OR its `token_file` changes (inode, size,
 mtime or ctime, so a token written, rotated, removed or chmod-ed after notify.conf counts), and on every tick while
 sending is disabled, so a token that becomes readable switches the pushes on within one interval.
@@ -76,6 +85,7 @@ import urllib.request
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docs_store  # noqa: E402
 import enrold as E  # noqa: E402
 import lanes_lib as L  # noqa: E402
 import tokens  # noqa: E402
@@ -95,6 +105,8 @@ PRESENCE = '*.pid'                                        # clients/ files only
 SEEN = '.seen.json'                                       # a sidebar's opened-lane record; desk devices only
                                                           # (a .pid of any age, devices/<device>.json not mobile)
                                                           # users/<login>.json written by a desk device counts too
+PUBLISHED_TITLE = 'Published'                            # a document published from a lane (notify_published)
+PUBLISHED_PRIORITY = 2
 ENROL_DIR = 'enrol-requests'                              # STATE/<this>/<id>.json: lanes-enrold's requests
 ENROL_SEEN = 'notify.enrol-seen.json'                     # STATE/<this>: the request ids already announced
 ENROL_TITLE = 'Enrol request'
@@ -275,6 +287,18 @@ def device_active(clients_dir, window, now, devices_dir=None, users_dir=None, me
     return any(within(at, window) for _login, at in marks)
 
 
+def action_url(template, lane_id, doc_id=None):
+    """notify.conf's `action_url` template made a push's tap target -> the URL, or '' without a template. `{lane}` is
+    the lane id; `{doc}` (plan W10 W7) the page of the document a `published` event is about, `/lanes-docs/d/<id>`
+    (docs_store.URL; a docs_store id, else nothing), and nothing for an event without one (a needs-you push) — so
+    `https://<host>:8443{doc}` opens the document. Both are percent-quoted."""
+    if not template:
+        return ''
+    doc = docs_store.URL.format(doc_id) if isinstance(doc_id, str) and docs_store.ID_RE.match(doc_id) else ''
+    return (template.replace('{lane}', urllib.parse.quote(lane_id, safe=''))
+            .replace('{doc}', urllib.parse.quote(doc, safe='/')))
+
+
 def _note(lane_id, status, agent, names, config):
     label = LABELS.get(status, status)
     name = _text(names.get(lane_id) or lane_id)
@@ -282,14 +306,50 @@ def _note(lane_id, status, agent, names, config):
     first = _line(f'{name}: {task} — {label}' if task else f'{name} — {label}')
     note = {'lane': lane_id, 'status': status, 'title': label,
             'message': f'{first}\nlanes-launch lane {lane_id}', 'priority': PRIORITY.get(status, 3)}
-    template = config.get('action_url') or ''
-    if template:
-        url = template.replace('{lane}', urllib.parse.quote(lane_id, safe=''))
+    url = action_url(config.get('action_url') or '', lane_id)
+    if url:
         note['click'] = url
         note['actions'] = [{'action': 'view', 'label': 'Open lane', 'url': url}]
     return note
 
 
+def _size(size):
+    if size < 1024:
+        return f'{size} B'
+    return f'{size / 1024:.1f} KiB' if size < 1024 * 1024 else f'{size / (1024 * 1024):.1f} MiB'
+
+
+def published_note(lane_id, meta, names, config):
+    """The push for a document stored from lane `lane_id` (`meta` its docs_store meta): the lane's name, the kind and
+    the size, and the document's page (module docstring) — never its title, name or content."""
+    name = _text(names.get(lane_id) or lane_id)
+    first = _line(f"{name} published a document ({_text(meta.get('kind'))}, {_size(int(meta.get('bytes') or 0))})")
+    note = {'lane': lane_id, 'status': 'published', 'doc': meta['id'], 'title': PUBLISHED_TITLE,
+            'message': f"{first}\n{docs_store.URL.format(meta['id'])}", 'priority': PUBLISHED_PRIORITY}
+    url = action_url(config.get('action_url') or '', lane_id, meta['id'])
+    if url:
+        note['click'] = url
+        note['actions'] = [{'action': 'view', 'label': 'Open document', 'url': url}]
+    return note
+
+
+def notify_published(lane_id, meta, names=None, conf_path=None, state=None, now=None, opener=None):
+    """Send the `published` push for a stored document (the docs service's pick-up calls it, W4) -> the note sent, or
+    None: sending disabled (no valid notify.conf at `conf_path`, else $LANES_NOTIFY_CONF, else the default), somebody
+    at a desk (device_active over `state`, default L.STATE), or the send failed (one journal line). Never raises for a
+    failed send; the caller rate-limits."""
+    config = read_config(conf_path or os.environ.get('LANES_NOTIFY_CONF') or DEFAULT_CONF)
+    if not config['enabled']:
+        return None
+    state = Path(state) if state is not None else L.STATE
+    now = time.time() if now is None else now
+    window = int(config.get('quiet_when_device_active_s', DEFAULT_QUIET) or 0)
+    if device_active(state / 'clients', window, now, state / 'devices'):
+        return None
+    note = published_note(lane_id, meta, names or {}, config)
+    return note if send(note, config, opener) else None
+
+
 def notify_changes(prev_status, new_status, config, names=None, now=None, clients_dir=None, devices_dir=None):
     """The notifications for lanes whose agent status ENTERED needs-you between two status.json documents.
     `prev_status` None = the first read: seed only, nothing is news. Empty when a desk device is present."""

package/payload/lanes/libexec/sidebar.py

@@ -7,6 +7,7 @@ Fully usable from the keyboard (touch/mouse is a bonus):
   ↑/↓ j/k move · Enter/→/Space open · J/K open next/previous lane · / filter · Esc clear · g/G · r reload
   2 / 3 open the lane under the cursor in the 2nd / 3rd viewport (wide view sessions) · x / × close (y, then Enter)
   u unregister a session added with a (z within 10 s undoes it; a declared lane says which file to edit)
+  d shows the cursor lane's docs link in the footer (plan W10 W7)
   ? shows every key in the body until the next key · Tab / Shift-Tab open the next / previous lane that needs you
 The keyboard goes back to the lane after every action (cockpit v3 S3): the sidebar and the lane share one keyboard, so
 an action that ends — a close, a rename, a register, a cancel, Esc, r, closing the key sheet, a click that opened
@@ -48,6 +49,9 @@ focus first; the file itself is then sent by the upload helper on your machine (
 there). Below it, when there is room, the strip row: the fleet economy line from the opt-in economy.json
 (`$8.5k/16k 53% · F2 S1 · spill 76%`), else which OTHER workspaces need you (`◆1 Worlds`). Column 34 of a lane row is
 one tail cell by priority: stale `?` > starving ⚠ > downgraded ↓ > mostly paid `$`.
+Docs (plan W10 W7): while the workspace's lanes have published documents the idle strip says ` ↑ uploads · ▤ docs N
+(U)`, one OSC 8 link to the docs page; the cursor row's name links to its lane's documents, and `d` shows that link in
+the footer. The counts and the origin come in status.json (statusd): no stat or fork of the sidebar's own.
 Truthful under load: a lane statusd could not observe keeps its last glyph, dimmed, with a `?`; the footer line warns
 when the host is under pressure or statusd has fallen behind (age of $STATE/health, measured with our own clock).
 Never frozen by an action (cockpit v3 S9): a close, `P`'s write and a new shell run on one worker thread (Worker); the
@@ -66,6 +70,7 @@ import sys
 import termios
 import threading
 import time
+import urllib.parse
 from operator import itemgetter
 from pathlib import Path
 import tty
@@ -184,6 +189,35 @@ PROFILE_LOCK_S = 0.2
 PROFILE_RETRY_S = 5.0
 # What `p`, `h` and `H` say on a device nobody owns (cockpit v3 R5): pins and hidden lanes live in the owner's profile.
 NO_PROFILE = 'no owner: lanes device claim'
+# The docs cockpit (plan W10 W7, LNS-108). The docs page is lanes-docsd behind Caddy's `handle_path /lanes-docs/*`; a
+# lane's documents are its index filtered `?ws=<ws>&lane=<lane>`. statusd publishes each lane's `docs: {n, at}` and the
+# document's `web_origin` (`https://<name>:8443`) in status.json, which this sidebar already reads — no stat, no fork
+# of its own. The links are OSC 8 hyperlinks (bytes, never cells): the upload strip's ` ↑ uploads · ▤ docs N  (U)` to
+# the page, the cursor row's name to its lane's documents, and the footer's `d` message to the same. Without an origin
+# there is no link (a terminal needs an absolute URL) and `d` says the path alone. The origin is checked again here: it
+# rides inside an OSC string, so only `https://<DNS host name>:8443` passes.
+DOCS_PATH = '/lanes-docs/'
+WEB_ORIGIN = re.compile(r'https://[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?:8443\Z', re.ASCII)
+
+
+def docs_count(row):
+    """A status.json lane row's document count (`docs.n`, plan W10 W7): a positive int, else 0."""
+    docs = row.get('docs') if isinstance(row, dict) else None
+    n = docs.get('n') if isinstance(docs, dict) else None
+    return n if isinstance(n, int) and not isinstance(n, bool) and n > 0 else 0
+
+
+def docs_url(origin, ws=None, lane=None):
+    """The docs page on `origin` ('' = the path alone), filtered to a workspace and a lane when given:
+    `/lanes-docs/?ws=<ws>&lane=<lane>`, each value percent-quoted (nothing in it can end an OSC string)."""
+    query = '&'.join(f'{key}={urllib.parse.quote(value, safe="")}' for key, value in (('ws', ws), ('lane', lane)) if value)
+    return f'{origin}{DOCS_PATH}' + (f'?{query}' if query else '')
+
+
+def osc8(url, text):
+    """`text` as ONE OSC 8 hyperlink to `url` (ST-terminated, no id); `text` as it is when there is no url. Costs
+    len(url) + 14 bytes and no cell: the budget gate's strip and cell walk read through it."""
+    return f'\033]8;;{url}\033\\{text}\033]8;;\033\\' if url else text
 
 
 def shown_version(path):
@@ -455,13 +489,13 @@ BOX_ROWS = 1    # the upload strip (spec §4.6(d)); it was a four-row box
 # config.kdl's shared block; lane chords such as Ctrl-Alt-m are no sidebar keys and stay off). 18 lines below the
 # dynamic version row (cockpit v3 V2, LNS-84: `  lanes <current> · view <tree>`, key_sheet) — exactly the 19-row body
 # of a 24-row pane with the strip row; R5's `p h` / `H o` (LNS-78) took the two rows S10 left, and V2's row the line
-# `u z` now share.
+# `u z` now share. Plan W10 W7's `d` (the cursor lane's docs link) joins the strip's own keys, `+ U d`, for the same reason.
 # test_sidebar.DocumentedKeys holds the sheet, the table and handle() to the same keys.
 KEY_SHEET = (('↑ ↓ j k', 'Up Dn j k', 'move'), ('⏎ → Space', 'Enter Spc', 'open the cursor lane'),
              ('J K', 'J K', 'open next / prev lane'), ('Tab S-Tab', 'Tab S-Tab', 'next / prev needing you'),
              ('2 3', '2 3', 'show in viewport 2 / 3'), ('/', '/', 'find a lane'),
              ('Esc', 'Esc', 'cancel, back to lane'), ('g G', 'g G', 'first / last'),
-             ('+ U', '+ U', 'new shell / upload'), ('a', 'a', 'add to a workspace'),
+             ('+ U d', '+ U d', 'shell / upload / docs'), ('a', 'a', 'add to a workspace'),
              ('x', 'x', 'close (y, then Enter)'), ('u z', 'u z', 'unregister / undo 10 s'),
              ('R', 'R', 'rename'), ('P', 'P', 'register a session'), ('p h', 'p h', 'pin / hide lane'),
              ('H o', 'H o', 'hide tab / hidden lanes'), ('r ?', 'r ?', 'reload / this sheet'),
@@ -649,6 +683,10 @@ class Sidebar:
     # W9 U6: whether clients/<device>.update-ready existed at the last look (poll_update), when to look next, and until
     # when a rebuild `r` started counts as on its way (monotonic seconds)
     update_ready, update_poll_at, rebuild_until = False, 0.0, 0.0
+    # The docs cockpit (plan W10 W7): status.json's `web_origin` ('' = none known, so no link), this workspace's
+    # document count (reload), the link of the footer message `d` set ('' = the message is no link; the message
+    # setter clears it) and the link the footer row draws this frame (footer_text sets it).
+    web_origin, docs_total, _message_link, footer_link = '', 0, '', ''
 
     def __init__(self, device, workspace, slot='main', viewports='1'):
         self.device, self.workspace, self.slot = device, workspace, slot
@@ -775,9 +813,12 @@ class Sidebar:
             self.status = status.get('lanes', {})
             self.unregistered = (status.get('unregistered') or {}).get(self.workspace, [])
             self.zmx = (status.get('zmx') or {}).get(self.workspace, [])
+            origin = status.get('web_origin')
+            self.web_origin = origin if isinstance(origin, str) and WEB_ORIGIN.match(origin) else ''
             self.keep_moved_row()
         if stamp[0] != self.stamp[0] or stamp[1] != self.stamp[1] or force:
             self.fleet = self.fleet_counts()
+            self.docs_total = self.workspace_docs()
         look = stamp[3] != self.stamp[3] or force
         profile = stamp[6] != self.stamp[6] or force
         if look:
@@ -1447,6 +1488,22 @@ class Sidebar:
         lane_id = entry.get('id')
         return bool(lane_id) and not entry.get('divider') and any(e.get('id') == lane_id for e in self.entries)
 
+    def workspace_docs(self):
+        """This workspace's documents (plan W10 W7): the `docs.n` of every lane it lists — registry lanes (hidden ones
+        too: their documents exist), zmx lanes and the sessions under Unregistered — each id once. reload() keeps it
+        (`docs_total`) for the upload strip; counts are every login's (DM-LANES-DOCS-COUNTS), the page shows a login
+        only what it may see."""
+        ids = {entry.get('id') for rows in (self.entries, self.zmx, self.unregistered) for entry in rows or ()
+               if isinstance(entry, dict)}
+        return sum(docs_count(self.status.get(lane_id)) for lane_id in ids if lane_id)
+
+    def lane_docs_link(self, lane_id):
+        """The OSC 8 target of a lane's name on the cursor row: its documents on the docs page, '' when the lane has
+        none or no origin is known (plan W10 W7)."""
+        if not self.web_origin or not docs_count(self.status.get(lane_id)):
+            return ''
+        return docs_url(self.web_origin, self.workspace, lane_id)
+
     def header_tally(self):
         """[(agent status, 'glyph+count')] for the header, in `HEADER_COUNTS` order, zeros omitted; a seen `done`
         is not counted (it left the Done section)."""
@@ -1516,8 +1573,11 @@ class Sidebar:
         viewers = viewer_mark(observed).replace('·', self.glyphs['marks']['viewer'])
         closable = bool(entry.get('closable')) and not pending   # a row being registered offers neither control
         can_register = closable and R.eligible(entry)
+        # Plan W10 W7: the cursor row's name is one OSC 8 link to its lane's documents while it has any.
+        link = self.lane_docs_link(entry['id']) if is_cursor else ''
         key = (entry.get('name'), entry.get('color'), entry.get('icon'), closable, can_register, key_state, stale,
-               viewers, status, age, tail, tail_role, is_cursor, is_viewing, mark, mark_role, cols, section_tone, hidden)
+               viewers, status, age, tail, tail_role, is_cursor, is_viewing, mark, mark_role, cols, section_tone, hidden,
+               link)
         cached = self.row_cache.get(entry['id'])
         if cached and cached[0] == key:
             self.row_hits += 1
@@ -1552,7 +1612,7 @@ class Sidebar:
         fg = (tone['ink-faint'] if hidden else f'\033[38;5;{color}m' if isinstance(color, int) and self.color != 'none'
               else tone['ink'] if self.vivid else '')
         lead = (tone['bold'] if is_viewing else '') + fg
-        name_cell = f'{lead}{clipped}{reset}' if lead else clipped
+        name_cell = osc8(link, f'{lead}{clipped}{reset}' if lead else clipped)
         if viewers:
             name_cell += f'{tone["ink-dim"]}{viewers}{reset}'
         # The `+` register control (README "Daily use") has no column in spec §4.2: it takes the spacer cell 28
@@ -2493,6 +2553,27 @@ class Sidebar:
             self.message = f'Shown {name}' if hidden else f'Hid {name} {g["sep"]} o shows it'
             self.release_focus()
 
+    def show_docs_link(self, entry):
+        """`d` (plan W10 W7, LNS-108): the cursor lane's documents link in the footer — a message like every other
+        (MESSAGE_S, or until the next action): the plain URL `https://<host>:8443/lanes-docs/?ws=<ws>&lane=<lane>`, as
+        much of it as the row holds, the whole footer text one OSC 8 link to all of it (⌘/Ctrl-click, or the
+        terminal's Copy Link, where 36 cells clip the text). Without an origin the path alone, no link. Then the
+        keyboard goes back to the lane, as after `p`; a row with no documents, or no lane, says so and keeps it."""
+        self.begin_action()
+        self.dirty = True
+        g = self.glyphs['marks']
+        lane_id = (entry or {}).get('id')
+        if not lane_id or entry.get('divider') or entry.get('action'):
+            self.message = 'no docs here'
+            return
+        if not docs_count(self.status.get(lane_id)):
+            self.message = f'no docs in {g["quote-open"]}{entry.get("name", lane_id)}{g["quote-close"]}'
+            return
+        url = docs_url(self.web_origin, self.workspace, lane_id)
+        self.message = url
+        self._message_link = url if self.web_origin else ''
+        self.release_focus()
+
     def toggle_hidden(self):
         """`o`: show the lanes the owner hid (faint, in their places; `h` there shows one for good) or hide them again.
         The footer says how many; then the keyboard goes back to the lane."""
@@ -2819,14 +2900,15 @@ class Sidebar:
 
     @message.setter
     def message(self, text):
-        # Every assignment is stamped (cockpit v3 S6): the message lasts MESSAGE_S from when it was SAID.
-        self._message, self.message_at = text, time.monotonic()
+        # Every assignment is stamped (cockpit v3 S6): the message lasts MESSAGE_S from when it was SAID. A new message
+        # is no link until `d` says it is one (plan W10 W7: show_docs_link sets `_message_link` after it).
+        self._message, self.message_at, self._message_link = text, time.monotonic(), ''
 
     def expire_message(self, now=None):
         """run()'s tick (cockpit v3 S6): a message MESSAGE_S old goes -> True when it went (one repaint). Otherwise only
         the next action's begin_action() clears it — never a key, a report, the wheel or a release."""
         if self._message and (time.monotonic() if now is None else now) - self.message_at >= MESSAGE_S:
-            self._message = ''
+            self._message, self._message_link = '', ''
             return True
         return False
 
@@ -2843,9 +2925,11 @@ class Sidebar:
 
     def strip_line(self, cols):
         """The upload strip (spec §4.6(d)): ONE row under the body, at most `cols − 1` cells — idle, armed, sending,
-        or the result for 8 s. Every glyph and separator is a mark, so the ASCII frame is seven-bit."""
+        or the result for 8 s. Every glyph and separator is a mark, so the ASCII frame is seven-bit. Idle while this
+        workspace has documents (plan W10 W7): ` ↑ uploads · ▤ docs N  (U)`, the whole text one OSC 8 link to the docs
+        page once statusd knows the origin (the page is where W5's browser uploads land too); with none, today's hint."""
         tone, g = self.tone, self.glyphs['marks']
-        sep = f' {g["sep"]} '
+        sep, link = f' {g["sep"]} ', ''
         if self.upload:
             count = len(self.upload['names'])
             text, style = f' {g["upload"]} sending {count} file{"s" if count != 1 else ""}', tone['tone-working']
@@ -2856,10 +2940,13 @@ class Sidebar:
         elif self.upload_note and time.time() - self.upload_note_at < 8:
             text = ' ' + self.upload_note
             style = tone['tone-done'] if self.upload_note.startswith(g['ok']) else tone['tone-urgent']
+        elif self.docs_total:
+            text, style = f' {g["upload"]} uploads{sep}{g["docs"]} docs {self.docs_total}  (U)', tone['ink-dim']
+            link = docs_url(self.web_origin) if self.web_origin else ''
         else:
             text, style = f' {g["upload"]} uploads{sep}click, then drop  (U)', tone['ink-dim']
         text, _used = clip(text, cols - 1)
-        return f'{style}{text}{tone["reset"]}'
+        return f'{style}{osc8(link, text)}{tone["reset"]}'
 
     def footer_text(self, cols, entries=(), legend=False):
         """The footer row -> (text, style, caret): ONE ladder for the desktop and the phone (cockpit v3 S6; until S6 the
@@ -2872,9 +2959,11 @@ class Sidebar:
         (r)` (W9 U6: the installed release lays this view out differently; `r` rebuilds it — the desktop's rung and
         the phone's, in the accent) › the focus legend (desktop) › the idle hint. Only the picker's way out, the
         legend and the idle hint are a device's own. Every glyph, separator and quote is a mark, so the ASCII footer
-        is seven-bit."""
+        is seven-bit. `footer_link` says which link footer_row draws this frame: the message's (`d`, plan W10 W7) while
+        the message is the rung shown, else none."""
         tone, g = self.tone, self.glyphs['marks']
         sep = f' {g["sep"]} '
+        self.footer_link = ''
         if self.prompt:
             return self.prompt_text(cols)
         if self.registration:
@@ -2892,6 +2981,7 @@ class Sidebar:
             text, style = f' {g["warning"]} registry: ' + self.errors[0], tone['tone-urgent']
         elif self.message:
             text, style = ' ' + self.message, tone['ink-dim']
+            self.footer_link = self._message_link
         elif self.undo:          # cockpit v3 S7: the `u` it undoes, until `z` or UNDO_S
             text, style = self.undo_text(cols), tone['ink-dim']
         elif self.update_ready:  # W9 U6: the installed release lays this view out differently; `r` rebuilds it
@@ -2942,11 +3032,12 @@ class Sidebar:
 
     def footer_row(self, cols, entries=(), legend=False):
         """footer_text() painted: the words in their style, then the caret in tone-working when a field is open. The
-        caller ends the row (`\\033[K\\033[J`); the bytes are the ones render() wrote before cockpit v3 S6."""
+        caller ends the row (`\\033[K\\033[J`); the bytes are the ones render() wrote before cockpit v3 S6. `d`'s
+        message (plan W10 W7) is one OSC 8 link to the whole URL, which a 36-cell row clips."""
         text, style, caret = self.footer_text(cols, entries, legend)
         reset = self.tone['reset']
         painted = f'{reset}{self.tone["tone-working"]}{self.glyphs["marks"]["caret"]}{reset}' if caret else ''
-        return f'{style}{text}{painted}{reset}'
+        return f'{style}{osc8(self.footer_link, text)}{painted}{reset}'
 
     def divider_line(self, entry, cols):
         """`── ◆ Needs you (3) ───` (spec §4.4), shared by the desktop and the phone (§4.10 "section headers as
@@ -3546,6 +3637,8 @@ class Sidebar:
                 self.request_hide_workspace()
             elif ch == 'o':
                 self.toggle_hidden()
+            elif ch == 'd':                   # plan W10 W7: the cursor lane's docs link in the footer
+                self.show_docs_link(entries[min(self.cursor, len(entries) - 1)] if entries else None)
             elif ch == 'P' and entries:
                 entry = entries[min(self.cursor, len(entries) - 1)]
                 self.start_promote(entry)

package/payload/lanes/libexec/statusd.py

@@ -13,10 +13,15 @@ It never INVENTS a state. "No answer" (a tmux, cgroup, docker or zmx read that t
 host) is not an observation: the lane keeps its last published state, marked stale, for at most STALE_MAX seconds
 and is 'unknown' after that. 'absent' / 'missing' are only published when a server answered without the session,
 or positively does not exist.
+
+The docs cockpit (plan W10 W7): a lane row carries `docs: {n, at}` while docs/counts.json counts documents for it
+(one stat of that file per cycle), and the document `web_origin`, the https origin the docs page answers on, once
+main() has learnt it between two cycles (refresh_origin).
 """
 import concurrent.futures
 import json
 import os
+import re
 import subprocess
 import sys
 import time
@@ -27,6 +32,7 @@ import lanes_lib as L  # noqa: E402
 import session_actions as A  # noqa: E402
 import agent_state as AS  # noqa: E402
 import guard as G  # noqa: E402
+import docs_store  # noqa: E402
 
 INTERVAL = float(os.environ.get('LANES_STATUS_INTERVAL', '3'))
 SLOWDOWN = {'ok': 1, 'busy': 2, 'critical': 4}   # a host under pressure gets FEWER spawns from us, not the same
@@ -56,6 +62,16 @@ FIELDS = ['session_name', 'pane_pid', 'pane_dead', 'window_activity', 'pane_curr
           'window_bell_flag', 'window_id', 'pane_id', 'pane_title']
 FORMAT = '\t'.join('#{' + f + '}' for f in FIELDS)
 VIEW_PREFIX = 'view-'   # a Throttle Studio browser attach: a grouped session named view-<studio>-<ch>
+# The docs cockpit (plan W10 W7, LNS-108). A lane row carries `docs: {n, at}` while docs/counts.json
+# (DM-LANES-DOCS-COUNTS) holds documents for it: ONE stat of that file per cycle, the file read only when it moved.
+# `web_origin` is the https origin Tailscale Serve answers on, the one the enrolment service announces (enrold
+# site_facts' host name: site.conf's LANES_SERVER_NAME, else this node's MagicDNS name), with Serve's port: the sidebar
+# builds its OSC 8 links to /lanes-docs/ on it and never forks to learn it. Resolved outside the cycle (main), at most
+# every ORIGIN_TTL seconds — enrold's own cache of the name — and not again on a host under pressure once known.
+WEB_PORT = 8443         # bin/lanes SERVE_PORT: `tailscale serve --https=8443` -> Caddy :8083 (web/Caddyfile)
+ORIGIN_TTL = 300        # enrold.TAILNET_TTL
+HOST_NAME = re.compile(r'(?=.{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])?)*\Z', re.ASCII)
 
 
 def log(where, error):
@@ -852,6 +868,68 @@ def update_containers(ctx, registry, level):
         info['running'] = pid_alive(info.get('pid'))
 
 
+def docs_counts(ctx):
+    """docs/counts.json as the lane rows carry it -> {lane id: {n, at}} ({} when absent or not valid). ONE os.stat of
+    the file per cycle; it is read (docs_store.read_counts: no link followed, no FIFO opened, the shape checked) only
+    when its (mtime, inode, size) moved since the last read — docs_store replaces it on every change."""
+    try:
+        info = os.stat(docs_store.counts_path())
+        stamp = (info.st_mtime_ns, info.st_ino, info.st_size)
+    except OSError:
+        stamp = None
+    if stamp != ctx.get('docs_stamp') or 'docs_counts' not in ctx:
+        ctx['docs_counts'] = docs_store.read_counts() if stamp else {}
+        ctx['docs_stamp'] = stamp
+    return ctx['docs_counts']
+
+
+def with_docs(lanes, counts):
+    """`lanes` with `docs: {n, at}` on every row counts.json gives documents (n > 0) and on no other row: absent at 0,
+    and dropped from a kept row whose lane has none any more. A row that changes is a NEW dict (DEF-1538: a kept row
+    may be the very object the published payload holds); the others are passed on as they are."""
+    out = {}
+    for lane_id, row in lanes.items():
+        entry = counts.get(lane_id) if isinstance(counts, dict) else None
+        want = {'n': entry['n'], 'at': entry['at']} if isinstance(entry, dict) and entry.get('n') else None
+        if not isinstance(row, dict) or row.get('docs') == want:
+            out[lane_id] = row
+            continue
+        row = {key: value for key, value in row.items() if key != 'docs'}
+        if want:
+            row['docs'] = want
+        out[lane_id] = row
+    return out
+
+
+def resolve_origin():
+    """`https://<name>:8443` — the origin the docs page answers on (Tailscale Serve -> Caddy), by the name enrold
+    announces (site_facts: site.conf's LANES_SERVER_NAME, else enrold.tailnet_name(), one bounded `tailscale status
+    --json` cached for its TAILNET_TTL), or None when there is no name or it is no DNS host name: it is written into
+    terminal OSC strings and links, so nothing but `[A-Za-z0-9.-]` ever reaches them."""
+    import enrold   # the enrolment service's own reader of the name; imported only when an origin is wanted
+    name = enrold.server_site().get('LANES_SERVER_NAME') or enrold.tailnet_name()
+    return f'https://{name}:{WEB_PORT}' if isinstance(name, str) and HOST_NAME.match(name) else None
+
+
+def refresh_origin(ctx, level, now=None):
+    """main()'s look for `web_origin`, never inside a cycle: at most every ORIGIN_TTL seconds, and on a host that is
+    not `ok` only while none is known yet (one bounded spawn, then it waits). -> True when it looked. A failure keeps
+    the last origin: an unanswered name is no reason to drop the links."""
+    now = time.time() if now is None else now
+    known = ctx.get('origin_at') is not None
+    if known and (now - ctx['origin_at'] < ORIGIN_TTL or level != 'ok'):
+        return False
+    ctx['origin_at'] = now
+    try:
+        origin = resolve_origin()
+    except Exception as error:
+        log('web origin', error)
+        return True
+    if origin or not known:
+        ctx['web_origin'] = origin
+    return True
+
+
 def build_payload(ctx, level, reconcile=True):
     """One observation pass -> the payload of status.json (None = there is no registry to observe). Every phase
     fails alone: what it could not observe is republished as last seen (stale), the other phases still run.
@@ -915,8 +993,15 @@ def build_payload(ctx, level, reconcile=True):
     # Outside the payload: it changes every cycle, and status.json is rewritten only on change (plus the heartbeat).
     ctx['zmx_listed_at'] = listed
     lanes.update(zmx_lanes)
-    return {'lanes': lanes, 'servers': servers, 'unregistered': unregistered, 'zmx': zmx_groups,
-            'containers': {k: {'running': v.get('running', False)} for k, v in containers.items()}}
+    try:   # plan W10 W7: the docs counts ride on the lane rows (one stat of docs/counts.json per cycle)
+        lanes = with_docs(lanes, docs_counts(ctx))
+    except Exception as error:
+        log('docs', error)
+    payload = {'lanes': lanes, 'servers': servers, 'unregistered': unregistered, 'zmx': zmx_groups,
+               'containers': {k: {'running': v.get('running', False)} for k, v in containers.items()}}
+    if ctx.get('web_origin'):   # additive, absent while no origin is known (refresh_origin, main())
+        payload['web_origin'] = ctx['web_origin']
+    return payload
 
 
 def new_context():
@@ -927,16 +1012,21 @@ def new_context():
     written = float(seed.get('updated_at') or 0)
     for entry in (seed.get('lanes') or {}).values():
         entry.setdefault('stale_since', int(written))
+    # The docs links' origin survives a restart (re-checked by main()'s first refresh_origin); only a valid one.
+    origin = seed.get('web_origin')
+    valid = (isinstance(origin, str) and origin.startswith('https://') and origin.endswith(f':{WEB_PORT}')
+             and HOST_NAME.match(origin[len('https://'):-len(f':{WEB_PORT}')]))
     return {'registry': None, 'stamp': 0, 'containers': {}, 'containers_at': 0.0,
             'payload': seed, 'published': None, 'status_at': written, 'cut': 0, 'unwalkable': [],
-            'container_status': {}, 'container_status_errors': {}}
+            'container_status': {}, 'container_status_errors': {}, 'web_origin': origin if valid else None}
 
 
 # ------------------------------------------- the in-container projection (LNS-32)
 # `~/.lz/status.json` in each workspace container: that container's slice of the payload, for the in-container Agent
 # API (`lane-mcp`, plan Track M), which cannot read the host's status.json. v1 = {v, at, lanes{<id>: {state, agent?,
-# attached?, viewers?, activity?, size?, stale?}}, unregistered[{id, name, workspace, boards, tmux, identity}]}.
-CONTAINER_STATUS_FIELDS = ('state', 'agent', 'attached', 'viewers', 'activity', 'size', 'stale')
+# attached?, viewers?, activity?, size?, stale?, docs?}}, unregistered[{id, name, workspace, boards, tmux, identity}]}.
+# `docs` (plan W10 W7, additive) is the host row's {n, at} verbatim, absent like there.
+CONTAINER_STATUS_FIELDS = ('state', 'agent', 'attached', 'viewers', 'activity', 'size', 'stale', 'docs')
 CONTAINER_STATUS_DIR = tuple(L.CONTAINER_HOME.strip('/').split('/')) + ('.lz',)
 CONTAINER_STATUS_FILE = 'status.json'
 
@@ -1147,6 +1237,8 @@ def main():
     while True:
         started = time.time()
         level, _payload = cycle(ctx)
+        # The docs links' origin (plan W10 W7): a bounded look between two cycles, never inside one.
+        refresh_origin(ctx, level)
         # Hot-reload: check if any terminals.json changed since we last synced.
         # Rate-limited to at most one triggered sync per HOT_SYNC_EVERY_S to avoid thrashing.
         if time.time() - last_triggered_sync > HOT_SYNC_EVERY_S and ctx['registry']:

package/payload/lanes/libexec/tokens.py

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
-"""The Lanes design tokens: ONE table, rendered seven ways. The sidebar imports `sgr_table` (truecolor, 256, 16 or
-none); `--kdl`, `--css`, `--sh`, `--md`, `--js` and `--ghostty-dark|--ghostty-light` write the Zellij theme, the phone
-CSS, the viewer's shell colour sets, the docs tables, the phone's terminal palette and the optional Ghostty palette
-files between markers; `--check` fails when any committed block differs. Spec:
+"""The Lanes design tokens: ONE table, rendered eight ways. The sidebar imports `sgr_table` (truecolor, 256, 16 or
+none); `--kdl`, `--css`, `--sh`, `--md`, `--js`, `--ghostty-dark|--ghostty-light` and `--docs-css` write the Zellij
+theme, the phone CSS, the viewer's shell colour sets, the docs tables, the phone's terminal palette, the optional
+Ghostty palette files and the docs page's CSS (plan W10 W6) between markers; `--check` fails when any committed block
+differs. Spec:
 docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md; palette v2 + the 256-colour set: cockpit v3 P1 (LNS-69).
 No third-party code; importable with no side effects."""
 import difflib
@@ -89,7 +90,10 @@ MARKS = {'cursor': ('▌', '|', 'accent'), 'viewing': ('›', '=', 'accent'), 'v
          # more`. The lowest of column 3's marks: pending, the viewports and the viewing mark win over it. Seven-bit
          # `^` is free in column 3 (`=` `2` `3` `~` are the others; the upload strip's `^` is no column-3 mark).
          'pinned': ('▲', '^', 'accent'),
-         'ok': ('✓', 'OK', 'tone-done'), 'fail': ('✗', 'X', 'tone-urgent')}
+         'ok': ('✓', 'OK', 'tone-done'), 'fail': ('✗', 'X', 'tone-urgent'),
+         # The docs cockpit on the upload strip (` ↑ uploads · ▤ docs 3  (U)`, plan W10 W7): the strip's own tone.
+         # Seven-bit `#` is free on that row (`^` uploads, `v` armed, `-` sep are the others).
+         'docs': ('▤', '#', 'ink-dim')}
 ECONOMY_TAIL = {'starving': ('⚠', '!', 'tone-attention'), 'downgraded': ('↓', 'v', 'tone-attention'), 'paid': ('$', '$', 'ink-dim')}
 MOBILE_AGENT_LABELS = {'needs_approval': 'Needs approval', 'needs_input': 'Needs you', 'working': 'Working',
                        'done': 'Done', 'errored': 'Error', 'shell': 'Shell', 'idle': 'Idle'}
@@ -242,6 +246,22 @@ def render_css():
     return '\n'.join(out) + '\n'
 
 
+# The docs page (plan W10 W6, LNS-107; web/docs.css) is its own HTML document, served by lanes-docsd, not the phone
+# shell: no html.lanes-mobile, no Zellij data-zj-theme. Its block puts the roles it paints on :root, dark by default and
+# light under the system's prefers-color-scheme, and only those roles (docs.css has a 2.5 KB cap; the full --css block
+# alone is 2 KB). test_docs_assets pins that docs.css uses exactly these.
+DOCS_ROLES = ('surface', 'surface-raised', 'line', 'ink', 'ink-dim', 'accent')
+
+
+def render_docs_css():
+    out = ['/* BEGIN lanes tokens (generated by libexec/tokens.py --docs-css; do not edit by hand) */', ':root {']
+    out += [f'  --lanes-{role}: {TOKENS["dark"][role]};' for role in DOCS_ROLES]
+    out += ['  color-scheme: dark;', '}', '@media (prefers-color-scheme: light) {', '  :root {']
+    out += [f'    --lanes-{role}: {TOKENS["light"][role]};' for role in DOCS_ROLES]
+    out += ['    color-scheme: light;', '  }', '}', '/* END lanes tokens */']
+    return '\n'.join(out) + '\n'
+
+
 # The painted roles as the viewer's shell variables (`tokens.sh`), in PAINTED order. LZ_DIM kept its v1 name.
 SH_NAMES = {'ink': 'LZ_INK', 'ink-dim': 'LZ_DIM', 'ink-faint': 'LZ_FAINT', 'accent': 'LZ_ACCENT',
             'tone-urgent': 'LZ_URGENT', 'tone-attention': 'LZ_ATTENTION', 'tone-working': 'LZ_WORKING',
@@ -333,14 +353,16 @@ def render_ghostty(variant):
 
 
 RENDERERS = {'kdl': render_kdl, 'css': render_css, 'sh': render_sh, 'md': render_md, 'js': render_js,
-             'ghostty-dark': lambda: render_ghostty('dark'), 'ghostty-light': lambda: render_ghostty('light')}
+             'ghostty-dark': lambda: render_ghostty('dark'), 'ghostty-light': lambda: render_ghostty('light'),
+             'docs-css': render_docs_css}
 TARGETS = {'kdl': 'zellij/config.kdl', 'css': 'web/mobile.css', 'sh': 'libexec/tokens.sh', 'md': 'docs/DESIGN.md',
            'js': 'web/mobile.js', 'ghostty-dark': 'client/ghostty/lanes-palette.conf',
-           'ghostty-light': 'client/ghostty/lanes-palette-light.conf'}
+           'ghostty-light': 'client/ghostty/lanes-palette-light.conf', 'docs-css': 'web/docs.css'}
 MARKERS = {'kdl': ('// BEGIN lanes tokens', '// END lanes tokens'), 'css': ('/* BEGIN lanes tokens', '/* END lanes tokens */'),
            'sh': ('# BEGIN lanes tokens', '# END lanes tokens'), 'md': ('<!-- BEGIN lanes tokens', '<!-- END lanes tokens -->'),
            'js': ('// BEGIN lanes tokens', '// END lanes tokens'),
-           'ghostty-dark': ('# BEGIN lanes tokens', '# END lanes tokens'), 'ghostty-light': ('# BEGIN lanes tokens', '# END lanes tokens')}
+           'ghostty-dark': ('# BEGIN lanes tokens', '# END lanes tokens'), 'ghostty-light': ('# BEGIN lanes tokens', '# END lanes tokens'),
+           'docs-css': ('/* BEGIN lanes tokens', '/* END lanes tokens */')}
 
 
 def render(kind):
@@ -392,7 +414,7 @@ def main(argv):
         return 0
     kind = argv[0].lstrip('-') if argv else ''
     if kind not in RENDERERS:
-        sys.exit('usage: tokens.py --kdl|--css|--sh|--md|--js|--ghostty-dark|--ghostty-light|--check|--write')
+        sys.exit('usage: tokens.py --kdl|--css|--sh|--md|--js|--ghostty-dark|--ghostty-light|--docs-css|--check|--write')
     sys.stdout.write(render(kind))
     return 0