From 2acde41e54f4f0976b629f9a74aff8d83106c141 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Wed, 11 Nov 2026 00:09:45 +0100
Subject: [PATCH] docs: the hive dashboard and agent page shrink to overviews

The hive dashboard and the per-agent page lose their control-by-control UI
description and endpoint tables from the handbook. The full text moves to
4-implementation/web-ui/dashboard.md and agent-page.md, and the handbook pages
keep what an operator needs to find and use them. Code comments that named the
old sections point at the new pages.
---
 docs/2-handbook/agents/web-page.md            | 435 +--------------
 docs/2-handbook/hives/README.md               |  11 +-
 docs/2-handbook/hives/dashboard.md            | 517 +-----------------
 .../agent-state/config-changes.md             |   2 +-
 .../agent-state/persistence.md                |   2 +-
 docs/4-implementation/networking/gateway.md   |   2 +-
 docs/4-implementation/web-ui/agent-page.md    | 424 ++++++++++++++
 docs/4-implementation/web-ui/dashboard.md     | 509 +++++++++++++++++
 docs/4-implementation/web-ui/shape.md         |   2 +-
 docs/5-project/process/gotchas.md             |   2 +-
 docs/README.md                                |   5 +-
 frontend/packages/agent/src/agent.css         |   6 +-
 .../packages/agent/src/components/Header.tsx  |   2 +-
 frontend/packages/agent/src/index.html        |   2 +-
 frontend/packages/agent/src/screen.html       |   6 +-
 frontend/packages/agent/src/types.ts          |   2 +-
 frontend/packages/dashboard/src/agents.js     |  20 +-
 frontend/packages/dashboard/src/common.css    |   2 +-
 frontend/packages/dashboard/src/dashboard.css |   2 +-
 frontend/packages/dashboard/src/index.html    |   2 +-
 .../shared/src/side-panel/hive-side-panel.js  |   2 +-
 hive-agent/src/login.rs                       |   2 +-
 hive-agent/src/web_ui/auth.rs                 |   2 +-
 hive-agent/src/web_ui/state.rs                |   4 +-
 nix/agent-modules/weston-vnc.nix              |   2 +-
 25 files changed, 1020 insertions(+), 947 deletions(-)
 create mode 100644 docs/4-implementation/web-ui/agent-page.md
 create mode 100644 docs/4-implementation/web-ui/dashboard.md

diff --git a/docs/2-handbook/agents/web-page.md b/docs/2-handbook/agents/web-page.md
index af5fd83d2..e0c9dfd5f 100644
--- a/docs/2-handbook/agents/web-page.md
+++ b/docs/2-handbook/agents/web-page.md
@@ -1,421 +1,24 @@
 # Per-agent page
 
-> Part of [Agents](README.md). See also:
-> [Shape (shared)](../../4-implementation/web-ui/shape.md) · [Dashboard layout](../hives/dashboard.md)
+> Part of [Agents](README.md). See also: [Dashboard layout](../hives/dashboard.md)
 
+Every agent's harness serves a page of its own, reached from the agent's row on
+the hive dashboard. It shows a live terminal view of what the agent is doing: its
+turns, tool calls and results as they happen, with the recent history replayed
+when you open it. The page has no message box; to write to an agent, use the
+terminal in the [swarm UI](../swarm/ui.md). Like the hive dashboard, it
+keeps shrinking, bit by bit.
 
-Two fixed-position layers frame a full-viewport terminal: a header and
-scrollable main content — plus a slide-in side panel for flyouts and long
-content. The page has no message box: to write to an agent, use the swarm
-UI's terminal.
+- **Header**: the agent's icon and name, a state badge (idle, thinking, needs
+  login), and pills for its inbox and todos. Selecting a pill opens the list in
+  a side panel. The inbox panel has **mark all read**, and the todos panel lets
+  you dismiss todos.
+- **State badge menu**: **cancel turn** stops the turn in flight, **new session**
+  starts the next turn without the resume session, and **log out** wipes the
+  agent's claude login (it then waits in `needs_login`).
+- **Stats page**: the agent's turn statistics. The same figures are in Grafana's
+  `agents` board.
 
