I lowkey forgot to commit

docs/04-spotify-integration.md

@@ -0,0 +1,19 @@
+# Spotify Integration
+
+## Credentials
+- Prefer configuring via `/admin/settings` (stored in DB).
+- Fallback to environment variables `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`.
+
+## API client
+- `src/Service/SpotifyClient.php`
+  - Client Credentials token fetch (cached)
+  - `searchAlbums(q, limit)`
+  - `getAlbum(id)` and `getAlbums([ids])`
+  - Centralized request pipeline: throttling, 429 backoff, response caching
+
+## Advanced search
+- The search page builds Spotify fielded queries:
+  - `album:"..."`, `artist:"..."`, `year:YYYY` or `year:YYYY-YYYY`
+  - Optional free-text added to the query
+
+