From cabde572e9cfd9e51c9235e1dc87c35e4fd196e0 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Fri, 2 Oct 2026 12:56:54 +0200
Subject: [PATCH] docs(web-ui): scope dashboard.md to what the hive UI renders

Per mara's review: the hive UI doc covers only what hive-c0re's pages
render. Removed the M4TR1X page section (the hive gateway redirects
/matrix/ to the swarm matrix client, which the swarm UI's quick links
open), the swarm-UI forge/matrix account-linking lines from the
CR3D3NTIALS section, the infra-services hivectl paragraph, and the H0M3
Matrix/Forge absence line. Added a single pointer to docs/swarm/ui.md,
and stated the account-linking and Matrix quick-link facts there.

Refs #3902
---
 docs/swarm/ui.md         | 28 ++++++++++++++++++++++++
 docs/web-ui/dashboard.md | 46 ++++++++--------------------------------
 2 files changed, 37 insertions(+), 37 deletions(-)

diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md
index 6c8d5f58..1bf48bbd 100644
--- a/docs/swarm/ui.md
+++ b/docs/swarm/ui.md
@@ -19,6 +19,27 @@ Everything it shows comes from [`swarm-controller`](../../swarm-controller/READM
 An agent created here or with `swarmctl agent create` starts `paused`; set it
 `up` from its card.
 
+### Linking external accounts
+
+Each agent on `/agents` opens two dialogs that write a credential for it
+into the swarm secret store through swarm-controller. Both are blind
+set/update actions: no route lists linked accounts or hands a token back.
+
+- **link a matrix account** — `PUT /api/hives/{hive}/agents/{agent}/matrix-accounts/{account}`,
+  either a pasted bearer token or a user id + password that
+  swarm-controller logs in with, storing the token it gets back.
+- **link a forge account** — `PUT /api/hives/{hive}/agents/{agent}/forge-accounts/{label}`
+  with a forge URL and an access token, stored at
+  `swarm/agents/<agent>/forge/<label>`. The agent's
+  `hive-agent-forge-accounts` unit fetches it into
+  `<state>/forge-<label>-token` and `<state>/forge-<label>.json`, the files
+  `hive-forge -f <label>` reads. The unit never deletes a pair: linking
+  the same label again overwrites both files, and a pair whose label the
+  store doesn't list stays untouched.
+
+Where each credential lives and who reads it:
+[`credentials.md`](credentials.md).
+
 ## Enabling
 
 ```nix
@@ -82,6 +103,13 @@ controller's host — `swarm-authelia.nix`, `hive-matrix.nix`,
 a nix-only change to that service's module, or an operator adding an entry
 directly. An empty list hides the button.
 
+The **Matrix** entry opens the swarm's matrix web client (fluffychat,
+`services.hyperhive.deploy.matrix.gui.package`) at the homeserver's
+gateway host, `chat.<swarm domain>` by default. `hive-matrix.nix` adds it
+only when `services.hyperhive.deploy.matrix.gui.enable` is on and the
+homeserver has a gateway host, the same condition under which that vhost
+serves the client at `/`.
+
 <details><summary>Adding a swarm service name: the two wiring sites</summary>
 
 Adding a swarm service name means touching two things. Missing the
diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index bf1b355f..305734f8 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -3,13 +3,17 @@
 > Part of [Web UI](README.md). See also:
 > [Shape (shared)](shape.md) · [Per-agent page](agent.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).
 
 hive-c0re serves the dashboard at `/dashboard.html` (with the home page 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 (`#swarm`, `#call`,
 `#permissions`, `#schedules`) drives which pane is
-active; hash changes don't reload the page. FL0W, L0GS, and the optional
-M4TR1X client are separate pages reachable from the H0M3 hub at `/`, not
+active; hash changes don't reload the page. FL0W, L0GS, and the other
+standalone pages are reachable from the H0M3 hub at `/`, not
 from the dashboard tab strip.
 
 **Chrome header** (fixed, overlays the active tab pane):
@@ -17,8 +21,8 @@ from the dashboard tab strip.
   at `/`. Every surface links back to the hub rather than to each other.
 - **Tab strip**: `◆ SW4RM ◆`, `◆ Y3R C4LL ◆`, `◆ P3RM1SS10NS ◆`,
   `◆ SCH3DUL3S ◆`. In-page tabs only — the SYST3M panels live on the
