diff --git a/.env.example b/.env.example
index e3db078d..61a3f6a9 100644
--- a/.env.example
+++ b/.env.example
@@ -10,7 +10,15 @@ DOMAIN=example.com
 PORT=3000
 HOST=0.0.0.0
 
-# Authentication — generate with: openssl rand -hex 32
+# ─── Authentication (REQUIRED) ──────────────────────────────
+# Secret that signs login tokens. This MUST be set to a strong random value.
+# Leaving it empty is intentional — `docker compose up` then fails immediately
+# with a clear message instead of the server boot-looping. Generate one with:
+#
+#     openssl rand -hex 32
+#
+# (./install.sh fills this in for you automatically — you only touch this when
+# configuring by hand.) Must be at least 32 characters.
 JWT_SECRET=
 
 # Registration — set to false to close signups after initial setup