diff --git a/docs/gateway.md b/docs/gateway.md
index 4274892d..544296da 100644
--- a/docs/gateway.md
+++ b/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)
diff --git a/docs/swarm/sso.md b/docs/swarm/sso.md
index 627120c4..a0775860 100644
--- a/docs/swarm/sso.md
+++ b/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: