diff --git a/frontend/packages/dashboard/src/tabs.js b/frontend/packages/dashboard/src/tabs.js
index db8ef08e..c3436323 100644
--- a/frontend/packages/dashboard/src/tabs.js
+++ b/frontend/packages/dashboard/src/tabs.js
@@ -217,17 +217,18 @@ window.marked = marked;
   function applyRebuildQueueChanged(ev) {
     rebuildQueueState = (ev.queue || []).slice();
     renderRebuildQueueFromState();
-    // Container cards surface in-flight rebuild / meta-update ops as
-    // a "building..." badge (#398) — re-render the SW4RM tab so
-    // newly-queued / newly-running ops light up the right card,
-    // and finished ops fall back to the regular state badges.
+    // Re-render the SW4RM tab so newly-queued / newly-running
+    // rebuild-queue ops light up the right card with a building…
+    // badge, and finished ops fall back to the regular state badges.
+    // See docs/web-ui.md::Container row for the badge taxonomy.
     renderContainersFromState();
   }
   // Map from agent name → highest-priority in-flight queue entry
   // (`running` beats `queued`). Used by the container row renderer
   // to surface "building..." / "meta-updating..." badges on the
   // SW4RM tab when an op is still in the rebuild queue but no
-  // operator-initiated transient is set (#398).
+  // operator-initiated transient is set — see docs/web-ui.md::Container
+  // row for the badge cross-reference between SW4RM and SYST3M.
   function inFlightOpsByAgent() {
     const out = new Map();
     for (const e of rebuildQueueState) {
@@ -477,22 +478,20 @@ window.marked = marked;
     const hostname = (s && s.hostname) || window.location.hostname;
     const ul = el('ul', { class: 'containers' });
     const tree = buildAgentTree(containers);
-    // In-flight rebuild / meta-update / destroy ops per agent name.
-    // Surface them as "building..." style badges on the container
-    // card when no operator-initiated transient already covers the
-    // row (#398). Mara: the SW4RM tab showed an agent as stopped
-    // while SYST3M showed an active rebuild; cross-reference fixes
-    // that.
+    // In-flight rebuild / meta-update / destroy ops per agent name —
+    // see docs/web-ui.md::Container row for the building… badge
+    // rationale (covers the SYST3M-shows-rebuild-but-SW4RM-shows-stopped
+    // gap when no operator transient is set).
     const inFlight = inFlightOpsByAgent();
     for (const node of tree) {
       const c = node.container;
       const url = `http://${hostname}:${c.port}/`;
       // Pending state is overlaid from the transient store first
       // (operator-initiated spawn/destroy/rebuild — covers the
-      // create+start window where the container literally isn't up
-      // yet), then from the rebuild_queue (#398 — covers in-flight
-      // ops the worker is running even if no transient was set).
-      // `ContainerStateChanged` doesn't carry either signal.
+      // create+start window when the container literally isn't up
+      // yet), then from the rebuild_queue (covers worker-driven ops
+      // even if no transient was set). `ContainerStateChanged`
+      // doesn't carry either signal.
       const transientKind = transientsState.get(c.name)?.kind || null;
       const op = !transientKind ? inFlight.get(c.name) : null;
       const pending = transientKind
@@ -565,8 +564,8 @@ window.marked = marked;
           iconImg.src = '/favicon.svg';
         });
       } else {
-        // Container stopped (#432) — skip the doomed `${url}icon` fetch
-        // and go straight to the dimmed hyperhive mark. Avoids a noisy
+        // Container stopped — skip the doomed `${url}icon` fetch and
+        // go straight to the dimmed hyperhive mark. Avoids a noisy
         // failed request in the console + the brief broken-image flash.
         icon.classList.add('icon-unreachable');
         iconImg.src = '/favicon.svg';
@@ -618,9 +617,10 @@ window.marked = marked;
       // (start / stop / restart / rebuild is in progress). Otherwise,
       // when the container is stopped, surface a single `■ not
       // running` badge; the backend has already cleared rate_limited /
-      // needs_login / ctx_tokens / status_text in that case (#432) so
-      // the rest of the chain is a no-op for stopped containers — but
-      // we still want SOME badge there so the row doesn't look empty.
+      // needs_login / ctx_tokens / status_text in that case (see
+      // docs/web-ui.md::Container row) so the rest of the chain is a
+      // no-op for stopped containers — but we still want SOME badge
+      // there so the row doesn't look empty.
       if (pending) {
         head.append(el('span', { class: 'pending-state' },
           el('span', { class: 'spinner' }, '◐'), ' ', pending + '…'));
@@ -681,9 +681,9 @@ window.marked = marked;
       // ── agent status text ─────────────────────────────────────────
       // Self-reported status (via set_status MCP tool) — only fresh
       // while the harness is up. The backend already clears
-      // `status_text` on stopped containers (#432) so we can render
-      // unconditionally here: a stopped container simply has no
-      // `status_text` and skips this block naturally.
+      // `status_text` on stopped containers (docs/web-ui.md::Container
+      // row) so we can render unconditionally here: a stopped
+      // container simply has no `status_text` and skips naturally.
       if (c.status_text) {
         const nowUnix = Math.floor(Date.now() / 1000);
         const ageStr = c.status_set_at != null