# AGENT QUICKSTART — `spotify-library-taxonomy-fixer` (`Library Atlas`)

## 1. Paste-Ready Agent Launch Prompt

```text
OPEN: venkatron/spotify-library-taxonomy-fixer (branch: main)
READ: AGENT-QUICKSTART.md -> taxonomy.yaml -> verified_playlists.json
DO:
  1. Run `python3 verify_fixture.py` (offline 41-track smoke test; must exit 0).
  2. Pick the matching 4-line playbook below (A: New Likes Delta, B: Spotify Write-Back, C: Chirp/DJ Export, D: Web Publish).
PROTECT:
  - Never run `08_unlike.py --apply` (bulk unliking is deferred).
  - Never overwrite `classification.override` or `facets_locked = 1`.
  - Keep `"playlist_prefix": "LA_"` in temporary `config.json`; delete `config.json` & `.tokens.json` before `git commit` or deploy.
VALIDATE: `python3 verify_fixture.py` && `test ! -f config.json && test ! -f .tokens.json`
STOP AFTER: Completing the requested playbook and syncing `public/`.
```

---

## 2. Snapshot in 6 Numbers (`2026-10-22`)

- **`17,686` tracks** in `library.db` (`14,504` Liked Songs + `3,182` playlist tracks; `99.6%` classified across `13` L1 genres → `69` subgenres; `454` co-artist homonyms rescued).
- **5 Orthogonal Axes**: `subgenre` (1:1 playlist home) + multi-label `moods` (`6`), `scenes` (`8`), `styles` (`7`), and `sample_roles` (`5` SHRIKE stem roles).
- **100% BPM & Camelot Sidecar**: `bpm`, `half_time_bpm` (`85↔170`), and `key_camelot` (`1A–12B`, led by `5A` and `8A`) on all `17,686` tracks.
- **86 Verified Live Spotify Playlists (`HTTP 200 OK`)**:
  - **`7` `LA_Algo_*` Sets (`168` tracks)**: 100% synced (`05_write_back.py --only-algo --apply`).
  - **`79` `LA_*` Subgenre Playlists (`16,227` live tracks vs. `16,513` reclassified plan)**: `+286` net delta ready when `--apply` is requested.
- **8 Cross-Facet Smart Crates (`_playlists`)**: Live in `viewer_data.json` & `chirp_crates.json` (dry-run on Spotify unless `--smart-playlists --apply` is requested).
- **Live Web URLs**: [library-atlas.pplx.app](https://library-atlas.pplx.app) · [library-atlas.pplx.app/one-pager.html](https://library-atlas.pplx.app/one-pager.html) · [spotify-library-taxonomy-fixer.pages.dev](https://spotify-library-taxonomy-fixer.pages.dev)

---

## 3. Four Copy-Paste Playbooks

### A. Pull & Classify Newly Liked Spotify Songs
```bash
python3 01_extract.py && python3 02_enrich.py --refresh-weights
python3 03_classify.py && python3 03_classify.py --populate-facets
python3 10_audio_features.py && python3 04_review.py
python3 09_music_brain.py && python3 11_algo_playlists.py
```

### B. Sync Playlists to Spotify (Dry-Run First, `--apply` Only After Approval)
```bash
python3 05_write_back.py --only-algo          # preview 7 LA_Algo_* sets (pass --apply to write)
python3 05_write_back.py                      # preview 79+ LA_* subgenre playlists (+286 delta)
python3 05_write_back.py --smart-playlists    # preview 8 LA_Crate_* smart crates
```

### C. Handoff to `venkatron/Chirp`, Serato DJ Pro, or Algoriddim `djay`
- **`Chirp` / `SHRIKE` / `ROOKERY`**: Read `chirp_crates.json` (`chirp.crate.manifest.v1`) for the 8 Smart Crates or `algo_playlists.json` / `.chirp-set.json` (`chirp.av_core.set.v1`) for deck A/B routing, half-time pivots, and `MOLT` presets.
- **Serato / `djay`**: Stream the 86 `LA_*` / `LA_Algo_*` playlists directly via Spotify integration, or export `.m3u8` (Serato) / `.rekordbox.xml` (`djay Pro`) from `#algoPanel` in `viewer.html`.

### D. Refresh `public/` & Deploy
```bash
cp -f viewer.html public/index.html && cp -f viewer.html public/viewer.html
cp -f one-pager.html AGENT-QUICKSTART.md AGENT-BRIEF.md ONE_PAGER.md MUSIC_BRAIN.md verified_playlists.json public/
rm -f config.json .tokens.json && python3 verify_fixture.py
```

---

## 4. Key Files Index

| File | Purpose |
|---|---|
| `AGENT-QUICKSTART.md` / `AGENT-BRIEF.md` | Fast startup checklist (`AGENT-QUICKSTART.md`) & full architecture/changelog (`AGENT-BRIEF.md`). |
| `one-pager.html` / `ONE_PAGER.md` | Visual & Markdown one-pager with all 86 verified Spotify playlist links. |
| `verified_playlists.json` | Offline audit of all 86 live Spotify playlists (`spotify_id`, `url`, `sp_total`, `plan_total`). |
| `music_brain.json` / `MUSIC_BRAIN.md` | Taste graph (`v1.2`), Suno `STYLE:`/`EXCLUDE:` recipes, and 5-axis summary. |
| `chirp_crates.json` / `algo_playlists.json` | Machine-readable manifests for `Chirp` (`CHIRP`/`SHRIKE`) and Algorithmic DJ Sets. |