-## Header
-
-Preact component tree (`Header.tsx` + `StatusChips.tsx` +
-`MetaNav.tsx` + `HeaderPill.tsx`, wired together in `Root.tsx`) — see
-`frontend/packages/agent/src/components/`. This section describes the
-rendered component tree: every element is Preact component output.
-
-**Fixed-overlay header** (`<header class="agent-header">`): frosted
-glass — `backdrop-filter: blur` lets scrolled terminal rows show
-through. Measures its own rendered height via `ResizeObserver`
-(`Header.tsx`) and writes it to a CSS custom property the content
-below reads for its offset, so content never overlaps the header
-regardless of how many rows of badges/pills wrap onto an extra line
-at a given viewport width. Two columns:
-
-<!-- vale write-good.Passive = NO -->
-- **Agent icon** (`<img class="agent-icon">`): fixed-size square
-  identity anchor — `width: 5em; height: 5em` with explicit pixel
-  sizing so the `<img>`'s intrinsic (large) dimensions don't push
-  the parent flex container open via `align-items: stretch`-driven
-  height feedback. Falls back to the dimmed hyperhive mark
-  (`/favicon.svg`) on load error (`/icon` 404s when the agent has no
-  `services.hyperhive.agent.icon` override — there is no server-side default image).
-- **Main column** (`.agent-header-main`, `Header.tsx`): two rows —
-  title (`◆ <label> ◆`) and, when set, the "swarm / hive" identity
-  line. Nothing else lives here; both rows are short, fixed-shape text
-  that doesn't wrap in practice, so this column's height stays stable
-  regardless of how many badges or pills are showing (a design
-  correction mid-review — the first pass put the variable-width
-  content here instead, which is exactly the kind of thing the
-  `ResizeObserver` measurement above exists to catch even when a
-  layout choice reintroduces it).
-- **Pills cluster** (`.agent-header-pills`, right-aligned): status
-  badges (`StatusChips.tsx`) and flyout triggers together in one row,
-  so the header reads as one identity zone + one status/actions zone:
-  - **Status badge**, one badge for liveness and turn state: `● alive`
-    (green) / `⊘ rate limited` (red) / `◌ needs login` / `◌ logging in` /
-    `○ offline` / `… connecting` / `💤 idle` / `🧠 thinking` /
-    `📦 compacting` / `… booting` + age suffix, or paused. Selecting it
-    opens a menu: `⏸ pause` / `▶ resume` (via the same hive-c0re-owned
-    `/api/pause/<name>` / `/api/resume/<name>` endpoints the dashboard
-    uses; pausing needs a write this unprivileged process can't make
-    directly), `■ cancel turn` (only while a turn is running),
-    `↻ new session` and `🔓 logout`. Cancel turn, new session and logout
-    need a second selection to confirm.
-  - **Model and effort badges** (`model · <name>`, `effort · <level>`):
-    display only. Each tooltip says where the value comes from
-    (`state.model_source` / `state.effort_source`: set on the swarm,
-    agent.nix, an existing `hyperhive-model` / `hyperhive-effort` file, or
-    the built-in default); the model's also says what the last turn
-    resolved it to. Both are set on the swarm: the swarm UI's agents page,
-    or `swarmctl agent inference set`
-    ([`inference.md`](../../4-implementation/swarm/inference.md)).
-  - On an ACP agent each badge shows the session's own value when it
-    doesn't offer the requested one. The effort badge is hidden
-    (`state.effort` is `null`) until the first turn has attached a
-    session, when the model offers no effort levels, and while a newly
-    set model waits for the next turn, since the levels come with the
-    model.
-  - **Ctx / cost badges**: `ctx · 142k` (last inference's prompt size,
-    tooltip shows % of context window) / `cost · 1.3M` (cumulative
-    tokens billed across every inference in the last turn).
-  - **Inbox / todos pills** (`📬 inbox · N` / `📋 todos · N`): hidden
-    when empty; selecting it opens the matching flyout in the side panel.
-  - **Profile avatar**: the signed-in user's initial, opening a popover with
-    their name and links to authelia's settings and sign-out pages, as on the
-    dashboard (`AgentUserMenu.tsx`). It shows only behind the gateway, where
-    the page shares the dashboard's origin and session; opened on the agent's
-    own port there is no sign-in and no avatar. The name comes from the
-    dashboard's `/api/whoami`, authelia's URL from the dashboard's
-    `/api/state`.
-  - **Links badge** (`🔗`): opens a popover listing `↑ dashboard`
-    (back-link to the host dashboard, `${dashboardBase}`)
-    followed by this agent's `agent_links()`-sourced navigation (stats,
-    screen when VNC is enabled, any `services.hyperhive.agent.dashboardLinks`
-    extras) — all as real `<a>` elements, not a `Dropdown`-style
-    command list, so ctrl/middle-click and "copy link address" keep
-    working. Each `AgentLink.kind` resolves differently: `container` →
-    same-origin path; `external` → already absolute. Same source
-    (`GET /api/state`'s `links` field) also feeds
-    `DashboardState.links` for the dashboard card's icon strip —
-    `agent_links()` in hive-agent is the single source of truth for
-    both. The dashboard link lives in this 🔗 popover. `cancel turn`,
-    `new session` and `log out` are rows of the state badge's menu, each
-    with a click-again confirm (see Actions below).
-<!-- vale write-good.Passive = YES -->
-
-Values throughout come from `GET /api/state`'s cold-load snapshot,
-kept in sync afterwards by the SSE stream (see Live view below) —
-`context_window_tokens` for the ctx badge tooltip, `qualified_label`
-(the hive-qualified `name@domain` form, used for the browser tab title
-so two tabs from different hives are distinguishable; the header's own
-`◆ <label> ◆` stays short).
-
-## Main content
-
-**Main content** (`<main class="agent-main">`): fills the viewport
-and scrolls behind the fixed header + footer.
-
-<!-- vale write-good.Passive = NO -->
-- `#status` overlay: empty when online; shows the login form / OAuth
-  URL when `status` is `needs_login_*`. The OAuth code input is
-  `type="password"` with a `👁 reveal` toggle that flips it back to
-  `text` on press so the operator can sanity-check the paste before
-  submit — avoids accidental on-screen token exposure to
-  shoulder-surfers or screenshots. `autocomplete="one-time-code"`
-  is the semantic value for OAuth codes (per WHATWG): browsers may
-  silently ignore `autocomplete="off"` on `type="password"`, but
-  browsers honour `one-time-code` and suppress the "save password
-  for this site?" prompt that would otherwise fire on submit.
-- Terminal-wrap: live event tail (sticky-bottom autoscroll +
-  `↓ N new` pill when not at bottom). The pill is **anchored in
-  `.agent-main`**, not in `log.parentElement = .terminal-wrap`:
-  `.terminal-wrap` applies `backdrop-filter: blur` for the frost
-  effect, which creates a CSS stacking context — anchoring the
-  pill inside that context would confine its `z-index` below the
-  fixed header in the root stacking context, and it'd never
-  float. `.agent-main` has no backdrop-filter (no stacking-context
-  creators), so the pill's `z-index` reaches the root and properly
-  composites above the header. Geometry is unchanged —
-  `.agent-main` and `.terminal-wrap` both `inset: 0` fill the same
-  area.
-<!-- vale write-good.Passive = YES -->
-
-## Side panel
-
-**Side panel** (slide-in from right): singleton shared with the
-dashboard's side panel shape. Carries inbox and todos flyouts (opened
-via the header pills) as well as long content (file previews, diffs,
-journald logs). Inbox flyout: unread messages addressed to this agent
-(`acked_at IS NULL`, newest-first, up to 30); reply messages indented
-with `↳ reply ·` in amber. A `✓ mark all read` button appears in the
-flyout header when the inbox is non-empty; selecting it confirms then
-POSTs cross-origin to the core dashboard's `POST
-/api/agent/{name}/mark-all-read`, which acks all pending messages for
-this agent so the harness won't receive wake-prompts for them. A `{
-marked: N }` pill surfaces the count. After the drain the inbox list
-empties on reload (the filter is `acked_at IS NULL`, so drained
-messages disappear). Todos flyout ("loose-ends v2"): the harness-local
-todos other subsystems push at this agent (`GET /api/todos`) — matrix,
-forge, and bash are the built-in producers, but any user-configured MCP
-server can push its own via the same in-agent socket. Each row shows the
-producing subsystem, an
-optional source label, a summary, and age. A checkbox per row plus a
-select-all / select-none / `✓ mark done` bulk row above the list POSTs
-the checked ids to `POST /api/todos/mark-done`, which dismisses them
-from the harness-local store (same effect as `cancel_loose_end(kind:
-"todo")`, just from the web UI instead of the agent's own tool calls).
-If the todo store errors or doesn't answer for any id, the endpoint returns
-500 naming how many ids failed, and the panel shows `failed: …` instead of
-`✓ marked done`.
-
-## Live view
-
-Each agent runs an `events::Bus`: a `tokio::sync::broadcast<LiveEvent>`
-plus a sqlite-backed history at `/harness/hyperhive-events.sqlite`.
-The harness emits `TurnStart { from, body, unread }`,
-`Stream(value)` (one per parsed stream-json line), `Note`,
-`TurnEnd { ok, note }`. Each event also carries a `ts` (unix
-seconds) — a flattened sibling of the event tag on both the live
-SSE frame and the replayed history rows. The web UI:
-
-- fetches `GET /events/history` on page load and replays the last
-  2000 events (oldest first);
-- then subscribes to `GET /events/stream` (SSE) for live tail;
-- shows a granular state badge above the terminal, driven
-  authoritatively from `/api/state.turn_state`. SSE turn_start /
-  turn_end still flip the badge instantly between renders;
-- terminal-themed: phosphor mauve glow, Crust bg,
-  backdrop-filter blur, row fade-in slide-up.
-
-The backfill/live-tail dedupe, sticky-bottom autoscroll, and "↓ N
-new" pill are the shared terminal-pane mechanics described in
-[Shape](../../4-implementation/web-ui/shape.md#shared-terminal-pane) — this page's log is one
-instance of that same factory.
-
-Per-stream rendering (see [`docs/4-implementation/web-ui/terminal-rendering.md`](../../4-implementation/web-ui/terminal-rendering.md) for
-the full row taxonomy and dispatch logic):
-
-- `Stream` `tool_use` →
-  - `Write` / `Edit`: collapsed `<details>` with a +/- diff body
-    (`-` lines from `input.old_string`, `+` lines from
-    `input.new_string` or every line of `input.content`).
-    Summary carries the path + line counts.
-  - others (`Read /path`, `Bash $ cmd`, `mcp__matrix__send_dm →
-    iris: "..."`, etc.): flat one-line per-tool format with
-    per-tool salient-arg extraction (`fmtToolUse`).
-- `Stream` `tool_result` short → flat `← ...`; long → collapsed
-  `<details>` `▸ ← Nl · headline` (select to expand full body).
-- `Stream` `thinking` → `.thinking` row with a `💭 thinking …`
-  indicator.
-- `Stream` `system` → handled by subtype: `plugin_install` and
-  `compact_boundary` emit muted notes; `commands_changed` emits an
-  expandable details row listing slash commands; `thinking_tokens`
-  updates a single in-place `🧠` counter; `init`, `result`, and
-  `rate_limit_event` drop silently (noise / used elsewhere); other
-  subtypes → muted `⚙ <subtype>` note.
-- `Note` → `· text`.
-- `TurnStart` → `◆ TURN ← <from>` with the wake-prompt body; a
-  muted `· HH:MM:SS` time suffix from the event `ts`.
-- `TurnEnd` → `✓ turn ok` / `✗ turn fail — note`, with a
-  `· HH:MM:SS · <duration>` suffix (duration = end − the paired
-  turn-start), triggers a `refreshState()`. The time suffix is
-  guarded on a numeric `ts`, so rows degrade cleanly when absent.
-
-## Actions
-
-The state badge's menu carries the actions on the agent's claude:
-
-- `cancel turn` — `POST /api/cancel` → SIGINT to the turn's claude and every
-  command it started (its process group), emits a Note. On an ACP agent
-  it sends the agent `session/cancel` instead, and SIGINT if the turn
-  hasn't ended 10s later. Offered while the state is `thinking`.
-- `new session` — `POST /api/new-session` (confirms first).
-  Arms a one-shot on the Bus; next turn runs without
-  `--continue`, dropping the resume session entirely.
-- `log out` — `POST /api/logout` (confirms first). Wipes OAuth
-  credential files, parks the agent in `needs_login`, and preserves
-  session history (`~/.claude/projects/`).
-
-`POST /api/compact` sets the deferred `Bus::request_compact()` flag and
-returns immediately. The harness runs the `/compact` at the next turn
-boundary (end of the in-flight turn, or `turn::run_pending_compact` when
-idle); output streams into the live panel, which ends with a `/compact done`
-or `/compact failed: …` note. It works mid-turn, not only when idle. Nothing
-on this page calls it now.
-
-## Per-agent endpoints
-
-Successful POSTs return 200 (no 303 redirects). Error responses
-use semantic status codes: **400** for missing/malformed input
-(`/api/todos/mark-done` with no todo ids), **500** only for genuine
-server/transport failures. `/compact` never conflicts: it queues
-and runs at the end of the current turn. The matching
-mutations fire `LiveEvent` variants on the per-agent bus, so the
-client doesn't refetch `/api/state` on submit — the SSE stream
-delivers the new state faster anyway.
-
-The agent has no login flow of its own. An agent without credentials
-reports `needs_login_idle`, the operator logs in from the swarm UI, and the
-credentials arrive from the swarm secret store.
-
-- `POST /api/cancel` — SIGINT the in-flight claude turn and the
-  commands it started. Emits a `LiveEvent::Note`.
-- `POST /api/compact` — run `/compact` on the persistent session
-  (same MCP config + system prompt + allowed tools as a normal
-  turn — only the stdin payload differs). Flips state to
-  `Compacting` via `Bus::set_state`, which emits
-  `TurnStateChanged`.
-- `POST /api/new-session` — arm a one-shot for the next turn to
-  drop `--continue`. Emits a `LiveEvent::Note`.
-- `POST /api/logout` — three-step teardown that re-uses the
-  existing `wait_for_login` resumption path:
-  1. SIGINT any running claude (matches `/api/cancel`'s pattern —
-     idempotent no-op when nothing is running) so the credential
-     wipe doesn't race a mid-API-call turn.
-  2. Delete only the OAuth credential files
-     (`.credentials.json` + `mcp-needs-auth-cache.json` under
-     `~/.claude/`). **Preserves** session history files
-     (`projects/<hash>/*.jsonl`), sessions, shell-snapshots,
-     plans, settings, telemetry, and the dir itself, so
-     `claude --continue` keeps working after a fresh login.
-     ⚠️ Deleting the whole `~/.claude/` directory instead breaks
-     session continuity — logout must stay narrowed to just the
-     credential files.
-  3. Flip `LoginState::NeedsLogin` + emit a `LiveEvent::Note`
-     naming the files it just deleted, then emit
-     `needs_login_idle`. The turn-loop's next iteration parks
-     into `wait_for_login`, which snapshots the credential dir
-     (now missing the wiped files) and resumes when a fresh
-     credentials file appears (a login from the swarm UI stores one,
-     and the agent installs it).
-
-  Always returns 200 with a body describing what happened — it
-  folds per-file errors into the response + the Note so the
-  operator sees them in the live panel rather than as an HTTP
-  error. Missing files (already logged out) count as
-  idempotent.
-- `GET /api/state` — cold-load snapshot (`StateSnapshot`) consumed by
-  the frontend (`useAgentState.ts`) on page load. Includes `turn_state`,
-  `context_window_tokens`, `qualified_label`,
-  `model`, `model_source`, `effort`, `effort_source`, `links`, and
-  other fields described inline throughout this document. All
-  subsequent state updates arrive via SSE.
-- `GET /api/dashboard-state` — lean snapshot of agent-owned fields
-  fetched once per running agent by the dashboard's container row to
-  get fresh values without relying on hive-c0re's periodic file-reads.
-  Returns `{ status_text?, status_set_at?, ctx_tokens?, context_window_tokens,
-  rate_limited, links }`. Only called when the container is running;
-  skipped (muted badges) when stopped. Also accessible via the gateway
-  at `/agent/<name>/api/dashboard-state`.
-- `GET /api/todos` — harness-local todos snapshot (loose-ends v2)
-  consumed by the todos flyout (`refreshTodos` / `buildTodosList`).
-  See the todos-flyout paragraph above for the producer/subsystem
-  model and the bulk mark-done row.
-- `GET /api/stats?window=24h|7d|30d|all` — time-bucketed turn analytics
-  `Snapshot` consumed by the `/stats` page. `all` ranges from the
-  earliest recorded turn with an adaptive bucket width.
-- `GET /icon` — agent's icon as `image/svg+xml`. Returns
-  `/etc/hyperhive/icon.svg` (set via `services.hyperhive.agent.icon` in `agent.nix`)
-  when present, otherwise **404** — there is no server-side default.
-  Consumers (dashboard container row, this page's own header icon)
-  hit `/icon` optimistically and fall back client-side on load failure
-  to the frontend-bundled `/favicon.svg` rather than probing first.
-- `GET /events/history` — replay buffer for the terminal.
-- `GET /screen` — VNC viewer page (minimal RFB-over-WebSocket
-  renderer — deliberately thin, just enough to display the
-  desktop + forward pointer + keyboard. A production-grade viewer
-  would vendor noVNC; this file ships the minimal in-tree variant).
-  Only accessible when `services.hyperhive.agent.gui.enable = true` in the agent's
-  `agent.nix`; the harness shows a 🖥 screen link in the state row
-  when `gui_vnc_port` is present. A `← agent` back-link in the page
-  header returns to the main per-agent page. Controls: `⤢ fit` CSS-downscales
-  the canvas to the window via `relayoutCanvas()` setting explicit
-  pixel dimensions on the canvas — *not* CSS `max-width/max-height`,
-  because a flex item's automatic minimum size (`min-width: auto`
-  resolves to the canvas's intrinsic framebuffer resolution) silently
-  clamps `max-*` back up, making fit mode a no-op that just centred +
-  clipped the oversized canvas. The fit-mode rules pin the canvas
-  with `flex: none; min-width: 0; min-height: 0` so the JS-set size
-  sticks. `⤡ match size` sends an RFB `SetDesktopSize` request so the
-  server (weston) changes its real output resolution to the window
-  dimensions; enabled once the server advertises the
-  `ExtendedDesktopSize` pseudo-encoding (`-308` rect in the header).
-  Fit-mode state persists in `localStorage` (`screen-fit`); default
-  is on. `sendPointer` rescales pointer coordinates so presses
-  land on the right pixel regardless of CSS scale.
-- `GET /screen/ws` — raw RFB byte relay: proxies WebSocket
-  frames to the weston VNC server at `127.0.0.1:<vnc_port>`.
-  Transparent to any RFB variant. VNC port comes from the
-  `HIVE_GUI_VNC_PORT` env var (a fixed port set on the harness
-  service when `services.hyperhive.agent.gui.enable`; see `weston-vnc.nix`).
-- `GET|POST /extra/<name>/…` — **extra web proxies** declared via
-  `services.hyperhive.agent.extraWebProxies` in `agent.nix` (serialised to the
-  `HIVE_EXTRA_WEB_PROXIES` env var as a JSON object
-  `{"<name>": "<upstream_url>"}`). Each entry mounts a transparent
-  reverse-proxy at `/extra/<name>/` that forwards every request (method,
-  headers, body) to the configured upstream, strips hop-by-hop headers
-  on both sides (repeated response headers such as two `Set-Cookie` lines
-  are all forwarded), and buffers the full response body (MVP — SSE
-  connections will appear as one large response rather than streaming).
-  The `/extra/` namespace ensures user-declared proxies can never
-  conflict with native agent endpoints. Upstream values are either an
-  `http(s)://` URL (forwarded via `reqwest`) or a Unix domain socket,
-  spelled `unix:<path>` (for example `unix:/run/myapp/http.sock`) — dialed
-  directly with a raw HTTP/1.1 client per request, since `reqwest` has
-  no UDS transport. Implemented in `web_ui/proxy.rs`.
-
-Bus events (new vocabulary on `/events/stream`):
-
-- `status_changed { status }` — `online` / `rate_limited` /
-  `needs_login_idle`. Drives the
-  alive-badge. The harness sets `rate_limited` when it detects a
-  429 response and clears it when the retry sleep expires.
-- `model_changed { model }` — drives the model chip. The harness emits it
-  when it applies or clears a swarm value.
-- `effort_changed { effort }` — drives the effort chip. The harness
-  emits it when it applies or clears a swarm value.
-- `token_usage_changed { ctx: TokenUsage, cost: TokenUsage }`
-  — drives the ctx + cost badges. Emitted from
-  `Bus::record_turn_usage` at turn-end; `ctx` is the last
-  inference's usage (current context size), `cost` is the
-  cumulative across every inference (the `result` event's
-  totals).
-- `turn_state_changed { state, since_unix }` — drives the
-  state badge (`idle`/`thinking`/`compacting`).
-
-## Stats page
-
-`GET /stats` is a separate per-agent page (served by the
-harness, linked from the per-agent page's `📊 stats →` and from
-each dashboard container row). A `← live` back-link in the page
-header returns to the main per-agent page. Turn analytics, read-only, from
-`/state/hyperhive-turn-stats.sqlite`. `GET /api/stats?window=
-24h|7d|30d|all` returns a time-bucketed `Snapshot`; the page renders
-it with Chart.js (bundled into `stats.js` via esbuild — no CDN
-dependency). Charts: turns, duration (p50 · p95 · avg), context
-tokens, token cost per bucket, a **turns-by-model** stacked bar
-(model choice drives token cost, so it sits directly under the
-cost chart), doughnuts for tool / wake-source / result mix, and a
-**result-trend** stacked bar — per-bucket `result_counts` so
-error / rate-limit / compaction outcomes are visible over time
-(the doughnut shows only the window total).
-A **favorite tools** doughnut shows the most-run shell commands —
-normalised `bash_commands` heads written per bash task by the
-hive-bash-daemon capture: the basename of the *first real command*,
-looking past `cd repo &&` prefixes, env-assignments, and
-prefix-runners like `sudo` / `env` (so `cd /repo && cargo build`
-records `cargo`, not `cd`). Read via `bash_breakdown`; the card
-stays hidden until the agent has run a bash command (a missing
-`bash_commands` table degrades to an empty list), so it never
-renders an empty chart.
-A summary chip row carries window totals, plus two
-token-efficiency chips derived from the bucket sums: **cache
-hit-rate** (`cache_read` over all input-side tokens) and
-**tokens/turn**. When `reminder_stats` is present (fetched via
-`ReminderRollup` RPC and merged into the snapshot in
-`web_ui/stats.rs::api_stats`) three more chips appear: **reminders
-scheduled / delivered / pending** for the window. When the
-per-session capture has data, a **first-turn ctx** chip shows the
-input tokens of the most recent fresh claude session's first turn —
-a proxy for system-prompt + AGENTS.md sprawl (a fresh session's first
-turn pays the full static prefix uncached). It's derived in `stats.rs`
-(`first_turn_ctx`: the first turn, `ORDER BY started_at LIMIT 1`, of
-the latest `sessions` row in the window) and stays out of the JSON
-until the `sessions` / `turn_stats.session_id` capture has rows — so
-the chip stays hidden on older dbs (inert-until-capture).
-`stats.rs` opens the sqlite db read-only and degrades to an
-empty snapshot on any error — the page is decorative, never
-authoritative.
+The header's parts, the live view, the endpoints the page and the harness serve,
+and the stats page are in
+[the agent page reference](../../4-implementation/web-ui/agent-page.md).
diff --git a/docs/2-handbook/hives/README.md b/docs/2-handbook/hives/README.md
index 314fc1a89..9d14506e0 100644
--- a/docs/2-handbook/hives/README.md
+++ b/docs/2-handbook/hives/README.md
@@ -99,15 +99,16 @@ For the code, these jump straight to the relevant section:
 - **"How does the dashboard SPA stay live without polling?"** →
   [`shape.md`](../../4-implementation/web-ui/shape.md) (SSE multiplexing,
   Worker-death self-heal, atomic repaint).
-- **"What does a container row contain?"** → [`dashboard.md`](dashboard.md)
-  (Container row, Selection bar).
+- **"What does a container row contain?"** →
+  [`dashboard.md`](../../4-implementation/web-ui/dashboard.md) (Container row,
+  Selection bar).
 - **"What endpoints does the dashboard expose?"** →
-  [`dashboard.md`](dashboard.md) (Dashboard endpoints, Dashboard event
-  channel).
+  [`dashboard.md`](../../4-implementation/web-ui/dashboard.md) (Dashboard endpoints,
+  Dashboard event channel).
 - **"How does the per-agent terminal render tool calls?"** →
   [`terminal-rendering.md`](../../4-implementation/web-ui/terminal-rendering.md)
   (the full row taxonomy and dispatch walkthrough); for a summary see
-  [`web-page.md`](../agents/web-page.md) (Per-stream rendering).
+  [`agent-page.md`](../../4-implementation/web-ui/agent-page.md) (Per-stream rendering).
 - **"Which CSS variable to use, and where are the colours defined?"** →
   [`css-vars.md`](../../4-implementation/web-ui/css-vars.md) (Palette, the
   single-source `base.css` rule).
diff --git a/docs/2-handbook/hives/dashboard.md b/docs/2-handbook/hives/dashboard.md
index c5ce56e31..e22efefeb 100644
--- a/docs/2-handbook/hives/dashboard.md
+++ b/docs/2-handbook/hives/dashboard.md
@@ -1,498 +1,33 @@
 # Dashboard layout
 
-> Part of [Hives](README.md). See also:
-> [Shape (shared)](../../4-implementation/web-ui/shape.md) · [Per-agent page](../agents/web-page.md)
+> Part of [Hives](README.md). See also: [Per-agent page](../agents/web-page.md)
 
-This page covers the per-hive UI that hive-c0re serves. Swarm-wide
-surfaces — the agent roster, agent creation, linking external forge and
-matrix accounts, the controller's job graph — are on the
-[swarm UI](../swarm/ui.md).
+The hive dashboard is the per-hive UI that hive-c0re serves at `/`. The
+[swarm UI](../swarm/ui.md) holds everything swarm-wide (the agent roster, agent
+creation, linking external forge and matrix accounts, the controller's job
+graph) and is where you do day-to-day work. The hive dashboard keeps shrinking:
+parts of it go, bit by bit.
 
-hive-c0re serves the dashboard at `/`.
-It has a fixed chrome header at the top and a `<main>` that shows exactly
-one tab pane at a time. The URL hash (`#agents`, `#rebuild`,
-`#kept`) drives which pane is
-active; hash changes don't reload the page.
+A fixed header holds the tab strip, a **pages** menu with links to the API docs
+and the swarm UI, and a profile menu with your authelia settings and sign-out.
+The URL hash (`#agents`, `#rebuild`, `#kept`) picks the tab.
 
-**Chrome header** (fixed, overlays the active tab pane):
-- **Pages menu**: a link icon at the right end of the chrome, beside the
-  profile avatar (`links-menu.js`, `@hive/shared`'s `LinksMenu`, the same
-  component the swarm UI uses for its service links), opening a popover with links to **api docs**
-  (`/api/docs/`) and **swarm** (the swarm
-  UI at the swarm apex domain, opened in a new tab). The swarm entry
-  comes from `state.swarm_public_url`, which hive-c0re reads from
-  `HIVE_SWARM_PUBLIC_URL` (set from `services.hyperhive.swarm.domain`);
-  with no domain set there is no swarm entry. The standalone pages link back to `/`.
-- **Profile menu**: the signed-in user's avatar at the right end of the
-  chrome (`user-menu.js`, the same component as the swarm UI's and the agent
-  page's). It opens a popover with the user's name and links to authelia's
-  settings and sign-out pages. The name comes from `/api/whoami`, which the
-  dashboard's nginx vhost proxies to authelia, and the links from
-  `state.authelia_public_url`, which hive-c0re reads from
-  `HIVE_AUTHELIA_PUBLIC_URL` (set from `services.hyperhive.swarm.authelia.url`).
-  If the name doesn't load the avatar shows a question mark, and without the URL the
-  popover has no links.
-- **Tab strip**: `◆ 4G3NTS ◆`, `◆ R3BU1LD QU3U3 ◆`,
-  `◆ K3PT ST4T3 ◆`.
-- **Banner-thin** (`░▒▓█▓▒░ HYPERHIVE / HIVE-C0RE / WE ARE THE WIRED ░▒▓█▓▒░`)
-  — sits below the tab strip.
-- **No warning banner.** No page shows hive-level warnings (host disk
-  pressure, failing background sweeps, forge boot failures, agents that
-  need a claude login). They live in a push-based registry
-  (`hive-c0re`'s `warnings.rs`): any subsystem raises or clears its own
-  entry through an RAII guard, and each raise logs one
-  `hive warning raised` line. The operator sees the registry as metrics and
-  Grafana alerts: see
-  [Hive-scoped metrics](../../4-implementation/scheduler/observability.md#hive-scoped-metrics-hive-c0re).
-  A container crash is a swarm-level Grafana alert on the crash watcher's
-  own log line, so a hive with no otel export has no operator-visible
-  warning signal beyond `/health/ready`.
-- **Browser tab title** — `hyperhive // h1ve-c0re` by default; updated
-  to `<swarm> / <hive> // h1ve-c0re` once `hive_name` / `swarm_name`
-  arrive in the state snapshot.
+- **4G3NTS** lists the hive's containers, one row each, sorted by name, with
+  the agent's status and the actions on it: rebuild, start, stop, destroy. A red
+  banner at the top says two agents hash to the same port. Rename one and
+  rebuild.
+- **R3BU1LD QU3U3** shows the rebuild queue and each build's log.
+- **K3PT ST4T3** lists agents with kept state and no container, with their size
+  and age. **PURG3** wipes one's state directory. The list also shows an agent
+  that's part-way through a spawn, because both look the same on disk: the row
+  says `offline` and the tab carries a warning.
 
-## 4G3NTS tab
-
-**C0NTAINERS** — live containers as a flat list, one row per
-container, sorted alphabetically by agent name; every container the
-rescan reports gets a row. Pulsing red banner at the top
-of this section if any two sub-agents hash to the same port
-(`port_conflicts` from `/api/state`): the operator must rename
-one of them and rebuild. `lifecycle::{spawn,rebuild}` also
-preflight this and refuse with a clear error message naming the
-conflicting agent.
-
-## K3PT ST4T3 tab
-
-Passive / rare-interaction state. `kept.js` renders it from the
-`/api/state` snapshot and keeps it live from the `tombstones_changed`
-stream event. (The rebuild queue and build logs are dashboard tabs too —
-see below.)
-
-Per-container CPU, memory and disk load isn't shown in the hive UI. The
-same figures go out as OTEL metrics and appear in Grafana (see
-[observability](../../4-implementation/scheduler/observability.md)). An agent's CPU and memory
-caps live per agent in the swarm UI.
-
-**K3PT ST4T3** — agents with kept state and **no container** (size + age +
-claude-creds badge). One action: `PURG3` (wipes the state
-dir; `POST /api/purge-tombstone/{name}`).
-
-⚠️ **Not only *destroyed* agents.** Nothing records a destroy: `Provision`
-writes every definition-side artifact (state subvolume,
-meta registration, topology entry) *before* the container exists,
-and that artifact set survives `lifecycle::destroy`. An agent
-part-way through a spawn is byte-identical on disk to a tombstone, and
-the pane lists both. The pane carries a standing warning to that effect, and
-the row badge says `offline` rather than `destroyed` — the absence of a
-container is all hive-c0re can actually prove. Fixing it properly
-needs a recorded destroy — **deferred** to the swarm-controller /
-snapshot-storage rework where the problem changes shape.
-
-## Build tab (`#rebuild`)
-
-The rebuild queue is the **R3BU1LD QU3U3** tab (`#rebuild`). It lives in `builds.js`, which `tabs.js` imports: the
-dashboard's one tab strip, `/api/state` snapshot and
-`/api/dashboard/stream` subscription serve them, with
-`rebuild_queue_changed` on the stream alongside the dashboard's other
-kinds.
-The 4G3NTS tab does **not** read the graph endpoint, by design — the swarm
-view stays independent of job-queue internals. Its per-agent pending
-badges are transient-only, and its queue-summary banner reads the much
-narrower `GET /api/jobq/rollup` instead (see Container row, below) — a
-handful of pre-tallied counts, not the graph. The banner's "view queue →"
-link goes to the `#rebuild` tab.
-
-**R3BU1LD QU3U3** — pending, in-flight, and recently settled container
-operations: rebuilds and first-spawns. One
-operation runs at a time; the worker drains FIFO. **Is a mounted
-`JobqGraph`** (the shared generic graph-viewer Preact component,
-`@hive/shared/jobq-graph.js` — the same one swarm-ui uses) —
-`builds.js` doesn't render the queue itself; it just mounts the component
-(`mountJobqGraph(container, props)`, since this page has no JSX
-pipeline) with an `onUpdate` callback to drive the two things below it
-that the generic view doesn't show. The component owns fetching, cold
-and live: `GET /api/jobq/graph` on mount, and a refetch via the mount
-handle's `.refresh()` on every `rebuild_queue_changed` SSE tick (that
-event is a bare `{ seq }` trigger carrying no queue payload; both
-dashboard pages treat the tick as a pure refetch trigger).
-
-Each row is one root graph node (`parent: null`); a multi-step op's
-per-agent subgraphs and sub-steps render as nodes within that one
-entry (structural `parent` edges define the tree; sibling order is
-array order, unchanged from the wire). A row shows a state glyph (`⏸`
-pending / `▶` running / `◐` finishing — own work done, a sub-node
-still running / `✔` done / `✖` failed / `⊘` cancelled / `·` skipped)
-and each step's own label/agent. A `Node`-kind dep on a sibling shows
-as a plain "waits on: `<label>`" text line under the row rather than a
-gutter rail — a rail breaks visually whenever a nested subtree sits
-between the two related rows, since a text line needs no continuous
-vertical space to draw.
-`builds.js` mounts the component with `cancellable` set, which turns on
-a per-node cancel button (`✕`) on any non-terminal row — the button
-calls the mount's `onCancel(id)` callback, and the page does the actual
-`POST /api/rebuild-queue/{id}/cancel`, matching that callback to its
-own domain concept (the component knows nothing about that endpoint).
-**Rows carry no source chip, kind label, timing, or build-log
-deep-link** — the generic graph wire doesn't carry those fields, and
-rows deliberately present exactly what the endpoint provides rather
-than reconstructing chrome hive-c0re doesn't send. Settled entries
-render their **full step tree**, not just a bare summary — the wire
-doesn't filter `Done` nodes out.
-
-**State filter.** A row of per-state checkboxes above
-the tree — one per lifecycle state, matching the row glyphs — lets the
-operator narrow which root groups render; unchecking a state re-fetches
-`GET /api/jobq/graph?states=<checked, comma-joined>` rather than
-hiding rows client-side, so the `onUpdate` callback's node list (and
-everything downstream of it) only
-ever sees what's actually shown. Filtering is by a **root's own**
-state, which is already its subtree's rolled-up answer, so the filter
-keeps or drops a whole group, never splitting mid-tree. Default selection is
-every state **except** `Done`/`Skipped` — a fresh queue view leads
-with what's still moving or needs attention, not the settled tail;
-builds.js omits the `states` param entirely (identical request to
-before this filter existed) when the operator has checked every state. Server-side: the query
-narrows [`Queue::graph_snapshot`]'s already-bounded (`MAX_HISTORY_DAGS`)
-root set — the history cap and the state filter are independent
-concerns, so a narrow filter never reaches further back in time to
-compensate.
-
-A build's output and history aren't on this page. hive-c0re logs every container build
-to the journal, and the swarm's `builds` Grafana board reads those lines: the builds with
-their outcome and runtime, and the output of the one you pick.
-
-## Container row
-
-A full-height **square agent icon** (5em, capped) on the left. The
-icon is the **selection toggle**: select (or Enter/Space) adds/removes
-the agent from the selection set; `aria-pressed` reflects the state;
-the tooltip says "select … for bulk actions" or "deselect … (or press
-Esc to clear all)." The `<img>` points at `<url>/icon`; load failure
-falls back to the dimmed hyperhive mark (`/favicon.svg`). The card
-body sits to the right with three stacked lines
-(`assets/agents.js::renderContainers`).
-
-<!-- vale write-good.Passive = NO -->
-**Icon layout + load strategy:** the `<img>` is absolutely
-positioned (`inset: 0`) inside the `.container-icon` wrapper —
-the wrapper is the flex child and sizes itself via `width: 5em` +
-`aspect-ratio: 1`, the `<img>` is out of flow so its load state
-(pending, loaded, broken) can never contribute intrinsic size or
-reflow the row. Without that, the row would briefly grow as the
-image's natural dimensions arrived, then snap back on
-`object-fit: contain`. The load itself is fire-and-forget: the
-dashboard doesn't pre-check whether the agent is reachable, it
-just lets the `<img>` try and listens for an `error` event. On
-failure the handler swaps the `src` to `/favicon.svg` (served by
-the dashboard itself, always reachable) and adds the
-`icon-unreachable` class for the dimmed look. When the dashboard
-already knows the container is stopped (`ContainerView.running = false`)
-the fallback fires immediately, skipping the doomed `<url>/icon`
-fetch entirely.
-<!-- vale write-good.Passive = YES -->
-
-<!-- vale write-good.Passive = NO -->
-**Line 1** — agent name (link → new tab), m1nd/ag3nt chip, an
-**icon-only nav strip** plus live agent-owned state, all populated
-async from a single `GET /api/dashboard-state` call to the agent's
-own hive-agent. The response (`DashboardState`) carries: `links` (nav
-strip entries — `📊 stats`, `🖥 screen` when GUI is enabled, plus any
-agent-declared `dashboardLinks` extras), `status_text` / `status_set_at` (agent
-self-reported status — the `(set N ago)` chip carries a `data-set-at`
-stamp and ticks every 30s to stay fresh across the long-lived keyed row
-cache), `rate_limited`. hive-agent is the single source
-of truth for all of these. The dashboard resolves each `AgentLink.kind`
-against a per-agent base URL depending on whether hive-gateway is in
-front (`StateSnapshot.gateway_enabled`, sourced from the
-`HIVE_GATEWAY_ENABLED` env). The c0re NixOS module sets that env
-unconditionally — the gateway always runs; the flag stays so the
-dashboard doesn't have to learn that. Gateway-on: base URL is
-`/agent/<name>` (same origin, gateway proxies to the
-per-agent harness — TCP or unix-domain depending on the agent's
-`HIVE_WEB_SOCKET` opt-in, see
-`docs/4-implementation/networking/gateway.md::Per-agent unix-socket upstream`).
-Gateway-off is the flag-absent fallback (a dashboard served outside a
-hyperhive deploy): base URL is
-`http://<host>:<container.port>` (direct TCP). External links are
-already absolute. The same base URL drives the primary agent-name
-link + favicon fetch, so the whole row routes through the gateway
-as a unit.
-<!-- vale write-good.Passive = YES -->
-
-<!-- vale write-good.Passive = NO -->
-**When the container is stopped** (`ContainerView.running = false`),
-the dashboard skips the async `dashboard-state` fetch entirely (the agent
-web server is down), so a single badge replaces the badge chain,
-the nav strip is empty, and status text and the rate-limited badge disappear. The agent icon goes straight to the dimmed
-`/favicon.svg` fallback instead of attempting a doomed load from the
-container's URL. Static fields — `pending_reminders`, `parent`, `config` link — remain visible
-regardless of run state.
-<!-- vale write-good.Passive = YES -->
-
-**Line 2** — status badges only (no per-card action buttons — actions
-live in the **selection bar** or the **per-agent `⋮` menu**, see
-below).
-
-### Status badges
-
-**Which single badge:** `ContainerView.failed`
-(systemd `ActiveState=failed` — the unit exhausted its bounded
-restarts and gave up on its own) draws a red `✖ gave up` badge;
-otherwise a plain muted `■ not running` — a container an operator
-stopped deliberately. Both states read `running: false`; `failed` is
-the orthogonal fact (a fourth one alongside `paused`/
-`needs_login`, same "independent flags, no state machine" shape —
-see `ContainerView`'s own doc comment) that tells them apart. An
-older hive-c0re without the field serves `failed: undefined`, which
-reads falsy — degrades cleanly to the single `not running` badge.
-
-When the container is running, status badges follow — `⊘ rate
-limited` (red, while the harness parks itself after a 429), `needs
-login` — plus **one `◐ pending-state…` pill per
-active transient** (replaces buttons during operator-initiated
-start / stop / restart / rebuild / destroy). An agent can carry
-**multiple transients at once** — for example a lease-exempt `prebuild`
-running alongside a `stop_for_update` on the same agent — and each
-renders as its own independent badge instead of collapsing
-into one label, matching the existing multi-badge convention this
-line already uses for `paused`.
-
-Any pending badge means the row is actually **running** something
-right now (see **Pending-badge derivation** below); every row
-carrying ≥1 badge keeps the amber row tint AND draws a **rotating
-amber ring** around the agent icon.
-
-**Pending-badge derivation:** transients only (`transientsState`,
-keyed `agent -> Map<kind, since_unix>`) — a transient is **derived
-from a job-queue node currently `Running`** against that agent, not
-declared per request, so its label follows the operation as it
-progresses (a rebuild reads `stop_for_update`, then `swap`, then
-`reconcile` rather than one constant `rebuilding` for its whole
-life). Two consequences for anything rendering it:
-
-- The label vocabulary is **open** — it's the node's own wire tag
-  (`NodeKind`'s `&str` conversion, the same strings the graph wire's node
-  labels carry), not a fixed set. Treat it as an opaque display
-  string; don't switch on specific values.
-- It's **not** exclusively operator-initiated, and **not** limited
-  to rebuild-shaped work — `running_transients()` in hive-c0re is
-  a status-only test (any `Running` node whose payload names a
-  non-empty agent lights a pill), so work the operator never
-  triggered (a crash-recover rebuild, a boot-sweep rebuild, a
-  lease-exempt `prebuild`) lights the same mechanism.
-
-Ops with no queue node behind them (destroy, migration) supply
-their own label directly via `TransientSet`/`TransientCleared`
-events carrying no backing node at all.
-
-**Queued (not-yet-started) work shows nothing on the card.** Only
-running work gets a per-agent pending badge, by design — the swarm
-view stays independent of job-queue internals. The queue-summary
-banner below is the only queued-work indicator on this tab, and it
-reads the narrow `/api/jobq/rollup` endpoint rather than the full
-graph.
-
-**Per-agent `⋮` overflow menu** — a `⋮` button appears on the right
-edge of each container row. Selecting it opens a small dropdown with
-per-agent actions and navigation links. Contents:
-
-- `↺ R3ST4RT` (running agents only) / `■ ST0P` (running only) /
-  `▶ ST4RT` (stopped only) — single-agent run-state toggles.
-  Identical to the bulk actions on the selection bar but operate
-  on one agent without requiring a selection.
-- `↻ R3BU1LD` — always available; queues a rebuild for this agent.
-- `DESTR0Y` / `PURG3` — destructive, each prompts for confirmation
-  via the themed dialog (see **Themed dialogs** below).
-
-**Build-queue summary banner** — when the job queue has any active
-work, a compact amber banner sits above the container list: `◐ build
-queue — N running · M queued — view queue →` (the link goes to the
-R3BU1LD QU3U3 tab). The shared `JobqRollup` Preact component
-(`@hive/shared/jobq-rollup.js` — the same one swarm-ui's `/jobs` page
-mounts, pointed at swarm-controller's own rollup endpoint instead),
-mounted once into `#jobq-rollup-section` by `agents.js::initJobqRollup`
-and refreshed via its own handle rather than being re-rendered by
-`renderContainers`. Reads `GET /api/jobq/rollup`
-(`hive-jobq-wire::state_rollup`) — `Vec<{ state, nodes, roots }>`,
-every lifecycle state present in a fixed order, zero counts included —
-rather than the full `/api/jobq/graph` tree: `running` sums the
-`Running` and `Finishing` entries' `roots` (`Finishing` = own work
-done, subtree still going, still in flight), `queued` reads the
-`Pending` entry's `roots`. `roots` specifically, not `nodes` — the
-banner means *N whole operations*, not raw steps (one rebuild is ~7
-nodes but 1 root); `nodes` exists on the same endpoint for a consumer
-that wants step-level counts instead, unused here.
-
-### Themed dialogs
-
-All confirmations and transient error notices use an in-app themed
-dialog system (`@hive/shared/modal.js`) rather than the browser's
-native `confirm()` / `alert()` chrome, so they match the Catppuccin
-palette and the OS can't style them away. Two primitives, both built
-on the `openDialog` core:
-
-- `themedConfirm({ message, danger, confirmLabel, checkboxes })`
-  — a modal confirm that resolves to `null` on cancel or an object
-  of checkbox states on confirm. Destructive actions pass
-  `danger: true` (the confirm button turns red and the cancel
-  button takes focus). Selecting the backdrop and `Esc` both cancel.
-- `themedToast(message, { type, ... })` — a non-blocking toast (top-right,
-  `info` / `error` / `ok`) for transient validation + action
-  failures, so an error doesn't lock the operator behind a modal.
-  Single-action errors autodismiss; bulk / partial-failure
-  summaries are sticky (select to dismiss) so they aren't missed.
-
-Every destructive run-state action (`ST0P`, `R3ST4RT`, `R3BU1LD`,
-`DESTR0Y`, `PURG3`) routes through `themedConfirm`, on both
-the per-agent `⋮` menu and the bulk selection bar.
-
-**Graceful stop** — the `■ ST0P` confirm dialog (per-agent and
-bulk) carries a `stop gracefully — let the agent finish its turn
-and flush state before the container stops` checkbox. When ticked,
-the action POSTs `/api/kill/<name>?graceful=true` (the bulk path
-appends the flag per-agent); unticked is the instant hard stop
-(`/api/kill/<name>` with no query). hive-c0re enqueues a
-`Signal` → `Drain` job-queue node pair (`NodeKind::Signal` /
-`NodeKind::Drain`): `Signal` sets the graceful-stop fence and kicks
-the harness so it runs one stop-checkpoint turn (so the agent can
-flush `/state`); `Drain` awaits the harness clearing that fence,
-bounded by a 3-minute timeout (`GRACEFUL_STOP_TIMEOUT`) that
-resolves either way and falls back to the downstream mechanical
-stop. The quiescing progress surfaces through the same
-rebuild-queue pending-badge mechanism the card already reads for a
-rebuild, driven by the `Signal`/`Drain` pair rather than a nix
-build. (The `hivectl stop --graceful` CLI flag enqueues the same
-`Signal`/`Drain` pair, so the dashboard and CLI paths behave
-identically.)
-
-## Selection bar
-
-Bulk actions (`R3ST4RT` / `ST0P` / `ST4RT` / `P4US3` / `R3SUM3` /
-`R3BU1LD` / `DESTR0Y` / `PURG3`) live here rather than as per-card
-buttons — see **Container row** above. Selecting an agent's icon
-toggles its selection (an in-memory `Set<name>`); `Esc` or the bar's
-`✕ clear` button drops everything. The selection persists across tab
-switches in-memory — the bar just hides on non-4G3NTS tabs since other
-tabs don't show the agent cards needed to cross-reference.
-
-When the operator selects one or more agents (via the icon), a sticky
-frosted-mauve bar slides up from the bottom of the viewport
-(`#selection-bar`, `position: fixed; bottom: 0`). It shows:
-
-<!-- vale write-good.Passive = NO -->
-- **Count + names** — "N agents selected · name1, name2, …"
-- **Bulk action buttons** — only enabled when ALL selected agents
-  support the action; greyed out with a tooltip naming the blockers
-  when the selection is mixed:
-  - `↺ R3ST4RT` — running agents only
-  - `■ ST0P` — running agents only
-  - `▶ ST4RT` — stopped agents only
-  - `⏸ P4US3` — unpaused agents only (orthogonal to running/stopped —
-    see **Container row**'s own pause/resume note)
-  - `▶ R3SUM3` — paused agents only
-  - `↻ R3BU1LD` — always available
-  - `DESTR0Y` / `PURG3` — always available
-<!-- vale write-good.Passive = YES -->
-
-  That list is the whole set — the bar offers no other bulk action.
-- **`✕ clear`** button + `Esc` key clear the entire selection.
-
-Every render prunes stale selections (agents destroyed while
-selected) before the bar appears.
-
-## Dashboard endpoints
-
-Also browsable interactively at `/api/docs` (a Swagger UI, linked from
-the pages menu's **api docs** entry), with the raw spec at `/api/openapi.json`.
-It's a growing supplement, not yet a full replacement for the list
-below — some endpoints aren't in it yet.
-
-- `POST /api/{rebuild,kill,restart,start,destroy,pause,resume}/{name}` —
-  lifecycle.
-  `destroy` accepts `purge=on` to also wipe state dirs.
-- `POST /api/purge-tombstone/{name}` — wipe a tombstone's state dirs.
-- `POST /api/rebuild-queue/{id}/cancel` — drop a `Queued` entry.
-  Refuses `Running` / terminal-state entries (in-flight
-  rebuilds can't be safely interrupted). Always 200; body is
-  `{"cancelled": true}` on a successful flip or
-  `{"cancelled": false}` when the entry wasn't in `Queued` state.
-- `POST /api/agent/{name}/mark-all-read` — ack all pending broker
-  messages for `{name}`. Backfills `delivered_at` for rows
-  not yet delivered and sets `acked_at = now`. Returns
-  `{ "marked": N }`. Agent name validated against
-  `[a-z0-9_-]`, 1-63 chars; 400 on bad input.
-- `GET /api/build-logs?limit=N` — most-recent build log headers across
-  all agents (`limit` defaults to 30).
-- `GET /api/build-log/{node_id}` and `/api/build-log/{node_id}/raw` — the
-  build log of one job-queue node, as JSON and as `text/plain`.
-- `GET /api/build-logs/{agent}?limit=N` — most-recent build log
-  headers for one agent, newest first. Returns
-  `Vec<BuildLogHeader>` (JSON): `id`, `agent`, `kind`, `cmdline`,
-  `started_at`, `finished_at`, `status` (`"ok"` / `"fail"` /
-  `null` while in-progress). `limit` defaults to 10, server-side
-  cap at 50. Agent name validated (`[a-z0-9_-]`, 1-63 chars).
-- `GET /api/build-logs/id/{id}` — full build log by id. Returns
-  `BuildLogFull` (JSON): all header fields plus `stdout` and
-  `stderr` as plain text (newline-terminated lines, utf-8). HTTP
-  404 when the row is missing (vacuum-reaped or stale id).
-- `GET /api/build-logs/id/{id}/stream` — live SSE stream of
-  stdout+stderr for an in-progress build (newline-delimited JSON
-  frames). The
-  stream closes when the build finishes or errors.
-- `GET /api/build-logs/id/{id}/raw` — raw concatenated
-  stdout+stderr as `text/plain`. Works on both finished and in-progress
-  build logs.
-
-- `GET /api/dashboard/stream` — unified live event channel:
-  broker `sent` / `delivered`, plus the mutation events listed
-  below. Each frame carries `seq`.
-  <!-- vale write-good.Passive = YES -->
-
-## Dashboard event channel
-
-Wire vocabulary on `/api/dashboard/stream` (kind tag is in the JSON
-payload):
-
-- `sent` / `delivered` — broker traffic, mirrored from the
-  intra-process channel by a forwarder task. Both carry `id: i64`
-  (the broker row id) and `in_reply_to: Option<i64>` for thread
-  rendering.
-- `transient_set` (name, transient_kind, since_unix) /
-  `transient_cleared` (name) — lifecycle action spinners. The
-  client ticks the elapsed-seconds badge off `since_unix`
-  client-side, no polling. `transient_kind` is an **open**
-  display string (the running node's own tag), not a fixed
-  enum — render it, don't branch on it.
-- `container_state_changed` (container: ContainerView) /
-  `container_removed` (name) — per-row container mutations,
-  emitted by `Coordinator::rescan_containers_and_emit` from
-  the job queue's own node execution (`job_queue::exec`, for example
-  after a rebuild's stop/swap/start steps or a destroy's teardown
-  step) — and from the 10s
-  `crash_watch` poll. Client upserts/removes by name and
-  reads the pending overlay from `transientsState` since the
-  payload doesn't carry it.
-- `rebuild_queue_changed` (seq) — **payload-free trigger**, fired on
-  every queue mutation (enqueue, state transition, dedup collapse,
-  terminal-history trim). Unlike the snapshot events below it ships
-  no state at all: the client re-fetches `GET /api/jobq/graph`, which
-  is where it reads the queue from cold too.
-- `tombstones_changed` (seq, tombstones: `Vec<TombstoneView>`) —
-  full snapshot of destroyed-but-state-kept agents. Emitted on
-  destroy, purge, and revive. The K3PT ST4T3 tab subscribes.
-
-
-<!-- vale write-good.Passive = NO -->
-`/api/state` is **only fetched on cold-load and on the few
-forms that mutate non-event-derived state** (PURG3, since
-tombstones aren't event-shaped yet). Every other section — transients,
-containers —
-derives from `/api/dashboard/stream` after the initial snapshot,
-maintaining its own client-side store and applying events on
-top.
-<!-- vale write-good.Passive = YES -->
-
-Generalised form helper: `form[data-confirm="…"]` pops
-`confirm()` before submit.
+Per-container CPU, memory and disk figures aren't shown here. They go out as
+metrics and appear in Grafana, and you set an agent's CPU and memory caps per
+agent in the swarm UI. The dashboard shows no hive warnings either; they show up
+as metrics and Grafana alerts (see
+[observability](../../4-implementation/scheduler/observability.md#hive-scoped-metrics-hive-c0re)).
 
+The container row, status badges, dialogs, the selection bar, the API endpoints
+and the event channel are in
+[the dashboard reference](../../4-implementation/web-ui/dashboard.md).
diff --git a/docs/4-implementation/agent-state/config-changes.md b/docs/4-implementation/agent-state/config-changes.md
index 98836c3fb..cdaeeed2c 100644
--- a/docs/4-implementation/agent-state/config-changes.md
+++ b/docs/4-implementation/agent-state/config-changes.md
@@ -205,7 +205,7 @@ each `git` call inline, never writing it into a repo's config, so
 no stored token sits in a repo an agent might one day read.
 
 The dashboard deep-links into this org — a `config repo` link
-per container row. See `docs/2-handbook/hives/dashboard.md`.
+per container row. See `docs/4-implementation/web-ui/dashboard.md`.
 
 ### Submitting agent's view of config repos
 
diff --git a/docs/4-implementation/agent-state/persistence.md b/docs/4-implementation/agent-state/persistence.md
index 1c0c4b1cf..59af116c3 100644
--- a/docs/4-implementation/agent-state/persistence.md
+++ b/docs/4-implementation/agent-state/persistence.md
@@ -247,7 +247,7 @@ Under `/var/lib/hyperhive/agents/<name>/`:
     has a value.
   - `hyperhive-harness.json` — rate-limited / needs-login flags read
     by the dashboard's async container-state fetch. See
-    `docs/2-handbook/hives/dashboard.md::Container row`.
+    `docs/4-implementation/web-ui/dashboard.md::Container row`.
 
   The agent writes its own instructions to `AGENTS.md` here; claude and
   opencode load it automatically from their cwd, `state/`. At boot,
diff --git a/docs/4-implementation/networking/gateway.md b/docs/4-implementation/networking/gateway.md
index a5d9e59ef..5d6554260 100644
--- a/docs/4-implementation/networking/gateway.md
+++ b/docs/4-implementation/networking/gateway.md
@@ -448,7 +448,7 @@ when `StateSnapshot.gateway_enabled` is true, and direct
 every hive, so the direct shape is a fallback for the variable being unset.
 Three render sites follow it: the agent-name link, the favicon fetch
 (`<url>/icon`), and the nav-strip `container`-kind links from
-`DashboardState.links` (`GET /api/dashboard-state`). See `docs/2-handbook/hives/dashboard.md::Container row` for the frontend side.
+`DashboardState.links` (`GET /api/dashboard-state`). See `docs/4-implementation/web-ui/dashboard.md::Container row` for the frontend side.
 
 ### Dialing another vhost by name (`verifiedProxyTo`)
 
diff --git a/docs/4-implementation/web-ui/agent-page.md b/docs/4-implementation/web-ui/agent-page.md
new file mode 100644
index 000000000..ac74d977e
--- /dev/null
+++ b/docs/4-implementation/web-ui/agent-page.md
@@ -0,0 +1,424 @@
+# Per-agent page: header, live view and endpoints
+
+The page each agent's harness serves: header, live view, side panel, actions,
+its endpoints and the stats page. The operator's overview is
+[the agent page](../../2-handbook/agents/web-page.md).
+
+Two fixed-position layers frame a full-viewport terminal: a header and
+scrollable main content — plus a slide-in side panel for flyouts and long
+content. The page has no message box: to write to an agent, use the swarm
+UI's terminal.
+
+## Header
+
+Preact component tree (`Header.tsx` + `StatusChips.tsx` +
+`MetaNav.tsx` + `HeaderPill.tsx`, wired together in `Root.tsx`) — see
+`frontend/packages/agent/src/components/`. This section describes the
+rendered component tree: every element is Preact component output.
+
+**Fixed-overlay header** (`<header class="agent-header">`): frosted
+glass — `backdrop-filter: blur` lets scrolled terminal rows show
+through. Measures its own rendered height via `ResizeObserver`
+(`Header.tsx`) and writes it to a CSS custom property the content
+below reads for its offset, so content never overlaps the header
+regardless of how many rows of badges/pills wrap onto an extra line
+at a given viewport width. Two columns:
+
+<!-- vale write-good.Passive = NO -->
+
+- **Agent icon** (`<img class="agent-icon">`): fixed-size square
+  identity anchor — `width: 5em; height: 5em` with explicit pixel
+  sizing so the `<img>`'s intrinsic (large) dimensions don't push
+  the parent flex container open via `align-items: stretch`-driven
+  height feedback. Falls back to the dimmed hyperhive mark
+  (`/favicon.svg`) on load error (`/icon` 404s when the agent has no
+  `services.hyperhive.agent.icon` override — there is no server-side default image).
+- **Main column** (`.agent-header-main`, `Header.tsx`): two rows —
+  title (`◆ <label> ◆`) and, when set, the "swarm / hive" identity
+  line. Nothing else lives here; both rows are short, fixed-shape text
+  that doesn't wrap in practice, so this column's height stays stable
+  regardless of how many badges or pills are showing (a design
+  correction mid-review — the first pass put the variable-width
+  content here instead, which is exactly the kind of thing the
+  `ResizeObserver` measurement above exists to catch even when a
+  layout choice reintroduces it).
+- **Pills cluster** (`.agent-header-pills`, right-aligned): status
+  badges (`StatusChips.tsx`) and flyout triggers together in one row,
+  so the header reads as one identity zone + one status/actions zone:
+  - **Status badge**, one badge for liveness and turn state: `● alive`
+    (green) / `⊘ rate limited` (red) / `◌ needs login` / `◌ logging in` /
+    `○ offline` / `… connecting` / `💤 idle` / `🧠 thinking` /
+    `📦 compacting` / `… booting` + age suffix, or paused. Selecting it
+    opens a menu: `⏸ pause` / `▶ resume` (via the same hive-c0re-owned
+    `/api/pause/<name>` / `/api/resume/<name>` endpoints the dashboard
+    uses; pausing needs a write this unprivileged process can't make
+    directly), `■ cancel turn` (only while a turn is running),
+    `↻ new session` and `🔓 logout`. Cancel turn, new session and logout
+    need a second selection to confirm.
+  - **Model and effort badges** (`model · <name>`, `effort · <level>`):
+    display only. Each tooltip says where the value comes from
+    (`state.model_source` / `state.effort_source`: set on the swarm,
+    agent.nix, an existing `hyperhive-model` / `hyperhive-effort` file, or
+    the built-in default); the model's also says what the last turn
+    resolved it to. Both are set on the swarm: the swarm UI's agents page,
+    or `swarmctl agent inference set`
+    ([`inference.md`](../swarm/inference.md)).
+  - On an ACP agent each badge shows the session's own value when it
+    doesn't offer the requested one. The effort badge is hidden
+    (`state.effort` is `null`) until the first turn has attached a
+    session, when the model offers no effort levels, and while a newly
+    set model waits for the next turn, since the levels come with the
+    model.
+  - **Ctx / cost badges**: `ctx · 142k` (last inference's prompt size,
+    tooltip shows % of context window) / `cost · 1.3M` (cumulative
+    tokens billed across every inference in the last turn).
+  - **Inbox / todos pills** (`📬 inbox · N` / `📋 todos · N`): hidden
+    when empty; selecting it opens the matching flyout in the side panel.
+  - **Profile avatar**: the signed-in user's initial, opening a popover with
+    their name and links to authelia's settings and sign-out pages, as on the
+    dashboard (`AgentUserMenu.tsx`). It shows only behind the gateway, where
+    the page shares the dashboard's origin and session; opened on the agent's
+    own port there is no sign-in and no avatar. The name comes from the
+    dashboard's `/api/whoami`, authelia's URL from the dashboard's
+    `/api/state`.
+  - **Links badge** (`🔗`): opens a popover listing `↑ dashboard`
+  (back-link to the host dashboard, `${dashboardBase}`)
+  followed by this agent's `agent_links()`-sourced navigation (stats,
+  screen when VNC is enabled, any `services.hyperhive.agent.dashboardLinks`
+  extras) — all as real `<a>` elements, not a `Dropdown`-style
+  command list, so ctrl/middle-click and "copy link address" keep
+  working. Each `AgentLink.kind` resolves differently: `container` →
+  same-origin path; `external` → already absolute. Same source
+  (`GET /api/state`'s `links` field) also feeds
+  `DashboardState.links` for the dashboard card's icon strip —
+  `agent_links()` in hive-agent is the single source of truth for
+  both. The dashboard link lives in this 🔗 popover. `cancel turn`,
+  `new session` and `log out` are rows of the state badge's menu, each
+  with a click-again confirm (see Actions below).
+  <!-- vale write-good.Passive = YES -->
+
+Values throughout come from `GET /api/state`'s cold-load snapshot,
+kept in sync afterwards by the SSE stream (see Live view below) —
+`context_window_tokens` for the ctx badge tooltip, `qualified_label`
+(the hive-qualified `name@domain` form, used for the browser tab title
+so two tabs from different hives are distinguishable; the header's own
+`◆ <label> ◆` stays short).
+
+## Main content
+
+**Main content** (`<main class="agent-main">`): fills the viewport
+and scrolls behind the fixed header + footer.
+
+<!-- vale write-good.Passive = NO -->
+
+- `#status` overlay: empty when online; shows the login form / OAuth
+  URL when `status` is `needs_login_*`. The OAuth code input is
+  `type="password"` with a `👁 reveal` toggle that flips it back to
+  `text` on press so the operator can sanity-check the paste before
+  submit — avoids accidental on-screen token exposure to
+  shoulder-surfers or screenshots. `autocomplete="one-time-code"`
+  is the semantic value for OAuth codes (per WHATWG): browsers may
+  silently ignore `autocomplete="off"` on `type="password"`, but
+  browsers honour `one-time-code` and suppress the "save password
+  for this site?" prompt that would otherwise fire on submit.
+- Terminal-wrap: live event tail (sticky-bottom autoscroll +
+`↓ N new` pill when not at bottom). The pill is **anchored in
+`.agent-main`**, not in `log.parentElement = .terminal-wrap`:
+`.terminal-wrap` applies `backdrop-filter: blur` for the frost
+effect, which creates a CSS stacking context — anchoring the
+pill inside that context would confine its `z-index` below the
+fixed header in the root stacking context, and it'd never
+float. `.agent-main` has no backdrop-filter (no stacking-context
+creators), so the pill's `z-index` reaches the root and properly
+composites above the header. Geometry is unchanged —
+`.agent-main` and `.terminal-wrap` both `inset: 0` fill the same
+area.
+<!-- vale write-good.Passive = YES -->
+
+## Side panel
+
+**Side panel** (slide-in from right): singleton shared with the
+dashboard's side panel shape. Carries inbox and todos flyouts (opened
+via the header pills) as well as long content (file previews, diffs,
+journald logs). Inbox flyout: unread messages addressed to this agent
+(`acked_at IS NULL`, newest-first, up to 30); reply messages indented
+with `↳ reply ·` in amber. A `✓ mark all read` button appears in the
+flyout header when the inbox is non-empty; selecting it confirms then
+POSTs cross-origin to the core dashboard's `POST
+/api/agent/{name}/mark-all-read`, which acks all pending messages for
+this agent so the harness won't receive wake-prompts for them. A `{
+marked: N }` pill surfaces the count. After the drain the inbox list
+empties on reload (the filter is `acked_at IS NULL`, so drained
+messages disappear). Todos flyout ("loose-ends v2"): the harness-local
+todos other subsystems push at this agent (`GET /api/todos`) — matrix,
+forge, and bash are the built-in producers, but any user-configured MCP
+server can push its own via the same in-agent socket. Each row shows the
+producing subsystem, an
+optional source label, a summary, and age. A checkbox per row plus a
+select-all / select-none / `✓ mark done` bulk row above the list POSTs
+the checked ids to `POST /api/todos/mark-done`, which dismisses them
+from the harness-local store (same effect as `cancel_loose_end(kind:
+"todo")`, just from the web UI instead of the agent's own tool calls).
+If the todo store errors or doesn't answer for any id, the endpoint returns
+500 naming how many ids failed, and the panel shows `failed: …` instead of
+`✓ marked done`.
+
+## Live view
+
+Each agent runs an `events::Bus`: a `tokio::sync::broadcast<LiveEvent>`
+plus a sqlite-backed history at `/harness/hyperhive-events.sqlite`.
+The harness emits `TurnStart { from, body, unread }`,
+`Stream(value)` (one per parsed stream-json line), `Note`,
+`TurnEnd { ok, note }`. Each event also carries a `ts` (unix
+seconds) — a flattened sibling of the event tag on both the live
+SSE frame and the replayed history rows. The web UI:
+
+- fetches `GET /events/history` on page load and replays the last
+  2000 events (oldest first);
+- then subscribes to `GET /events/stream` (SSE) for live tail;
+- shows a granular state badge above the terminal, driven
+  authoritatively from `/api/state.turn_state`. SSE turn_start /
+  turn_end still flip the badge instantly between renders;
+- terminal-themed: phosphor mauve glow, Crust bg,
+  backdrop-filter blur, row fade-in slide-up.
+
+The backfill/live-tail dedupe, sticky-bottom autoscroll, and "↓ N
+new" pill are the shared terminal-pane mechanics described in
+[Shape](../web-ui/shape.md#shared-terminal-pane) — this page's log is one
+instance of that same factory.
+
+Per-stream rendering (see [`docs/4-implementation/web-ui/terminal-rendering.md`](../web-ui/terminal-rendering.md) for
+the full row taxonomy and dispatch logic):
+
+- `Stream` `tool_use` →
+  - `Write` / `Edit`: collapsed `<details>` with a +/- diff body
+    (`-` lines from `input.old_string`, `+` lines from
+    `input.new_string` or every line of `input.content`).
+    Summary carries the path + line counts.
+  - others (`Read /path`, `Bash $ cmd`, `mcp__matrix__send_dm →
+iris: "..."`, etc.): flat one-line per-tool format with
+    per-tool salient-arg extraction (`fmtToolUse`).
+- `Stream` `tool_result` short → flat `← ...`; long → collapsed
+  `<details>` `▸ ← Nl · headline` (select to expand full body).
+- `Stream` `thinking` → `.thinking` row with a `💭 thinking …`
+  indicator.
+- `Stream` `system` → handled by subtype: `plugin_install` and
+  `compact_boundary` emit muted notes; `commands_changed` emits an
+  expandable details row listing slash commands; `thinking_tokens`
+  updates a single in-place `🧠` counter; `init`, `result`, and
+  `rate_limit_event` drop silently (noise / used elsewhere); other
+  subtypes → muted `⚙ <subtype>` note.
+- `Note` → `· text`.
+- `TurnStart` → `◆ TURN ← <from>` with the wake-prompt body; a
+  muted `· HH:MM:SS` time suffix from the event `ts`.
+- `TurnEnd` → `✓ turn ok` / `✗ turn fail — note`, with a
+  `· HH:MM:SS · <duration>` suffix (duration = end − the paired
+  turn-start), triggers a `refreshState()`. The time suffix is
+  guarded on a numeric `ts`, so rows degrade cleanly when absent.
+
+## Actions
+
+The state badge's menu carries the actions on the agent's claude:
+
+- `cancel turn` — `POST /api/cancel` → SIGINT to the turn's claude and every
+  command it started (its process group), emits a Note. On an ACP agent
+  it sends the agent `session/cancel` instead, and SIGINT if the turn
+  hasn't ended 10s later. Offered while the state is `thinking`.
+- `new session` — `POST /api/new-session` (confirms first).
+  Arms a one-shot on the Bus; next turn runs without
+  `--continue`, dropping the resume session entirely.
+- `log out` — `POST /api/logout` (confirms first). Wipes OAuth
+  credential files, parks the agent in `needs_login`, and preserves
+  session history (`~/.claude/projects/`).
+
+`POST /api/compact` sets the deferred `Bus::request_compact()` flag and
+returns immediately. The harness runs the `/compact` at the next turn
+boundary (end of the in-flight turn, or `turn::run_pending_compact` when
+idle); output streams into the live panel, which ends with a `/compact done`
+or `/compact failed: …` note. It works mid-turn, not only when idle. Nothing
+on this page calls it now.
+
+## Per-agent endpoints
+
+Successful POSTs return 200 (no 303 redirects). Error responses
+use semantic status codes: **400** for missing/malformed input
+(`/api/todos/mark-done` with no todo ids), **500** only for genuine
+server/transport failures. `/compact` never conflicts: it queues
+and runs at the end of the current turn. The matching
+mutations fire `LiveEvent` variants on the per-agent bus, so the
+client doesn't refetch `/api/state` on submit — the SSE stream
+delivers the new state faster anyway.
+
+The agent has no login flow of its own. An agent without credentials
+reports `needs_login_idle`, the operator logs in from the swarm UI, and the
+credentials arrive from the swarm secret store.
+
+- `POST /api/cancel` — SIGINT the in-flight claude turn and the
+  commands it started. Emits a `LiveEvent::Note`.
+- `POST /api/compact` — run `/compact` on the persistent session
+  (same MCP config + system prompt + allowed tools as a normal
+  turn — only the stdin payload differs). Flips state to
+  `Compacting` via `Bus::set_state`, which emits
+  `TurnStateChanged`.
+- `POST /api/new-session` — arm a one-shot for the next turn to
+  drop `--continue`. Emits a `LiveEvent::Note`.
+- `POST /api/logout` — three-step teardown that re-uses the
+  existing `wait_for_login` resumption path:
+  1. SIGINT any running claude (matches `/api/cancel`'s pattern —
+     idempotent no-op when nothing is running) so the credential
+     wipe doesn't race a mid-API-call turn.
+  2. Delete only the OAuth credential files
+     (`.credentials.json` + `mcp-needs-auth-cache.json` under
+     `~/.claude/`). **Preserves** session history files
+     (`projects/<hash>/*.jsonl`), sessions, shell-snapshots,
+     plans, settings, telemetry, and the dir itself, so
+     `claude --continue` keeps working after a fresh login.
+     ⚠️ Deleting the whole `~/.claude/` directory instead breaks
+     session continuity — logout must stay narrowed to just the
+     credential files.
+  3. Flip `LoginState::NeedsLogin` + emit a `LiveEvent::Note`
+     naming the files it just deleted, then emit
+     `needs_login_idle`. The turn-loop's next iteration parks
+     into `wait_for_login`, which snapshots the credential dir
+     (now missing the wiped files) and resumes when a fresh
+     credentials file appears (a login from the swarm UI stores one,
+     and the agent installs it).
+
+  Always returns 200 with a body describing what happened — it
+  folds per-file errors into the response + the Note so the
+  operator sees them in the live panel rather than as an HTTP
+  error. Missing files (already logged out) count as
+  idempotent.
+
+- `GET /api/state` — cold-load snapshot (`StateSnapshot`) consumed by
+  the frontend (`useAgentState.ts`) on page load. Includes `turn_state`,
+  `context_window_tokens`, `qualified_label`,
+  `model`, `model_source`, `effort`, `effort_source`, `links`, and
+  other fields described inline throughout this document. All
+  subsequent state updates arrive via SSE.
+- `GET /api/dashboard-state` — lean snapshot of agent-owned fields
+  fetched once per running agent by the dashboard's container row to
+  get fresh values without relying on hive-c0re's periodic file-reads.
+  Returns `{ status_text?, status_set_at?, ctx_tokens?, context_window_tokens,
+rate_limited, links }`. Only called when the container is running;
+  skipped (muted badges) when stopped. Also accessible via the gateway
+  at `/agent/<name>/api/dashboard-state`.
+- `GET /api/todos` — harness-local todos snapshot (loose-ends v2)
+  consumed by the todos flyout (`refreshTodos` / `buildTodosList`).
+  See the todos-flyout paragraph above for the producer/subsystem
+  model and the bulk mark-done row.
+- `GET /api/stats?window=24h|7d|30d|all` — time-bucketed turn analytics
+  `Snapshot` consumed by the `/stats` page. `all` ranges from the
+  earliest recorded turn with an adaptive bucket width.
+- `GET /icon` — agent's icon as `image/svg+xml`. Returns
+  `/etc/hyperhive/icon.svg` (set via `services.hyperhive.agent.icon` in `agent.nix`)
+  when present, otherwise **404** — there is no server-side default.
+  Consumers (dashboard container row, this page's own header icon)
+  hit `/icon` optimistically and fall back client-side on load failure
+  to the frontend-bundled `/favicon.svg` rather than probing first.
+- `GET /events/history` — replay buffer for the terminal.
+- `GET /screen` — VNC viewer page (minimal RFB-over-WebSocket
+  renderer — deliberately thin, just enough to display the
+  desktop + forward pointer + keyboard. A production-grade viewer
+  would vendor noVNC; this file ships the minimal in-tree variant).
+  Only accessible when `services.hyperhive.agent.gui.enable = true` in the agent's
+  `agent.nix`; the harness shows a 🖥 screen link in the state row
+  when `gui_vnc_port` is present. A `← agent` back-link in the page
+  header returns to the main per-agent page. Controls: `⤢ fit` CSS-downscales
+  the canvas to the window via `relayoutCanvas()` setting explicit
+  pixel dimensions on the canvas — _not_ CSS `max-width/max-height`,
+  because a flex item's automatic minimum size (`min-width: auto`
+  resolves to the canvas's intrinsic framebuffer resolution) silently
+  clamps `max-*` back up, making fit mode a no-op that just centred +
+  clipped the oversized canvas. The fit-mode rules pin the canvas
+  with `flex: none; min-width: 0; min-height: 0` so the JS-set size
+  sticks. `⤡ match size` sends an RFB `SetDesktopSize` request so the
+  server (weston) changes its real output resolution to the window
+  dimensions; enabled once the server advertises the
+  `ExtendedDesktopSize` pseudo-encoding (`-308` rect in the header).
+  Fit-mode state persists in `localStorage` (`screen-fit`); default
+  is on. `sendPointer` rescales pointer coordinates so presses
+  land on the right pixel regardless of CSS scale.
+- `GET /screen/ws` — raw RFB byte relay: proxies WebSocket
+  frames to the weston VNC server at `127.0.0.1:<vnc_port>`.
+  Transparent to any RFB variant. VNC port comes from the
+  `HIVE_GUI_VNC_PORT` env var (a fixed port set on the harness
+  service when `services.hyperhive.agent.gui.enable`; see `weston-vnc.nix`).
+- `GET|POST /extra/<name>/…` — **extra web proxies** declared via
+  `services.hyperhive.agent.extraWebProxies` in `agent.nix` (serialised to the
+  `HIVE_EXTRA_WEB_PROXIES` env var as a JSON object
+  `{"<name>": "<upstream_url>"}`). Each entry mounts a transparent
+  reverse-proxy at `/extra/<name>/` that forwards every request (method,
+  headers, body) to the configured upstream, strips hop-by-hop headers
+  on both sides (repeated response headers such as two `Set-Cookie` lines
+  are all forwarded), and buffers the full response body (MVP — SSE
+  connections will appear as one large response rather than streaming).
+  The `/extra/` namespace ensures user-declared proxies can never
+  conflict with native agent endpoints. Upstream values are either an
+  `http(s)://` URL (forwarded via `reqwest`) or a Unix domain socket,
+  spelled `unix:<path>` (for example `unix:/run/myapp/http.sock`) — dialed
+  directly with a raw HTTP/1.1 client per request, since `reqwest` has
+  no UDS transport. Implemented in `web_ui/proxy.rs`.
+
+Bus events (new vocabulary on `/events/stream`):
+
+- `status_changed { status }` — `online` / `rate_limited` /
+  `needs_login_idle`. Drives the
+  alive-badge. The harness sets `rate_limited` when it detects a
+  429 response and clears it when the retry sleep expires.
+- `model_changed { model }` — drives the model chip. The harness emits it
+  when it applies or clears a swarm value.
+- `effort_changed { effort }` — drives the effort chip. The harness
+  emits it when it applies or clears a swarm value.
+- `token_usage_changed { ctx: TokenUsage, cost: TokenUsage }`
+  — drives the ctx + cost badges. Emitted from
+  `Bus::record_turn_usage` at turn-end; `ctx` is the last
+  inference's usage (current context size), `cost` is the
+  cumulative across every inference (the `result` event's
+  totals).
+- `turn_state_changed { state, since_unix }` — drives the
+  state badge (`idle`/`thinking`/`compacting`).
+
+## Stats page
+
+`GET /stats` is a separate per-agent page (served by the
+harness, linked from the per-agent page's `📊 stats →` and from
+each dashboard container row). A `← live` back-link in the page
+header returns to the main per-agent page. Turn analytics, read-only, from
+`/state/hyperhive-turn-stats.sqlite`. `GET /api/stats?window=
+24h|7d|30d|all` returns a time-bucketed `Snapshot`; the page renders
+it with Chart.js (bundled into `stats.js` via esbuild — no CDN
+dependency). Charts: turns, duration (p50 · p95 · avg), context
+tokens, token cost per bucket, a **turns-by-model** stacked bar
+(model choice drives token cost, so it sits directly under the
+cost chart), doughnuts for tool / wake-source / result mix, and a
+**result-trend** stacked bar — per-bucket `result_counts` so
+error / rate-limit / compaction outcomes are visible over time
+(the doughnut shows only the window total).
+A **favorite tools** doughnut shows the most-run shell commands —
+normalised `bash_commands` heads written per bash task by the
+hive-bash-daemon capture: the basename of the _first real command_,
+looking past `cd repo &&` prefixes, env-assignments, and
+prefix-runners like `sudo` / `env` (so `cd /repo && cargo build`
+records `cargo`, not `cd`). Read via `bash_breakdown`; the card
+stays hidden until the agent has run a bash command (a missing
+`bash_commands` table degrades to an empty list), so it never
+renders an empty chart.
+A summary chip row carries window totals, plus two
+token-efficiency chips derived from the bucket sums: **cache
+hit-rate** (`cache_read` over all input-side tokens) and
+**tokens/turn**. When `reminder_stats` is present (fetched via
+`ReminderRollup` RPC and merged into the snapshot in
+`web_ui/stats.rs::api_stats`) three more chips appear: **reminders
+scheduled / delivered / pending** for the window. When the
+per-session capture has data, a **first-turn ctx** chip shows the
+input tokens of the most recent fresh claude session's first turn —
+a proxy for system-prompt + AGENTS.md sprawl (a fresh session's first
+turn pays the full static prefix uncached). It's derived in `stats.rs`
+(`first_turn_ctx`: the first turn, `ORDER BY started_at LIMIT 1`, of
+the latest `sessions` row in the window) and stays out of the JSON
+until the `sessions` / `turn_stats.session_id` capture has rows — so
+the chip stays hidden on older dbs (inert-until-capture).
+`stats.rs` opens the sqlite db read-only and degrades to an
+empty snapshot on any error — the page is decorative, never
+authoritative.
diff --git a/docs/4-implementation/web-ui/dashboard.md b/docs/4-implementation/web-ui/dashboard.md
new file mode 100644
index 000000000..b70444d44
--- /dev/null
+++ b/docs/4-implementation/web-ui/dashboard.md
@@ -0,0 +1,509 @@
+# Hive dashboard: tabs, container rows and endpoints
+
+The hive UI that hive-c0re serves at `/`, tab by tab, with its endpoints and
+event channel. The operator's overview is
+[the dashboard page](../../2-handbook/hives/dashboard.md); the swarm UI is
+where day-to-day work happens.
+
+This page covers the per-hive UI that hive-c0re serves. Swarm-wide
+surfaces — the agent roster, agent creation, linking external forge and
+matrix accounts, the controller's job graph — are on the
+[swarm UI](../../2-handbook/swarm/ui.md).
+
+hive-c0re serves the dashboard at `/`.
+It has a fixed chrome header at the top and a `<main>` that shows exactly
+one tab pane at a time. The URL hash (`#agents`, `#rebuild`,
+`#kept`) drives which pane is
+active; hash changes don't reload the page.
+
+**Chrome header** (fixed, overlays the active tab pane):
+
+- **Pages menu**: a link icon at the right end of the chrome, beside the
+  profile avatar (`links-menu.js`, `@hive/shared`'s `LinksMenu`, the same
+  component the swarm UI uses for its service links), opening a popover with links to **api docs**
+  (`/api/docs/`) and **swarm** (the swarm
+  UI at the swarm apex domain, opened in a new tab). The swarm entry
+  comes from `state.swarm_public_url`, which hive-c0re reads from
+  `HIVE_SWARM_PUBLIC_URL` (set from `services.hyperhive.swarm.domain`);
+  with no domain set there is no swarm entry. The standalone pages link back to `/`.
+- **Profile menu**: the signed-in user's avatar at the right end of the
+  chrome (`user-menu.js`, the same component as the swarm UI's and the agent
+  page's). It opens a popover with the user's name and links to authelia's
+  settings and sign-out pages. The name comes from `/api/whoami`, which the
+  dashboard's nginx vhost proxies to authelia, and the links from
+  `state.authelia_public_url`, which hive-c0re reads from
+  `HIVE_AUTHELIA_PUBLIC_URL` (set from `services.hyperhive.swarm.authelia.url`).
+  If the name doesn't load the avatar shows a question mark, and without the URL the
+  popover has no links.
+- **Tab strip**: `◆ 4G3NTS ◆`, `◆ R3BU1LD QU3U3 ◆`,
+  `◆ K3PT ST4T3 ◆`.
+- **Banner-thin** (`░▒▓█▓▒░ HYPERHIVE / HIVE-C0RE / WE ARE THE WIRED ░▒▓█▓▒░`)
+  — sits below the tab strip.
+- **No warning banner.** No page shows hive-level warnings (host disk
+  pressure, failing background sweeps, forge boot failures, agents that
+  need a claude login). They live in a push-based registry
+  (`hive-c0re`'s `warnings.rs`): any subsystem raises or clears its own
+  entry through an RAII guard, and each raise logs one
+  `hive warning raised` line. The operator sees the registry as metrics and
+  Grafana alerts: see
+  [Hive-scoped metrics](../scheduler/observability.md#hive-scoped-metrics-hive-c0re).
+  A container crash is a swarm-level Grafana alert on the crash watcher's
+  own log line, so a hive with no otel export has no operator-visible
+  warning signal beyond `/health/ready`.
+- **Browser tab title** — `hyperhive // h1ve-c0re` by default; updated
+  to `<swarm> / <hive> // h1ve-c0re` once `hive_name` / `swarm_name`
+  arrive in the state snapshot.
+
+## 4G3NTS tab
+
+**C0NTAINERS** — live containers as a flat list, one row per
+container, sorted alphabetically by agent name; every container the
+rescan reports gets a row. Pulsing red banner at the top
+of this section if any two sub-agents hash to the same port
+(`port_conflicts` from `/api/state`): the operator must rename
+one of them and rebuild. `lifecycle::{spawn,rebuild}` also
+preflight this and refuse with a clear error message naming the
+conflicting agent.
+
+## K3PT ST4T3 tab
+
+Passive / rare-interaction state. `kept.js` renders it from the
+`/api/state` snapshot and keeps it live from the `tombstones_changed`
+stream event. (The rebuild queue and build logs are dashboard tabs too —
+see below.)
+
+Per-container CPU, memory and disk load isn't shown in the hive UI. The
+same figures go out as OTEL metrics and appear in Grafana (see
+[observability](../scheduler/observability.md)). An agent's CPU and memory
+caps live per agent in the swarm UI.
+
+**K3PT ST4T3** — agents with kept state and **no container** (size + age +
+claude-creds badge). One action: `PURG3` (wipes the state
+dir; `POST /api/purge-tombstone/{name}`).
+
+⚠️ **Not only _destroyed_ agents.** Nothing records a destroy: `Provision`
+writes every definition-side artifact (state subvolume,
+meta registration, topology entry) _before_ the container exists,
+and that artifact set survives `lifecycle::destroy`. An agent
+part-way through a spawn is byte-identical on disk to a tombstone, and
+the pane lists both. The pane carries a standing warning to that effect, and
+the row badge says `offline` rather than `destroyed` — the absence of a
+container is all hive-c0re can actually prove. Fixing it properly
+needs a recorded destroy — **deferred** to the swarm-controller /
+snapshot-storage rework where the problem changes shape.
+
+## Build tab (`#rebuild`)
+
+The rebuild queue is the **R3BU1LD QU3U3** tab (`#rebuild`). It lives in `builds.js`, which `tabs.js` imports: the
+dashboard's one tab strip, `/api/state` snapshot and
+`/api/dashboard/stream` subscription serve them, with
+`rebuild_queue_changed` on the stream alongside the dashboard's other
+kinds.
+The 4G3NTS tab does **not** read the graph endpoint, by design — the swarm
+view stays independent of job-queue internals. Its per-agent pending
+badges are transient-only, and its queue-summary banner reads the much
+narrower `GET /api/jobq/rollup` instead (see Container row, below) — a
+handful of pre-tallied counts, not the graph. The banner's "view queue →"
+link goes to the `#rebuild` tab.
+
+**R3BU1LD QU3U3** — pending, in-flight, and recently settled container
+operations: rebuilds and first-spawns. One
+operation runs at a time; the worker drains FIFO. **Is a mounted
+`JobqGraph`** (the shared generic graph-viewer Preact component,
+`@hive/shared/jobq-graph.js` — the same one swarm-ui uses) —
+`builds.js` doesn't render the queue itself; it just mounts the component
+(`mountJobqGraph(container, props)`, since this page has no JSX
+pipeline) with an `onUpdate` callback to drive the two things below it
+that the generic view doesn't show. The component owns fetching, cold
+and live: `GET /api/jobq/graph` on mount, and a refetch via the mount
+handle's `.refresh()` on every `rebuild_queue_changed` SSE tick (that
+event is a bare `{ seq }` trigger carrying no queue payload; both
+dashboard pages treat the tick as a pure refetch trigger).
+
+Each row is one root graph node (`parent: null`); a multi-step op's
+per-agent subgraphs and sub-steps render as nodes within that one
+entry (structural `parent` edges define the tree; sibling order is
+array order, unchanged from the wire). A row shows a state glyph (`⏸`
+pending / `▶` running / `◐` finishing — own work done, a sub-node
+still running / `✔` done / `✖` failed / `⊘` cancelled / `·` skipped)
+and each step's own label/agent. A `Node`-kind dep on a sibling shows
+as a plain "waits on: `<label>`" text line under the row rather than a
+gutter rail — a rail breaks visually whenever a nested subtree sits
+between the two related rows, since a text line needs no continuous
+vertical space to draw.
+`builds.js` mounts the component with `cancellable` set, which turns on
+a per-node cancel button (`✕`) on any non-terminal row — the button
+calls the mount's `onCancel(id)` callback, and the page does the actual
+`POST /api/rebuild-queue/{id}/cancel`, matching that callback to its
+own domain concept (the component knows nothing about that endpoint).
+**Rows carry no source chip, kind label, timing, or build-log
+deep-link** — the generic graph wire doesn't carry those fields, and
+rows deliberately present exactly what the endpoint provides rather
+than reconstructing chrome hive-c0re doesn't send. Settled entries
+render their **full step tree**, not just a bare summary — the wire
+doesn't filter `Done` nodes out.
+
+**State filter.** A row of per-state checkboxes above
+the tree — one per lifecycle state, matching the row glyphs — lets the
+operator narrow which root groups render; unchecking a state re-fetches
+`GET /api/jobq/graph?states=<checked, comma-joined>` rather than
+hiding rows client-side, so the `onUpdate` callback's node list (and
+everything downstream of it) only
+ever sees what's actually shown. Filtering is by a **root's own**
+state, which is already its subtree's rolled-up answer, so the filter
+keeps or drops a whole group, never splitting mid-tree. Default selection is
+every state **except** `Done`/`Skipped` — a fresh queue view leads
+with what's still moving or needs attention, not the settled tail;
+builds.js omits the `states` param entirely (identical request to
+before this filter existed) when the operator has checked every state. Server-side: the query
+narrows [`Queue::graph_snapshot`]'s already-bounded (`MAX_HISTORY_DAGS`)
+root set — the history cap and the state filter are independent
+concerns, so a narrow filter never reaches further back in time to
+compensate.
+
+A build's output and history aren't on this page. hive-c0re logs every container build
+to the journal, and the swarm's `builds` Grafana board reads those lines: the builds with
+their outcome and runtime, and the output of the one you pick.
+
+## Container row
+
+A full-height **square agent icon** (5em, capped) on the left. The
+icon is the **selection toggle**: select (or Enter/Space) adds/removes
+the agent from the selection set; `aria-pressed` reflects the state;
+the tooltip says "select … for bulk actions" or "deselect … (or press
+Esc to clear all)." The `<img>` points at `<url>/icon`; load failure
+falls back to the dimmed hyperhive mark (`/favicon.svg`). The card
+body sits to the right with three stacked lines
+(`assets/agents.js::renderContainers`).
+
+<!-- vale write-good.Passive = NO -->
+
+**Icon layout + load strategy:** the `<img>` is absolutely
+positioned (`inset: 0`) inside the `.container-icon` wrapper —
+the wrapper is the flex child and sizes itself via `width: 5em` +
+`aspect-ratio: 1`, the `<img>` is out of flow so its load state
+(pending, loaded, broken) can never contribute intrinsic size or
+reflow the row. Without that, the row would briefly grow as the
+image's natural dimensions arrived, then snap back on
+`object-fit: contain`. The load itself is fire-and-forget: the
+dashboard doesn't pre-check whether the agent is reachable, it
+just lets the `<img>` try and listens for an `error` event. On
+failure the handler swaps the `src` to `/favicon.svg` (served by
+the dashboard itself, always reachable) and adds the
+`icon-unreachable` class for the dimmed look. When the dashboard
+already knows the container is stopped (`ContainerView.running = false`)
+the fallback fires immediately, skipping the doomed `<url>/icon`
+fetch entirely.
+
+<!-- vale write-good.Passive = YES -->
+
+<!-- vale write-good.Passive = NO -->
+
+**Line 1** — agent name (link → new tab), m1nd/ag3nt chip, an
+**icon-only nav strip** plus live agent-owned state, all populated
+async from a single `GET /api/dashboard-state` call to the agent's
+own hive-agent. The response (`DashboardState`) carries: `links` (nav
+strip entries — `📊 stats`, `🖥 screen` when GUI is enabled, plus any
+agent-declared `dashboardLinks` extras), `status_text` / `status_set_at` (agent
+self-reported status — the `(set N ago)` chip carries a `data-set-at`
+stamp and ticks every 30s to stay fresh across the long-lived keyed row
+cache), `rate_limited`. hive-agent is the single source
+of truth for all of these. The dashboard resolves each `AgentLink.kind`
+against a per-agent base URL depending on whether hive-gateway is in
+front (`StateSnapshot.gateway_enabled`, sourced from the
+`HIVE_GATEWAY_ENABLED` env). The c0re NixOS module sets that env
+unconditionally — the gateway always runs; the flag stays so the
+dashboard doesn't have to learn that. Gateway-on: base URL is
+`/agent/<name>` (same origin, gateway proxies to the
+per-agent harness — TCP or unix-domain depending on the agent's
+`HIVE_WEB_SOCKET` opt-in, see
+`docs/4-implementation/networking/gateway.md::Per-agent unix-socket upstream`).
+Gateway-off is the flag-absent fallback (a dashboard served outside a
+hyperhive deploy): base URL is
+`http://<host>:<container.port>` (direct TCP). External links are
+already absolute. The same base URL drives the primary agent-name
+link + favicon fetch, so the whole row routes through the gateway
+as a unit.
+
+<!-- vale write-good.Passive = YES -->
+
+<!-- vale write-good.Passive = NO -->
+
+**When the container is stopped** (`ContainerView.running = false`),
+the dashboard skips the async `dashboard-state` fetch entirely (the agent
+web server is down), so a single badge replaces the badge chain,
+the nav strip is empty, and status text and the rate-limited badge disappear. The agent icon goes straight to the dimmed
+`/favicon.svg` fallback instead of attempting a doomed load from the
+container's URL. Static fields — `pending_reminders`, `parent`, `config` link — remain visible
+regardless of run state.
+
+<!-- vale write-good.Passive = YES -->
+
+**Line 2** — status badges only (no per-card action buttons — actions
+live in the **selection bar** or the **per-agent `⋮` menu**, see
+below).
+
+### Status badges
+
+**Which single badge:** `ContainerView.failed`
+(systemd `ActiveState=failed` — the unit exhausted its bounded
+restarts and gave up on its own) draws a red `✖ gave up` badge;
+otherwise a plain muted `■ not running` — a container an operator
+stopped deliberately. Both states read `running: false`; `failed` is
+the orthogonal fact (a fourth one alongside `paused`/
+`needs_login`, same "independent flags, no state machine" shape —
+see `ContainerView`'s own doc comment) that tells them apart. An
+older hive-c0re without the field serves `failed: undefined`, which
+reads falsy — degrades cleanly to the single `not running` badge.
+
+When the container is running, status badges follow — `⊘ rate
+limited` (red, while the harness parks itself after a 429), `needs
+login` — plus **one `◐ pending-state…` pill per
+active transient** (replaces buttons during operator-initiated
+start / stop / restart / rebuild / destroy). An agent can carry
+**multiple transients at once** — for example a lease-exempt `prebuild`
+running alongside a `stop_for_update` on the same agent — and each
+renders as its own independent badge instead of collapsing
+into one label, matching the existing multi-badge convention this
+line already uses for `paused`.
+
+Any pending badge means the row is actually **running** something
+right now (see **Pending-badge derivation** below); every row
+carrying ≥1 badge keeps the amber row tint AND draws a **rotating
+amber ring** around the agent icon.
+
+**Pending-badge derivation:** transients only (`transientsState`,
+keyed `agent -> Map<kind, since_unix>`) — a transient is **derived
+from a job-queue node currently `Running`** against that agent, not
+declared per request, so its label follows the operation as it
+progresses (a rebuild reads `stop_for_update`, then `swap`, then
+`reconcile` rather than one constant `rebuilding` for its whole
+life). Two consequences for anything rendering it:
+
+- The label vocabulary is **open** — it's the node's own wire tag
+  (`NodeKind`'s `&str` conversion, the same strings the graph wire's node
+  labels carry), not a fixed set. Treat it as an opaque display
+  string; don't switch on specific values.
+- It's **not** exclusively operator-initiated, and **not** limited
+  to rebuild-shaped work — `running_transients()` in hive-c0re is
+  a status-only test (any `Running` node whose payload names a
+  non-empty agent lights a pill), so work the operator never
+  triggered (a crash-recover rebuild, a boot-sweep rebuild, a
+  lease-exempt `prebuild`) lights the same mechanism.
+
+Ops with no queue node behind them (destroy, migration) supply
+their own label directly via `TransientSet`/`TransientCleared`
+events carrying no backing node at all.
+
+**Queued (not-yet-started) work shows nothing on the card.** Only
+running work gets a per-agent pending badge, by design — the swarm
+view stays independent of job-queue internals. The queue-summary
+banner below is the only queued-work indicator on this tab, and it
+reads the narrow `/api/jobq/rollup` endpoint rather than the full
+graph.
+
+**Per-agent `⋮` overflow menu** — a `⋮` button appears on the right
+edge of each container row. Selecting it opens a small dropdown with
+per-agent actions and navigation links. Contents:
+
+- `↺ R3ST4RT` (running agents only) / `■ ST0P` (running only) /
+  `▶ ST4RT` (stopped only) — single-agent run-state toggles.
+  Identical to the bulk actions on the selection bar but operate
+  on one agent without requiring a selection.
+- `↻ R3BU1LD` — always available; queues a rebuild for this agent.
+- `DESTR0Y` / `PURG3` — destructive, each prompts for confirmation
+  via the themed dialog (see **Themed dialogs** below).
+
+**Build-queue summary banner** — when the job queue has any active
+work, a compact amber banner sits above the container list: `◐ build
+queue — N running · M queued — view queue →` (the link goes to the
+R3BU1LD QU3U3 tab). The shared `JobqRollup` Preact component
+(`@hive/shared/jobq-rollup.js` — the same one swarm-ui's `/jobs` page
+mounts, pointed at swarm-controller's own rollup endpoint instead),
+mounted once into `#jobq-rollup-section` by `agents.js::initJobqRollup`
+and refreshed via its own handle rather than being re-rendered by
+`renderContainers`. Reads `GET /api/jobq/rollup`
+(`hive-jobq-wire::state_rollup`) — `Vec<{ state, nodes, roots }>`,
+every lifecycle state present in a fixed order, zero counts included —
+rather than the full `/api/jobq/graph` tree: `running` sums the
+`Running` and `Finishing` entries' `roots` (`Finishing` = own work
+done, subtree still going, still in flight), `queued` reads the
+`Pending` entry's `roots`. `roots` specifically, not `nodes` — the
+banner means _N whole operations_, not raw steps (one rebuild is ~7
+nodes but 1 root); `nodes` exists on the same endpoint for a consumer
+that wants step-level counts instead, unused here.
+
+### Themed dialogs
+
+All confirmations and transient error notices use an in-app themed
+dialog system (`@hive/shared/modal.js`) rather than the browser's
+native `confirm()` / `alert()` chrome, so they match the Catppuccin
+palette and the OS can't style them away. Two primitives, both built
+on the `openDialog` core:
+
+- `themedConfirm({ message, danger, confirmLabel, checkboxes })`
+  — a modal confirm that resolves to `null` on cancel or an object
+  of checkbox states on confirm. Destructive actions pass
+  `danger: true` (the confirm button turns red and the cancel
+  button takes focus). Selecting the backdrop and `Esc` both cancel.
+- `themedToast(message, { type, ... })` — a non-blocking toast (top-right,
+  `info` / `error` / `ok`) for transient validation + action
+  failures, so an error doesn't lock the operator behind a modal.
+  Single-action errors autodismiss; bulk / partial-failure
+  summaries are sticky (select to dismiss) so they aren't missed.
+
+Every destructive run-state action (`ST0P`, `R3ST4RT`, `R3BU1LD`,
+`DESTR0Y`, `PURG3`) routes through `themedConfirm`, on both
+the per-agent `⋮` menu and the bulk selection bar.
+
+**Graceful stop** — the `■ ST0P` confirm dialog (per-agent and
+bulk) carries a `stop gracefully — let the agent finish its turn
+and flush state before the container stops` checkbox. When ticked,
+the action POSTs `/api/kill/<name>?graceful=true` (the bulk path
+appends the flag per-agent); unticked is the instant hard stop
+(`/api/kill/<name>` with no query). hive-c0re enqueues a
+`Signal` → `Drain` job-queue node pair (`NodeKind::Signal` /
+`NodeKind::Drain`): `Signal` sets the graceful-stop fence and kicks
+the harness so it runs one stop-checkpoint turn (so the agent can
+flush `/state`); `Drain` awaits the harness clearing that fence,
+bounded by a 3-minute timeout (`GRACEFUL_STOP_TIMEOUT`) that
+resolves either way and falls back to the downstream mechanical
+stop. The quiescing progress surfaces through the same
+rebuild-queue pending-badge mechanism the card already reads for a
+rebuild, driven by the `Signal`/`Drain` pair rather than a nix
+build. (The `hivectl stop --graceful` CLI flag enqueues the same
+`Signal`/`Drain` pair, so the dashboard and CLI paths behave
+identically.)
+
+## Selection bar
+
+Bulk actions (`R3ST4RT` / `ST0P` / `ST4RT` / `P4US3` / `R3SUM3` /
+`R3BU1LD` / `DESTR0Y` / `PURG3`) live here rather than as per-card
+buttons — see **Container row** above. Selecting an agent's icon
+toggles its selection (an in-memory `Set<name>`); `Esc` or the bar's
+`✕ clear` button drops everything. The selection persists across tab
+switches in-memory — the bar just hides on non-4G3NTS tabs since other
+tabs don't show the agent cards needed to cross-reference.
+
+When the operator selects one or more agents (via the icon), a sticky
+frosted-mauve bar slides up from the bottom of the viewport
+(`#selection-bar`, `position: fixed; bottom: 0`). It shows:
+
+<!-- vale write-good.Passive = NO -->
+
+- **Count + names** — "N agents selected · name1, name2, …"
+- **Bulk action buttons** — only enabled when ALL selected agents
+  support the action; greyed out with a tooltip naming the blockers
+  when the selection is mixed:
+  - `↺ R3ST4RT` — running agents only
+  - `■ ST0P` — running agents only
+  - `▶ ST4RT` — stopped agents only
+  - `⏸ P4US3` — unpaused agents only (orthogonal to running/stopped —
+    see **Container row**'s own pause/resume note)
+  - `▶ R3SUM3` — paused agents only
+  - `↻ R3BU1LD` — always available
+  - `DESTR0Y` / `PURG3` — always available
+  <!-- vale write-good.Passive = YES -->
+
+  That list is the whole set — the bar offers no other bulk action.
+
+- **`✕ clear`** button + `Esc` key clear the entire selection.
+
+Every render prunes stale selections (agents destroyed while
+selected) before the bar appears.
+
+## Dashboard endpoints
+
+Also browsable interactively at `/api/docs` (a Swagger UI, linked from
+the pages menu's **api docs** entry), with the raw spec at `/api/openapi.json`.
+It's a growing supplement, not yet a full replacement for the list
+below — some endpoints aren't in it yet.
+
+- `POST /api/{rebuild,kill,restart,start,destroy,pause,resume}/{name}` —
+  lifecycle.
+  `destroy` accepts `purge=on` to also wipe state dirs.
+- `POST /api/purge-tombstone/{name}` — wipe a tombstone's state dirs.
+- `POST /api/rebuild-queue/{id}/cancel` — drop a `Queued` entry.
+  Refuses `Running` / terminal-state entries (in-flight
+  rebuilds can't be safely interrupted). Always 200; body is
+  `{"cancelled": true}` on a successful flip or
+  `{"cancelled": false}` when the entry wasn't in `Queued` state.
+- `POST /api/agent/{name}/mark-all-read` — ack all pending broker
+  messages for `{name}`. Backfills `delivered_at` for rows
+  not yet delivered and sets `acked_at = now`. Returns
+  `{ "marked": N }`. Agent name validated against
+  `[a-z0-9_-]`, 1-63 chars; 400 on bad input.
+- `GET /api/build-logs?limit=N` — most-recent build log headers across
+  all agents (`limit` defaults to 30).
+- `GET /api/build-log/{node_id}` and `/api/build-log/{node_id}/raw` — the
+  build log of one job-queue node, as JSON and as `text/plain`.
+- `GET /api/build-logs/{agent}?limit=N` — most-recent build log
+  headers for one agent, newest first. Returns
+  `Vec<BuildLogHeader>` (JSON): `id`, `agent`, `kind`, `cmdline`,
+  `started_at`, `finished_at`, `status` (`"ok"` / `"fail"` /
+  `null` while in-progress). `limit` defaults to 10, server-side
+  cap at 50. Agent name validated (`[a-z0-9_-]`, 1-63 chars).
+- `GET /api/build-logs/id/{id}` — full build log by id. Returns
+  `BuildLogFull` (JSON): all header fields plus `stdout` and
+  `stderr` as plain text (newline-terminated lines, utf-8). HTTP
+  404 when the row is missing (vacuum-reaped or stale id).
+- `GET /api/build-logs/id/{id}/stream` — live SSE stream of
+  stdout+stderr for an in-progress build (newline-delimited JSON
+  frames). The
+  stream closes when the build finishes or errors.
+- `GET /api/build-logs/id/{id}/raw` — raw concatenated
+  stdout+stderr as `text/plain`. Works on both finished and in-progress
+  build logs.
+
+- `GET /api/dashboard/stream` — unified live event channel:
+  broker `sent` / `delivered`, plus the mutation events listed
+  below. Each frame carries `seq`.
+  <!-- vale write-good.Passive = YES -->
+
+## Dashboard event channel
+
+Wire vocabulary on `/api/dashboard/stream` (kind tag is in the JSON
+payload):
+
+- `sent` / `delivered` — broker traffic, mirrored from the
+  intra-process channel by a forwarder task. Both carry `id: i64`
+  (the broker row id) and `in_reply_to: Option<i64>` for thread
+  rendering.
+- `transient_set` (name, transient_kind, since_unix) /
+  `transient_cleared` (name) — lifecycle action spinners. The
+  client ticks the elapsed-seconds badge off `since_unix`
+  client-side, no polling. `transient_kind` is an **open**
+  display string (the running node's own tag), not a fixed
+  enum — render it, don't branch on it.
+- `container_state_changed` (container: ContainerView) /
+  `container_removed` (name) — per-row container mutations,
+  emitted by `Coordinator::rescan_containers_and_emit` from
+  the job queue's own node execution (`job_queue::exec`, for example
+  after a rebuild's stop/swap/start steps or a destroy's teardown
+  step) — and from the 10s
+  `crash_watch` poll. Client upserts/removes by name and
+  reads the pending overlay from `transientsState` since the
+  payload doesn't carry it.
+- `rebuild_queue_changed` (seq) — **payload-free trigger**, fired on
+  every queue mutation (enqueue, state transition, dedup collapse,
+  terminal-history trim). Unlike the snapshot events below it ships
+  no state at all: the client re-fetches `GET /api/jobq/graph`, which
+  is where it reads the queue from cold too.
+- `tombstones_changed` (seq, tombstones: `Vec<TombstoneView>`) —
+  full snapshot of destroyed-but-state-kept agents. Emitted on
+  destroy, purge, and revive. The K3PT ST4T3 tab subscribes.
+
+<!-- vale write-good.Passive = NO -->
+
+`/api/state` is **only fetched on cold-load and on the few
+forms that mutate non-event-derived state** (PURG3, since
+tombstones aren't event-shaped yet). Every other section — transients,
+containers —
+derives from `/api/dashboard/stream` after the initial snapshot,
+maintaining its own client-side store and applying events on
+top.
+
+<!-- vale write-good.Passive = YES -->
+
+Generalised form helper: `form[data-confirm="…"]` pops
+`confirm()` before submit.
diff --git a/docs/4-implementation/web-ui/shape.md b/docs/4-implementation/web-ui/shape.md
index 76029a772..9ae349412 100644
--- a/docs/4-implementation/web-ui/shape.md
+++ b/docs/4-implementation/web-ui/shape.md
@@ -1,7 +1,7 @@
 # Shape (shared by both)
 
 > Part of [Hives](../../2-handbook/hives/README.md). See also:
-> [Dashboard layout](../../2-handbook/hives/dashboard.md) · [Per-agent page](../../2-handbook/agents/web-page.md)
+> [Dashboard reference](dashboard.md) · [Per-agent page reference](agent-page.md)
 
 ## Shared routes
 
diff --git a/docs/5-project/process/gotchas.md b/docs/5-project/process/gotchas.md
index d2d5311c0..742e03d5f 100644
--- a/docs/5-project/process/gotchas.md
+++ b/docs/5-project/process/gotchas.md
@@ -402,7 +402,7 @@ Never use raw `curl` for forge access.
 `nix/agent-modules/weston-vnc.nix` adds an optional Weston Wayland
 compositor with the `vnc-backend` plugin, surfaced as
 `services.hyperhive.agent.gui.enable = true` per-agent. The harness's
-`/screen/ws` WebSocket relay (`docs/2-handbook/agents/web-page.md::Per-agent endpoints`)
+`/screen/ws` WebSocket relay (`docs/4-implementation/web-ui/agent-page.md::Per-agent endpoints`)
 connects to the compositor at `127.0.0.1:<vnc_port>`.
 
 - **Port allocation**: a **fixed** port (`services.hyperhive.agent.gui.vncPort`,
diff --git a/docs/README.md b/docs/README.md
index 3ff5d5efa..1b9d987c0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -73,7 +73,7 @@ The host a hive runs on and the operator's tools for it. Start at
 
 - **What does the dashboard look like, and how to use it?** →
   [`2-handbook/hives/`](2-handbook/hives/README.md), with the full tab-by-tab
-  reference in [`dashboard`](2-handbook/hives/dashboard.md).
+  reference in [`dashboard`](4-implementation/web-ui/dashboard.md).
 - **What does `hivectl` do? Provisioning, gateway users, container
   shells?** → [`2-handbook/hives/hivectl.md`](2-handbook/hives/hivectl.md) (the curated guide);
   [`2-handbook/hives/hivectl-cli.md`](2-handbook/hives/hivectl-cli.md) for the exhaustive,
@@ -98,7 +98,8 @@ One agent: its roster entry, state, config and page. Start at
 - **Who can do what to whom — the agent roster and privilege?** →
   [`2-handbook/agents/agent-roster.md`](2-handbook/agents/agent-roster.md).
 - **What does an agent's own page show?** →
-  [`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md).
+  [`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md); the full
+  reference is [`agent-page`](4-implementation/web-ui/agent-page.md).
 - **Agent trust model, prompt-injection threat model, credential
   isolation?** → [`2-handbook/agents/security.md`](2-handbook/agents/security.md).
 
diff --git a/frontend/packages/agent/src/agent.css b/frontend/packages/agent/src/agent.css
index 6e471724d..e81f634c8 100644
--- a/frontend/packages/agent/src/agent.css
+++ b/frontend/packages/agent/src/agent.css
@@ -16,7 +16,7 @@
 
 /* ─── full-screen layout overrides ─────────────────────────────────
    The agent page mounts a full-viewport terminal under a fixed
-   frosted-glass header. See docs/2-handbook/agents/web-page.md::Per-agent
+   frosted-glass header. See docs/4-implementation/web-ui/agent-page.md::Per-agent
    page for the layer / pill / side-panel structure; rules below
    override the in-page defaults from @hive/shared. */
 
