diff --git a/.env.example b/.env.example
index c96d7f7..4ce5c49 100644
--- a/.env.example
+++ b/.env.example
@@ -6,6 +6,15 @@
 #
 # `.env` is gitignored; this `.env.example` file is the canonical reference.
 
+# ---- Mode ----
+
+# Set to `production` to enable strict startup checks (most importantly:
+# the server refuses to boot when DB_PASSWORD is empty instead of warning
+# and continuing). Leave unset / `development` for local + test runs that
+# don't need a real database. The Dockerfile and docker-compose.yml api
+# service both default this to `production` automatically.
+# NODE_ENV=production
+
 # ---- HTTP server ----
 
 # Port the API listens on. Use a non-privileged port (>1024) so the process