documentation and env changes

docs/spotify-integration.md

@@ -0,0 +1,30 @@
+# Spotify Integration
+
+## Credentials
+- Preferred: Manage in `/admin/settings` (persisted in DB; no restart required)
+- Env fallback: `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`
+
+## API Client
+- `src/Service/SpotifyClient.php`
+  - Client Credentials token fetch with caching
+  - `searchAlbums(q, limit)` — album search endpoint
+  - `getAlbum(id)` / `getAlbums([ids])` — metadata fetch
+  - `getAlbumWithTracks(id)` — metadata + hydrated tracklist
+  - `getAlbumTracks(id)` — raw paginated tracks (when needed)
+
+### Caching & Rate Limits
+- Access tokens are cached until expiry to avoid unnecessary auth calls.
+- Downstream requests should be mindful of Spotify rate limits; user actions are debounced in the UI and server calls are focused on album/track data needed by the current page.
+
+## Advanced search syntax
+- Fielded queries are composed as:
+  - `album:"..."`, `artist:"..."`, `year:YYYY` or `year:YYYY-YYYY`
+  - Optional free text is appended to the query
+- Examples:
+  - `album:"in rainbows" artist:"radiohead"`
+  - `year:1999-2004 post rock`
+
+## Admin settings
+- Update credentials in `/admin/settings`
+- Settings are stored in the database; `APP_ENV` reload or container restart is not required
+