@@ -184,7 +184,7 @@ h3 {
 }
 .agent-icon {
   /* Square identity anchor — explicit 5em sizing + align-self.
-     See docs/2-handbook/agents/web-page.md::Per-agent page (Agent icon) for the
+     See docs/4-implementation/web-ui/agent-page.md::Per-agent page (Agent icon) for the
      intrinsic-dim-pushes-parent-flex-open + sticks-to-top
      rationale. */
   width: 5em;
@@ -594,7 +594,7 @@ pre.diff {
 /* Tail pill (↓ N new): z-index bumped above the floating chrome so the
    pill sits on the top layer instead of being clipped by it. (Pill is anchored in
    `.agent-main` rather than `.terminal-wrap` — see
-   docs/2-handbook/agents/web-page.md::Per-agent page Terminal-wrap paragraph for the
+   docs/4-implementation/web-ui/agent-page.md::Per-agent page Terminal-wrap paragraph for the
    backdrop-filter stacking-context rationale.) */
 .agent-main .tail-pill {
   bottom: 0.6em;
diff --git a/frontend/packages/agent/src/components/Header.tsx b/frontend/packages/agent/src/components/Header.tsx
index 0ccc172fe..61c4723b2 100644
--- a/frontend/packages/agent/src/components/Header.tsx
+++ b/frontend/packages/agent/src/components/Header.tsx
@@ -50,7 +50,7 @@ export interface HeaderProps {
    * a variable pill count) grows to fit badges+pills together, keeping
    * the header a stable height even on widescreen. Meta-nav
    * (`<MetaNav>`) lives here too, as a fixed-size trigger, not an
-   * inline link list in the title row (docs/2-handbook/agents/web-page.md). */
+   * inline link list in the title row (docs/4-implementation/web-ui/agent-page.md). */
   pills?: ComponentChildren;
 }
 
diff --git a/frontend/packages/agent/src/index.html b/frontend/packages/agent/src/index.html
index 039e3661a..601856b60 100644
--- a/frontend/packages/agent/src/index.html
+++ b/frontend/packages/agent/src/index.html
@@ -19,7 +19,7 @@
   <body class="agent-shell">
     <!-- The Preact rewrite owns everything below — header, terminal,
        side panel. See main.tsx/Root.tsx for the component
-       tree; docs/2-handbook/agents/web-page.md for the design. -->
+       tree; docs/4-implementation/web-ui/agent-page.md for the design. -->
     <div id="preact-root"></div>
 
     <script type="module" src="static/main.js" defer></script>
diff --git a/frontend/packages/agent/src/screen.html b/frontend/packages/agent/src/screen.html
index 9525825e1..c630771b8 100644
--- a/frontend/packages/agent/src/screen.html
+++ b/frontend/packages/agent/src/screen.html
@@ -36,7 +36,7 @@
     <script>
       // Minimal RFB-over-WebSocket renderer. Connects to `screen/ws` on
       // the same host; the harness relays raw RFB bytes to the VNC server
-      // running inside the container. See docs/2-handbook/agents/web-page.md (GET /screen)
+      // running inside the container. See docs/4-implementation/web-ui/agent-page.md (GET /screen)
       // for the design rationale + canvas-sizing implementation notes.
 
       (function () {
@@ -61,7 +61,7 @@
         });
 
         // --- Fit-to-window toggle ---
-        // See docs/2-handbook/agents/web-page.md::Per-agent endpoints (GET /screen) for the
+        // See docs/4-implementation/web-ui/agent-page.md::Per-agent endpoints (GET /screen) for the
         // localStorage persistence + canvas-intrinsic-resolution +
         // pointer-rescale model.
         let fitMode = localStorage.getItem("screen-fit") !== "off";
@@ -105,7 +105,7 @@
         // Sends an RFB SetDesktopSize request so the VNC server (weston)
         // changes its actual output resolution to match the browser
         // viewport — sharper than fit-mode's CSS downscale. Gated on the
-        // server's ExtendedDesktopSize advert; see docs/2-handbook/agents/web-page.md::Per-agent
+        // server's ExtendedDesktopSize advert; see docs/4-implementation/web-ui/agent-page.md::Per-agent
         // endpoints (GET /screen).
         let extDesktopSupported = false;
         let screenId = 1; // captured from the server's ExtendedDesktopSize advert
diff --git a/frontend/packages/agent/src/types.ts b/frontend/packages/agent/src/types.ts
index 390fee76e..6a05a8f1b 100644
--- a/frontend/packages/agent/src/types.ts
+++ b/frontend/packages/agent/src/types.ts
@@ -34,7 +34,7 @@ export interface AgentState {
 // in the agent page header (stats/screen + any
 // `services.hyperhive.agent.dashboardLinks` extras). `agent_links()` on the backend
 // is the single source of truth for what links an agent exposes; see
-// docs/2-handbook/agents/web-page.md::Header for the kind → URL resolution table.
+// docs/4-implementation/web-ui/agent-page.md::Header for the kind → URL resolution table.
 export interface AgentLink {
   url: string;
   icon: string;
diff --git a/frontend/packages/dashboard/src/agents.js b/frontend/packages/dashboard/src/agents.js
index d9e21b4da..7b4366527 100644
--- a/frontend/packages/dashboard/src/agents.js
+++ b/frontend/packages/dashboard/src/agents.js
@@ -1,7 +1,7 @@
 // 4G3NTS (containers) domain — extracted from tabs.js.
 // Agent topology, container-row rendering, selection bar, and all
 // live-update apply handlers for container-state, transient, and
-// job-queue-rollup ops. See docs/2-handbook/hives/dashboard.md::Container row for the
+// job-queue-rollup ops. See docs/4-implementation/web-ui/dashboard.md::Container row for the
 // rendering contract.
 
 import { $, form, fmtAgeSecs } from "./common.js";
@@ -26,14 +26,14 @@ const containerRowCache = new Map();
 // by agent name -> Map<transient_kind, since_unix>: an agent can hold
 // several pills at once (every *running* node naming the agent lights
 // one now, not just a curated "worth surfacing" subset — see
-// docs/2-handbook/hives/dashboard.md::Container row), keyed the same way the backend's
+// docs/4-implementation/web-ui/dashboard.md::Container row), keyed the same way the backend's
 // own tombstone map is, `(agent, label)`, so a clear only removes the
 // specific pill it names rather than guessing. `since_unix` is
 // wall-clock so the elapsed-seconds badge ticks without polling.
 const transientsState = new Map();
 
 // In-memory set of selected agent logical names backing the sticky
-// #selection-bar. See docs/2-handbook/hives/dashboard.md::Selection bar for the
+// #selection-bar. See docs/4-implementation/web-ui/dashboard.md::Selection bar for the
 // interaction model (icon-click toggle, Esc/clear button drop,
 // tab-gated visibility).
 const selectionState = new Set();
@@ -214,7 +214,7 @@ function derivePortConflicts(containers) {
 }
 
 // ─── container ordering ──────────────────────────────────────────────────────
-// Flat alphabetical sort — see docs/2-handbook/hives/dashboard.md::C0NTAINERS.
+// Flat alphabetical sort — see docs/4-implementation/web-ui/dashboard.md::C0NTAINERS.
 
 function sortedContainerRows(containers) {
   // Close any open context menu before replacing the DOM tree — the
@@ -272,7 +272,7 @@ function buildContainerLi(c, opts) {
   // Agent icon: 5em square wrapper with an absolutely-positioned
   // <img> + fire-and-forget load with /favicon.svg fallback. The
   // wrapper doubles as the selection toggle (click / keyboard).
-  // See docs/2-handbook/hives/dashboard.md::Container row for the layout + load-strategy
+  // See docs/4-implementation/web-ui/dashboard.md::Container row for the layout + load-strategy
   // rationale.
   const iconImg = el("img", { class: "container-icon-img", alt: "" });
   const icon = el(
@@ -436,7 +436,7 @@ function buildContainerLi(c, opts) {
   // dashboard-state fetch above.
   if (pending.length) {
     // One badge per pill — an agent can carry several transients at
-    // once now (see docs/2-handbook/hives/dashboard.md::Container row), each rendered
+    // once now (see docs/4-implementation/web-ui/dashboard.md::Container row), each rendered
     // independently rather than collapsed into one label.
     for (const label of pending) {
       head.append(
@@ -506,7 +506,7 @@ function buildContainerLi(c, opts) {
 
   // Per-card action buttons (R3ST4RT / ST0P / ST4RT / R3BU1LD /
   // DESTR0Y / PURG3) live on the selection bar, not here — see
-  // docs/2-handbook/hives/dashboard.md::Selection bar. The contextual `needs update ↻`
+  // docs/4-implementation/web-ui/dashboard.md::Selection bar. The contextual `needs update ↻`
   // chip in the head row stays — it's a state-hint, not an
   // action button.
 
@@ -577,7 +577,7 @@ export function renderContainers(s) {
   // TCP fallback — the gateway proxies the prefix to the per-agent
   // harness (unix-domain via `agent-sockets.json`, or a computed TCP
   // loopback port while the socket marker is absent). See
-  // `docs/2-handbook/hives/dashboard.md::Container row` + `docs/4-implementation/networking/gateway.md::Vhost map`.
+  // `docs/4-implementation/web-ui/dashboard.md::Container row` + `docs/4-implementation/networking/gateway.md::Vhost map`.
   const gatewayLinks = !!(s && s.gateway_enabled);
   const ul = existingUl ?? el("ul", { class: "containers" });
   const rows = sortedContainerRows(containers);
@@ -597,7 +597,7 @@ export function renderContainers(s) {
     // full stop (mara, on review: "remove the per agent pending stuff -
     // only show what is running"; rendered one badge per pill — mara,
     // earlier: "show all running nodes that name the agent"). See
-    // docs/2-handbook/hives/dashboard.md::Container row.
+    // docs/4-implementation/web-ui/dashboard.md::Container row.
     const transientKindsMap = transientsState.get(c.name);
     // Sorted for stable badge order across renders — Map iteration
     // order is insertion order, which shifts as pills clear/re-add.
@@ -663,7 +663,7 @@ export function renderContainers(s) {
 
 // ─── selection bar ───────────────────────────────────────────────────────────
 // Sticky-bottom strip; visible when >=1 agent selected on the 4G3NTS
-// tab. See docs/2-handbook/hives/dashboard.md::Selection bar for the interaction model
+// tab. See docs/4-implementation/web-ui/dashboard.md::Selection bar for the interaction model
 // and the per-action availability rules (disabled-with-tooltip for
 // actions that don't apply to the full selection). Actions POST per
 // agent in a loop (endpoints are individually idempotent /
diff --git a/frontend/packages/dashboard/src/common.css b/frontend/packages/dashboard/src/common.css
index 9157671bb..e548e8272 100644
--- a/frontend/packages/dashboard/src/common.css
+++ b/frontend/packages/dashboard/src/common.css
@@ -225,7 +225,7 @@ code {
 }
 /* M0V3 affordance (selection bar) — mauve reads as "structural
    change" rather than the destructive red / amber chrome of
-   destroy / rebuild. See docs/2-handbook/hives/dashboard.md::Selection bar. */
+   destroy / rebuild. See docs/4-implementation/web-ui/dashboard.md::Selection bar. */
 .btn-move {
   color: var(--purple);
   border-color: var(--purple);
diff --git a/frontend/packages/dashboard/src/dashboard.css b/frontend/packages/dashboard/src/dashboard.css
index 3ab63bd53..7b6ab0d52 100644
--- a/frontend/packages/dashboard/src/dashboard.css
+++ b/frontend/packages/dashboard/src/dashboard.css
@@ -12,7 +12,7 @@
 
 /* ─── tabbed dashboard chrome ──────────────────────────────────────
    Top-of-page sticky header with banner + tab strip. SSE stays
-   alive across tab switches. See docs/2-handbook/hives/dashboard.md::Chrome header + Tab strip for the
+   alive across tab switches. See docs/4-implementation/web-ui/dashboard.md::Chrome header + Tab strip for the
    routing model. */
 
 body.dashboard-shell {
diff --git a/frontend/packages/dashboard/src/index.html b/frontend/packages/dashboard/src/index.html
index 12e035292..6a57a84aa 100644
--- a/frontend/packages/dashboard/src/index.html
+++ b/frontend/packages/dashboard/src/index.html
@@ -165,7 +165,7 @@
 
     <!-- Selection action bar. Sticky-bottom strip that slides into
        view when one or more agent cards is selected (click the icon
-       to toggle). See docs/2-handbook/hives/dashboard.md::Selection bar for the bulk
+       to toggle). See docs/4-implementation/web-ui/dashboard.md::Selection bar for the bulk
        action gating + clear semantics. -->
     <div
       id="selection-bar"
diff --git a/frontend/packages/shared/src/side-panel/hive-side-panel.js b/frontend/packages/shared/src/side-panel/hive-side-panel.js
index b6146e4dd..59d76b6e3 100644
--- a/frontend/packages/shared/src/side-panel/hive-side-panel.js
+++ b/frontend/packages/shared/src/side-panel/hive-side-panel.js
@@ -31,7 +31,7 @@ import { el } from "../dom.js";
 import { attachShadowCss } from "../shadow-css.js";
 import sidePanelCss from "./hive-side-panel.css";
 
-// See docs/2-handbook/agents/web-page.md::Side panel for the hit-strip + pointer-capture +
+// See docs/4-implementation/web-ui/agent-page.md::Side panel for the hit-strip + pointer-capture +
 // localStorage persistence model; CSS clamps the stored value to min
 // 320px / max 96vw and out-of-range stored values are dropped silently.
 // Shared by both packages deliberately — see module header.
diff --git a/hive-agent/src/login.rs b/hive-agent/src/login.rs
index 7c00f7186..e07bac9c2 100644
--- a/hive-agent/src/login.rs
+++ b/hive-agent/src/login.rs
@@ -33,7 +33,7 @@ pub fn default_dir() -> PathBuf {
 /// exactly these to force re-login while preserving session-history files —
 /// so boot detection ([`has_session`]) and logout agree by construction.
 /// Rationale + the previous wholesale-wipe shape we replaced live in
-/// `docs/2-handbook/agents/web-page.md::Per-agent endpoints`
+/// `docs/4-implementation/web-ui/agent-page.md::Per-agent endpoints`
 /// (the `/api/logout` bullet).
 ///
 /// `.credentials.json` is the actual OAuth session; `mcp-needs-auth-cache.json`
diff --git a/hive-agent/src/web_ui/auth.rs b/hive-agent/src/web_ui/auth.rs
index 59390002f..3d08fa997 100644
--- a/hive-agent/src/web_ui/auth.rs
+++ b/hive-agent/src/web_ui/auth.rs
@@ -17,7 +17,7 @@ use super::{AppState, LoginStateCell};
 /// resumes when a fresh credentials file appears (the swarm login stores
 /// one and `claude_credentials` installs it).
 /// Always returns 200 with a body describing what happened. See
-/// `docs/2-handbook/agents/web-page.md::Per-agent endpoints`
+/// `docs/4-implementation/web-ui/agent-page.md::Per-agent endpoints`
 /// (the `/api/logout` bullet) for the three-step rationale +
 /// preservation invariants.
 pub(super) async fn post_logout(State(state): State<AppState>) -> Response {
diff --git a/hive-agent/src/web_ui/state.rs b/hive-agent/src/web_ui/state.rs
index 7713d4486..f19de4c1c 100644
--- a/hive-agent/src/web_ui/state.rs
+++ b/hive-agent/src/web_ui/state.rs
@@ -142,7 +142,7 @@ pub(super) struct StateSnapshot {
     /// Navigation links for this agent page. Also served via
     /// `DashboardState.links` (`GET /api/dashboard-state`) for the
     /// dashboard card's icon strip. Both are produced by `agent_links()`
-    /// — single source of truth. See [`docs/2-handbook/hives/dashboard.md::Container row`]
+    /// — single source of truth. See [`docs/4-implementation/web-ui/dashboard.md::Container row`]
     /// for the frontend resolver + which links appear in which conditions.
     links: Vec<AgentLink>,
     /// Human name of this hive instance (e.g. `"pr1ma"`). Sourced
@@ -262,7 +262,7 @@ fn read_own_status() -> (Option<String>, Option<i64>) {
 /// for `External`; the frontend resolves each against its `kind`
 /// against the right base so the backend never has to guess the
 /// operator's browser host. See
-/// `docs/2-handbook/hives/dashboard.md::Container row` for
+/// `docs/4-implementation/web-ui/dashboard.md::Container row` for
 /// the resolver + how `deployed:<sha>` ships alongside.
 ///
 /// Icons are real emoji, not unicode arrow/geometric glyphs — mara:
diff --git a/nix/agent-modules/weston-vnc.nix b/nix/agent-modules/weston-vnc.nix
index 3bbdd52bf..0b66c5745 100644
--- a/nix/agent-modules/weston-vnc.nix
+++ b/nix/agent-modules/weston-vnc.nix
@@ -38,7 +38,7 @@ in
   # Port allocation, weston bind-address quirk, PAM service name, the
   # Type=simple choice, idle-time=0: all in
   # docs/5-project/process/gotchas.md::Weston VNC compositor.
-  # Harness-side WebSocket relay shape: docs/2-handbook/agents/web-page.md::Per-agent
+  # Harness-side WebSocket relay shape: docs/4-implementation/web-ui/agent-page.md::Per-agent
   # endpoints (`/screen` + `/screen/ws`).
 
   options.services.hyperhive.agent.gui.enable = lib.mkOption {