From 8ba1947c3fa33955c728e66fb765b78de21e32e0 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive>
Date: Sun, 31 May 2026 23:27:52 +0200
Subject: [PATCH] docs: add P33RS tab to dashboard layout docs

---
 docs/web-ui.md           |  2 +-
 docs/web-ui/dashboard.md | 57 +++++++++++++++++++++++++++++++---------
 2 files changed, 45 insertions(+), 14 deletions(-)

diff --git a/docs/web-ui.md b/docs/web-ui.md
index 73178aeb..052b4357 100644
--- a/docs/web-ui.md
+++ b/docs/web-ui.md
@@ -13,7 +13,7 @@ This doc has been split for readability. Pick the section you need:
   per-agent relative paths, `data-async` form pattern, side panel,
   atomic repaint.
 - **[Dashboard layout](web-ui/dashboard.md)** — tab contents
-  (SW4RM, Y3R C4LL, SYST3M, SCH3DUL3S, S3TT1NGS), container row,
+  (SW4RM, Y3R C4LL, SYST3M, SCH3DUL3S, P33RS, S3TT1NGS), container row,
   topology tree, selection bar, approval card, browser
   notifications, dashboard endpoints + event channel.
 - **[Per-agent page](web-ui/agent.md)** — header, main terminal,
diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index 9633c6f9..7edaeec8 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -6,22 +6,23 @@
 
 The dashboard (`/`) has a fixed chrome header at the top and a
 `<main>` that shows exactly one tab pane at a time. The URL hash
-(`#swarm`, `#call`, `#system`, `#schedules`) drives which pane is
-active; hash changes don't reload the page. FL0W is a separate
-full-page terminal at `/flow.html` — its tab-strip entry is a
-cross-page link (`◆ FL0W ◆ →`), not a pane swap.
+(`#swarm`, `#call`, `#system`, `#schedules`, `#peers`, `#settings`)
+drives which pane is active; hash changes don't reload the page.
+FL0W is a separate full-page terminal at `/flow.html` — its
+tab-strip entry is a cross-page link (`◆ FL0W ◆ →`), not a pane
+swap.
 
 **Chrome header** (fixed, overlays the active tab pane):
 - **Tab strip**: `◆ SW4RM ◆`, `◆ Y3R C4LL ◆`, `◆ SYST3M ◆`,
-  `◆ SCH3DUL3S ◆`, `◆ M4TR1X ◆ →` (optional page link, see below),
-  `◆ FL0W ◆ →` (page link), and `◆ S3TT1NGS ◆`. Count pills on
-  SW4RM (container count), Y3R C4LL (pending approvals + questions),
-  and SCH3DUL3S (active schedules); FL0W pill mirrors the operator
-  inbox length (hidden when zero); S3TT1NGS has no count. The
-  M4TR1X → entry is hidden when
-  `services.hyperhive.matrix.gui.enable` is off (defaults to
-  `matrix.enable`) so operators without the matrix GUI on don't
-  see a dead link — tabs.js gates the `hidden` attribute on
+  `◆ SCH3DUL3S ◆`, `◆ P33RS ◆` (hidden when no peers configured),
+  `◆ M4TR1X ◆ →` (optional page link, see below), `◆ FL0W ◆ →`
+  (page link), and `◆ S3TT1NGS ◆`. Count pills on SW4RM (container
+  count), Y3R C4LL (pending approvals + questions), and SCH3DUL3S
+  (active schedules); FL0W pill mirrors the operator inbox length
+  (hidden when zero); P33RS and S3TT1NGS have no count. The M4TR1X →
+  entry is hidden when `services.hyperhive.matrix.gui.enable` is off
+  (defaults to `matrix.enable`) so operators without the matrix GUI
+  on don't see a dead link — tabs.js gates the `hidden` attribute on
   `state.matrix_gui_enabled` from `/api/state`.
 - **Banner-thin** (`░▒▓█▓▒░ HYPERHIVE / HIVE-C0RE / WE ARE THE WIRED ░▒▓█▓▒░`)
   — sits below the tab strip.
@@ -177,6 +178,36 @@ button hard-deletes (`POST /cancel-reminder/{id}`) and a
 Lives in the SCH3DUL3S tab alongside operator schedules so the
 operator has one place for everything time-fired.
 
+## P33RS tab
+
+Peer hives in this swarm. The tab is hidden when the
+`state.peer_hives` array from `/api/state` is empty (i.e. no
+`services.hyperhive.swarm.peers` are configured). When at least
+one peer is present the `hidden` attribute is removed and the tab
+becomes active.
+
+**P33R H1V3S** — each peer renders as a card row: a globe icon
+(`🌐`), the peer's configured label as the primary name, and the
+peer dashboard URL as a clickable secondary link. Clicking the
+URL opens the peer hive's dashboard in a new tab.
+
+### Backend wiring
+
+The host daemon reads `services.hyperhive.swarm.peers` from the
+nix config, serialises each entry as `{ name, url }` into
+`state.peer_hives: Vec<PeerHiveView>`, and includes the field
+in the `/api/state` snapshot. `tabs.js` reads
+`state.peer_hives` on every `refreshState` call and calls
+`renderPeerHives(peers)`, which rebuilds the `#peers-section`
+div from scratch.
+
+The `name` field is the operator-assigned label; `url` is the
+peer's dashboard root URL (e.g. `http://domain/`). Both come
+from the env var `HYPERHIVE_PEERS` (a JSON array of
+`{ label, domain }` pairs) that the nix module writes into the
+c0re container environment. `parse_peer_hives()` in `dashboard.rs`
+converts `domain` to `url = http://{domain}/` for the frontend.
+
 ## S3TT1NGS tab
 
 Operator-local preferences. State lives in the browser's