@mthines/reaper-mcp 0.19.0 → 0.70.2

package/{knowledge → claude/knowledge}/workflows/gain-staging.md

@@ -71,37 +71,28 @@ params:
 
 Record: peak level (dBFS), RMS level (dBFS) for each track.
 
-Target levels (perceived-loudness-aware):
-- **Sub/bass instruments**: -16 to -14 dBFS RMS (sounds quieter than metered)
-- **Full-range instruments**: -18 dBFS RMS (±3 dB acceptable)
-- **Presence-range instruments**: -19 to -20 dBFS RMS (sounds louder than metered)
-- **High-frequency instruments**: -20 to -22 dBFS RMS
+Target levels (headroom, not balance):
+- **Average**: -18 dBFS RMS (±3 dB acceptable) on every track
 - **Peak**: -12 dBFS (not exceeding -6 dBFS)
 
+These raw targets only give plugins a sensible input level and keep the bus out of clipping. They say nothing about how loud a track sounds in the mix. Balance is a separate step, done afterwards on perceived loudness (`reference/perceived-loudness.md`).
+
 If a track reads:
 - Average of -30 dBFS → needs gain increase
 - Average of -8 dBFS → needs gain reduction
 - Peak of -3 dBFS → dangerously hot, reduce gain
 
-### Step 5: Calculate gain adjustments (perceived-loudness-aware)
-
-Use instrument-appropriate targets rather than a flat -18 dBFS for all tracks. The human ear is 10-15 dB more sensitive at 2-5 kHz than at 100 Hz, so bass instruments need higher meter readings to sound perceptually balanced (see `knowledge/reference/perceived-loudness.md`):
+### Step 5: Calculate gain adjustments
 
-| Instrument Category | Target RMS | Rationale |
-|-------------------|-----------|-----------|
-| Sub/bass (kick sub, bass, 808) | -16 to -14 dBFS | Low frequencies sound quieter than metered |
-| Full-range (piano, guitar, strings) | -18 dBFS | Standard target; spans the perceptual range |
-| Presence-range (vocals, snare, lead guitar) | -19 to -20 dBFS | 2-5 kHz content sounds louder than metered |
-| High-frequency (cymbals, hi-hats, shakers) | -20 to -22 dBFS | Very sensitive frequency range |
+Use the same -18 dBFS RMS target for every track. Don't use different raw targets per instrument to "pre-balance" the mix: raw RMS doesn't track perceived loudness, so the balance has to be set in LU afterwards anyway (Step 8).
 
 For each track:
 ```
 gain_adjustment_dB = target_dBFS - current_average_dBFS
 ```
 
-Example: Bass averages -24 dBFS → target -15 → needs +9 dB
-Example: Vocal averages -10 dBFS → target -19 → needs -9 dB
-Example: Piano averages -24 dBFS → target -18 → needs +6 dB
+Example: Bass averages -24 dBFS → target -18 → needs +6 dB
+Example: Vocal averages -10 dBFS → target -18 → needs -8 dB
 
 Round to nearest 0.5 dB for practical purposes.
 
@@ -131,13 +122,20 @@ params:
 
 Target: Mix bus should peak at -6 to -3 dBFS. If it's hitting 0 dBFS, pull all track faders down proportionally (or reduce master fader by the excess dB).
 
-### Step 8: Check instrument relationships
+### Step 8: Set the balance on perceived loudness
+
+Gain staging sets the floor; the balance is built on top of it, and only on perceived values:
 
-Re-play the chorus section. Listen for:
-- Does the kick still hit harder than the snare? (relative levels should still feel musical)
-- Do vocals still sit over the instruments? (if not, the relative balance was off before; adjust individual tracks)
+```
+tool: measure_tracks
+params:
+  trackIndices: [mix bus, lead vocal, guitars, drums, bass]
+  metrics: ["lufs"]
+  startPosition: [chorus start]
+  durationSeconds: 10
+```
 
-If relative balance is wrong, apply additional individual adjustments AFTER the gain staging is complete. Gain staging sets the floor; the mix is built on top of it.
+Add each track's fader to its reading (the meters are pre-fader). Then express each element as LU below the mix bus, and place it against the stem reference points in `reference/perceived-loudness.md`. Move faders by the LU difference, re-measure, and listen. If the user says something sounds too loud or too quiet, their ear is the finding.
 
 ### Step 9: Save post-staging snapshot
 
@@ -176,4 +174,4 @@ After completing gain staging:
 - **Ignoring bus tracks**: A drum bus that's receiving 8 inputs at -18 dBFS each will be summing to a much higher level. The bus fader controls the drum bus output level — check and adjust it.
 - **Single-moment readings**: Read meters over a representative 10+ second passage, not a single snapshot that may catch silence or a single loud peak.
 - **Not checking after gain staging**: Always play the mix after staging to confirm balance feels correct. The numbers are targets, not rules — use ears to verify.
-- **Setting all tracks to the same level**: A flat -18 dBFS on every track ignores psychoacoustic loudness perception. Bass instruments need higher readings; presence-range instruments need lower readings. See `knowledge/reference/perceived-loudness.md`.
+- **Treating gain staging as balance**: Equal -18 dBFS RMS on every track is correct for headroom, and it is not a balance. Never judge or set balance on RMS or peak readings; do it in LU (Step 8, `knowledge/reference/perceived-loudness.md`).

package/{knowledge → claude/knowledge}/workflows/learn-plugin.md

@@ -1,14 +1,14 @@
 ---
 name: Learn Plugin
 id: learn-plugin
-description: Discover an unknown plugin by reading its parameters, researching online, and creating a knowledge file
+description: Discover an unknown plugin by reading its parameters, researching online, and saving a plugin knowledge record
 ---
 
 # Learn Plugin
 
 ## When to Use
 
-When you encounter an installed FX plugin that has no knowledge file and you need to understand what it does, how to use it, and what parameters to set. This workflow turns an unknown plugin into a documented, reusable knowledge file.
+When you encounter an installed FX plugin that has no plugin record and you need to understand what it does, how to use it, and what parameters to set. This workflow turns an unknown plugin into a documented, reusable plugin record in LoreKit.
 
 ## Prerequisites
 
@@ -76,61 +76,28 @@ From what you've learned, decide:
 | Field | How to determine |
 |-------|-----------------|
 | `name` | Full display name as shown in REAPER |
-| `fx_match` | The exact name from REAPER's FX list, plus common variations (VST/VST3/AU) |
+| `fx` patterns (`fx::` tags) | The exact name from REAPER's FX list, plus common variations (VST/VST3/AU) |
 | `category` | Primary category from: eq, compressor, limiter, saturator, reverb, delay, gate, de-esser, amp-sim, channel-strip, stereo-imager, multiband, pitch-correction |
 | `vendor` | The plugin manufacturer |
 | `preference` | 30-50 for free/stock, 55-70 for decent third-party, 70-85 for preferred, 85-95 for industry-standard |
 | `style` | transparent, character, vintage, modern, or surgical |
 | `replaces` | Stock REAPER plugin IDs this can replace (e.g., "rea-eq", "rea-comp") |
 
-### Step 5: Write the knowledge file
+### Step 5: Write the plugin record
 
-Create the file at `knowledge/plugins/{vendor-slug}/{plugin-slug}.md` using the template structure:
+Plugin knowledge lives in LoreKit, not in this repo: write one record to scope
+`project::reaper-mcp` with key `user::plugins::{vendor-slug}/{plugin-slug}` (the
+user's layer — `plugins::…` keys are the read-only built-in layer). The record
+shape, the tag list (`plugin-knowledge`, `category::…`, `preference::…`, one
+`fx::…` per FX name, …) and the exact `memory.write` call are in
+`reference/memory-protocol.md` → "Plugin knowledge". The fields above become the
+record's header line and its tags; put the verified parameter map from Step 2
+under `## Learned notes`. No expiry.
 
-```markdown
----
-name: {Plugin Name}
-fx_match: ["{exact REAPER name}", "{alternate match}"]
-category: {category}
-style: {style}
-vendor: {Vendor Name}
-preference: {score}
-replaces: [{stock plugins if applicable}]
----
-
-# {Plugin Name}
-
-## What it does
-
-{1-2 paragraphs: purpose, character, primary use cases}
-
-## Key parameters by name
-
-| Parameter | Range | Description |
-|-----------|-------|-------------|
-| {exact name} | {range} | {description} |
-
-## Recommended settings
-
-### Use case: {instrument or purpose}
-
-| Parameter | Value | Why |
-|-----------|-------|-----|
-| {name} | {value} | {reason} |
-
-## Presets worth knowing
-
-- **{Preset Name}** — {what it does}
-
-## When to prefer this
-
-- {situations where this plugin is the best choice}
-```
-
-### Step 6: Verify the knowledge file
+### Step 6: Verify the plugin record
 
-After writing the file, confirm:
-- `fx_match` patterns actually match the installed FX name (case-insensitive substring)
+After writing the record, confirm:
+- its `fx::` tags actually match the installed FX name (case-insensitive substring)
 - All parameter names are EXACT (copy from `get_fx_parameters` output)
 - Category and preference score are appropriate
 - Recommended settings include at least one concrete use case

package/{knowledge → claude/knowledge}/workflows/master-bus.md

@@ -143,6 +143,12 @@ Watch the GR meter on the limiter:
 - Average 0.5–2 dB GR: Good — the mix is being lightly limited
 - Average 4+ dB GR: The mix is too loud before the limiter; reduce compressor stage or fix upstream
 
+If guitars and bass audibly dip on each drum hit in the full mix (but the drums sound fine soloed), the limiter is pumping:
+
+1. **Find keyed ducking first.** Any dynamic EQ/comp band with an external sidechain ducks on its key. Follow each key with `get_track_routing` (receives). Kick→bass ducking deeper than about −3 dB is audible pumping.
+2. **Clip before the limiter** instead of turning the drive down. Use a clipper (Free Clip 2, Event Horizon) with its ceiling ~1–1.5 dB under the peak level arriving there. Measured on a metal bus: pumping std 1.35 → 1.06 dB, and +0.25 LU louder. Lowering the drive 1.5 dB only got to 1.51 → 1.35 dB and cost 0.4 LU.
+3. **Measure during playback** with an `mcp_gain_trace` pre/post pair (Verification below).
+
 ### Step 6: Check mono compatibility
 
 ```
@@ -193,12 +199,18 @@ Optionally before the compressor:
 3. Export a 30-second clip and check on headphones, phone speaker, and car audio
 4. Verify LUFS integrated reading matches the target platform
 5. Check that transients are still felt (kick punch, snare snap) despite limiting
+6. Measure pumping during playback, no render needed:
+   - Add `JS: reaper-mcp/mcp_gain_trace` at the start of the bus chain (Mode pre) and again at the end (Mode post, same Slot).
+   - Play the loud section, then read the post instance: p5 / p1 are how deep the level dips go, relative to the median gain; std is how much the gain moves.
+   - Compare variants with each other on the same section. About 1.0–1.3 dB std is clean on a loud metal bus; 1.5 dB and above is audible pumping.
 
 ## Common Pitfalls
 
 - **Master bus too loud before the chain**: If peaks are above -3 dBFS before the limiter, the limiter is doing too much work. Fix the mix upstream.
 - **Heavy glue compression + heavy limiting**: Double processing. If the compressor is doing 4+ dB GR and the limiter is doing 4+ dB GR, the mix is being over-squashed. Choose one.
 - **Linear phase EQ artifacts**: Linear phase EQ adds pre-ringing at low frequencies with heavy processing. Keep EQ moves subtle on the master bus.
-- **Chasing loud**: Increasing the limiter's Input Gain to match a loud reference track can destroy the dynamics and make the mix sound flat. Trust the LUFS target.
+- **Chasing loud**: Increasing the limiter's Input Gain to match a loud reference track can destroy the dynamics and make the mix sound flat. Trust the LUFS target. Streaming turns loud masters down to about −14 LUFS, so the extra limiting only costs punch there. In a live A/B/C of a metal chorus, the user picked the −8.3 LUFS version over −7.8 and −6.9 as "most clear".
+- **Trusting a reference's loudness blindly**: Check the reference with `analyze_audio_file` first. A mono file at −18 LUFS peaking at −7 dBTP is a rip or a pre-master, not a release, so use it for tone only.
+- **Rendering to verify while the user works**: A render's progress window takes focus. Verify by measuring during playback and render only the final deliverable.
 - **Exporting without checking LUFS**: Integrated LUFS requires measuring the entire song. A 30-second check is not sufficient for integrated measurement. Play the full song with the LUFS meter running.
 - **Not saving a pre-master snapshot**: Always save a snapshot before adding master bus processing. The user may want to A/B compare.

package/claude/knowledge/workflows/section-levels.md

@@ -0,0 +1,138 @@
+---
+name: Section Levels
+id: section-levels
+description: Balance a track per song section with pooled automation items on its Volume envelope
+---
+
+# Section Levels
+
+## When to Use
+
+When a track sits right in one part of the song and wrong in another:
+
+- "The vocal is a bit loud in the first verse"
+- "The guitars disappear in the chorus"
+- "Make the vocal even between verse, chorus and bridge"
+
+## The approach (opinionated)
+
+Section level changes go on the track's **Volume envelope** as **automation items**,
+with one **pool per section type**. Every chorus is an instance of the "Chorus" pool,
+so changing one chorus changes all of them.
+
+- **Never use item gain or take volume for this.** It changes the signal going into
+  the FX chain, so compressors, saturation and amp sims (Helix Native and similar)
+  react differently. The envelope acts after the chain, at the fader.
+- **Never ride the fader with loose points** for a repeated section. They drift
+  apart the moment one copy is edited.
+- **A section that happens once** (an intro verse over a thin arrangement, a bridge)
+  gets its own pool. Don't bend a shared pool to fit one occurrence.
+- **Name the pools after the section**, prefixed with the track role: `Vox Verse`,
+  `Vox Chorus`, `Vox C`, `Gtr Chorus`.
+- **Pools are project-wide.** When a track is duplicated (for example a new lead
+  with a different amp sim), instance the same pools on the new track instead of
+  copying the points, so both stay in step.
+
+## Step-by-Step
+
+### Step 1: Save a snapshot and find the sections
+
+```
+tool: snapshot_save
+params: { name: "before-section-levels", trackIndices: [<track>], fullChunk: true }
+
+tool: list_regions
+```
+
+Snapshots store mixer state, not envelopes. `fullChunk: true` keeps the track chunk,
+envelopes included, and each tool call is also one undo point (`undo_project`).
+
+### Step 2: Measure each section against the mix
+
+Render the track and the mix bus once each with `analyze_track_offline`, using
+`sectionSeconds` (or one call per region). For each section, take the track's
+loudness minus the mix's loudness. The constant offset doesn't matter, only how
+it moves between sections. A track rendered as a stem excludes its folder's fader,
+so compare sections with each other, never the absolute numbers.
+
+Example (lead vocal, vocal minus mix in LU):
+
+| Section | vox − mix |
+|---|---|
+| Verse 1, first half | −0.9 |
+| Verse 1, second half | −3.8 |
+| Chorus | −5.0 |
+| Verse 2 | −4.3 |
+| C | −5.6 |
+
+Read this as: the first half of verse 1 sits about 3–4 LU more forward than the rest,
+and C is a touch behind the choruses. Breakdowns that are far lower are usually an
+arrangement choice; ask before you level them.
+
+### Step 3: Make sure the Volume envelope exists
+
+```
+tool: get_track_envelopes        # look for "Volume"
+tool: create_track_envelope
+params: { trackIndex: <track>, envelopeName: "Volume" }
+```
+
+### Step 4: Create one pool per section type
+
+Insert the first occurrence of each section type with its points. Points are given in
+seconds from the item start, and in `db` on volume envelopes.
+
+```
+tool: insert_automation_item
+params:
+  trackIndex: <track>
+  envelopeIndex: 0
+  position: 120
+  length: 32
+  name: "Vox Chorus"
+  points: '[{"time":0,"db":0.5}]'
+```
+
+Note the returned `poolId`. For a one-off section with a ramp back to 0 dB, end the
+ramp at the item's length and set `loop: false`:
+
+```
+points: '[{"time":0,"db":-2},{"time":32,"db":-2},{"time":33.5,"db":0}]'
+```
+
+### Step 5: Instance the pool on every repeat
+
+```
+tool: insert_automation_item
+params: { trackIndex: <track>, envelopeIndex: 0, position: 204, length: 32, poolId: <Chorus pool> }
+```
+
+`pooledWith` in the response counts the other instances of that pool in the project.
+
+### Step 6: Verify, then adjust one pool
+
+```
+tool: list_automation_items          # every section covered, the right pool on each
+tool: get_envelope_points
+params: { trackIndex: <track>, envelopeIndex: 0, automationItemIndex: <i> }
+```
+
+Re-measure the same sections. To change all choruses, edit one instance's points with
+`edit_envelope_points` and `automationItemIndex`; every instance follows. Keep moves
+small (0.5–2 dB) and let the user listen.
+
+## Gotchas
+
+- **Fader-scaled values:** REAPER's Volume envelope stores 716.2 for 0 dB, not 1.0.
+  Always pass `db`.
+- **Automation items override the underlying envelope** where they sit; between items
+  the envelope's own points apply.
+- **Looping:** a looped item repeats its pool's points over its length. A flat level
+  loops fine; a ramp should use `loop: false`.
+- **Points outside an item** are refused, and a point at the item's very end is kept
+  1 ms inside it, because REAPER drops pool points past the pool's length.
+
+## Related
+
+- `workflows/vocal-chain.md` — the processing chain the envelope sits after
+- `reference/perceived-loudness.md` — why balance is judged in LU, never dBFS

package/{knowledge → claude/knowledge}/workflows/session-prep.md

@@ -64,6 +64,10 @@ Apply clear, consistent names. Standard naming conventions:
 | Vocals | Lead Vox, BV 1, BV 2, BV Harmony, Dbl Vox |
 | Effects | FX Riser, FX Impact, FX Ambience |
 
+Don't prefix a track with its folder or role ("A INST", "STEM DRUMS", "LIVE OUT"):
+the folder hierarchy already says where it belongs, so the same name under
+different folders is fine. Keep names the user chose.
+
 ```
 tool: set_track_property
 params:

package/claude/knowledge/workflows/transient-lighting.md

@@ -0,0 +1,52 @@
+---
+name: Transient Lighting
+id: transient-lighting
+description: Find the hits in a song (drums, accents) and turn them into lighting (or any) automation that flashes in time
+---
+
+# Transient Lighting
+
+## When to Use
+
+When something should follow the hits of a song:
+
+- "Make the lights flash on the kick and snare"
+- "Create lighting automation that matches the transients"
+- "Where are the big accents in this song?"
+- Video cuts, markers or MIDI triggers synced to drum hits
+
+## Tools
+
+- `detect_transients`: hit times (project seconds), strength 0..1, dominant band
+  (low = kick/bass, mid = snare/vocals, high = hats/cymbals), per-band counts, per-section density.
+- `create_transient_automation`: the same detection, written as one pulse per hit
+  (attack, hold, decay) onto an existing envelope. `dryRun` shows the points first.
+
+## Steps
+
+1. **Find what the audience hears.** Analyze a **track** (`trackIndex`), not the file, whenever the
+   song is an item in the project: a live-set reference is often warped onto the click with stretch
+   markers and pitched, and a file is read as-is. Seen live: an mp3 with 159 stretch markers read
+   2.6% fast, and its hits drifted off the grid by seconds. If the track runs a stem separator
+   (e.g. Acon Digital Remix), the full mix is its input: bypass it for one render, then re-enable.
+2. **Pick the source per idea.**
+   - Drum flashes: the drum stem or drum bus, `bands: ["low","mid"]` (kick + snare), `minStrength`
+     0.5, `minGapMs` about one 16th (90 ms at 160 BPM), `holdMs` 20, `decayMs` 150.
+   - Big accents: the full mix, `minStrength` 0.8, `minGapMs` 250, `holdMs` 40, `decayMs` 400.
+3. **Read the sections before writing.** Use `sectionSeconds` or the project's regions. Sections
+   with few hits (a sustained wall-of-sound chorus) look dull as flashes; give those sustained
+   brightness on the main light track instead.
+4. **Use the project's tempo map as the grid.** The detector's `tempo` is a single autocorrelation
+   guess: it is wrong for odd meters (7/4 as 3+4, a 6/8 bridge) and low `confidence` means ignore it.
+5. **Write onto a new, muted track.** Copy the rig's MIDI/DMX plugin (e.g. ReaControlMIDI) from an
+   existing light track with `copy_fx` so the channel and CC mapping match, `create_track_envelope`
+   on its intensity parameter, then `create_transient_automation`. Muted, it never drives the rig
+   until the user unmutes it. Set the envelope's default point at 0 s to the base value
+   (`edit_envelope_points`), or the lights sit at the plugin's current value before the song starts.
+
+## Checks
+
+- Strong hits of a full mix and a drum stem of the same song should mostly coincide (within 10 ms);
+  if they match no better than random times, one source is warped or offset.
+- Hits of a song played to a click lock onto its tempo: phase coherence at the project tempo far above
+  a random spread. A band's feel shows as a steady per-section offset (verses 15 ms behind the click).

package/claude/skills/critique/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: critique
+description: >
+  Analyzes a live REAPER mix and produces a measured, actionable critique —
+  gain staging, frequency balance, dynamics, loudness, and stereo image — backing
+  every claim with a meter, spectrum, or LUFS reading. Read-only: makes no changes.
+  Use when the user asks to roast, review, analyze, or find problems in a mix.
+  Triggers on "roast my mix", "what's wrong with my mix", "analyze my mix",
+  "review my mix", "/critique".
+argument-hint: '[focus area, optional]'
+license: MIT
+metadata:
+  author: mthines
+  version: '1.0.0'
+  workflow_type: advisory
+  tags:
+    - mixing
+    - analysis
+    - critique
+    - metering
+    - reaper
+    - audio
+---
+
+# Critique ("Roast My Mix")
+
+Act as a brutally honest, constructive mix critic operating a **live** REAPER
+session through the `reaper` MCP tools. **Observe and report only — make no
+changes.** After the report, ask which problems to fix first and hand off to
+`/mixer` (execution) or `/mastering` (final loudness).
+
+Back every claim with a measurement — never "it's muddy", always "200–400 Hz
+sits +4 dB above the average curve".
+
+## Memory — recall first, and learn from your analysis
+
+Per `reference/memory-protocol.md` (the self-improvement loop is general to every
+mix skill — `/critique` included).
+
+**Recall (before analyzing)** — learned memory is in LoreKit, scope
+`project::reaper-mcp` (if `memory.*` isn't connected, say so and carry on):
+- the `loop::mixing-lessons` bucket (capped at 5 + one keyword search) — past
+  process lessons help you weight what to flag.
+- the plugin records for **every** plugin you comment on, looked up before you judge it
+  (match FX names via their
+  `fx::` tags; a setting the record calls intentional or warns about shapes your flag) — both the built-in record (`get_builtin_knowledge`) and the user's
+  `user::plugins::{vendor}/{plugin}` overlay, which wins: the user's tools and taste.
+
+**Capture (process lessons about your *analysis*).** Read-only means you don't
+change the *mix* — it does **not** mean you don't learn:
+- **At a correction point — immediately:** the user says a flag was wrong or
+  intentional, or points out a real problem you missed. Dedup-search, then
+  write/UPDATE a `user::mixing-lessons::<slug>` lesson (`source_agent: "critique"`;
+  never a built-in key) and
+  say you did (key + takeaway).
+- **End-of-session retrospective (always):** before the report, ask whether your
+  read of the mix was off anywhere; capture anything that surfaced.
+- A lesson at `seen_count >= 3` is promotable via `/mix-memory promote`.
+
+(You still make no *mix* changes — a captured lesson is the only thing you write.)
+
+## Analysis checklist (run all; back each with a reading)
+
+1. **Session overview** — `get_project_info`, `list_tracks`: track count, tempo,
+   sample rate, bus structure.
+2. **Gain staging** (headroom only) — `play` the loudest section, then
+   `read_track_meters` per track. Flag tracks averaging below ~-24 or above ~-10
+   dBFS, peaks at/above -3 dBFS, mix bus above -6 dBFS. These raw readings judge
+   headroom, never balance.
+3. **Balance** (perceived loudness) — one `measure_tracks` call with `lufs` over a
+   section where every element plays (`list_regions`), the mix bus included. Add
+   each track's fader (the meters are pre-fader) and express each element as LU
+   below the mix bus. Compare against the stem reference points in
+   `reference/perceived-loudness.md`.
+4. **Frequency balance** — `spectrum` from the same call (read 3+ times; each
+   is a ~0.5 s snapshot) and judge on `kDb`, never the raw `db`. Compare a band
+   only with the same band on another track or a reference: masking (kick/bass
+   60–125 Hz, bass/guitars 125–250 Hz, guitars/vocal 1–4 kHz), low-mid mud
+   (200–400 Hz), harshness (2–5 kHz), missing air (10–16 kHz).
+5. **Dynamics** — `read_track_crest` on the bus. <6 dB squashed · 8–12 healthy ·
+   >15 may need control.
+6. **Loudness** — `analyze_track_offline` on the master (-1) over the whole
+   song with `sectionSeconds: 10`: integrated LUFS, LRA, true peak and the
+   loudest/quietest sections vs genre/platform targets (see
+   `reference/metering.md`). Add `referencePath` when the user names a reference
+   song; report its loudness and tonal-balance deltas. Its resonance and
+   sibilance hints back up the frequency findings in step 4.
+7. **Stereo image** — `read_track_correlation` on the bus. <0 phase cancellation
+   (critical) · 0.0–0.3 may collapse in mono · >0.8 very narrow. Verify bass is mono.
+8. **FX chain audit** — `get_track_properties` per track: audio with 0 FX, 10+ FX
+   (over-processed), missing HPF on non-bass.
+9. **Common mistakes** — load `genres/{genre}.md` (if a genre is named) and
+   `reference/common-mistakes.md`.
+
+## Report format
+
+```
+Mix Analysis Report
+
+Session: {name} | {n} tracks | {tempo} BPM | {rate} Hz
+Overall: [2–3 honest sentences]
+
+Critical Issues (fix first):
+1. {issue}: {what the meters/spectrum showed} → {fix}
+
+Notable Issues:
+1. {issue}: {evidence} → {fix}
+
+Working Well:
+- {at least one genuine positive}
+
+Recommended Next Steps:
+1. {most impactful} 2. {next} 3. {next}
+
+Hand off to /mixer to execute, then /mastering for final loudness.
+```
+
+## Rules
+
+- Honest but constructive — explain *why* each thing is a problem.
+- Every claim cites a perceptual measurement (LU, `kDb`, Hz); raw dBFS only for headroom.
+- Always suggest a specific fix, not just the problem.
+- Find at least one genuine positive.
+- **Perceived values only, never raw** — every balance claim cites LU (post-fader,
+  against the mix bus, same section) and every tonal claim `kDb` (same band across
+  tracks or a reference). Never flag balance from peak/RMS dBFS or raw band `db`.
+- **The user's ear is the finding** — if they hear something the numbers don't
+  show, suspect the measurement (section, pre-fader reading, changed plugin) first.
+- **Run the end-of-session retrospective before reporting** (Memory) and capture
+  any analysis lesson it surfaces; if the user corrects a flag mid-session, write
+  that lesson immediately. Say what you captured (or that nothing surfaced).