diff --git a/config/.env.template b/config/.env.template
index 4850222..bd0de14 100644
--- a/config/.env.template
+++ b/config/.env.template
@@ -1,22 +1,45 @@
 # Agnes AI Data Analyst - Environment Variables
+# =============================================
 # Copy to .env: cp config/.env.template .env
 # .env is gitignored - NEVER commit it.
 
-# Required
-JWT_SECRET_KEY=           # python -c "import secrets; print(secrets.token_hex(32))"
+# ── REQUIRED ────────────────────────────────────────
+JWT_SECRET_KEY=              # python -c "import secrets; print(secrets.token_hex(32))"
+SESSION_SECRET=              # python -c "import secrets; print(secrets.token_hex(32))"
 
-# Google OAuth (optional — needed for Google login)
+# ── GOOGLE OAUTH (required for Google login) ────────
 # GOOGLE_CLIENT_ID=
 # GOOGLE_CLIENT_SECRET=
 
-# Keboola adapter (optional — skip if using CSV/sample data)
+# ── KEBOOLA (required for Keboola data source) ──────
 # KEBOOLA_STORAGE_TOKEN=
 # KEBOOLA_STACK_URL=https://connection.keboola.com
 
-# Bootstrap admin (optional — used on first docker compose up)
+# ── BIGQUERY (required for BigQuery data source) ─────
+# BIGQUERY_PROJECT=
+# BIGQUERY_LOCATION=us
+
+# ── BOOTSTRAP (first deploy only) ───────────────────
 # SEED_ADMIN_EMAIL=admin@example.com
 
-# Optional services
+# ── EMAIL / SMTP (required for magic link auth) ─────
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASSWORD=
+
+# ── OPTIONAL SERVICES ───────────────────────────────
 # TELEGRAM_BOT_TOKEN=
 # JIRA_WEBHOOK_SECRET=
+# JIRA_API_TOKEN=
 # ANTHROPIC_API_KEY=
+# LLM_API_KEY=
+
+# ── DESKTOP APP ─────────────────────────────────────
+# DESKTOP_JWT_SECRET=       # Separate secret for desktop app tokens
+
+# ── DEPLOYMENT ──────────────────────────────────────
+# DATA_DIR=/data            # Default: /data in Docker, ./data locally
+# LOG_LEVEL=info            # debug, info, warning, error
+# CORS_ORIGINS=http://localhost:3000,http://localhost:8000
+# DOMAIN=data.yourcompany.com  # For Caddy TLS (production profile)