-  standalone **C0R3** page (`/core.html`), and FL0W / L0GS / ST4TS /
-  M4TR1X live on their own pages too, all reachable from the
+  standalone **C0R3** page (`/core.html`), and FL0W / L0GS / ST4TS
+  live on their own pages too, all reachable from the
   H0M3 hub (not the tab strip). Count pills on SW4RM
   (container count), Y3R C4LL (pending approvals + unread
   operator messages), and SCH3DUL3S (active schedules).
@@ -165,11 +169,6 @@ last-sampled value (`null` until the first sample). Network isn't tracked
 per container — see `docs/networking/network.md` for the current
 per-agent netns model.
 
-Hive infrastructure services (`hive-ci`, `hive-forge`, `hive-gateway`,
-`hive-matrix`) have no dashboard panel — `hivectl stop`/`start`/`restart`
-is the only control surface, a separate host-admin-socket path with no
-HTTP route and no agent-facing equivalent.
-
 ## BU1LDS page (`/builds.html`)
 
 The build lifecycle hub — rebuild queue, live build log, meta inputs,
@@ -293,9 +292,7 @@ on the H0M3 hub, same minimal chrome as `/logs.html` (a `← home` back-link
 than `/core.html`'s plain title. Its own esbuild bundle
 (`credentials.js`); no SSE — it reads `/api/state` once for the (shared)
 agent picker and otherwise works off purpose-built endpoints per tab.
-One sub-tab:
-
-Link an external matrix account from the swarm UI (`LinkMatrixAccountForm` → swarm-controller).
+One sub-tab, GITHUB.
 
 ### GITHUB tab
 
@@ -315,8 +312,6 @@ Provisioning posts `POST /api/github-account` (form-encoded `agent`,
 `application/problem+json` with the message in `detail`. The token is never
 echoed back in either direction.
 
-Link an external forge account from the swarm UI (`LinkForgeAccountForm` → swarm-controller); the agent fetches it into the files `hive-forge -f <label>` reads. A `forge-<label>-token`/`forge-<label>.json` pair already on disk is never deleted, so `hive-forge -f <label>` keeps reading it until a swarm-UI link under that label overwrites both files (`nix/agent-modules/forge-accounts.nix:11-13,159-176`).
-
 ## P3RM1SS10NS tab
 
 Per-agent permission configuration. Two sections, each rendered as a
@@ -536,26 +531,6 @@ they're enabled there, because `NOTIF.show()` in
 `hyperhive.notify.muted` localStorage key, not on the buttons
 existing in the page DOM.
 
-## M4TR1X page (`/matrix/`, optional)
-
-A static matrix web client (default `pkgs.fluffychat-web` rebuilt
-with `--base-href /matrix/`, swappable via
-`services.hyperhive.deploy.matrix.gui.package`) served by the hive-gateway
-nginx container at `/matrix/` when
-`services.hyperhive.deploy.matrix.gui.enable` is on (defaults to
-`matrix.enable`). c0re signals availability via the
-`HIVE_MATRIX_GUI_ENABLED` env var → `state.matrix_gui_enabled` in
-`/api/state`; the gateway does the actual static serving.
-
-The operator reaches it from the swarm-ui LinksMenu (see
-`docs/swarm/ui.md::Quick links`), and logs in once with the
-in-host tuwunel homeserver URL (`http://localhost:8008` or whatever
-the matrix module exposes).
-
-The unified nginx-front re-root to
-`https://chat.${hyperhive.swarm.domain}` + `.well-known/matrix/client`
-autodiscovery lives in `docs/networking/gateway.md` (atlas's lane).
-
 ## FL0W page (`/flow.html`)
 
 A dedicated full-page terminal (not a tab pane — a separate HTML
@@ -607,9 +582,6 @@ from the shared theme (Catppuccin Mocha via `common.css` + `theme.css`).
 `home.js` fills the swarm/hive identity line at the top. All dashboard
 sub-pages include a `← Home` back-link for navigation.
 
-No Matrix or Forge tile here — the operator reaches those surfaces
-(`/matrix/`, the forge's own public URL) directly, not via the dashboard UI.
-
 ## L0GS page (`/logs.html`)
 
 A dedicated log-viewer page (not a tab pane — a separate HTML page),