docs(3186): the setup walkthrough gains the swarm SSO bootstrap

`setup.md` is the page someone follows on a fresh deploy, and it had no
step for authelia at all — so the operator finished the walkthrough with
a crash-looping container and a 502, having done everything the doc
asked. The warnings added to sso.md and gateway.md only help someone who
is already debugging; this is the page that decides whether they end up
debugging.

New step 3, gated on `swarm.authelia.enable`, placed before matrix
because it is part of getting the front door open. Says plainly that it
is required to finish the install, names the symptom it prevents, and
links sso.md for the detail rather than restating it.

Renumbers matrix (4), spawn (5) and host commands (6), including the
matrix block's own 3a–3e labels, which would otherwise disagree with
their heading.

docs/gateway.md

@@ -18,6 +18,8 @@ Single nginx in front of every hyperhive web surface. Runs on the **host**, next
 
 The authelia vhost is declared only by the host that **runs** authelia, not by every hive that uses it — a client hive knows the swarm's `authelia.url` but must not answer for a name it doesn't serve. Its server name is exactly `swarm.authelia.domain`: authelia validates `authelia_url ⊂ session cookie domain` at startup, so a near-miss is a container that refuses to boot. It carries no `auth_basic` — the login page must not sit behind the login mechanism it replaces — and sets the four `X-Forwarded-{Proto,Host,Uri,For}` headers, since authelia decides by the *original* request rather than the hop it sees.
 
+⚠️ **A `502` from this vhost usually means authelia has no users yet, not that the proxy is misconfigured.** Authelia treats an empty user store as a fatal startup error, so an enabled-but-unbootstrapped swarm crash-loops the container while the vhost in front of it works perfectly. Check `journalctl -M swarm-authelia -u authelia-swarm` before suspecting anything here; the bootstrap step is in [`swarm/sso.md`](swarm/sso.md).
+
 Per-agent UIs stay sub-path because they're hyperhive-internal and base-path-aware. External standard apps (forge / matrix) get sub-domains because their defaults work cleanly at sub-domain root + per-origin cookies / storage isolation matters.
 
 ## Discovery flow (matrix)

docs/setup.md

@@ -1,7 +1,8 @@
 # First-run setup (fresh-deploy bootstrap)
 
 How to bring a fresh hyperhive hive online: provision accounts, open
-the gateway, make matrix reachable, and spawn the first sub-agents.
+the gateway, bootstrap swarm SSO, make matrix reachable, and spawn the
+first sub-agents.
 
 Aimed at `ruth` (the root/manager agent) on a fresh deploy, but it's a
 plain reference doc — read it whenever you need the bootstrap command
@@ -34,27 +35,44 @@ echo "hunter2" | hivectl gateway create-user mara --password-stdin
 hivectl gateway list-users
 ```
 
-### 3 · Matrix
+### 3 · Swarm SSO (only when `swarm.authelia.enable`)
+
+⚠️ **Required to finish the install, not optional.** Authelia treats an
+empty user store as a fatal startup error, so until this runs the
+container crash-loops and `auth.<swarm.domain>` answers `502 Bad
+Gateway` — a working vhost in front of an upstream that refuses to
+start. Skipping this step looks like a broken proxy.
 
 ```bash
-# 3a. Ensure the hive-internal admin account exists first
+# Runs as root on the host that RUNS authelia (not necessarily the
+# controller host). Prints a generated password once — record it.
+swarmctl user add mara --display-name Mara --email mara@example.com --group admins
+```
+
+Detail, including what the password is and why this stays manual:
+[`swarm/sso.md`](swarm/sso.md).
+
+### 4 · Matrix
+
+```bash
+# 4a. Ensure the hive-internal admin account exists first
 hivectl matrix sync-admin
 
-# 3b. Provision ruth's own matrix account
+# 4b. Provision ruth's own matrix account
 hivectl matrix create-user ruth
 
-# 3c. Create a human matrix account
+# 4c. Create a human matrix account
 hivectl matrix create-user mara --password hunter2
 
-# 3d. Invite the operator to the hive Space (and optionally to rooms)
+# 4d. Invite the operator to the hive Space (and optionally to rooms)
 hivectl matrix invite mara
 hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'
 
-# 3e. Promote the operator to homeserver admin if needed
+# 4e. Promote the operator to homeserver admin if needed
 hivectl matrix promote-user mara
 ```
 
-### 4 · Spawn sub-agents
+### 5 · Spawn sub-agents
 
 Sub-agent creation goes through the approval queue — ruth proposes, the
 operator approves, the container builds. From ruth's own turn (inside
@@ -75,7 +93,7 @@ request_init_config(name: "iris")
 
 See [`approvals.md`](approvals.md) for the full flow.
 
-### 5 · Useful host commands
+### 6 · Useful host commands
 
 ```bash
 # Roster: all agents, status, rev, parent, pending reminders

docs/swarm/sso.md

@@ -18,10 +18,25 @@ name all follow `swarm.authelia.enable`, so there is nothing to turn on
 separately. (Details, including why a client hive must not declare that
 vhost: [`../gateway.md`](../gateway.md).)
 
-Reachable is not the same as usable: the provider is generated with an
-empty user set, deliberately. A provider with nobody in it yet is the
-correct state for a fresh swarm — it is not a half-finished install, and
-seeding a default account would be a credential in a config file.
+**Authelia does not start until at least one user exists.** The user
+store is generated empty — deliberately, since seeding a default account
+would put a credential in a config file — but authelia validates it at
+startup and treats "no users" as fatal:
+
+```
+error reading the authentication database: could not validate the schema:
+  users: non zero value required
+```
+
+It then exits 1 and systemd restarts it, so a swarm that has been
+enabled but not bootstrapped shows a **crash-looping unit** and `502 Bad
+Gateway` from the vhost — not a login page with nobody able to use it.
+The gateway is working in that state; the upstream is not up.
+
+⚠️ So the step below is **required to finish the install**, not an
+optional first-login convenience. Run it before concluding anything is
+wrong with the proxy: a 502 here means "no users yet" far more often
+than it means a routing fault.
 
 Add the first subject on the host running authelia: