From fc3533992ac650558f8579eadf3501d5d2a08bb5 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Sat, 5 Sep 2026 07:51:15 -0400
Subject: [PATCH] =?UTF-8?q?pop=20study/map.py:=20bar-by-bar=20song=20map?=
 =?UTF-8?q?=20=E2=80=94=20chord=20lane,=20phrase=20keys,=20band=20heat?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Third tool in the single-study-toolkit. Consumes a report.json,
beat-tracks, picks the downbeat phase where chord changes land
hardest, fits maj/min triads to per-bar harmonic chroma with a small
diatonic prior seeded by each phrase's key (keeps buried thirds from
flipping major bars minor), and writes MAP.md (chords + degrees vs.
the global key), map.json, and a three-panel fig-map. Registered as
analysis.study-map.

Claude-Session: https://claude.ai/code/session_01LaRrW1RHanS8it7SzgrqeV
---
 pop/MENU-WISHLIST.md |  5 +++++
 pop/lib/menu.mjs     |  4 ++++
 pop/study/README.md  | 12 ++++++++++++
 3 files changed, 21 insertions(+)

diff --git a/pop/MENU-WISHLIST.md b/pop/MENU-WISHLIST.md
index b906cc68fb..c83c9a22e5 100644
--- a/pop/MENU-WISHLIST.md
+++ b/pop/MENU-WISHLIST.md
@@ -48,6 +48,11 @@ All from Abe's 2026-05-21 list.
   study reports: section timelines, band-balance heatmap, loudness
   small multiples, `COMPARISON.md` stat table.
   → `study/compare.py`
+- 🟢 **study map** (`analysis.study-map`) — bar-by-bar song map from a
+  study report: downbeat-aligned chord lane (triad templates + diatonic
+  prior per phrase key), per-phrase keys, band heatmap, `MAP.md` with
+  degrees vs. the global key.
+  → `study/map.py`
 
 ### score — notation & sequencing
 - 🟢 **audio → rhythm sequence** (`score.audio-to-rhythm`) — onset-detect
diff --git a/pop/lib/menu.mjs b/pop/lib/menu.mjs
index cb2c90429f..a413dae389 100644
--- a/pop/lib/menu.mjs
+++ b/pop/lib/menu.mjs
@@ -152,6 +152,10 @@ export const MENU = {
       params: ["out"],
       blurb: "several study reports side by side — timelines, band balance, loudness",
     },
+    "study-map": {
+      file: "study/map.py",
+      blurb: "bar-by-bar song map from a study report — chord lane, phrase keys, band heat",
+    },
   },
 
   vocal: {
diff --git a/pop/study/README.md b/pop/study/README.md
index dfa1e26c26..34d1737bdd 100644
--- a/pop/study/README.md
+++ b/pop/study/README.md
@@ -36,6 +36,18 @@ Compare several studied tracks:
 That writes `COMPARISON.md` plus section-timeline, band-balance, and
 loudness-small-multiple figures.
 
+Map a studied track bar by bar (chords, phrase keys, energy):
+
+```fish
+.venv/bin/python study/map.py study/out/track-slug/report.json
+```
+
+That writes `MAP.md`, `map.json`, and `fig-map.png` next to the report —
+a per-bar chord lane (triad templates over harmonic chroma, downbeat
+phase picked where chord changes land hardest, with a small diatonic
+prior from each phrase's key), per-phrase keys, and the six-band heatmap
+on one time axis.
+
 ## honesty notes
 
 - Loudness range and true peak are **approximations** (RMS-window LRA,
-- 
2.51.2