Complete Stats & Narrative Engine + Testing Suite

- Stats: Added K-Means clustering, Tempo Zones, Harmonic Profile.
- Narrative: Optimized for Gemini tokens + JSON robustness.
- Testing: Added comprehensive backend/TESTING.md and standalone test script.
- Setup: Improved get_refresh_token.py for user onboarding.

backend/TESTING.md

@@ -0,0 +1,76 @@
+# Testing Guide
+
+This project includes a comprehensive test suite to verify the calculation engine (`StatsService`) and the AI narrative generation (`NarrativeService`).
+
+## 1. Quick Start (Standalone Test)
+
+You can run the full stats verification script without installing `pytest`. This script uses an in-memory SQLite database, seeds it with synthetic listening history (including skips, sessions, and specific genres), and prints the computed analysis JSON.
+
+```bash
+# Ensure you are in the root directory
+# If you are using the virtual environment:
+source backend/venv/bin/activate
+
+# Run the test
+python backend/tests/test_stats_full.py
+```
+
+### What does this verify?
+- **Volume Metrics:** Total plays, unique tracks/artists.
+- **Session Logic:** Correctly groups plays into sessions based on 20-minute gaps.
+- **Skip Detection:** Identifies "boredom skips" based on timestamp deltas.
+- **Vibe Analysis:** Verifies K-Means clustering, tempo zones, and harmonic profiles.
+- **Context Analysis:** Checks if plays are correctly attributed to Playlists/Albums.
+
+## 2. Generating a Spotify Refresh Token
+
+To run the actual application, you need a Spotify Refresh Token. We provide a script to automate the OAuth flow.
+
+1.  **Prerequisites:**
+    *   Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/).
+    *   Create an App.
+    *   In settings, add `http://localhost:8888/callback` to "Redirect URIs".
+    *   Get your **Client ID** and **Client Secret**.
+
+2.  **Run the Script:**
+    ```bash
+    python backend/scripts/get_refresh_token.py
+    ```
+
+3.  **Follow Instructions:**
+    *   Enter your Client ID/Secret when prompted.
+    *   The script will open your browser.
+    *   Log in to Spotify and authorize the app.
+    *   The script will print your `SPOTIFY_REFRESH_TOKEN` in the terminal.
+
+4.  **Save to .env:**
+    Copy the output into your `.env` file.
+
+## 3. Full Test Suite (Pytest)
+
+If you wish to run the full suite using `pytest` (recommended for CI/CD), install the dev dependencies:
+
+```bash
+pip install pytest
+```
+
+Then run:
+
+```bash
+pytest backend/tests
+```
+
+## 4. Manual Verification
+
+To verify the system end-to-end with real data:
+
+1.  Start the backend:
+    ```bash
+    python backend/run_worker.py
+    ```
+2.  Wait for a few minutes for data to ingest (check logs).
+3.  Run the analysis manually:
+    ```bash
+    python backend/run_analysis.py
+    ```
+4.  Check the database or logs for the generated `AnalysisSnapshot`.