Initial haunt-fm implementation

Full music recommendation pipeline: listening history capture via webhook,
Last.fm candidate discovery, iTunes preview download, CLAP audio embeddings
(512-dim), pgvector cosine similarity recommendations, playlist generation
with known/new track interleaving, and Music Assistant playback via HA.

Includes: FastAPI app, SQLAlchemy models, Alembic migrations, Docker Compose
with pgvector/pg17, status dashboard, and all API endpoints.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,54 @@
+# haunt-fm
+
+Personal music recommendation service. Captures listening history from Music Assistant, discovers similar tracks via Last.fm, embeds audio with CLAP, and generates playlists.
+
+## Quick Start
+
+```bash
+# On NAS
+cd /volume1/homes/antialias/projects/haunt-fm
+docker compose up -d
+docker compose exec haunt-fm alembic upgrade head
+```
+
+## Architecture
+
+- **FastAPI** app with async SQLAlchemy + asyncpg
+- **PostgreSQL + pgvector** for tracks, embeddings, and vector similarity search
+- **CLAP model** (laion/larger_clap_music) for 512-dim audio embeddings
+- **Last.fm API** for track similarity discovery
+- **iTunes Search API** for 30-second audio previews
+- **Music Assistant** (via Home Assistant REST API) for playback
+
+## Key Commands
+
+```bash
+# Health check
+curl http://192.168.86.51:8321/health
+
+# Log a listen event
+curl -X POST http://192.168.86.51:8321/api/history/webhook \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Song","artist":"Artist"}'
+
+# Run discovery
+curl -X POST http://192.168.86.51:8321/api/admin/discover -H "Content-Type: application/json" -d '{}'
+
+# Get recommendations
+curl http://192.168.86.51:8321/api/recommendations?limit=20
+
+# Generate and play a playlist
+curl -X POST http://192.168.86.51:8321/api/playlists/generate \
+  -H "Content-Type: application/json" \
+  -d '{"total_tracks":20,"known_pct":30,"speaker_entity":"media_player.living_room_2","auto_play":true}'
+```
+
+## Environment Variables
+
+All prefixed with `HAUNTFM_`. See `.env.example` for full list.
+
+## Database
+
+- Alembic migrations in `alembic/versions/`
+- Run migrations: `alembic upgrade head`
+- Schema: tracks, listen_events, track_embeddings, similarity_links, taste_profiles, playlists, playlist_tracks