docs: improve environment variables documentation

.env.example

@@ -1,31 +1,73 @@
-# Local development environment variables
-# Copy this to .env and configure for your local setup
+# PolicyEngine API v2 - Environment Variables
+# Copy this to .env and configure for your environment
 
-# Supabase (local instance via `supabase start`)
+# =============================================================================
+# SUPABASE (Database & Storage)
+# =============================================================================
+# For local development: run `supabase start` and use the local URLs
+# For production: get these from Supabase Dashboard > Settings > API
+
+# Supabase API URL (NOT the database URL)
 SUPABASE_URL=http://127.0.0.1:54321
-SUPABASE_KEY=ey...
-SUPABASE_SERVICE_KEY=ey...
+
+# Supabase anon/public key (safe to expose in client)
+SUPABASE_KEY=your-anon-key
+
+# Supabase service role key (server-side only, never expose)
+SUPABASE_SERVICE_KEY=your-service-role-key
+
+# PostgreSQL connection string for direct database access
+# For production Supabase: use the "connection string" from Dashboard > Settings > Database
+# Format: postgresql://postgres.[project-ref]:[password]@[host]:6543/postgres
 SUPABASE_DB_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
 
-# Storage
+# =============================================================================
+# STORAGE
+# =============================================================================
+# Supabase storage bucket name for datasets
 STORAGE_BUCKET=datasets
 
-# API
+# =============================================================================
+# API CONFIGURATION
+# =============================================================================
 API_TITLE=PolicyEngine API
 API_VERSION=0.1.0
 API_PORT=8000
 DEBUG=true
 
-# Logfire (get token from https://logfire.pydantic.dev)
-LOGFIRE_TOKEN=your-logfire-token-here
+# =============================================================================
+# LOGGING (Logfire)
+# =============================================================================
+# Get token from https://logfire.pydantic.dev
+LOGFIRE_TOKEN=
 LOGFIRE_ENVIRONMENT=local
 
-# Modal.com (compute backend)
-# Get tokens from modal.com dashboard or via `modal token new`
-MODAL_TOKEN_ID=ak-...
-MODAL_TOKEN_SECRET=as-...
-
-# Demo agent
+# =============================================================================
+# AGENT (Claude Code)
+# =============================================================================
+# Anthropic API key for Claude
 ANTHROPIC_API_KEY=sk-ant-...
+
+# Whether to use Modal for agent compute (false = run locally)
 AGENT_USE_MODAL=false
+
+# PolicyEngine API URL that the agent will use
 POLICYENGINE_API_URL=http://localhost:8000
+
+# =============================================================================
+# MODAL SECRETS (for production)
+# =============================================================================
+# Modal secrets are NOT set via .env - they're managed via Modal CLI:
+#
+# 1. modal secret create policyengine-db \
+#      DATABASE_URL='postgresql://...' \
+#      SUPABASE_URL='https://...' \
+#      SUPABASE_KEY='...' \
+#      SUPABASE_SERVICE_KEY='...' \
+#      STORAGE_BUCKET='datasets'
+#
+# 2. modal secret create anthropic-api-key \
+#      ANTHROPIC_API_KEY='sk-ant-...'
+#
+# 3. modal secret create logfire-token \
+#      LOGFIRE_TOKEN='...'

README.md

@@ -166,6 +166,27 @@ GET  /variables               List variables
 GET  /health                  Health check
 ```
 
+## Environment variables
+
+Copy `.env.example` to `.env` and configure. All variables are documented in `.env.example`.
+
+| Variable | Description |
+|----------|-------------|
+| `SUPABASE_URL` | Supabase API URL (https://...) |
+| `SUPABASE_KEY` | Supabase anon/public key |
+| `SUPABASE_SERVICE_KEY` | Supabase service role key |
+| `SUPABASE_DB_URL` | PostgreSQL connection string |
+| `STORAGE_BUCKET` | Supabase storage bucket name |
+| `LOGFIRE_TOKEN` | Logfire observability token |
+| `ANTHROPIC_API_KEY` | Anthropic API key for agent |
+| `AGENT_USE_MODAL` | Use Modal for agent (true/false) |
+
+For production Modal deployment, secrets are managed via Modal CLI (not .env):
+```bash
+modal secret create policyengine-db DATABASE_URL='...' SUPABASE_URL='...' ...
+modal secret create anthropic-api-key ANTHROPIC_API_KEY='...'
+```
+
 ## Development
 
 ```bash

docs/.env.example

@@ -1,2 +1,7 @@
 # Docs site environment variables
+# Copy to .env.local for local development
+
+# API URL for the docs site to connect to
+# Local development: http://localhost:8000
+# Production: https://v2.api.policyengine.org
 NEXT_PUBLIC_API_URL=http://localhost:8000