diff --git a/Configuration.md b/Configuration.md
new file mode 100644
index 0000000..0cb0a6d
--- /dev/null
+++ b/Configuration.md
@@ -0,0 +1,99 @@
+# Configuration
+
+| Meta | Value |
+|------|-------|
+| **Repo** | `xpltdco/media-rip` |
+| **Page** | `Configuration` |
+| **Audience** | developers, agents |
+| **Last Updated** | 2026-04-04 |
+| **Status** | current |
+
+## Config Priority
+
+1. **Environment variables** (highest — always win)
+2. **YAML file** (`/app/config.yaml` mount)
+3. **Admin panel changes** (persisted to SQLite `config` table)
+4. **Hardcoded defaults** (lowest)
+
+Env var format: `MEDIARIP__SECTION__KEY=value` (double underscore separator).
+
+## Server
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEDIARIP__SERVER__HOST` | `0.0.0.0` | Bind address |
+| `MEDIARIP__SERVER__PORT` | `8000` | Listen port |
+| `MEDIARIP__SERVER__LOG_LEVEL` | `info` | `debug`, `info`, `warning`, `error` |
+| `MEDIARIP__SERVER__DB_PATH` | `mediarip.db` | SQLite database filename |
+| `MEDIARIP__SERVER__DATA_DIR` | `/data` | Config/session storage directory |
+| `MEDIARIP__SERVER__API_KEY` | — | Optional API key for non-browser access |
+
+## Downloads
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEDIARIP__DOWNLOADS__OUTPUT_DIR` | `/downloads` | Media output directory |
+| `MEDIARIP__DOWNLOADS__MAX_CONCURRENT` | `3` | Max parallel download threads |
+
+## Session
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEDIARIP__SESSION__MODE` | `isolated` | `isolated` (per-browser), `shared` (all users), `open` (no cookies) |
+| `MEDIARIP__SESSION__TIMEOUT_HOURS` | `72` | Cookie/session lifetime in hours |
+
+## Admin
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEDIARIP__ADMIN__ENABLED` | `true` | Enable admin panel |
+| `MEDIARIP__ADMIN__USERNAME` | `admin` | Admin username |
+| `MEDIARIP__ADMIN__PASSWORD` | — | Plaintext password (hashed with bcrypt at startup, cleared from memory) |
+
+## Purge (Auto-Cleanup)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEDIARIP__PURGE__ENABLED` | `true` | Enable scheduled cleanup |
+| `MEDIARIP__PURGE__MAX_AGE_MINUTES` | `1440` | Retention period (default 24h) |
+| `MEDIARIP__PURGE__CRON` | `* * * * *` | Cron schedule (default: every minute) |
+| `MEDIARIP__PURGE__PRIVACY_MODE` | `false` | Aggressive cleanup (deletes downloads + logs) |
+| `MEDIARIP__PURGE__PRIVACY_RETENTION_MINUTES` | `1440` | Privacy mode retention |
+
+## UI
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEDIARIP__UI__DEFAULT_THEME` | `dark` | Default theme ID |
+| `MEDIARIP__UI__WELCOME_MESSAGE` | — | Custom header text |
+| `MEDIARIP__UI__THEME_DARK` | `cyberpunk` | Theme for dark mode |
+| `MEDIARIP__UI__THEME_LIGHT` | `light` | Theme for light mode |
+| `MEDIARIP__UI__THEME_DEFAULT_MODE` | `dark` | Initial mode (`dark` or `light`) |
+
+## yt-dlp
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEDIARIP__YTDLP__EXTRACTOR_ARGS` | — | JSON object for yt-dlp extractor_args |
+
+Example: `'{"youtube": {"player_client": ["web_safari"]}}'`
+
+## Built-in Themes
+
+| ID | Mode | Style |
+|----|------|-------|
+| `cyberpunk` | Dark | Neon chrome aesthetic (default dark) |
+| `dark` | Dark | Standard dark |
+| `midnight` | Dark | Deep blue |
+| `hacker` | Dark | Green terminal |
+| `neon` | Dark | Vivid neon colors |
+| `light` | Light | Clean white (default light) |
+| `paper` | Light | Warm off-white |
+| `arctic` | Light | Cool blue-white |
+| `solarized` | Light | Solarized palette |
+
+## Custom Themes
+
+Mount a directory to `/themes`. Each theme is a subdirectory containing:
+- `metadata.json`: `{"name": "My Theme", "author": "...", "description": "..."}`
+- `theme.css`: CSS custom property overrides (50+ variables available)
\ No newline at end of file