diff --git a/docs/agent-api.md b/docs/agent-api.md
index 7dc9103..7723590 100644
--- a/docs/agent-api.md
+++ b/docs/agent-api.md
@@ -50,7 +50,7 @@ Same effect — the agent picks up the topic and speaks the reply. (Use whicheve
 | "put on your Donald Trump voice and tell me a joke" | `speak_as` | piper (per-character) |
 | "send {topic}/{payload}" (advanced) | `ha_service_cmd` | HA any service |
 | any open question | `answer` | OmniRoute LLM |
-| "play {artist/album}" | `play_music` | Mopidy *(planned)* |
+| "play {artist/album}" | `play_music` | Mopidy → Spotify (gst-plugin-spotify + credentials.json) ✅ |
 
 The LLM picks the tool automatically from natural language — you don't pick it.
 
diff --git a/docs/overview.md b/docs/overview.md
index af35445..a884b6b 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -36,7 +36,8 @@ A fully-local, private voice assistant. You say **"Hey Jervis"**, then a natural
 │    • feed_fish            → HA input_button.fish_feeder              │
 │    • set_reminder         → HA persistent_notification               │
 │    • speak_as(voice,text) → piper per-character voice                │
-│    • play_music           → Mopidy (planned)                         │
+│    • play_music           → Mopidy (Spotify, WORKING)               │
+│    • pause/stop/next      → Mopidy MPD (planned)                    │
 └───────────────────────────────────────────────────────────────────────┘
                           │  reply text
                           ▼
@@ -60,7 +61,7 @@ A fully-local, private voice assistant. You say **"Hey Jervis"**, then a natural
 | OmniRoute | `.13` | `:20129` (API) | — | LLM gateway (OpenAI-compatible) |
 | piper_tts | `.13` | `:10200` | `sam/speech_piper` | TTS (Wyoming) |
 | Snapcast | `.13` | `:1780` | — | Multi-room audio |
-| Mopidy / librespot | `.13` | `:6600`/`:6680` | — | Music sources |
+| Mopidy / librespot | `.13` | `:6600`/`:6680` | — | Music: Spotify via gst-plugin-spotify + device-auth credentials |
 | Home Assistant | `.30` | `:8123` (REST) | — | Home control |
 | KitchenOwl | `.35` | `owl.lab.audasmedia.com.au` | — | Shopping list |
 | mosquitto | `.13` + `.30` | `:1883` | — | MQTT brokers |
@@ -78,6 +79,18 @@ A fully-local, private voice assistant. You say **"Hey Jervis"**, then a natural
 
 ---
 
+## Music playback (Mopidy + Spotify) — working 2026-08-30
+
+`play_music` → Mopidy (MPD :6600) → Spotify → Snapcast → speakers.
+
+**Two pieces were required (both were the blocker):**
+1. **`gst-plugin-spotify`** — the `spotifyaudiosrc` GStreamer element that decodes `spotify:track` URIs. Added `pkgs.gst_all_1.gst-plugins-rs` to `systemd.services.mopidy.environment.GST_PLUGIN_PATH` in `.13` `configuration.nix` (also isolated Mopidy's GST path to its own 1.28.4 plugins + a void `GST_PLUGIN_SYSTEM_PATH` to avoid the system pipewire plugin poisoning the registry).
+2. **`credentials.json`** — generated via librespot **device-authorization flow** (`get_creds_device`, built from librespot dev branch — has `DeviceAuthClient`). The old PKCE redirect flow (`get_creds`) is **broken** in librespot (deterministic `code_verifier was incorrect`). Device flow prints `spotify.com/pair` + code; user approves on any device. File at `/var/lib/mopidy/spotify/credentials-cache/credentials.json` (mopidy-owned).
+
+Also fixed along the way: mopidy-local disabled (empty `library.db` crashed search: `no such table: tracks`); Mopidy-Spotify creds re-authed via mopidy.com (old grant revoked).
+
+**librespot (NixOS speaker's Spotify Connect output) is separate and untouched.**
+
 ## Run / manage
 
 - Agent service (persistent, auto-starts): `systemctl status voice-agent` (NixOS systemd unit declared in `/etc/nixos/configuration.nix`). Restart: `sudo systemctl restart voice-agent`.