diff --git a/.env.example b/.env.example
index 40503b36b..12e4e3d1c 100644
--- a/.env.example
+++ b/.env.example
@@ -116,3 +116,13 @@ LOG_TO_FILE=true
 # REQUIRE_EMAIL_VERIFIED=true, because an identity provider that does not
 # verify addresses would let anyone claim someone else's account. The whole
 # config is then skipped and logged; the app still starts.
+#
+# ISSUER_URL must be https:// and publicly reachable -- private, loopback,
+# link-local, numeric-encoded and IPv4-mapped hosts are rejected. An in-cluster
+# URL like http://keycloak:8080 is refused with a single log line and no SSO
+# button; use the externally-reachable HTTPS issuer URL instead.
+#
+# NAME is matched against the existing providers on every boot: setting it to
+# the name of one you already created in the UI ADOPTS and OVERWRITES it (its
+# issuer, client id and secret are replaced and it becomes read-only). Pick a
+# name that doesn't collide unless that takeover is intended.