docs(web-ui): update C0R3/L0GS/BU1LDS page docs to reflect build queue move

R3BU1LD QU3U3 and M3T4 1NPUTS moved from /core.html to /builds.html
(the BU1LDS page); the BUILD log tab moved from /logs.html to /builds.html.
dashboard.md still described the old 4-tab C0R3 page and 4-tab L0GS page.

Changes:
- C0R3 page section: update to the actual 2 tabs (K3PT ST4T3 +
  C0NT41N3R L04D); add pointer to BU1LDS page
- Add new BU1LDS page section: R3BU1LD QU3U3 (with all 9 queue kind
  glyphs + deferred-start parent_id note), M3T4 1NPUTS, BUILD L0GS
- L0GS page section: update to actual 3 tabs (AGENT / SYSTEM / AUDIT);
  remove BUILD sub-tab prose; add pointer to BU1LDS page
- Fix two stale 'C0R3 page R3BU1LD QU3U3' refs to 'BU1LDS page'
- web-ui.md index: mention BU1LDS alongside C0R3 and L0GS
This commit is contained in:
iris 2026-07-02 12:18:54 +02:00 committed by mara
commit a589acf4d1
2 changed files with 100 additions and 95 deletions

View file

@ -13,8 +13,9 @@ This doc has been split for readability. Pick the section you need:
per-agent relative paths, `data-async` form pattern, side panel, per-agent relative paths, `data-async` form pattern, side panel,
atomic repaint. atomic repaint.
- **[Dashboard layout](web-ui/dashboard.md)** — tab contents - **[Dashboard layout](web-ui/dashboard.md)** — tab contents
(SW4RM, Y3R C4LL, P3RM1SS10NS, SCH3DUL3S) + the standalone C0R3 page (SW4RM, Y3R C4LL, P3RM1SS10NS, SCH3DUL3S) + standalone pages
(`/core.html` — the old SYST3M panels), container row, (C0R3 `/core.html`, BU1LDS `/builds.html`, L0GS `/logs.html`,
M4TR1X ACC0UNTS `/matrix-accounts.html`), container row,
topology tree, selection bar, approval card, browser topology tree, selection bar, approval card, browser
notifications, dashboard endpoints + event channel. notifications, dashboard endpoints + event channel.
- **[Per-agent page](web-ui/agent.md)** — header, main terminal, - **[Per-agent page](web-ui/agent.md)** — header, main terminal,

View file

