docs/gateway.md

@@ -18,8 +18,6 @@ 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,8 +1,7 @@
 # First-run setup (fresh-deploy bootstrap)
 
 How to bring a fresh hyperhive hive online: provision accounts, open
-the gateway, bootstrap swarm SSO, make matrix reachable, and spawn the
-first sub-agents.
+the gateway, 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
@@ -35,44 +34,27 @@ echo "hunter2" | hivectl gateway create-user mara --password-stdin
 hivectl gateway list-users
 ```
 
-### 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.
+### 3 · Matrix
 
 ```bash
-# 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
+# 3a. Ensure the hive-internal admin account exists first
 hivectl matrix sync-admin
 
-# 4b. Provision ruth's own matrix account
+# 3b. Provision ruth's own matrix account
 hivectl matrix create-user ruth
 
-# 4c. Create a human matrix account
+# 3c. Create a human matrix account
 hivectl matrix create-user mara --password hunter2
 
-# 4d. Invite the operator to the hive Space (and optionally to rooms)
+# 3d. Invite the operator to the hive Space (and optionally to rooms)
 hivectl matrix invite mara
 hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'
 
-# 4e. Promote the operator to homeserver admin if needed
+# 3e. Promote the operator to homeserver admin if needed
 hivectl matrix promote-user mara
 ```
 
-### 5 · Spawn sub-agents
+### 4 · 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
@@ -93,7 +75,7 @@ request_init_config(name: "iris")
 
 See [`approvals.md`](approvals.md) for the full flow.
 
-### 6 · Useful host commands
+### 5 · Useful host commands
 
 ```bash
 # Roster: all agents, status, rev, parent, pending reminders

docs/swarm/sso.md

@@ -18,25 +18,10 @@ 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).)
 
-**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.
+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.
 
 Add the first subject on the host running authelia: