diff --git a/.env.example b/.env.example
index ab39c6c..3d4290c 100644
--- a/.env.example
+++ b/.env.example
@@ -1,33 +1,50 @@
-# =============================================================================
-# Control Center — Environment Configuration Template
-# =============================================================================
-# Copy this file to `.env` and fill in real values.
-# Never commit `.env` — it is in .gitignore by default.
-# =============================================================================
+# Control Center - Environment Variables
+# ======================================
 
-# ── Database ────────────────────────────────────────────────────────────────
-POSTGRES_DB=controlcenter
-POSTGRES_USER=controlcenter
-POSTGRES_PASSWORD=changeme
-POSTGRES_PORT=5432
-
-# ── Backend ───────────────────────────────────────────────────────────────────
-BACKEND_PORT=8080
+# ── Backend Variables ───────────────────────────────────────────────────
+# Server configuration
+PORT=8080
+CORS_ORIGIN=http://localhost:3000
 LOG_LEVEL=info
 ENVIRONMENT=development
 
-# ── Frontend ────────────────────────────────────────────────────────────────
-FRONTEND_PORT=3000
+# Database connection (PostgreSQL DSN)
+# Format: postgresql://user:password@host:port/database?sslmode=disable
+DATABASE_URL=postgresql://controlcenter:controlcenter@localhost:5432/controlcenter?sslmode=disable
 
-# ── CORS ────────────────────────────────────────────────────────────────────
-# Comma-separated allowed origins.  Use "*" for local dev.
-CORS_ORIGIN=http://localhost:3000
+# Gateway (OpenClaw) connection
+# WebSocket gateway config (primary path)
+WS_GATEWAY_URL=ws://host.docker.internal:18789/
+# Gateway auth token — same as OPENCLAW_GATEWAY_TOKEN (set in environment)
+GATEWAY_TOKEN=
 
-# ── OpenClaw Gateway ──────────────────────────────────────────────────────────
-# URL to the OpenClaw gateway agent status endpoint.
-# In Docker Compose, use the container name or host.docker.internal for the
-# gateway running outside Compose.
+# REST poller config (fallback, only used if WS fails to connect)
 GATEWAY_URL=http://host.docker.internal:18789/api/agents
-
-# How often to poll the gateway for agent state updates.
+# Polling interval for agent state updates (fallback only)
 GATEWAY_POLL_INTERVAL=5s
+
+# ── Frontend Variables (via Vite) ───────────────────────────────────────
+# The Vite config exposes these as import.meta.env.VITE_*
+# Set via environment variable when building: VITE_API_URL
+# VITE_API_URL=http://localhost:8080
+
+# ── Docker Compose Specific ─────────────────────────────────────────────
+# When using docker-compose, these are set in the services section
+# See docker-compose.yml for service-specific environment variables
+
+# ── Database Configuration ─────────────────────────────────────────────
+# Set in the db service environment section of docker-compose.yml
+# POSTGRES_USER=controlcenter
+# POSTGRES_PASSWORD=controlcenter
+# POSTGRES_DB=controlcenter
+
+# ── Development Notes ───────────────────────────────────────────────────
+# For local development without Docker:
+# 1. Start PostgreSQL locally
+# 2. Run: go run ./cmd/server/main.go
+# 3. Run: npm run dev in frontend/
+#
+# For Docker deployment:
+# 1. Copy .env.example to .env (backend only)
+# 2. Run: docker compose up -d
+# 3. Access frontend at http://localhost:3000