Add skip tracking, compressed heatmap, listening log, docs, tests, and OpenAI support

Major changes:
- Add skip tracking: poll currently-playing every 15s, detect skips (<30s listened)
- Add listening-log and sessions API endpoints
- Fix ReccoBeats client to extract spotify_id from href response
- Compress heatmap from 24 hours to 6 x 4-hour blocks
- Add OpenAI support in narrative service (use max_completion_tokens for new models)
- Add ListeningLog component with timeline and list views
- Update all frontend components to use real data (album art, play counts)
- Add docker-compose external network (dockernet) support
- Add comprehensive documentation (API, DATA_MODEL, ARCHITECTURE, FRONTEND)
- Add unit tests for ingest and API endpoints

docker-compose.template.yml

@@ -0,0 +1,64 @@
+# MusicAnalyser Docker Compose Template
+# Copy this file to docker-compose.yml and fill in your values
+# Or use environment variables / .env file
+
+version: '3.8'
+
+services:
+  backend:
+    build:
+      context: ./backend
+    image: ghcr.io/bnair123/musicanalyser:latest
+    container_name: music-analyser-backend
+    restart: unless-stopped
+    volumes:
+      - music_data:/app/data
+    environment:
+      - DATABASE_URL=sqlite:////app/data/music.db
+      # Required: Spotify API credentials
+      - SPOTIFY_CLIENT_ID=your_spotify_client_id_here
+      - SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here
+      - SPOTIFY_REFRESH_TOKEN=your_spotify_refresh_token_here
+      # Required: AI API key (choose one)
+      - OPENAI_API_KEY=your_openai_api_key_here
+      # OR
+      - GEMINI_API_KEY=your_gemini_api_key_here
+      # Optional: Genius for lyrics
+      - GENIUS_ACCESS_TOKEN=your_genius_token_here
+    ports:
+      - '8000:8000'
+    networks:
+      - dockernet
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/snapshots?limit=1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+  frontend:
+    build:
+      context: ./frontend
+    image: ghcr.io/bnair123/musicanalyser-frontend:latest
+    container_name: music-analyser-frontend
+    restart: unless-stopped
+    ports:
+      - '8991:80'
+    networks:
+      - dockernet
+    depends_on:
+      backend:
+        condition: service_healthy
+
+volumes:
+  music_data:
+    driver: local
+
+networks:
+  dockernet:
+    external: true
+    # If you don't have an external dockernet, create it with:
+    # docker network create dockernet
+    # Or change to:
+    # dockernet:
+    #   driver: bridge