diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..f529dc1
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,25 @@
+# Terra-View deployment configuration — EXAMPLE / template.
+#
+# Copy this to `.env` in the same directory as docker-compose.yml and fill in
+# real values:   cp .env.example .env
+# `.env` is gitignored — NEVER commit real secrets. Docker Compose auto-loads
+# `.env` and substitutes these into the ${VAR} placeholders in docker-compose.yml.
+
+# Cookie-signing secret shared by the client portal AND the operator-auth
+# session cookie. MUST be a strong random value in production — the in-code
+# fallback ("dev-insecure-change-me") is public and forgeable.
+# Generate one (and keep it secret):
+#   python3 -c "import secrets; print(secrets.token_urlsafe(48))"
+SECRET_KEY=change-me-generate-a-strong-random-value
+
+# Set true ONLY when the app is served over HTTPS. On plain HTTP leave it false,
+# or the browser won't send the session cookie and login will look broken.
+COOKIE_SECURE=false
+
+# Operator-auth login gate. Leave false to deploy "dark" (the app behaves exactly
+# as before — nothing gated, nothing can lock you out). Roll out by: deploy with
+# false -> seed a superadmin via `docker compose exec web-app python3
+# backend/operator_admin.py create-superadmin ...` -> confirm you can log in ->
+# set true and `docker compose up -d web-app` to enforce. Setting it back to
+# false is the instant escape hatch.
+OPERATOR_AUTH_ENABLED=false