docs: split swarm.md into a directory, starting with the services page

`docs/swarm.md` becomes `docs/swarm/README.md` and the shared-services
material moves to `docs/swarm/services.md`, following the shape
`docs/turn-loop/` and `docs/web-ui/` already use. The README keeps a
pointer so the reading path is unbroken.

Every referrer moved with it — five docs pages, two option descriptions
in swarm.nix, and CLAUDE.md's reading path. A pointer to a file that
moved is worse than one to a file that was deleted: the content still
exists, so the reader concludes the note is wrong rather than the path.

CLAUDE.md

@@ -223,7 +223,7 @@ read them à la carte.
   bridge network for?"** → [`docs/network.md`](docs/network.md).
 - **"How do I connect two hives into a swarm? How do I declare peer
   hives and configure TLS trust?"** →
-  [`docs/swarm.md`](docs/swarm.md).
+  [`docs/swarm/`](docs/swarm/README.md).
 - **"Where do agent snapshots go? How does the swarm's `btrfs receive`
   endpoint authenticate a pushing hive, and what does a snapshot
   actually contain?"** →

docs/README.md

@@ -71,7 +71,7 @@ declarations.
   discovery work?** → [`gateway.md`](gateway.md).
 - **How does DNS resolution work in agent containers? What's the
   bridge network for?** → [`network.md`](network.md).
-- **How do I connect two hives into a swarm?** → [`swarm.md`](swarm.md)
+- **How do I connect two hives into a swarm?** → [`swarm/`](swarm/README.md)
   (peer hives, TLS trust).
 - **Where do agent snapshots go? How does the swarm's `btrfs receive`
   endpoint authenticate a pushing hive?** →

docs/gateway.md

@@ -198,7 +198,7 @@ The issuer is a **host-held hive CA**, not a bare self-signed leaf. A host servi
 
 **Why a CA, not a bare leaf**: a bare self-signed leaf is its own trust anchor, so every regeneration is a new anchor every consumer must re-trust — and a runtime-generated, in-container leaf can't be wired into an agent's build-time trust store at all. With a stable CA, agents and federation peers trust it *once*; leaf rotation never re-breaks them.
 
