diff --git a/Configuration.md b/Configuration.md
new file mode 100644
index 0000000..7385c92
--- /dev/null
+++ b/Configuration.md
@@ -0,0 +1,163 @@
+# Configuration
+
+| Meta | Value |
+|------|-------|
+| **Repo** | `xpltdco/fractafrag` |
+| **Page** | `Configuration` |
+| **Audience** | developers, agents |
+| **Last Updated** | 2026-04-04 |
+| **Status** | current |
+
+## Overview
+
+Configuration is managed through environment variables defined in `.env` (loaded by Docker Compose). The API service parses settings via Pydantic Settings in `services/api/app/config.py`. The frontend uses Vite environment variables prefixed with `VITE_`.
+
+## Environment Variables
+
+### Database
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DB_PASS` | Yes | — | PostgreSQL password |
+| `POSTGRES_USER` | No | `fracta` | PostgreSQL username |
+| `POSTGRES_DB` | No | `fractafrag` | PostgreSQL database name |
+| `DATABASE_URL` | Auto | (constructed) | Full connection string: `postgresql+asyncpg://{user}:{pass}@postgres:5432/{db}` |
+
+### Authentication (JWT)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `JWT_SECRET` | Yes | — | HMAC signing key (must be 64 hex characters) |
+| `JWT_ALGORITHM` | No | `HS256` | JWT signing algorithm |
+| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | No | `15` | Access token TTL in minutes |
+| `JWT_REFRESH_TOKEN_EXPIRE_DAYS` | No | `30` | Refresh token TTL in days |
+
+### Cloudflare Turnstile (CAPTCHA)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TURNSTILE_SITE_KEY` | No | — | Frontend widget key (skipped if not set) |
+| `TURNSTILE_SECRET` | No | — | Server-side verification key |
+
+### Stripe (Payments)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `STRIPE_SECRET_KEY` | For M4 | — | Stripe API secret key |
+| `STRIPE_PUBLISHABLE_KEY` | For M4 | — | Stripe public key (frontend) |
+| `STRIPE_WEBHOOK_SECRET` | For M4 | — | Webhook signature verification |
+
+### AI Providers
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ANTHROPIC_API_KEY` | For AI gen | — | Claude API key (platform default) |
+| `OPENAI_API_KEY` | For AI gen | — | GPT API key (platform default) |
+| `BYOK_MASTER_KEY` | For BYOK | — | Encryption key for user-provided AI keys (32 hex chars) |
+
+### MCP Server
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MCP_API_KEY_SALT` | No | — | HMAC salt for MCP client key authentication |
+
+### Renderer
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MAX_RENDER_DURATION` | No | `8` | Max seconds to render a shader |
+| `RENDER_OUTPUT_DIR` | No | `/renders` | Volume mount path for render output |
+| `RENDERER_URL` | No | `http://renderer:3100` | Renderer service endpoint (used by worker) |
+
+### Redis
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `REDIS_URL` | No | `redis://redis:6379/0` | Redis connection string |
+
+### Frontend (Vite)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VITE_API_URL` | No | `http://localhost/api` | API endpoint for frontend |
+| `VITE_MCP_URL` | No | `http://localhost/mcp` | MCP server endpoint |
+
+### Celery Worker
+
+| Variable | Set In | Default | Description |
+|----------|--------|---------|-------------|
+| `CELERY_TASK_TIME_LIMIT` | docker-compose | `120` | Hard kill after N seconds |
+| `CELERY_TASK_SOFT_TIME_LIMIT` | docker-compose | `90` | Soft warning at N seconds |
+| `CELERY_WORKER_PREFETCH_MULTIPLIER` | docker-compose | `1` | Tasks fetched per worker |
+| `CELERY_WORKER_MAX_TASKS_PER_CHILD` | docker-compose | `100` | Worker recycling threshold |
+
+## PostgreSQL Extensions
+
+Enabled in `db/init.sql`:
+
+| Extension | Purpose |
+|-----------|---------|
+| `uuid-ossp` | UUID generation (`gen_random_uuid()`) |
+| `vector` | pgvector for similarity search (512-dim) |
+| `pg_trgm` | Trigram text search on titles and prompts |
+
+## Redis Configuration
+
+Set via Docker Compose command:
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| `appendonly` | `yes` | AOF persistence enabled |
+| `maxmemory` | `256mb` | Memory cap |
+| `maxmemory-policy` | `allkeys-lru` | Evict least-recently-used keys |
+
+## Subscription Tiers
+
+Configured in the application (not environment):
+
+| Tier | Shader Limit | Desires | AI Gen | API Keys | BYOK |
+|------|-------------|---------|--------|----------|------|
+| `free` | 5/month | Read only | No | No | No |
+| `pro` | Unlimited | Create + tip | Yes (credits) | Yes | Yes |
+| `studio` | Unlimited | Create + tip | Yes (unlimited) | Yes | Yes |
+
+## Example .env File
+
+```env
+# Database
+DB_PASS=your-secure-database-password
+POSTGRES_USER=fracta
+POSTGRES_DB=fractafrag
+
+# JWT (generate with: openssl rand -hex 32)
+JWT_SECRET=your-64-hex-character-jwt-secret-key-here-must-be-exactly-64chars
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
+JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
+
+# Cloudflare Turnstile (optional in dev)
+# TURNSTILE_SITE_KEY=your-site-key
+# TURNSTILE_SECRET=your-secret-key
+
+# Stripe (optional until M4)
+# STRIPE_SECRET_KEY=sk_test_...
+# STRIPE_PUBLISHABLE_KEY=pk_test_...
+# STRIPE_WEBHOOK_SECRET=whsec_...
+
+# AI Providers (optional until M5)
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# BYOK_MASTER_KEY=your-32-hex-char-master-key
+
+# MCP
+# MCP_API_KEY_SALT=your-hmac-salt
+
+# Renderer
+MAX_RENDER_DURATION=8
+
+# Redis
+REDIS_URL=redis://redis:6379/0
+
+# Frontend
+VITE_API_URL=http://localhost/api
+VITE_MCP_URL=http://localhost/mcp
+```
\ No newline at end of file