docs+nix: fix stale peer-hives-dashboard references (hyperhive#3294)

Follow-up to the peer-hives removal: docs/web-ui/dashboard.md drops
the whole "P33R H1V3S" section + its stale #peers hash and tab-strip
mentions; docs/swarm/README.md's runtime-effects list and
cross-references point at swarm-ui's roster page instead. Nix comments
in hive-c0re/environment.nix, swarm.nix and swarm-wireguard.nix that
described HYPERHIVE_PEERS/certFingerprint as dashboard-consumed are
updated to say what's actually still true (agent identity only).

Deliberately NOT removed: the `certFingerprint` nix option itself.
It has no remaining Rust consumer, but deleting a documented,
potentially already-set option is a bigger, breaking change than
removing dead display code — flagged in docs/swarm/README.md with a
note instead of silently dropped, so an operator or reviewer can make
that call explicitly rather than have it made for them here.
This commit is contained in:
iris 2026-08-15 17:37:36 +02:00
commit 8c8f0e2758
5 changed files with 39 additions and 67 deletions

View file

@ -129,10 +129,17 @@ conventionally `<name>.<swarm.domain>`, but a wrong domain that
evaluates cleanly points at a real machine that isn't the one you meant.
**`certFingerprint`** (`"sha256:…"`, optional) pins that hive's TLS
_leaf_. Scopes **only** to hive-c0re's own peer HTTPS checks (the P33RS
dashboard links + agent peer discovery below); matrix federation never
consults it. Omit it for any hive under the swarm root CA or a public
CA — which is the normal case.
_leaf_. Matrix federation never consults it. Omit it for any hive
under the swarm root CA or a public CA — which is the normal case.
⚠️ **Currently unconsumed by any Rust code.** It was read by the
per-hive dashboard's now-removed "peer hives" display (see below);
that was its only consumer. Left in place rather than deleted along
with that display — removing a documented, potentially
already-set nix option is a bigger, more consequential (breaking)
change than removing dead display code, and wants its own explicit
decision rather than being swept up here. A future peer-facing
feature (e.g. pinning a peer in `swarm-ui`) could pick it back up.
> **There is no per-hive CA field.** Trust inside a swarm comes from the
> swarm root ([`ca.md`](ca.md)): every hive chains to it, so one anchor
@ -180,19 +187,17 @@ environment and forwarded to agent containers.
## What the config does at runtime
1. **Dashboard P33RS tab** — hive-c0re reads `HYPERHIVE_PEERS` and
surfaces it as the peer list in the dashboard's state API. The
dashboard shows a P33RS tab (hidden when the list is empty) with a
card per peer linking to `https://{domain}/`. Wire format + module
pointer: `docs/web-ui/dashboard.md` § P33RS tab.
2. **Agent identity** — the same `HYPERHIVE_PEERS` env var is
forwarded to agent containers, so agent code can discover peer
hives and address them with qualified names (`agent@domain`). See
1. **Agent identity** — the `HYPERHIVE_PEERS` env var is forwarded to
agent containers, so agent code can discover peer hives and
address them with qualified names (`agent@domain`). See
`hive-agent/src/identity.rs`'s module doc for the label/domain
helpers.
helpers. The swarm-wide hive roster used to also be shown as a
"peer hives" list on the per-hive dashboard; that display was
removed in favour of `swarm-ui`'s own roster page (`docs/swarm/
ui.md`), which reads the same directory from `swarm-controller`
instead.
3. **Matrix federation** — when `matrix.enable` is on, tuwunel
2. **Matrix federation** — when `matrix.enable` is on, tuwunel
federates with the peer's matrix server (discovered via the peer's
`.well-known/matrix/server` delegation, which the gateway serves).
Federation validates the peer's TLS certificate against the matrix
@ -370,6 +375,8 @@ it is stored in the queue, not in the daemon.
- `docs/conventions.md` § Hive identity — env vars, qualified labels
- `docs/matrix.md` — matrix federation, TLS cert auto-generation,
firewall posture
- `docs/web-ui/dashboard.md` § P33RS tab — dashboard surface
- `docs/swarm/ui.md` — the swarm-wide hive roster, now the operator
surface for "what hives exist" (superseded the per-hive dashboard's
old "peer hives" display)
- `docs/gateway.md` — nginx vhosts and the `.well-known/matrix/`
auto-discovery scheme