diff --git a/docs/gateway.md b/docs/gateway.md
index 544296da..b02b9752 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -477,10 +477,16 @@ palette (`#1e1e2e` bg, `#cdd6f4` text, `#cba6f7` heading). No
 dependencies on the frontend dist — these pages render even when
 hive-c0re itself is down.
 
-Scope is intentionally narrow: only routes already special-cased in
-the nginx config get custom error pages. Other gateway routes
-(forge / matrix / fluffychat) get nginx defaults — extending the
-custom-error pattern there is a separate follow-up.
+Scope is intentionally narrow: a route earns a custom page when the
+default status code would point at the wrong component. The per-agent
+routes qualify (a 502 there means the harness is restarting, not that
+the gateway is broken), and so does `auth.<swarm>` — a dead authelia
+upstream almost always means the user store was never bootstrapped, and
+a bare 502 blames the proxy, which is the one part that is working.
+
+Forge / matrix / fluffychat still get nginx defaults: their upstreams
+being down means what the status code says, so a themed page would add
+styling and no information.
 
 ## HTTP Basic auth
 
diff --git a/nix/host-modules/hive-gateway/vhosts.nix b/nix/host-modules/hive-gateway/vhosts.nix
index 297c724f..06eb4482 100644
--- a/nix/host-modules/hive-gateway/vhosts.nix
+++ b/nix/host-modules/hive-gateway/vhosts.nix
@@ -13,7 +13,7 @@
   hyperhiveDomain,
   dashboardDist,
   swaggerUiTheme, # nix/packages/swagger-ui-theme.nix: has index.html + hyperhive-theme.css
-  errorPages, # ./error-pages.nix: { notFound, unreachable, unauthorized }
+  errorPages, # ./error-pages.nix: { notFound, unreachable, unauthorized, ssoUnavailable }
   tlsCert,
   tlsKey,
   svcCert, # swarm-services leaf, for names the hive CA cannot sign