@ -126,72 +126,13 @@ in_reply_to, file_refs).
Passive / rare-interaction state. No longer a dashboard tab — it's a Passive / rare-interaction state. No longer a dashboard tab — it's a
standalone page reached from the **Core** tile on the H0M3 hub (served at standalone page reached from the **Core** tile on the H0M3 hub (served at
`/core.html`), with the same minimal chrome as `/logs.html`: a `← home` `/core.html`), with the same minimal chrome as `/logs.html`: a `← home`
back-link + a `createTabStrip` sub-tab nav (**R3BU1LD QU3U3** default, back-link + a `createTabStrip` sub-tab nav (**K3PT ST4T3** default,
then **M3T4 1NPUTS**, **K3PT ST4T3**, **C0NT41N3R L04D**). The page is its then **C0NT41N3R L04D**). The page is its own esbuild bundle (`core.js`)
own esbuild bundle (`core.js`) that cold-loads `/api/state` and subscribes that cold-loads `/api/state` and subscribes to `/api/dashboard/stream` for
to `/api/dashboard/stream` for the same live events as the dashboard `tombstones_changed`, `capabilities_changed`, and `tool_groups_changed`
(`rebuild_queue_changed`, `meta_inputs_changed`, `meta_update_running`, (the latter two re-render the stale-perms sub-section when permission
`tombstones_changed`). The dashboard keeps the rebuild-queue *state* (it data changes). (Rebuild queue and meta inputs have moved to the BU1LDS
drives the "building…" badges on SW4RM agent cards) but no longer renders page — see below.)
these panels.
**M3T4 1NPUTS** — inputs in `meta/flake.lock` the operator can
selectively `nix flake update`, rendered as an indented tree:
every fetched input at every depth (`hyperhive`,
`hyperhive/nixpkgs`, `agent-<n>`, `agent-<n>/mcp-<x>`, …), each
shown once at its shallowest path. `read_meta_inputs` walks the
lock graph with a `visited` set — `follows` aliases and rev-less
nodes are skipped. A `select all / select none`
control sits above the tree. Checking inputs + submitting bumps
the lock in `/meta/` and rebuilds the selected agents in
sequence; each outcome reaches the root agent as a `rebuilt`
system event. `POST /api/meta-update`. While a lock-bump ripple runs,
the panel shows a pulsing "⏳ meta-update running" banner and the
update button is disabled (snapshot field `meta_update_running`,
live event `meta_update_running`).
**R3BU1LD QU3U3** — pending and recently-completed container
operations: rebuilds, meta-update cascades, and first-spawns.
One operation runs at a time; the worker drains FIFO. Each row
shows a state glyph (`⏸` queued / `▶` running / `✔` done /
`✖` failed / `⊘` cancelled), kind glyph + verb (`↻ rebuild`,
`◆ meta_update`, `✨ spawn`, `🗑 destroy`, `↺ restart`,
`⚡ startup_sweep`, `🔑 perm_change`, `⏹ graceful_stop`,
`▶ start`, `■ stop`), agent name, source
chip (`manual | meta_update | auto_update | startup_sweep | crash_recover | approval`
— green for operator-approved config changes), timing, and an
optional reason / error. Meta-update cascade rebuilds and deferred
start-after-rebuild follow-ups nest under their parent entry
(`parent_id` grouping; `rqe-child` CSS class).
Dedup: re-enqueueing a still-queued op for the same agent
collapses into the existing entry. All timing labels stay live:
running entries tick elapsed seconds every second; queued and
terminal ("done N ago" / "failed N ago") labels tick every 30s so
keyed rows never show stale timestamps as they persist across
`rebuild_queue_changed` snapshots. When the worker has annotated the current phase
a cyan `↳ <step>` sub-line appears under the main row showing the
in-flight step name (e.g. `↳ meta prepare_deploy``↳ nixos-container update`
`↳ finalize deploy`). Terminal transitions clear `step` on the
backend so Done / Failed rows don't render stale labels.
Queued entries carry a `✗` cancel button on the right edge;
running / done / failed / cancelled entries don't show it — the
backend refuses cancellation for non-`Queued` rows anyway
(`POST /api/rebuild-queue/{id}/cancel`). Successful
cancel flips the row to `⊘ cancelled` via the next
`rebuild_queue_changed` snapshot.
Cold-loaded from `/api/state.rebuild_queue`; live updates via
`rebuild_queue_changed` snapshot event.
Below the queue, a **live build-log panel** (`#rebuild-live-log`,
`renderRebuildLiveLog`) streams the currently-running rebuild's output
inline — collapsible, with a live/ok/fail badge and a `↓ raw` download.
It's keyed to the running entry's `build_log_id` and opens one
`EventSource` to `GET /api/build-logs/id/{id}/stream` (the same stream
the L0GS page BUILD tab uses; the stream replays accumulated output on
connect). It lives in its own container outside `#rebuild-queue-section`
so the queue's per-row re-render (rows rebuild as the `step` advances)
never tears down the open stream; it hides when nothing is building and
each row keeps its `logs →` link out to the full L0GS history.
**K3PT ST4T3** — two sub-sections on one pane: **K3PT ST4T3** — two sub-sections on one pane:
@ -228,6 +169,91 @@ omitted — agents share the host netns, so there is no per-container net
counter (per-agent network needs the netns-isolation roadmap in counter (per-agent network needs the netns-isolation roadmap in
`docs/network.md`). `docs/network.md`).
## BU1LDS page (`/builds.html`)
The build lifecycle hub — rebuild queue, live build log, meta inputs,
and build log history on one page. Standalone page reached from the
**Builds** tile on the H0M3 hub, same minimal chrome as `/core.html`.
Three sub-tabs: **R3BU1LD QU3U3** (default), **M3T4 1NPUTS**,
**BUILD L0GS**. Its own esbuild bundle (`builds.js`); cold-loads
`/api/state` and subscribes to `/dashboard/stream` for
`rebuild_queue_changed`, `meta_inputs_changed`, `meta_update_running`.
The dashboard tab keeps the rebuild-queue *state* for the SW4RM
card badges without rendering these panels.
**R3BU1LD QU3U3** — pending and recently-completed container
operations: rebuilds, meta-update cascades, and first-spawns.
One operation runs at a time; the worker drains FIFO. Each row
shows a state glyph (`⏸` queued / `▶` running / `✔` done /
`✖` failed / `⊘` cancelled), kind glyph + verb (`↻ rebuild`,
`◆ meta_update`, `✨ spawn`, `🗑 destroy`, `↺ restart`,
`⚡ startup_sweep`, `🔑 perm_change`, `⏹ graceful_stop`, `▶ start`,
`■ stop`), agent name,
source chip (`manual | meta_update | auto_update | startup_sweep | crash_recover | approval`
— green for operator-approved config changes), timing, and an
optional reason / error. Meta-update cascade rebuilds and
deferred-start follow-ups nest under their parent entry (`parent_id`
grouping; `rqe-child` CSS class — e.g. a `Rebuild` entry groups its
`Start` child, which fires after the profile-swap to free the build
lane before the container boot). Dedup: re-enqueueing a still-queued
op for the same agent collapses into the existing entry. All timing
labels stay live: running entries tick elapsed seconds every second;
queued and terminal ("done N ago" / "failed N ago") labels tick every
30s so keyed rows never show stale timestamps as they persist across
`rebuild_queue_changed` snapshots. When the worker has annotated the
current phase a cyan `↳ <step>` sub-line appears under the main row
showing the in-flight step name (e.g. `↳ meta prepare_deploy`
`↳ nixos-container update``↳ finalize deploy`). Terminal
transitions clear `step` on the backend so Done / Failed rows don't
render stale labels.
Queued entries carry a `✗` cancel button on the right edge;
running / done / failed / cancelled entries don't show it — the
backend refuses cancellation for non-`Queued` rows anyway
(`POST /api/rebuild-queue/{id}/cancel`). Successful
cancel flips the row to `⊘ cancelled` via the next
`rebuild_queue_changed` snapshot.
Cold-loaded from `/api/state.rebuild_queue`; live updates via
`rebuild_queue_changed` snapshot event.
Below the queue, a **live build-log panel** (`#rebuild-live-log`,
`renderRebuildLiveLog`) streams the currently-running rebuild's output
inline — collapsible, with a live/ok/fail badge and a `↓ raw` download.
It's keyed to the running entry's `build_log_id` and opens one
`EventSource` to `GET /api/build-logs/id/{id}/stream` (the same stream
the BUILD L0GS tab uses; the stream replays accumulated output on
connect). It lives in its own container outside `#rebuild-queue-section`
so the queue's per-row re-render (rows rebuild as the `step` advances)
never tears down the open stream; it hides when nothing is building and
each row keeps its `logs →` link out to the full build log history.
**M3T4 1NPUTS** — inputs in `meta/flake.lock` the operator can
selectively `nix flake update`, rendered as an indented tree:
every fetched input at every depth (`hyperhive`,
`hyperhive/nixpkgs`, `agent-<n>`, `agent-<n>/mcp-<x>`, …), each
shown once at its shallowest path. `read_meta_inputs` walks the
lock graph with a `visited` set — `follows` aliases and rev-less
nodes are skipped. A `select all / select none`
control sits above the tree. Checking inputs + submitting bumps
the lock in `/meta/` and rebuilds the selected agents in
sequence; each outcome reaches the root agent as a `rebuilt`
system event. `POST /meta-update`. While a lock-bump ripple runs,
the panel shows a pulsing "⏳ meta-update running" banner and the
update button is disabled (snapshot field `meta_update_running`,
live event `meta_update_running`).
**BUILD L0GS** — all-agents build log history (moved from `/logs.html`).
Lazy-loaded on first tab activation; auto-refreshes when
`rebuild_queue_changed` fires. Fetches `GET /api/build-logs?limit=30`.
Renders a scrollable list of build entries; each row is a collapsible
button showing status badge (`live` / `ok` / `fail`), agent name,
elapsed duration, build kind, age, and the invocation command line.
Expanding a row fetches the full stdout+stderr via
`GET /api/build-logs/id/{id}`. A live in-progress build shows a `live`
badge with a ticking elapsed-time chip; expanding streams output via
`GET /api/build-logs/stream/{id}` with sticky-bottom auto-scroll
(suspends on manual scroll-up). Deep-link: `?id=N#buildlogs` opens the
entry with that id pre-expanded.
## M4TR1X ACC0UNTS page (`/matrix-accounts.html`) ## M4TR1X ACC0UNTS page (`/matrix-accounts.html`)
Operator surface to provision / log in a per-agent **external** matrix Operator surface to provision / log in a per-agent **external** matrix
@ -631,31 +657,9 @@ root. All dashboard sub-pages include a `← Home` back-link for navigation.
A dedicated log-viewer page (not a tab pane — a separate HTML page), A dedicated log-viewer page (not a tab pane — a separate HTML page),
reachable from the Logs tile on the H0M3 hub. Minimal chrome: reachable from the Logs tile on the H0M3 hub. Minimal chrome:
a `← home` back link and a four-item sub-tab strip. Tab a `← home` back link and a three-item sub-tab strip. Tab
routing is hash-based (`#build`, `#agent`, `#system`, `#audit`); default is routing is hash-based (`#agent`, `#system`, `#audit`); default is
`#build`. `#agent`. (Build log history has moved to the BU1LDS page — see above.)
**BUILD sub-tab** — all-agents build log history. Fetches
`GET /api/build-logs?limit=30` on load and on `↻ refresh`. Renders
a scrollable list of build entries; each row is a collapsible button
showing status badge (`live` / `ok` / `fail`), agent name, elapsed
duration, build kind, age, and the invocation command line.
Expanding a row fetches the full stdout+stderr via
`GET /api/build-logs/id/{id}`.
A live in-progress build shows a `live` badge with an elapsed-time
chip that ticks every second (updated by a `setInterval` on the
row; cleared when the build finishes or the stream errors). Expanding
a live row streams its output via `GET /api/build-logs/id/{id}/stream`
(newline-delimited JSON frames) with **sticky-bottom auto-scroll**:
the stream scrolls to keep the latest output visible as long as the
operator hasn't scrolled up manually; once the operator scrolls up,
new lines append silently at the bottom without jumping.
The build list auto-refreshes when a `rebuild_queue_changed` SSE
event fires while the BUILD tab is active (2s debounce to let the
backend commit the new row). The `↻ refresh` button triggers an
immediate re-fetch.
**AGENT sub-tab** — per-container journald viewer. Two selects: agent **AGENT sub-tab** — per-container journald viewer. Two selects: agent
name (populated from `GET /api/state`) and unit filter name (populated from `GET /api/state`) and unit filter
@ -769,7 +773,7 @@ fetch entirely.
(per queue `kind` — e.g. a `start` entry shows `starting…` / (per queue `kind` — e.g. a `start` entry shows `starting…` /
`start queued`, `stop` and `graceful_stop` both show `stopping…` / `start queued`, `stop` and `graceful_stop` both show `stopping…` /
`stop queued`) sourced from `rebuildQueueState` — so the SW4RM tab `stop queued`) sourced from `rebuildQueueState` — so the SW4RM tab
shows the same progress visible on the C0R3 page's R3BU1LD QU3U3. shows the same progress visible on the BU1LDS page's R3BU1LD QU3U3.
The row visual splits queued vs running: a **queued** entry shows The row visual splits queued vs running: a **queued** entry shows
only the pending-state pill (no row tint, so a long queue doesn't only the pending-state pill (no row tint, so a long queue doesn't
paint half the tab amber); a **running** entry keeps the amber paint half the tab amber); a **running** entry keeps the amber
@ -834,7 +838,7 @@ agent is stale. Banner pulses on each broker SSE event
**Build-queue summary banner** — when the rebuild queue has any **Build-queue summary banner** — when the rebuild queue has any
`queued` / `running` entries, a compact amber banner sits above the `queued` / `running` entries, a compact amber banner sits above the
container list: `◐ build queue — N running · M queued — view queue →` container list: `◐ build queue — N running · M queued — view queue →`
(the link goes to the C0R3 page's R3BU1LD QU3U3). It replaces the (the link goes to the BU1LDS page's R3BU1LD QU3U3). It replaces the
old per-transient spinner list; the actual running step for each old per-transient spinner list; the actual running step for each
agent is already shown on its card (transient + in-flight-queue agent is already shown on its card (transient + in-flight-queue
badges), so the top of the tab only needs the at-a-glance summary. badges), so the top of the tab only needs the at-a-glance summary.