diff --git a/docs/gateway.md b/docs/gateway.md
index 2be01b92..9673cc19 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -466,3 +466,14 @@ follow-up.
 display in the credential dialog. Defaults to `"hyperhive"`. Must not
 contain `"` or `$`.
 
+**Custom 401 page:** when credentials are absent or wrong, nginx serves
+a Catppuccin-styled `unauthorized.html` page (built into the same Nix
+derivation as the agent error pages) that tells the operator which
+`hivectl` command to run to create a user. The response status is still
+`401` (`error_page 401 =401 /__hive_auth_unauthorized`) so browsers
+present the login dialog on the first visit — users who dismiss the
+dialog see the human-readable hint. The internal exact-match location
+(`= /__hive_auth_unauthorized`) beats `location /` in nginx's prefix
+ordering, preventing the subrequest from looping back through
+`auth_basic`.
+