diff --git a/.env.example b/.env.example
index a110cc71..bd5ec34d 100644
--- a/.env.example
+++ b/.env.example
@@ -39,6 +39,39 @@ APP_KEY=base64:your-app-key-here=
 # Bcrypt cost factor for new password hashes.
 BCRYPT_COST=12
 
+# --- ANTI-DDOS (app-layer gate, production only) ---
+# On by default in production. Set to "false" to disable (not recommended).
+ANTI_DDOS_ENABLED=true
+# Per-category request thresholds over the given window (per client IP).
+ANTI_DDOS_PAGES_LIMIT=300
+ANTI_DDOS_PAGES_WINDOW_SEC=60
+ANTI_DDOS_API_LIMIT=600
+ANTI_DDOS_API_WINDOW_SEC=60
+ANTI_DDOS_AUTH_LIMIT=20
+ANTI_DDOS_AUTH_WINDOW_SEC=60
+# Whole-site safety valve per window (sheds everything for global_halt_ms when hit).
+ANTI_DDOS_GLOBAL_LIMIT=18000
+ANTI_DDOS_GLOBAL_WINDOW_SEC=60
+ANTI_DDOS_GLOBAL_HALT_MS=10000
+# Violations accumulate inside this window before an IP is hard-blocked.
+ANTI_DDOS_VIOLATION_WINDOW_SEC=600
+ANTI_DDOS_MAX_VIOLATIONS=10
+# Escalation tiers "minViolations:ttlSeconds" — how long an offender stays blocked.
+ANTI_DDOS_BLOCK_TIERS=5:600,20:3600,50:86400
+
+# --- CLOUDFLARE API (automatic edge blocks, optional) ---
+# When set, the anti-DDoS gate automatically mirrors hard-blocked IPs to the
+# zone's IP Access Rules so repeat offenders are dropped at the Cloudflare
+# edge (works on every plan, incl. Free). Token permissions required:
+#   Zone > Zone > Read  and  Zone > Firewall > Edit
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ZONE_ID=
+# Runtime toggle; leave true to auto-create Cloudflare blocks at the block
+# threshold. Also overridable live from the admin panel.
+CLOUDFLARE_AUTO_BLOCK_ENABLED=true
+# Override for tests/staging (production uses the public endpoint by default).
+CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
+
 # --- PATHS ---
 BADGE_UPLOAD_DIR=./public/assets/images/badges
 EMULATOR_JAR_PATH=./emulator/Arcturus.jar