docs(swarm): the shared-services switch and the SSO provider

Names the one toggle and what derives from it, and the authelia shape:
container where the swarm's services live, client pointer everywhere,
users database written by swarm-controller rather than by hand.

docs/swarm.md

@@ -113,6 +113,60 @@ the CA is re-issued under the root and the leaf re-signed. Until then
 the hive serves TLS exactly as before and is simply not part of the
 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 they
+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.
+
+### 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.
+
 ## Declaring peer hives
 
 ```nix