diff --git a/.env.example b/.env.example
index d7b0d49..cd56468 100644
--- a/.env.example
+++ b/.env.example
@@ -1,17 +1,85 @@
-# Database
+# ─────────────────────────────────────────────────────────────────────────────
+# CapaKraken — environment variable reference
+#
+# Copy this file to .env and fill in the values before running the app.
+# Lines starting with # are comments. Lines with no value are optional.
+#
+# IMPORTANT: Never commit your actual .env file — it is gitignored.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ─── App / Auth ──────────────────────────────────────────────────────────────
+
+# REQUIRED — Public URL of the app (with scheme, no trailing slash).
+# Used in email links (invites, password reset) and as the Auth.js base URL.
+# Must use https:// in production.
+NEXTAUTH_URL=https://capakraken.example.com
+
+# REQUIRED — Secret used to sign and encrypt JWTs and session cookies.
+# Generate one with: openssl rand -base64 32
+# Must not be a known placeholder value in production (e.g. "changeme").
+NEXTAUTH_SECRET=
+
+# ─── Database ────────────────────────────────────────────────────────────────
+
+# REQUIRED — PostgreSQL connection string.
+# When running with Docker Compose the app container uses the Docker-internal
+# host (postgres:5432); the host-level connection (for pnpm dev on the host)
+# uses localhost:5433 (the published port).
 DATABASE_URL=postgresql://capakraken:capakraken_dev@localhost:5433/capakraken
-DATABASE_URL_TEST=postgresql://capakraken:capakraken_test@localhost:5434/capakraken_test
-ALLOW_DESTRUCTIVE_DB_TOOLS=false
-CONFIRM_DESTRUCTIVE_DB_NAME=
 
-# Redis
-REDIS_URL=redis://localhost:6380
+# ─── Redis ───────────────────────────────────────────────────────────────────
 
-# Auth.js
-NEXTAUTH_URL=http://localhost:3100
-# Local development only. Production must provide a long random secret outside the repository.
-NEXTAUTH_SECRET=dev-secret-change-in-production
+# REQUIRED for SSE (real-time updates) and rate limiting.
+# When using Docker Compose this is handled automatically inside the container
+# (redis://redis:6379). Only needed when running `pnpm dev` directly on the host.
+# REDIS_URL=redis://localhost:6380
 
-# App
-NODE_ENV=development
-PORT=3100
+# Controls which backend is used for rate limiting.
+# Values: "redis" (default, requires REDIS_URL) | "memory" (in-process, not
+# suitable for multi-instance deployments).
+# RATE_LIMIT_BACKEND=redis
+
+# ─── SMTP ────────────────────────────────────────────────────────────────────
+#
+# SMTP settings can be configured here OR via the Admin → Settings UI.
+# Environment variables override the database values at runtime.
+# If neither is set, email sending is silently skipped (logged at warn level).
+#
+# For local development the Docker Compose stack includes MailHog
+# (http://localhost:8025) — no SMTP configuration is needed there.
+
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_USER=no-reply@example.com
+# SMTP_PASSWORD=
+# SMTP_FROM=CapaKraken <no-reply@example.com>
+# SMTP_TLS=true     # "true" = SMTPS (port 465); "false" = STARTTLS or plain
+
+# ─── pgAdmin (dev / Docker Compose only) ─────────────────────────────────────
+
+# REQUIRED when starting Docker Compose with the `full` profile.
+# Used as the password for the pgAdmin web UI (http://localhost:5050).
+PGADMIN_PASSWORD=
+
+# Email shown on the pgAdmin login screen (default: admin@capakraken.dev).
+# PGADMIN_EMAIL=admin@capakraken.dev
+
+# ─── Logging ─────────────────────────────────────────────────────────────────
+
+# Log verbosity. Values: trace | debug | info | warn | error | fatal
+# Default: info
+# LOG_LEVEL=info
+
+# ─── Security / Cron ─────────────────────────────────────────────────────────
+
+# Secret used to authenticate requests to cron endpoints (/api/cron/*).
+# Generate one with: openssl rand -hex 32
+# If not set, cron endpoints are disabled.
+# CRON_SECRET=
+
+# ─── Testing (never enable in production) ────────────────────────────────────
+
+# Disables rate limiting and session tracking during end-to-end tests.
+# MUST be "false" or unset in production — the runtime will refuse to start
+# if this is "true" and NODE_ENV is "production".
+# E2E_TEST_MODE=false