docs: add swarm.md — multi-hive peer config guide

docs/swarm.md

@@ -0,0 +1,103 @@
+# Multi-hive swarms
+
+A **swarm** is a collection of agents that share an identity and
+coordinate across one or more hives. A single hyperhive instance
+running on one host is already a swarm (one hive). This doc covers
+the additional config needed when the swarm spans multiple hosts.
+
+## Terminology
+
+- **hive** — a single hyperhive installation on one host. Has its
+  own `services.hyperhive.domain` DNS name and its own set of agent
+  containers.
+- **swarm** — one or more hives whose operators have declared them
+  as peers. Agents can be qualified as `agent@hive-domain`.
+- **peer hive** — a remote hive declared under
+  `services.hyperhive.swarm.peers` on the local host.
+
+## Hive identity config
+
+```nix
+services.hyperhive = {
+  domain   = "pr1ma.example.com";   # machine-addressable DNS domain
+  hiveName  = "pr1ma";              # human display name (optional)
+  swarmName = "constellat1on";      # shared swarm display name (optional)
+};
+```
+
+`domain` is required when matrix federation is on (`matrix.enable`);
+it drives `HYPERHIVE_HIVE_DOMAIN` in every container so agents can
+form qualified labels (`iris@pr1ma.example.com`). `hiveName` and
+`swarmName` are purely display — they surface in the dashboard chrome
+header and per-agent system prompts. Federated hives at different
+domains can share a `swarmName`.
+
+See `docs/conventions.md` § Hive identity for the env-var chain
+and `qualify()` / `qualified_label()` semantics.
+
+## Declaring peer hives
+
+```nix
+services.hyperhive.swarm.peers = {
+  "lab.example.com"  = { };                               # CA-trusted (Let's Encrypt etc.)
+  "edge.corp"        = { certFingerprint = "sha256:…"; }; # self-signed TLS
+};
+```
+
+The attrset key is the peer's DNS domain. `certFingerprint` is
+optional:
+
+- **Omitted / null** — the system CA bundle validates the peer's TLS
+  cert. Correct for peers with Let's Encrypt or any standard CA cert.
+- **Set** (`"sha256:…"`) — pin a specific cert fingerprint. Use this
+  for peers whose self-signed TLS cert doesn't chain to a CA your
+  host trusts.
+
+The nix module serialises the attrset to a `HYPERHIVE_PEERS` JSON
+array (`[{ domain, cert_fingerprint }]`) injected into the c0re
+environment and forwarded to agent containers.
+
+## What the config does at runtime
+
+1. **Dashboard P33RS tab** — `parse_peer_hives()` in `dashboard.rs`
+   reads `HYPERHIVE_PEERS` and includes
+   `peer_hives: Vec<{ name, url }>` in `/api/state`. The dashboard
+   shows a P33RS tab (hidden when the list is empty) with a card per
+   peer linking to `https://{domain}/`. See
+   `docs/web-ui/dashboard.md` § P33RS tab.
+
+2. **Agent identity** — `identity::peers()` in `hive-ag3nt` reads
+   the same env var and exposes the peer list to agents via
+   `get_agent_meta` so agents can address peers with qualified names
+   (`agent@peer-domain`).
+
+3. **Matrix federation** — when `matrix.enable` is on, tuwunel
+   federates with the peer's matrix server at
+   `matrix.{peer-domain}:8448`. No extra config needed; federation
+   works as soon as the domains are reachable and TLS validates.
+   See `docs/matrix.md` for federation firewall requirements.
+
+## Bilateral setup
+
+Each hive must declare the other. If hive A lists hive B as a peer,
+B must also list A for agents on B to see A in their peer list:
+
+```
+# hive A (pr1ma.example.com)
+services.hyperhive.swarm.peers."edge.corp" = { };
+
+# hive B (edge.corp)
+services.hyperhive.swarm.peers."pr1ma.example.com" = { certFingerprint = "sha256:…"; };
+```
+
+Mixed trust is fine: A trusts B via CA bundle (no fingerprint), B
+pins A's self-signed cert.
+
+## Cross-references
+
+- `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/gateway.md` — nginx vhosts and the `.well-known/matrix/`
+  auto-discovery scheme