diff --git a/docs/config.md b/docs/config.md
new file mode 100644
index 0000000..dc4d1cd
--- /dev/null
+++ b/docs/config.md
@@ -0,0 +1,47 @@
+# Configuration reference
+
+Everything is environment variables — no config files beyond `.env` sourcing.
+
+## shipper (generator machine)
+
+| Var | Default | Meaning |
+|---|---|---|
+| `LIBRARY_DIR` | `library` | ai-radio app library dir (contains `index.json` + genre folders) |
+| `SHIP_STAGING_DIR` | `ship_out` | local dir for transcoded mp3s + playlist |
+| `SHIP_REMOTE_TARGET` | — (required) | scp target: `user@vps:/opt/airstudio/web/ai-radio/` |
+| `SHIP_SSH_KEY` | — | identity file for scp |
+| `SHIP_POLL_INTERVAL_S` | `60` | seconds between cycles |
+| `PLAYLIST_SIZE` | `40` | tracks in the rolling playlist |
+| `NEWNESS_BIAS` | `3` | lower = fresher songs dominate (weight=1/(rank+bias)) |
+| `MP3_BITRATE` | `128k` | transcode bitrate |
+| `STATION_NAME` | `AI Radio` | ID3 album + playlist prefix |
+
+## streamer (VPS)
+
+| Var | Default | Meaning |
+|---|---|---|
+| `STREAM_WEBROOT` | `/usr/local/share/icecast/web/ai-radio` | where shipped files live |
+| `ICECAST_ADDR` | `icecast:8000` | icecast host:port |
+| `ICECAST_SOURCE_PASSWORD` | `hackme` | **change this** |
+| `ICECAST_MOUNT` | `/ai-radio.mp3` | mount point |
+| `STATION_NAME` | `AI Radio` | stream name / MQTT artist |
+| `STATION_DESCRIPTION` | `Endless AI-generated radio` | icecast description |
+| `MP3_BITRATE` | `128` | kbps, used for stream pacing + icecast metadata |
+| `STREAM_PUBLIC_URL` | — | advertised URL (MQTT payload, icecast url) |
+| `MQTT_ADDR` | empty = disabled | `host:port` of the MQTT broker |
+| `MQTT_USER` / `MQTT_PASS` | — | broker auth (optional) |
+| `MQTT_CLIENT_ID` | `radio-streamer` | MQTT client id |
+| `MQTT_TOPIC` | `airstudio/nowplaying` | now-playing topic |
+
+## icecast.xml (VPS)
+
+Three secrets must be changed from `CHANGE_ME_*`:
+`source-password` (matches `ICECAST_SOURCE_PASSWORD`), `relay-password`,
+`admin-password`. Admin UI: `http://<vps>:8000/admin/`.
+
+## Tuning cheat-sheet
+
+- Want the stereo to hear new songs ASAP → `NEWNESS_BIAS=1`, small `SHIP_POLL_INTERVAL_S`.
+- Want variety over freshness → `NEWNESS_BIAS=10+`.
+- Better sound → `MP3_BITRATE=192k` (also bump streamer `MP3_BITRATE=192`).
+- MQTT-only mode (no icecast): not supported; the stream is the product.