diff --git a/Configuration.md b/Configuration.md
new file mode 100644
index 0000000..15b8e7b
--- /dev/null
+++ b/Configuration.md
@@ -0,0 +1,198 @@
+# Configuration
+
+| Meta | Value |
+|------|-------|
+| **Repo** | `xpltdco/tubearr` |
+| **Page** | `Configuration` |
+| **Audience** | developers, agents |
+| **Last Updated** | 2026-04-04 |
+| **Status** | current |
+
+## Overview
+
+All configuration is managed through environment variables, parsed in `src/config/index.ts`. In development, use a `.env` file (loaded via dotenv). In Docker, set variables in `docker-compose.yml` or pass them with `-e`.
+
+Some settings can also be changed at runtime via the API (`PUT /api/v1/system/settings`) and are persisted in the `systemConfig` database table.
+
+## Environment Variables
+
+### Server
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `TUBEARR_PORT` | number | `8989` | HTTP server listen port |
+| `NODE_ENV` | string | `development` | `development` or `production`. Affects logging format, Vite middleware, yt-dlp auto-update |
+| `TUBEARR_LOG_LEVEL` | string | `info` | Fastify/Pino log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal` |
+
+### Storage
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `TUBEARR_DB_PATH` | string | `./data/tubearr.db` | Path to SQLite database file. In Docker: `/config/tubearr.db` |
+| `TUBEARR_MEDIA_PATH` | string | `./media` | Root directory for downloaded media files. In Docker: `/media` |
+| `TUBEARR_COOKIE_PATH` | string | `./data/cookies` | Directory for per-platform cookie files. In Docker: `/config/cookies` |
+
+### Authentication
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `TUBEARR_API_KEY` | string | auto-generated UUID | API key for external access. If not set, a UUID is generated on first run and stored in the database |
+
+### Scheduling
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `TUBEARR_SCHEDULER_ENABLED` | boolean | `true` | Enable/disable the automatic channel monitoring scheduler |
+| `TUBEARR_DEFAULT_CHECK_INTERVAL` | number | `360` | Default channel check interval in minutes (6 hours) |
+
+### Rate Limiting
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `TUBEARR_RATELIMIT_YOUTUBE_MS` | number | `1000` | Minimum milliseconds between YouTube API requests |
+| `TUBEARR_RATELIMIT_SOUNDCLOUD_MS` | number | `3000` | Minimum milliseconds between SoundCloud API requests |
+
+### Concurrency
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `TUBEARR_CONCURRENT_DOWNLOADS` | number | `2` | Maximum number of simultaneous download tasks |
+
+## Runtime Settings (via API)
+
+These settings can be changed without restarting the application:
+
+| Setting | API Path | Stored In |
+|---------|----------|-----------|
+| Check interval | `PUT /api/v1/system/settings` | `systemConfig.check_interval` |
+| Concurrent downloads | `PUT /api/v1/system/settings` | `systemConfig.concurrent_downloads` |
+| API key | `POST /api/v1/system/apikey/regenerate` | `systemConfig.api_key` |
+
+## Platform Settings (via API)
+
+Per-platform defaults configured through `PUT /api/v1/platform-settings/:platform`:
+
+| Setting | Description | Applies To |
+|---------|-------------|------------|
+| `checkInterval` | Default monitoring interval (minutes) | New channels on this platform |
+| `concurrencyLimit` | Max concurrent operations | Rate-limited per platform |
+| `rateLimitDelay` | Milliseconds between requests | API throttling |
+| `defaultMonitoringMode` | Default mode for new channels | `all`, `future`, `existing`, `none` |
+| `grabAllEnabled` | Enable back-catalog import | Collect endpoints |
+| `grabAllOrder` | Import order | `newest` or `oldest` first |
+| `scanLimit` | Max items per scan | Monitoring checks |
+| `subtitleLanguages` | Default subtitle languages | Comma-separated codes |
+| `defaultFormatProfileId` | Default quality profile | New downloads |
+
+## Format Profiles (via API)
+
+Quality presets configured through `POST/PUT /api/v1/format-profile`:
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `videoResolution` | `best`, `2160p`, `1440p`, `1080p`, `720p`, `480p`, `360p` | Target video resolution |
+| `audioCodec` | `opus`, `aac`, `mp3`, `vorbis` | Preferred audio codec |
+| `audioBitrate` | `320k`, `256k`, `192k`, `128k`, `96k`, `64k` | Audio quality |
+| `containerFormat` | `mp4`, `mkv`, `webm`, `mp3`, `opus`, `m4a` | Output container |
+| `embedSubtitles` | boolean | Embed subtitles in media file |
+| `subtitleLanguages` | string | Comma-separated language codes (e.g., `en,es`) |
+| `embedChapters` | boolean | Embed chapter markers |
+| `embedThumbnail` | boolean | Embed thumbnail in metadata |
+| `sponsorBlockRemove` | string | Comma-separated SponsorBlock categories to auto-remove |
+
+**SponsorBlock categories:** `sponsor`, `selfpromo`, `interaction`, `intro`, `outro`, `preview`, `music_offtopic`, `filler`
+
+## Notification Channels (via API)
+
+Configured through `POST/PUT /api/v1/notification`:
+
+### Discord
+
+```json
+{
+  "type": "discord",
+  "config": {
+    "webhookUrl": "<your-discord-webhook-url>"
+  }
+}
+```
+
+### Email
+
+```json
+{
+  "type": "email",
+  "config": {
+    "smtpHost": "smtp.example.com",
+    "smtpPort": 587,
+    "username": "<your-email>",
+    "password": "<your-password>",
+    "to": "recipient@example.com"
+  }
+}
+```
+
+### Pushover
+
+```json
+{
+  "type": "pushover",
+  "config": {
+    "userKey": "<your-user-key>",
+    "apiToken": "<your-api-token>"
+  }
+}
+```
+
+### Telegram
+
+```json
+{
+  "type": "telegram",
+  "config": {
+    "botToken": "<your-bot-token>",
+    "chatId": "<your-chat-id>"
+  }
+}
+```
+
+Each notification channel has event toggles: `onGrab`, `onDownload`, `onFailure`.
+
+## Docker Environment Defaults
+
+When running in Docker (set automatically by the Dockerfile):
+
+| Variable | Docker Default |
+|----------|---------------|
+| `NODE_ENV` | `production` |
+| `TUBEARR_DB_PATH` | `/config/tubearr.db` |
+| `TUBEARR_MEDIA_PATH` | `/media` |
+| `TUBEARR_COOKIE_PATH` | `/config/cookies` |
+
+## Example .env File
+
+```env
+# Server
+TUBEARR_PORT=8989
+NODE_ENV=development
+TUBEARR_LOG_LEVEL=info
+
+# Storage
+TUBEARR_DB_PATH=./data/tubearr.db
+TUBEARR_MEDIA_PATH=./media
+TUBEARR_COOKIE_PATH=./data/cookies
+
+# Auth (optional — auto-generated if not set)
+# TUBEARR_API_KEY=your-uuid-here
+
+# Scheduling
+TUBEARR_SCHEDULER_ENABLED=true
+TUBEARR_DEFAULT_CHECK_INTERVAL=360
+
+# Rate limiting
+TUBEARR_RATELIMIT_YOUTUBE_MS=1000
+TUBEARR_RATELIMIT_SOUNDCLOUD_MS=3000
+
+# Concurrency
+TUBEARR_CONCURRENT_DOWNLOADS=2
+```
\ No newline at end of file