@mthines/reaper-mcp 0.19.0 → 0.70.2

package/claude/skills/editing/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: editing
+description: >
+  Edits a live REAPER session through the reaper MCP tools: MIDI parts (writing,
+  rewriting, quantizing, importing), arrangement (split, move, copy, insert or
+  remove time), timing and phase, crossfades and comping, voice recordings into
+  arrangements, audio stem separation, and A/B-testing variations in fixed lanes.
+  Changes notes and items, not levels or FX; use /mixer for those. Use when asked
+  to edit, rewrite, tighten, comp, change the groove, compare parts, turn humming
+  or beatboxing into music, or split a recording into stems. Triggers on "edit
+  the drums", "change the chorus", "make a variation", "A/B these takes",
+  "comp this", "tighten the timing", "compose from this recording", "turn my
+  humming into a song", "split stems", "/editing".
+argument-hint: '[what to edit, voice recording, stems, or versions to compare]'
+license: MIT
+metadata:
+  author: mthines
+  version: '1.0.0'
+  workflow_type: applied
+  tags:
+    - editing
+    - midi
+    - arrangement
+    - comping
+    - reaper
+---
+
+# Editing
+
+Edit the notes, items and structure of a **live** REAPER session through the
+`reaper` MCP tools. This skill changes what plays and when. Levels, EQ,
+compression and the master belong to `/mixer` and `/mastering`; what a sampled
+instrument expects (note map, keyswitches) comes from `/learn-plugin`'s LoreKit
+record. After an edit, hand the balance question to `/mixer`.
+
+The step-by-step procedures (crossfades, phase, stretch markers, head and tail
+cleanup, arrangement edits) are in `knowledge/workflows/editing.md`; load it for
+audio cleanup. Voice sketches and stem separation use the workflows below, not
+the recorded-track cleanup procedure.
+
+## Rules that save sessions
+
+1. **Re-list before every index-based write.** The user edits the session while
+   you work: a deleted or added track moves every index after it (this once put
+   an EQ on the wrong tracks). `list_tracks` (filtered by `parent`) or
+   `get_track_lanes` right before each batch, and target by name where it is
+   unique. Item indexes also change after every move, import or delete.
+2. **Snapshots do not store items.** `snapshot_save` keeps faders and FX
+   parameters, so it cannot undo a MIDI or arrangement edit. Before changing
+   items, keep the original as a **take** of the item it replaces (see "Keeping
+   the original" below), or as the A lane of a lane pair. **Never mute an
+   original and leave it under or beside the new item**: overlapping muted items
+   clutter the timeline and are easy to leave muted. Delete the original only
+   when the user says the new version won.
+3. **Keep the user's selection in mind.** `set_selected_items` and item actions
+   replace it; say so when it ends up changed.
+4. **Validate, then write.** Check pitch range, track and item before the first
+   write. A MIDI write that fails halfway is undone by the server; a bad import
+   can still leave an item you did not want, so list items after.
+5. **Check the instrument before writing MIDI.** A sampled instrument has note
+   ranges and keyswitch zones (Odin x Ari Lite: notes below 36 are keyswitches,
+   so music written there is silent or switches articulation). Read the plugin's
+   record (`get_builtin_knowledge`, `memory.read` of `user::plugins::…`) before
+   writing a part, and probe one note if it is unverified.
+6. **Plugin gate — no plugin is touched before its memory is read.** Before the
+   first call that adds, sets, loads a preset for, writes MIDI to, or reads parameters
+   of a plugin (`add_fx`, `setup_fx_chain`, `set_fx_parameter`,
+   `set_multiple_fx_parameters`, `set_fx_preset`, `load_fx_chain`, MIDI for an
+   instrument track, take FX), look it up — every plugin, every time it is new to this
+   session, including ones the user named, ones already in the project and ones you
+   only meet while listing a chain. Never skip it because the plugin looks familiar.
+   Look up both layers: `list_builtin_knowledge { query: "<plugin name>" }` (or `tags:
+   ["fx::<FX name>"]`) / `get_builtin_knowledge { key: "plugins::{vendor}/{plugin}" }`,
+   and `memory.search` / `memory.read` of `user::plugins::{vendor}/{plugin}` (the user's
+   record wins). Then **follow the record**: its MIDI map and note ranges, parameter
+   scaling, recommended settings and gotchas decide what you do, and a setting you were
+   about to use that the record warns against is not used. Say it in one chat line
+   ("Recalled Odin x Ari Lite: notes <36 are keyswitches → transposing"). Keep a running
+   list of recalled plugins and don't re-read those. No record in either layer: say so
+   and carry on (or bootstrap it when the user asked for the plugin by name). LoreKit
+   not connected: say so once and use the built-in read only.
+
+## Writing and rewriting MIDI
+
+- **Fast path for a whole part:** generate one `.mid` per instrument with a node
+  script (480 PPQ, a tempo and 4/4 meta event, an end-of-track at the last bar
+  line), then `import_midi_file { path, trackIndex, position }`. Thousands of
+  `insert_midi_note` calls are far slower. The file's tempo is **not** applied:
+  set the project tempo first.
+- **Drum maps are not General MIDI.** Check the kit's record (GGD Invasion: kick
+  R24/L23, snare 26, toms 33-38, hats 43/45, crash L52, china 65). Alternate kick
+  feet when two hits are a 16th apart.
+- **Small changes:** `edit_midi_notes` / `insert_midi_notes` (batch),
+  `transform_midi` (transpose, velocity, humanize, length) and `quantize_midi`
+  (grid, strength, swing). Positions are in beats, velocity 1-127.
+- **Replacing a section:** import the new section at its start time on the same
+  track, then fold old and new into one item of takes (below) until approved.
+  Imported items never overwrite existing ones.
+- **Keeping the original (takes, never mute).** For one section replaced:
+  1. `set_selected_items` on exactly the old and new item of **one** section,
+     then `run_action 40543` ("Take: Implode items on same track into takes").
+     Do one section per call: selecting several sections at once merges them
+     all into a single item (seen live; `undo_project` reverts it). Work from
+     the highest item index down, since indexes shift after each implode.
+  2. The takes keep the lower-indexed item first. `list_takes` the item, then
+     `set_active_take` the version that should play (`takeIndex` 1 when the
+     new item came after the old one).
+  3. The imploded item can inherit the mute: `get_media_item_properties`, and if
+     `muted`, `set_media_item_properties { mute: 0 }` (the parameter is `mute`,
+     a number 0/1, not a boolean).
+  4. Switch versions later with `set_active_take`; when the user decides, delete
+     the losing take (or keep it). Take names are blank for imported items; say
+     which take is which in chat.
+  Use fixed lanes below instead when whole-song versions are compared.
+- **Big MIDI calls can hit the 10 s bridge timeout** (seen on a 400-note
+  `transform_midi` while the user was in the session). Prefer re-importing a
+  generated file over editing hundreds of notes in place.
+
+## Voice recordings to a playable arrangement
+
+For "make music from this humming/beatboxing", use `transcribe_voice_sketch`.
+Do not substitute a hand-written melody or a generic MIDI script for analyzing
+the recording. File analysis/export does not require REAPER; importing and
+playing the result requires a live bridge.
+
+1. **Locate and protect the source.** Use an absolute path on the machine running
+   the MCP server. Download an attachment there first; a cloud attachment or an
+   orb path is not automatically accessible to a local server. Keep the original
+   file unchanged. Select the musical range with `startTime`/`endTime` to exclude
+   speech, count-ins and long silence, at most 120 seconds per call.
+2. **Analyze before importing.** Start with `limit: 0` and no `outputPath` for
+   summaries, warnings, tempo and key. Use `mode: auto` for mixed humming and
+   beatboxing, `melody` for humming alone, `drums` for beatboxing alone. The core
+   sidecar is sufficient; no pitch model or Demucs install is needed. If the
+   tool is missing, check the server build/connection rather than inventing an
+   alternative implementation. Missing core setup:
+   `reaper-mcp setup-sidecar --without-aesthetics`.
+3. **Resolve musical uncertainty.** Ordinary timing drift becomes one rounded
+   tempo. Automatic changes need two adjacent four-second windows and at least
+   20% difference by default; exact half/double-time changes remain ambiguous.
+   If the pulse is uncertain, use the user's BPM or offer short auditions of
+   plausible pulses, then rerun with `bpm` to fix the chosen tempo. Never reuse
+   a previous recording's BPM as a default. Meter is assumed 4/4 and the first
+   onset is beat zero, not a detected downbeat. Report weak key confidence or a
+   fallback key; do not force the melody into it. `key` overrides accompaniment
+   only. For missed low/short syllables, try a lower `pitchMin` or `minNoteMs`
+   down to 40, explaining the increased false-note risk. If recognition remains
+   poor, ask for a cleaner take or separate humming and beatboxing takes.
+4. **Export the requested draft.** Use `arrange: true` for generated drums, bass,
+   chords and repeated detected melody, default 16 bars. Use `arrange: false`
+   for detected melody/percussion only. `mode` limits extraction, not the
+   generated backing parts. Backbeats, fills, chords and song
+   sections are proposals, not recovered performances. Choose a new absolute
+   `.mid` `outputPath` under an existing folder. Export includes every note
+   regardless of response pagination. With separate takes, extract each in its
+   own mode with a shared BPM/grid and combine once; do not stack two complete
+   generated backing bands. Align takes using a known cue or ask for their
+   offset; each take's first onset becomes its own beat zero.
+5. **Set tempo before MIDI import.** Inspect `get_tempo_map` and existing items.
+   In an empty project starting at zero, apply `arrangement.tempos` for the full
+   generated score, or `tempo.segments` for transcription-only output. Use
+   `set_project_tempo` for the first BPM and `add_tempo_marker` with
+   `timeSigNumerator: 4`, `timeSigDenominator: 4`, `linear: false` at zero to
+   establish 4/4; use `linear: false` for later changes too. Convert segment
+   beats to project seconds by integrating the preceding BPM segments, not by
+   using the initial BPM throughout. Source `time`/`originSeconds` are original file times, not marker
+   positions for the exported score. Preserve an existing project's tempo map
+   by default; resolve a mismatch with the user before changing it. Then
+   `import_midi_file { path, newTracks: true, trackIndex, position }` creates one
+   named track per part. Re-list immediately before choosing `trackIndex`.
+   The importer applies neither the file tempo map nor GM program changes.
+6. **Make it audible.** Hand instrument/FX setup to `/mixer`: choose installed
+   drum, bass, chord and lead instruments and check their knowledge records.
+   The exported drum part is GM on MIDI channel 10; verify the kit's channel
+   handling and map, then remap notes when necessary. Do not transpose all drum
+   notes as a melodic part. Check melody/bass ranges and keyswitches too. A
+   successful MIDI import is not proof of audible playback.
+7. **Verify a short section first.** Read back the imported notes, tempo map and
+   track placement, then play a representative groove and melody for the user.
+   Check audible output through `/mixer` and ask whether the pulse, melody and
+   drum roles match the idea. Fix octaves, false notes and drum mapping before
+   polishing or extending. Keep variants in fixed lanes and compare them at a
+   shared project tempo; use separate projects or rendered WAVs for different
+   tempo maps. Report what was detected, what was generated and what is unsure.
+
+## Stem splitting: choose the right operation
+
+- **Mixed voice sketch:** start with `transcribe_voice_sketch` directly. Pitch
+  and percussion are analyzed independently, including overlapping events.
+  Do not run Demucs first by default. Its accuracy on humming plus beatboxing
+  is unverified; if explicitly tried, keep a direct-transcription baseline and
+  audition both before discarding anything.
+- **Recorded band or song:** use `separate_stems` for audio source separation.
+  `htdemucs` gives drums, bass, other and vocals; `htdemucs_6s` also gives guitar
+  and piano. Neither splits kick/snare/hat. Requires the opt-in
+  `reaper-mcp setup-sidecar --with-separation`; the six-source model downloads
+  weights on first use. Explain missing dependencies/downloads before setup.
+  Choose an explicit range, at most 600 seconds, and a fresh `outDir`. A track
+  input is rendered post-FX; use its original file only when that is the wanted
+  source. Leave the source untouched and listen for bleed and artifacts before
+  relying on a separated stem.
+- **Generated instrument WAVs:** `transcribe_voice_sketch` with `outputPath`
+  plus `soundfontPath` renders a mix and instrument stems. These are
+  resynthesized instruments, not isolated original voice audio. This optional
+  route needs local FluidSynth and the user's GM `.sf2`, with at most 240
+  seconds including release tail. Prefer MIDI plus installed instruments when
+  those dependencies are absent. A `preview.error` can accompany a successful
+  MIDI export; keep that file and do not retry the same existing output path.
+- **Individual generated drum parts:** the tool exports one drum MIDI part and
+  one `drums.wav`, not separate kit-piece WAVs. If requested, split the generated
+  GM drum notes by pitch into kick, snare, hat and other MIDI parts before
+  instrument-specific remapping. Keep a shared origin and tempo, preserve
+  velocities, and mute the unsplit copy when playing the split parts. Separate
+  audio outputs need a verified kit-output setup or separate renders; delegate
+  that routing/render setup to `/mixer`. Never label these as isolated beatbox
+  audio.
+
+For Demucs insertion, `insertTracks: true` creates a **muted folder**. A track's
+stems start at `startTime`; a file's start at `filePosition + startTime`, where
+`filePosition` is the project position of the source file's second zero. Inspect
+returned `inserted`/`warning` and re-list tracks before retrying; files can exist
+even if insertion failed. For generated WAVs, use `insert_audio_file` to place
+every instrument stem at the same chosen project position. Play either the
+source/mix or the stem set, not both. Check parent mute and solo states when a
+stem seems silent; preserve the source and make A/B switching explicit.
+
+## A/B-testing MIDI or arrangement variants (fixed lanes)
+
+Use this to compare alternatives that change notes or arrangement: a drum
+groove, a bass line, a different chorus. A snapshot cannot switch them (rule 2),
+and a muted duplicate is easy to leave muted (so never use one; one section
+replaced is a take, see "Keeping the original").
+
+**One lane per complete version.** Each lane holds the whole song, so one switch
+plays a whole version and nothing is left silent. A lane with only a changed
+section forces the unchanged sections into another lane, and playing one lane
+alone then silences them.
+
+1. `set_track_lanes { track, fixedLanes: true }`: every item goes on lane 0
+   (version A). `laneCount` needs `fixedLanes: true`.
+2. With only lane 0 playing, run action 42505 ("Track lanes: Duplicate items from
+   playing lanes to new lanes"): lane 1 starts as a full copy.
+3. Make the change in lane 1. To bring a newly imported item in, `set_selected_items`
+   then 40068 (up one lane), 40107 (down one lane) or 42588 (bottom lane), and
+   delete the copy it replaces. Run `get_track_lanes` after each move.
+4. Name the lanes: `names: [{ lane: 0, name: "A original" }, { lane: 1, name: "B half-time chorus" }]`
+   (objects, not strings).
+5. **Switch:** `set_track_lanes { track, play: 1 }` plays lane 1 alone, `play: 0`
+   lane 0. A number is exclusive, an array (`play: [0, 2]`) is layered.
+6. **Decide:** `comp_lanes` takes sections from either lane onto a new comp lane
+   (a committed copy, not a switch). Delete the losers afterwards (action 42691
+   removes lanes that are not playing, with their items).
+
+Gotchas:
+- Unchanged sections exist in every lane, so an edit in one lane does not reach
+  the others. Finish shared edits first, or make them in each lane.
+- `get_track_lanes` / `set_track_lanes` take `track`, not `trackIndex`.
+- Turning lanes off puts every item on one lane, all playing (`undo_project`
+  restores).
+- A full A/B is a lane choice plus a mix snapshot: lanes for notes and
+  arrangement, snapshots (`/mixer`) for faders, EQ and the master.
+- For a few-note tweak, edit in place; lanes are for whole alternatives.
+
+## Workflow
+
+1. **Understand** the edit and the song structure (`list_regions`, `list_markers`,
+   `get_tempo_map`). Load `workflows/editing.md` for audio editing.
+2. **Protect:** `snapshot_save { name: "before-{task}" }` for the mix, and keep
+   the original items (rule 2).
+3. **Re-list**, then edit (rule 1), explaining the musical reason for each change.
+4. **Verify:** list the items and lanes again, play the changed range for the user
+   (`set_cursor_position` + `play`), and check the result with the meters through
+   `/mixer` when level or tone may have moved. Ask the user to listen: their ear
+   decides.
+5. **Report** what changed, where the originals are, and how to switch back.
+
+## Interpreting vague requests
+
+"Slows down", "bigger", "less busy" can mean several things. State the reading you
+chose (for "the groove slows down": half-time at the same tempo, not a tempo
+change, since the other parts would have to follow) and offer the other.

package/claude/skills/learn-plugin/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: learn-plugin
+description: Teach the mixing skills one plugin or a list of them (researched in parallel): researches each on the web, tests it live in REAPER and writes its plugin knowledge record to LoreKit, asking the user only what it couldn't work out
+---
+
+# /learn-plugin
+
+This skill teaches the mixing skills a plugin. It writes the plugin's **plugin
+knowledge record** to the user's own LoreKit layer: scope `project::reaper-mcp`,
+key `user::plugins::{vendor}/{plugin}`, following
+`knowledge/reference/memory-protocol.md`.
+
+It does the work itself before asking anything. The **`plugin-researcher`**
+agent researches the plugin on the web, loads it on a scratch track, probes its
+parameters, and writes the record. Then this skill asks the user **only** the
+questions the agent couldn't answer, and folds the answers in.
+
+If an opt-in extension drives the plugin (a `list_tool_categories` category named
+after it, e.g. `vital`), the agent reads its internals through it and tags the record
+`extension::<name>`, so `/mixer` and `/mastering` know to use it. A plugin that hides
+its sound in internal state and has no extension gets a one-line offer to build one
+(`reaper-mcp extension new <name>`, see `docs/EXTENSIONS.md`).
+
+The mixing skills use the same agent to bootstrap plugins they don't know. To
+recall or tidy memory, use `/mix-memory`. If the `memory.*` tools are not
+connected, do not stop at an error: read `~/.claude/knowledge/reference/lorekit-setup.md` (in a clone: `knowledge/reference/lorekit-setup.md`) and walk
+the user through connecting LoreKit (free, a few minutes), then carry on once it is.
+If they decline, say there is nowhere to save the record and stop.
+
+Every learned plugin should end up in the **built-in plugin list**
+(`docs/PLUGINS.md`). A **publisher** (writing member of the `reaper-mcp` LoreKit
+org, e.g. the maintainer) publishes the record and updates the list in their
+clone (Step 5). Everyone else gets it there through a contribution PR, and the
+list updates when the maintainer publishes it.
+
+## Trigger
+
+The user types `/learn-plugin [plugin]`, or asks Claude to "learn about a
+plugin", "research this plugin" or "add plugin knowledge".
+
+## Instructions
+
+### Step 1: Get the plugin name(s)
+
+Take them from the arguments: one plugin, or a list (one per line, or comma
+separated). If there are none, ask a single question:
+
+> "Which plugin should I learn?"
+
+If the user already said something about one (what they use it for, how they
+set it up), keep it as caller context for that plugin in Step 2. Don't ask for
+anything else yet.
+
+Also check, once, whether the user is a **publisher**: `org.list`, and look for
+the `reaper-mcp` org with a writing role (member, admin or owner). Remember the
+answer for Steps 3 and 5. No `org.list` tool, or no such membership: not a
+publisher.
+
+### Step 2: Dispatch the researchers, all at once
+
+One `plugin-researcher` per plugin, **all in the same message** so they run in
+parallel. Even when the user says "one at a time", run them in parallel: the
+agents are built for it, and only the questions are asked plugin by plugin.
+Give each one a short, unique uppercase tag for its scratch track:
+
+```text
+Agent(subagent_type: "plugin-researcher",
+      prompt: "Plugin: <exact name>\nScratch track tag: <TAG, e.g. PROQ4>\nCaller context: <anything the user said, or 'none'>")
+```
+
+Tell the user what is happening, in one line: each researcher looks the plugin
+up on the web and briefly adds a scratch track `[MCP] plugin-research <TAG>` to
+their project, which it removes afterwards. Several at once can make REAPER lag
+for a moment while heavy plugins load. Then wait for the reports. As each one
+arrives, give a one-line status (key, proposed preference, what was verified
+live, number of open questions). Don't ask yet.
+
+**No `plugin-researcher` agent available** (the Agent tool is missing, or the
+agent isn't installed)? Do its steps here instead. Read
+`~/.claude/agents/plugin-researcher.md` (in the repo:
+`.claude/agents/plugin-researcher.md`) and follow it.
+
+### Step 3: Ask only the open questions
+
+Show the report's summary lines: the key written, FX names, category/style,
+what was verified live, sources.
+
+Then ask **only** the report's open questions, all at once in one
+`AskUserQuestion` call (up to 4). Each question offers the value the agent
+already wrote as the first option, labelled "(keep)":
+
+- **Preference:** offer the proposed number plus the neighbouring bands from
+  the field guide (e.g. "65 — good third-party (keep)", "80 — go-to",
+  "45 — fallback only").
+- **Habit or settings questions:** offer "Use the researched defaults (keep)"
+  and let the user type their own in "Other".
+
+More than 4 open questions? Ask the 4 that change the record the most. List the
+rest as already filled in from research, and say the user can change them with
+another `/learn-plugin`.
+
+No open questions besides preference? Ask only the preference confirmation.
+
+**Publishers only:** add one question per plugin, in the same call: "Publish
+**[Plugin]** to built-in for every reaper-mcp user?" with "Publish (adds it to
+the built-in plugin list)" first and "Keep it in my layer" second. It counts
+toward the 4; with several plugins, one question "Publish all N to built-in?"
+is enough.
+
+**Several plugins:** start asking once most reports are in, without waiting for
+a slow last one. `AskUserQuestion` takes 4 questions per call, so batch across
+plugins and name the plugin in every question:
+
+1. Preferences first, 4 plugins per call. Two utilities with the same kind of
+   question can share one question.
+2. Then the facts about the user's setup that change the records the most,
+   e.g. what an offline instance or a hardware-control track is for.
+3. Then habits, settings and naming questions, which matter less.
+
+Stop after about 3–4 calls. Anything still unasked keeps the researched value;
+list those questions at the end, and say the user can change any of them with
+another `/learn-plugin`. When an answer can be checked in REAPER (e.g. "it was
+offline, check again"), check it read-only and fold in what you find.
+
+### Step 4: Fold the answers in
+
+Answers that only kept the agent's values change nothing; skip the write.
+Otherwise `memory.read` the `user::` key and change only what the user answered:
+
+- preference → the header line **and** the `preference::<n>` tag
+- when they pick it → `## When to prefer this`
+- their own settings → a `###` use case under `## Recommended settings`,
+  marked as the user's own
+
+Then `memory.write` the full record and full tag list (a write replaces both),
+with `source_agent: "learn-plugin"` and no `ttl_days`. Keep everything else the
+agent wrote, `## Learned notes` included.
+
+**Several plugins:** make the writes in parallel, one subagent per record, or a
+single subagent for several records that only change the preference. Give each
+one the key, the exact changes, and the rule to keep everything else word for
+word.
+
+### Step 5: Add it to the built-in plugin list
+
+**Publisher who chose Publish:** run `/mix-memory publish` for each plugin's
+`user::plugins::…` key (it merges with any built-in record, checks privacy,
+writes the built-in key and removes the `user::` copy). Its last step rebuilds
+`docs/PLUGINS.md` in the clone with `scripts/plugin-list.mjs`; with several
+plugins, run the script once at the end. Say which rows were added and that
+`docs/PLUGINS.md` needs a commit.
+
+**Everyone else (or "Keep it in my layer"):** don't edit `docs/PLUGINS.md`; it
+lists only built-in records, and a local edit blocks the bridge's one-click
+Update. Tell the user, in two lines, how to get it listed:
+
+> To share **[Plugin]** with every reaper-mcp user: open the bridge window's
+> **Plugins** tab and press **Contribute**. That opens a pull request with your
+> record; once the maintainer publishes it, it's added to the built-in plugin
+> list (`docs/PLUGINS.md`).
+
+### Step 6: Confirm
+
+> "Done! **[Plugin Name]** is saved to LoreKit as
+> `user::plugins::{vendor}/{plugin}` (preference n/100, [category]).
+> [Verified live: N params, the scaling of K of them. | Not tested live: reason.]
+>
+> The mixing skills will use it for **[category]** jobs when it's your
+> highest-preference installed plugin, and will add to its learned notes as they
+> work with it."
+
+Published in Step 5? Say "is now built in as `plugins::{vendor}/{plugin}`"
+instead, and add the `docs/PLUGINS.md` row to commit.
+
+If the report said the scratch track couldn't be removed, say that first and
+name the track.
+
+**Several plugins:** one table instead (plugin, key, preference, category,
+verified live, published or how to contribute), then the Step 7 overviews,
+shortened to a few lines each.
+
+### Step 7: Show how it works
+
+Always end with the overview from the report's **How it works** section, under
+the heading **"How [Plugin Name] works"**. Update it with the user's answers
+from Step 3 first: fill in or correct **Your setup**, and adjust **In practice**
+where an answer changes what the mixer can do. Keep the agent's structure (what
+it is, the key point, the control table, presets, your setup, in practice). Keep
+it plain, not fancy.
+
+The report has no overview (an older agent, or you did the steps inline)?
+Write one in that structure from the final record.
+
+## Notes
+
+- **Ask little.** Anything the web or REAPER can answer (exact FX name, vendor,
+  category, parameters, ranges, presets, typical settings) is never asked.
+  The user is asked about their taste and habits, or a fact the sources disagree
+  on and testing couldn't settle.
+- **Self-improvement loop (per `memory-protocol.md`).** The main output is the
+  plugin record. If a run shows a recurring process lesson (e.g. a vendor whose
+  FX names don't match its marketing name, a category that's often mis-picked,
+  a plugin type whose params can't be probed), dedup-search and write or update
+  a `user::mixing-lessons::<slug>` lesson (`source_agent: "learn-plugin"`) and
+  mention it.
+- The `fx::` tags must be the **exact** FX-browser names. They're matched as
+  case-insensitive substrings of installed FX names. The agent takes them from
+  `search_fx`, so they always match this machine.
+- The header line and the tags must stay in step: lookups filter on the tags,
+  people read the header.

package/claude/skills/mastering/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: mastering
+description: >
+  Masters the mix bus in a live REAPER session — gentle corrective EQ, glue
+  compression, and a true-peak limiter targeting a platform LUFS standard — while
+  verifying against metering and preserving the mix's character. Use when the user
+  asks to master, finalize, or prepare a track for Spotify/Apple/streaming or a
+  specific loudness target. Triggers on "master this", "prepare for Spotify",
+  "final master", "hit -14 LUFS", "/mastering".
+argument-hint: '[platform or LUFS target]'
+license: MIT
+metadata:
+  author: mthines
+  version: '1.0.0'
+  workflow_type: applied
+  tags:
+    - mastering
+    - loudness
+    - lufs
+    - limiter
+    - reaper
+    - audio
+---
+
+# Mastering
+
+Act as a mastering engineer working the mix bus in a **live** REAPER session via
+the `reaper` MCP tools. Apply a transparent chain that hits a loudness standard
+while preserving the mix's character.
+
+**Mastering is subtle** — moves are fractions of a dB. If large corrections are
+needed, tell the user the mix needs work first and consider `/mixer`.
+
+## Targets
+
+Default to **-14 LUFS, -1.0 dBTP** (safe for all streaming) unless the user names
+a platform. Full target table: `reference/metering.md`.
+
+## Memory
+
+Per `reference/memory-protocol.md` — plugin knowledge and lessons in LoreKit
+(scope `project::reaper-mcp`), in two layers: the read-only **built-in** layer and
+the user's own `user::` layer on top. Reads combine both; writes go to `user::` keys only.
+- **Before:** read the `loop::mixing-lessons` bucket (capped at 5 + one search on
+  "mastering limiter loudness …") and, for your limiter/EQ/comp plugins, both
+  `get_builtin_knowledge { key: "plugins::{vendor}/{plugin}" }` and `memory.read`
+  of `user::plugins::{vendor}/{plugin}` — past
+  targets the user preferred and known gotchas (the user record wins).
+- **Plugin gate — no plugin is touched before its memory is read.** Before the
+  first call that adds, sets, loads a preset for, writes MIDI to, or reads parameters
+  of a plugin (`add_fx`, `setup_fx_chain`, `set_fx_parameter`,
+  `set_multiple_fx_parameters`, `set_fx_preset`, `load_fx_chain`, MIDI for an
+  instrument track, take FX), look it up — every plugin, every time it is new to this
+  session, including ones the user named, ones already in the project and ones you
+  only meet while listing a chain. Never skip it because the plugin looks familiar.
+  Look up both layers: `list_builtin_knowledge { query: "<plugin name>" }` (or `tags:
+  ["fx::<FX name>"]`) / `get_builtin_knowledge { key: "plugins::{vendor}/{plugin}" }`,
+  and `memory.search` / `memory.read` of `user::plugins::{vendor}/{plugin}` (the user's
+  record wins). Then **follow the record**: its MIDI map and note ranges, parameter
+  scaling, recommended settings and gotchas decide what you do, and a setting you were
+  about to use that the record warns against is not used. Say it in one chat line
+  ("Recalled Odin x Ari Lite: notes <36 are keyswitches → transposing"). Keep a running
+  list of recalled plugins and don't re-read those. No record in either layer: say so
+  and carry on (or bootstrap it when the user asked for the plugin by name). LoreKit
+  not connected: say so once and use the built-in read only.
+- **Unknown plugin?** Bootstrap it first (see protocol): dispatch the
+  `plugin-researcher` agent (or follow its steps yourself), then read its
+  `user::plugins::` record and use it.
+- **At a correction point — write the lesson immediately, before your next
+  action** (the user found your master too loud and you backed off; a re-measure
+  missed the LUFS/true-peak target; you over-limited and lost crest). Non-
+  negotiable (see Hard Rules); **say in chat that you captured it** (key +
+  takeaway). A silent skip is a bug.
+- **End-of-session retrospective (always, even on a clean master).** Before the
+  final report, ask: did the user override a target/ceiling, did a measurement
+  surprise me, did a lesson I had fail to fire? If anything surfaced, write or
+  UPDATE a lesson (rewriting the same key bumps the store's `seen_count`). A
+  lesson seen `>= 3×` is promotable to a Hard Rule via `/mix-memory promote`.
+- **Durable facts:** also capture a verified limiter param map or a ceiling the
+  user kept under the `user::plugins::` record's `## Learned notes`
+  (read-merge-write; never write a built-in key). Name the key you wrote.
+
+## Workflow
+
+1. **Snapshot** — `snapshot_save { name: "pre-master" }`.
+2. **Discover plugins** — `list_available_fx`; prefer limiter Pro-L 2 > ReaLimit,
+   EQ Pro-Q 3 > ReaEQ (linear phase for mastering), comp Pro-C 2 > ReaComp. Check
+   the LoreKit plugin records (built-in + `user::`) for settings; bootstrap any
+   unknown plugin first.
+3. **Assess the bus** — `analyze_track_offline { trackIndex: -1, startTime: 0,
+   endTime: <song end>, sectionSeconds: 10 }`: integrated LUFS over the whole
+   song (not a few seconds of meter), LRA, true peak, crest, loudest/quietest
+   sections and band balance. With a reference song, add `referencePath` for the
+   loudness and tonal-balance delta. Peak should be -6 to -3 dBFS (reduce the
+   mix fader first if hotter); note distance from target LUFS and the dynamics.
+   Pass the target as `targetLufs` on every `read_track_lufs` / `measure_tracks`
+   call, so the bridge page shows each reading against it.
+4. **Corrective EQ** — gentle only. Typical: steep HPF 20–30 Hz; low shelf -0.5 to
+   -1 dB @ 80 Hz; low-mid dip -0.5 to -1 dB @ 250–350 Hz; +0.5 dB presence @
+   2–4 kHz only if needed; air shelf +0.5 to +1 dB @ 10–12 kHz. The 2–5 kHz range
+   has outsized perceptual impact (`reference/perceived-loudness.md`). Judge the
+   bus spectrum on K-weighted `kDb`, never raw `db`, against a level-matched
+   reference band by band, and read it 3+ times (each read is a ~0.5 s snapshot). **If you're
+   EQing more than ±2 dB, the mix has a problem — go back.**
+5. **Glue compression** (optional) — only for cohesion: 1.5:1–2:1, slow attack
+   30–80 ms, auto/200–500 ms release, **1–2 dB GR max**. More GR → fix the mix.
+6. **Limiter** (last in chain) — ceiling -1.0 dBTP (streaming) or -0.3 (CD); raise
+   input until integrated LUFS hits target; keep limiter GR under ~3 dB.
+   If the limiter pumps (guitars/bass dip on every drum hit), **clip before
+   it** rather than lowering drive or limiting harder. Put a clipper (e.g.
+   Free Clip 2) just before the limiter, with a ceiling ~1–1.5 dB under the
+   level that *arrives at it* (an upstream limiter's ceiling, not 0 dBFS).
+   The clipper only alters the peak samples, while the limiter's gain change
+   pulls the whole mix down for its release time. Seen live: master pumping
+   std 1.35 → 1.06 dB at +0.25 LU. Keep it to ≤1.5 dB (lesson
+   drum-bus-clip-buries-attack).
+   **Dynamics over loudness:** streaming turns everything down to about -14
+   LUFS, so a hotter master only loses punch there. Don't chase a loud
+   reference's LUFS. Offer louder as an option the user picks by ear.
+7. **Verify** — `analyze_track_offline` on the master over the whole song:
+   integrated LUFS within 0.5 of target, true peak below the ceiling, LRA and
+   crest genre-appropriate; `read_track_correlation` healthy (>0.3). To compare
+   chain versions, `analyze_track_aesthetics` on the same 30 s range keeps the
+   default level match (-18 LUFS), so the louder master does not win by level;
+   PQ moves under ~0.1 are noise (`reference/aesthetics-scoring.md`).
+   While the user is working in REAPER, verify during playback instead of
+   rendering (a render window takes focus). Use `measure_tracks` on the bus for
+   LUFS + true peak over the loud section, or the stock Loudness Meter in
+   true-peak mode. For a final choice, build 2–3 variants and switch them live
+   with `run_plan` (mixer skill, step 7). Render the deliverable once, when the
+   user asks.
+8. **Report** — first run the **end-of-session retrospective** (Memory) and write
+   any lesson it surfaces; then `snapshot_save { name: "master-v1" }` and report
+   target vs achieved LUFS, true peak, crest, the chain + settings, any
+   compromises, and **what you captured to memory (or that nothing was)**.
+
+## Hard Rules
+
+<!-- Promotion target: recurring mastering lessons graduate here via /mix-memory promote. -->
+
+- **No plugin without its memory.** Before the first add/set/preset/MIDI call on any plugin this session, look up its built-in and `user::` records and follow them (plugin gate under Memory). Skipping the lookup because the plugin looks familiar is a bug.
+
+- **Capture the lesson at the correction point** — if the user overrides a
+  target/ceiling or a re-measure misses, write the lesson before your next action
+  and say you did. Never end a session that had a correction without a written
+  lesson. (Invariant.)
+- **Mastering is the final stage** — the mix should already be finished.
+- **If the bus clips before you start, reduce it first** — don't just add a limiter.
+- **Linear-phase EQ if available** — avoids phase shift on the master.
+- **Always A/B with `snapshot_restore`** — mastering is subtle enough to fool you.
+- **A balanced master slopes gently down** from lows to highs on the analyzer.