diff --git a/docs/setup.md b/docs/setup.md
index a49ebb12..41050375 100644
--- a/docs/setup.md
+++ b/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