-**What consumers trust**: `trust-bundle.pem` in the same state dir, not `ca.pem`. The hive CA is itself issued under the swarm root ([`swarm.md`](swarm.md#swarm-ca) has the hierarchy), and an intermediate is not a chain a verifier can terminate at — so the bundle carries the hive CA plus whatever it is rooted at. nginx is handed the leaf with the hive CA appended for the same reason. Everything that trusts the hive's TLS reads the bundle: agents (via `security.pki.certificateFiles`), the CI and forge containers, and a federating peer.
+**What consumers trust**: `trust-bundle.pem` in the same state dir, not `ca.pem`. The hive CA is itself issued under the swarm root ([`swarm/`](swarm/README.md#swarm-ca) has the hierarchy), and an intermediate is not a chain a verifier can terminate at — so the bundle carries the hive CA plus whatever it is rooted at. nginx is handed the leaf with the hive CA appended for the same reason. Everything that trusts the hive's TLS reads the bundle: agents (via `security.pki.certificateFiles`), the CI and forge containers, and a federating peer.
 
 **Why on by default**: matrix-dart-sdk (FluffyChat's SDK) hardcodes `https://<host>/.well-known/matrix/client` for homeserver discovery and refuses to fall back to plain http. Without TLS the browser client cannot bootstrap.
 

docs/matrix.md

@@ -180,7 +180,7 @@ at the protocol level from first boot (`allow_federation = true`) but
 no remote homeserver is trusted until listed here. For a closed
 single-hive deployment the default empty list is correct — add peer
 hive domains here when connecting hives into a swarm (see
-[`docs/swarm.md`](swarm.md)).
+[`docs/swarm/`](swarm/README.md)).
 
 **`maxRequestSize`** (default `20_000_000` bytes = 20 MB) — maximum
 size of a single matrix client request body. Matches the matrix-spec

docs/network.md

@@ -66,7 +66,7 @@ The flows, end to end:
   the host forwards + masquerades out its uplink.
 - **Swarm** — peer hives connect over the `wg-hive` WireGuard mesh
   and reach each other's gateway/forge across it
-  ([`docs/swarm.md`](swarm.md)).
+  ([`docs/swarm/`](swarm/README.md)).
 - **Control plane (no network)** — per-agent broker socket
   `/run/hive/mcp.sock`, privileged helper `/run/hive/priv.sock`,
   operator admin `/run/hyperhive/host.sock`, and the per-agent UI

docs/snapshot-store.md

@@ -35,7 +35,7 @@ services.hyperhive.swarm.wireguard = {
 
 The store host is a swarm member like any other: peers declare it, and
 it declares them, through `services.hyperhive.swarm.peers`. See
-[swarm.md](swarm.md) for the mesh itself.
+[swarm/](swarm/README.md) for the mesh itself.
 
 Note that the mesh is gated on `swarm.wireguard.enable`, **not** on
 `c0re.enable` --- a store host runs no hive and would otherwise get no

docs/swarm/README.md

@@ -115,62 +115,9 @@ swarm's trust hierarchy.
 
 ## Running the swarm's shared services
 
-Some things exist once per **swarm**, not once per hive: the forge, the
-matrix homeserver, the SSO provider, the CA. Two options say where the
-optional ones live, and everything else derives:
-
-```nix
-services.hyperhive.enableAllLocalDefaults = true;   # everything on this box
-# or, for a dedicated services host with hives elsewhere:
-services.hyperhive.swarm.enableRequiredServices = true;
-```
-
-`enableAllLocalDefaults` is the all-on-one-box switch: it defaults both
-`swarm.enableRequiredServices` (the shared services run here) and
-`swarm.ca.autoConfigure` (the swarm CA is generated here). Each derived
-toggle can still be set on its own, so "all local except X" needs no
-further option.
-
-**Both default to off**, and that is deliberate: a host cannot tell
-whether it is meant to be the swarm's service host, so this is an
-operator saying so rather than something inferred. With them off, a hive
-is a *client* of those services — it configures how to reach them and
-runs none of them.
-
-The forge is the exception, and not because it is per-hive: it is
-swarm-wide but **not optional**, being the canonical store for the meta
-flake and every agent's config repo, so it deploys with hyperhive itself
-and has no `enable` to derive from anything.
-
-### SSO (authelia)
-
-One authelia per swarm, in a `swarm-authelia` container, at
-`auth.<hive-domain>`. Operator and agents are both subjects of the same
-provider, differentiated by roles and claims rather than by mechanism —
-there is one IdP and one auth path.
-
-- **`swarm.authelia.enable`** — run the container here. Defaults from
-  `swarm.enableRequiredServices`.
-- **`swarm.authelia.url`** — where clients are sent to authenticate.
-  Present on **every** hive, defaulting to this host's own instance only
-  when this module is the thing running it; otherwise `null`, and a hive
-  joining someone else's swarm sets it explicitly. Null means "no SSO
-  configured", and consumers say so rather than guessing an address.
-
-The users database is written by swarm-controller, not by hand: agents
-are created and destroyed continuously, so the subject set is dynamic.
-This module only guarantees the file exists and parses, so authelia
-starts with nobody in it rather than failing to start — a provider with
-no subjects yet is the correct state before anything has provisioned
-them. Session and storage keys are generated in the container on first
-boot and never rotated automatically; replacing one invalidates data
-already written (sessions, the encrypted store), so that is an operator
-action.
-
-Storage is local sqlite and the notifier writes to a file. Both are
-small-deployment choices, and the scope is the justification: redis
-buys shared session state across replicas and there is one instance;
-SMTP exists to mail humans, and provisioning here is programmatic.
+One authelia, one matrix, one forge per swarm — which host runs them,
+and what a hive that runs none of them configures instead:
+[`services.md`](services.md).
 
 ## Declaring peer hives
 

docs/swarm/services.md

@@ -0,0 +1,59 @@
+# Swarm-wide services
+
+Some things exist once per **swarm**, not once per hive: the forge, the
+matrix homeserver, the SSO provider, the CA. Two options say where the
+optional ones live, and everything else derives:
+
+```nix
+services.hyperhive.enableAllLocalDefaults = true;   # everything on this box
+# or, for a dedicated services host with hives elsewhere:
+services.hyperhive.swarm.enableRequiredServices = true;
+```
+
+`enableAllLocalDefaults` is the all-on-one-box switch: it defaults both
+`swarm.enableRequiredServices` (the shared services run here) and
+`swarm.ca.autoConfigure` (the swarm CA is generated here). Each derived
+toggle can still be set on its own, so "all local except X" needs no
+further option.
+
+**Both default to off**, and that is deliberate: a host cannot tell
+whether it is meant to be the swarm's service host, so this is an
+operator saying so rather than something inferred. With them off, a hive
+is a *client* of those services — it configures how to reach them and
+runs none of them.
+
+The forge is the exception, and not because it is per-hive: it is
+swarm-wide but **not optional**, being the canonical store for the meta
+flake and every agent's config repo, so it deploys with hyperhive itself
+and has no `enable` to derive from anything.
+
+### SSO (authelia)
+
+One authelia per swarm, in a `swarm-authelia` container, at
+`auth.<hive-domain>`. Operator and agents are both subjects of the same
+provider, differentiated by roles and claims rather than by mechanism —
+there is one IdP and one auth path.
+
+- **`swarm.authelia.enable`** — run the container here. Defaults from
+  `swarm.enableRequiredServices`.
+- **`swarm.authelia.url`** — where clients are sent to authenticate.
+  Present on **every** hive, defaulting to this host's own instance only
+  when this module is the thing running it; otherwise `null`, and a hive
+  joining someone else's swarm sets it explicitly. Null means "no SSO
+  configured", and consumers say so rather than guessing an address.
+
+The users database is written by swarm-controller, not by hand: agents
+are created and destroyed continuously, so the subject set is dynamic.
+This module only guarantees the file exists and parses, so authelia
+starts with nobody in it rather than failing to start — a provider with
+no subjects yet is the correct state before anything has provisioned
+them. Session and storage keys are generated in the container on first
+boot and never rotated automatically; replacing one invalidates data
+already written (sessions, the encrypted store), so that is an operator
+action.
+
+Storage is local sqlite and the notifier writes to a file. Both are
+small-deployment choices, and the scope is the justification: redis
+buys shared session state across replicas and there is one instance;
+SMTP exists to mail humans, and provisioning here is programmatic.
+

nix/host-modules/swarm.nix

@@ -33,7 +33,7 @@
               Generate with `openssl x509 -noout -fingerprint -sha256`,
               then strip the colons and prepend `sha256:`. A malformed
               value is ignored with a warning rather than weakening
-              trust. See docs/swarm.md for the full recipe.
+              trust. See docs/swarm/README.md for the full recipe.
 
               Scopes only to hive-c0re's own peer HTTPS checks — it does
               NOT help Matrix federation (tuwunel validates against its
@@ -62,7 +62,7 @@
               inside the hive (agents + the Matrix container), never the
               host system trust store. Mutually complementary with
               `certFingerprint`; set `caCert` for the federation case. See
-              docs/swarm.md.
+              docs/swarm/README.md.
             '';
           };