@mthines/reaper-mcp 0.19.0 → 0.70.3-beta.86.1

package/README.md

@@ -1,593 +1,551 @@
-# reaper-mcp
+<div align="center">
 
-AI-powered mixing for REAPER DAW. An MCP server that gives AI agents (Claude Code, etc.) full control over REAPER — real-time metering, FX management, transport control, frequency analysis, and an AI mix engineer knowledge base.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/logo-dark.svg">
+  <img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/logo.svg" alt="reaper-mcp" width="360">
+</picture>
 
-```
-"Please gain stage my tracks"
-"The chorus needs more energy — make the vocals cut through"
-"I hear some low-end rumble, can you fix that?"
-"Roast my mix — what could be improved?"
-```
+<br><br>
 
-## Quick Start
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/hero.svg" alt="reaper-mcp — Mix by asking. Type what you hear and an AI mix engineer inside your REAPER session does it." width="100%">
 
-```bash
-# Interactive guided setup (recommended)
-npx @mthines/reaper-mcp init
+<br>
 
-# Or non-interactive — install everything with defaults
-npx @mthines/reaper-mcp init --yes
-```
+**Type what you hear. It measures, decides and makes the change live in your REAPER session.**
+<br>
+You chat in plain English in Claude Code, by keyboard (or dictation, if you like). No menus to learn, no exporting, no code.
 
-The `init` wizard walks you through:
-1. Installing the REAPER bridge (Lua + JSFX analyzers)
-2. Installing AI mix knowledge and agents
-3. Configuring Claude Code settings (auto-allows all 80 REAPER tools)
-4. Optionally creating a project-local `.mcp.json`
+<br>
 
-Then load `mcp_bridge.lua` in REAPER and open Claude Code — you're ready to mix.
+[![REAPER 6+](https://img.shields.io/badge/REAPER-6%2B-22d3a6?style=for-the-badge)](https://www.reaper.fm/)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-ready-a78bfa?style=for-the-badge)](https://claude.com/claude-code)
+[![LoreKit](https://img.shields.io/badge/Memory-LoreKit-7c3aed?style=for-the-badge)](https://lorekit.io)
+[![macOS · Windows · Linux](https://img.shields.io/badge/macOS_·_Windows_·_Linux-1a1240?style=for-the-badge)](#-install-in-3-steps)
+[![MIT](https://img.shields.io/badge/license-MIT-ff7a45?style=for-the-badge)](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/LICENSE)
 
-## What it does
+[**Install in 3 steps**](#-install-in-3-steps) · [See it work](#-just-type-what-you-hear) · [What you get](#-why-producers-use-it) · [Watch it work](#-see-what-your-agent-is-doing) · [Extensions](#-extensions-teach-it-your-plugin) · [FAQ](#-faq)
 
-```
-Claude Code
-  ├── MCP Tools (80) ──→ controls REAPER in real-time
-  │   ├── Track management (list, get/set properties, arm, phase, input)
-  │   ├── FX management (add/remove, get/set parameters, enable/offline, presets)
-  │   ├── Transport (play, stop, record, cursor position)
-  │   ├── Metering (peak/RMS, FFT spectrum, LUFS, correlation, crest factor)
-  │   ├── Selection (selected tracks, time selection)
-  │   ├── Markers & regions (list, add, delete)
-  │   ├── Tempo map (all tempo/time sig changes)
-  │   ├── Envelopes (list, read/write automation points)
-  │   ├── MIDI editing (14 tools: notes, CC, items, analysis, batch ops)
-  │   ├── Media items (11 tools: properties, split, move, trim, stretch)
-  │   ├── Plugin discovery (list installed FX, search, presets)
-  │   ├── Snapshots (save/restore/delete mixer state for A/B comparison)
-  │   └── Routing (sends, receives, bus structure)
-  │
-  └── Mix Engineer Knowledge ──→ knows HOW to use those tools
-      ├── Plugin knowledge (ReaEQ, Pro-Q 3, Helix Native, etc.)
-      ├── Genre rules (rock, pop, hip-hop, electronic, orchestral, metal)
-      ├── Workflows (gain staging, vocal chain, drum bus, mastering)
-      └── Reference (frequencies, compression, LUFS targets, perceived loudness, common mistakes)
-```
+</div>
 
-## Architecture
+---
 
-```
-Claude Code ←stdio→ MCP Server (TypeScript) ←JSON files→ Lua Bridge (REAPER)
-                                                              │
-                                              ReaScript API ←─┘
-                                              gmem[] shared memory ←── JSFX Analyzers
-```
+## 💬 Just type what you hear
 
-REAPER's scripting environment is sandboxed — no sockets, no HTTP. The Lua bridge runs inside REAPER via `reaper.defer()` at ~30ms intervals, polling a shared directory for JSON command/response files. Round-trip latency: ~50-150ms.
+You know what's wrong with your mix. You just don't want to spend an hour in
+plugin windows fixing it. Type it into Claude Code the way you'd say it to an
+engineer. It's a text chat, so no microphone or voice setup is needed (dictate
+with your OS if you prefer, it's the same thing to the agent):
 
-## Installation
+> 🎧 *"Please gain stage my tracks."*
+>
+> 🎸 *"The chorus needs more energy. Make the vocals cut through."*
+>
+> 🔊 *"I hear some low-end rumble. Can you fix that?"*
+>
+> 🔥 *"Roast my mix. What could be better?"*
+>
+> 💿 *"Master this for Spotify."*
 
-### Prerequisites
+Here's what happens next:
 
-- [REAPER](https://www.reaper.fm/) v6.0+ (v7.0+ recommended)
-- [Node.js](https://nodejs.org/) 20+
-- [SWS Extensions](https://www.sws-extension.org/) (recommended — enables plugin discovery and enhanced features)
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/session-demo.svg" alt="Illustrative session: the mixer saves a snapshot, measures, cuts the guitars where they mask the vocal, compresses the vocal, re-measures and saves an after snapshot." width="100%">
 
-### Option A: Interactive Setup (recommended)
+It isn't a preset and it isn't a guess. Before it touches anything it **measures your
+actual tracks** (loudness, spectrum, stereo width, dynamics). It makes the change with
+**the plugins you own**, then **measures again** to check it worked.
 
-```bash
-npx @mthines/reaper-mcp init
-```
+---
+
+## ✨ Why producers use it
+
+<table>
+<tr>
+<td width="33%" valign="top">
+
+### 👂 It measures, then mixes
+It reads LUFS, true peak, the frequency spectrum, stereo correlation and crest factor
+on every track before it decides anything, and again after. You get numbers, not vibes.
+
+</td>
+<td width="33%" valign="top">
+
+### 🎛️ It uses *your* plugins
+It finds your installed FX and reaches for the best one you have: **FabFilter Pro-Q 3**
+if it's there, **ReaEQ** if not. Anything it doesn't know yet, it learns.
+
+</td>
+<td width="33%" valign="top">
+
+### 🛟 You can't lose your mix
+It saves a snapshot **before and after** every change, so you can A/B them with one
+click. Each edit is a single REAPER undo step.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+### 🎸 It knows the genre
+Rock, pop, hip-hop, electronic, metal, orchestral. It adjusts loudness targets, low-end
+handling and dynamics to the style. Just tell it what you're making.
+
+</td>
+<td valign="top">
+
+### 🧠 It remembers
+With **[LoreKit](#-lorekit-the-knowledge-core)** as its memory, it keeps what it learns
+about your plugins and your taste, so a correction sticks. It also draws on a shared
+plugin library that grows every time someone
+**[contributes](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/knowledge/contributions/README.md)**, you included.
+
+</td>
+<td valign="top">
+
+### ⚡ It works live, in real time
+It talks straight to your open session, about 50–150 ms per action. You don't bounce
+or upload anything, and you hear each change as it happens.
 
-The wizard guides you through selecting which components to install:
-- **REAPER Bridge** — Lua bridge + JSFX analyzers (copied to your REAPER resource folder)
-- **AI Skills & Agents** — knowledge base, mix agents, rules, skills (global or project-local)
-- **Claude Code Settings** — auto-allows all 80 REAPER tools (no permission prompts)
-- **Project Config** — `.mcp.json` for the current directory (opt-in)
+</td>
+</tr>
+</table>
 
-For CI/automation, use `--yes` to skip prompts and install everything with defaults:
+---
+
+## 🔍 How it works
+
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/how-it-works.svg" alt="You describe what you hear, Claude measures and decides, REAPER changes live. Every change: snapshot, measure, decide, change, re-measure." width="100%">
+
+**You stay in charge.** Ask it to explain before it acts, undo anything, or use
+`/critique` for advice without a single change to your project.
+
+---
+
+## 🧠 LoreKit: the knowledge core
+
+A mix engineer's value is what they've learned. reaper-mcp keeps all of that in
+**[LoreKit](https://lorekit.io)**, a free, open-source memory store for AI agents. It's
+what turns a remote control into an engineer that gets better every session.
+
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/knowledge-core.svg" alt="LoreKit at the center: the mix skills read plugin records and lessons before acting and write back what they learned." width="100%">
+
+- 🎛️ **One record per plugin.** What it is, what each knob does, the settings that
+  worked and the gotchas. Ask for a plugin it has never seen and it **researches it,
+  inspects it live and writes the record first**, then uses it. You can also teach it
+  one with `/learn-plugin`.
+- 📝 **Lessons from your corrections.** Revert a change, or have a re-measure come back
+  worse, and it saves a lesson right then. A lesson that keeps coming up becomes one of
+  the mixer's permanent rules, so it stops making that mistake.
+- 🧩 **Built-in knowledge plus your own.** It ships with a curated, read-only set of
+  plugin records and lessons, and everything it learns from *you* goes into your own
+  layer on top. When the two disagree, yours wins, so your taste never gets
+  overwritten. The built-in set comes with the server, read-only, and needs no
+  LoreKit account. Connect your own LoreKit to start your layer.
+- 📚 **A built-in plugin library.** FabFilter, Soundtoys, Valhalla, iZotope, Melodyne, the
+  REAPER stock plugins and more: see the **[built-in plugin list](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/PLUGINS.md)**, and how
+  to add yours.
+- 🤝 **Share what you taught it.** Press **Contribute** in the bridge page's Plugins tab
+  and your plugin records become a pull request. Once the maintainer approves it, they're
+  built in for every reaper-mcp user and added to the
+  [plugin list](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/PLUGINS.md) ([how it works](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/knowledge/contributions/README.md)).
+  Regular contributors can publish straight to built-in, no pull request: ask on
+  [Discord](https://discord.gg/Eg8tznuXp4).
+- 🌍 **It follows you.** The memory isn't tied to one project folder. Whatever song
+  you open, it brings what it knows.
+- 🔒 **Audio knowledge only.** It never stores client names, song titles or license keys.
+
+> **No LoreKit? It still mixes.** Everything works without it. It just starts from
+> scratch every session instead of getting smarter. Genre rules, step-by-step workflows
+> and reference sheets (frequencies, compression, loudness) ship with the repo either way.
+
+---
+
+## 🚀 Install in 3 steps
+
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/install-steps.svg" alt="1. Get REAPER, Claude Code and Node.js. 2. Paste one command. 3. Click Run on mcp_bridge.lua in REAPER." width="100%">
+
+### 1 · Get the apps
+
+| | | |
+|---|---|---|
+| 🎚️ **REAPER** | your DAW (v6+, v7 recommended) | [reaper.fm](https://www.reaper.fm/) |
+| 🤖 **Claude Code** | the AI you talk to | [claude.com/claude-code](https://claude.com/claude-code) |
+| 🟢 **Node.js 20+** | runs the connector behind the scenes | [nodejs.org](https://nodejs.org/) |
+| 🧠 **LoreKit** *(recommended)* | the memory, so it learns | [lorekit.io](https://lorekit.io) |
+| ➕ **SWS Extensions** *(optional)* | extra REAPER powers | [sws-extension.org](https://www.sws-extension.org/) |
+
+### 2 · Paste these commands
+
+Open a terminal, then run:
 
 ```bash
-npx @mthines/reaper-mcp init --yes             # bridge + global skills + settings
-npx @mthines/reaper-mcp init --yes --project   # also creates .mcp.json in current directory
+npm install -g @mthines/reaper-mcp
+reaper-mcp setup     # installs the bridge and status page into REAPER
+reaper-mcp init      # connects Claude Code and adds the mix skills
 ```
 
-### Option B: Manual Steps
+That's it. No clone, no build. To update later, run `npm install -g @mthines/reaper-mcp` again,
+then `reaper-mcp setup`. The bridge window in REAPER also shows an **Update** notice.
 
-If you prefer to run each step individually:
+### 3 · Click Run in REAPER
 
-```bash
-# 1. Install REAPER components (Lua bridge + JSFX analyzers)
-npx @mthines/reaper-mcp setup
+In REAPER: **Actions → Show action list → Load ReaScript…**, pick **`mcp_bridge.lua`**
+and click **Run**. A small status window opens, showing the bridge is live. 🟢
+Running it again stops the bridge.
+
+**Now open Claude Code in any folder (your song folder is perfect) and start mixing:**
 
-# 2. Install AI mix knowledge (globally by default, or --project for local)
-npx @mthines/reaper-mcp install-skills
-npx @mthines/reaper-mcp install-skills --project  # project-local alternative
+```
+/mixer Please gain stage my tracks
 ```
 
-**What gets installed:**
+<details>
+<summary><b>Something not working?</b></summary>
 
-The `setup` command copies into your REAPER resource folder:
-- `mcp_bridge.lua` — persistent Lua bridge script
-- `mcp_snapshot_manager.lua` — snapshot manager GUI (save/restore/delete from REAPER)
-- `mcp_analyzer.jsfx` — FFT spectrum analyzer
-- `mcp_lufs_meter.jsfx` — ITU-R BS.1770 LUFS meter
-- `mcp_correlation_meter.jsfx` — stereo correlation analyzer
-- `mcp_crest_factor.jsfx` — dynamics/crest factor meter
+<br>
 
-The `install-skills` command installs to `~/.claude/` (global, default) or `.claude/` (project):
-- `agents/` — mix engineer subagents (`@mix-engineer`, `@gain-stage`, `@mix-analyzer`, `@master`)
-- `rules/` — architecture and development rules
-- `skills/` — skills like `/learn-plugin`
-- `knowledge/` — plugin knowledge, genre rules, workflows, reference data
+- **Run `reaper-mcp doctor`.** It checks the bridge, the skills and the Claude Code config, and says how to fix what's off.
+- **Is the bridge running?** The status window shows 🟢 when it is. If not, run `mcp_bridge.lua` again from REAPER's action list.
+- **Claude Code doesn't see REAPER?** Install Claude Code first, then run `reaper-mcp init` again.
+- **Missing skills?** `reaper-mcp install-skills` copies them into `~/.claude` (it never overwrites files you edited).
+- **Audio analysis (loudness, masking, stems)?** `reaper-mcp setup-sidecar` (needs Python 3.10+).
 
-### Start the Lua Bridge in REAPER
+</details>
 
-After setup (either option), load the bridge in REAPER:
+---
 
-1. Open REAPER
-2. **Actions > Show action list > Load ReaScript**
-3. Select `mcp_bridge.lua` from your REAPER Scripts folder
-4. Click **Run** — the bridge runs persistently in the background
+## 🎚️ Meet your engineers
 
-You should see in REAPER's console: `MCP Bridge: Started`
+Seven skills, each tuned for a job. Type the slash command, or just describe what you
+want and the right one starts.
 
-### Verify
+| | Skill | What it does | Try |
+|---|---|---|---|
+| 🎚️ | **`/mixer`** | Does the mixing: gain staging, vocal chains, drum bus, low end, stereo image | `/mixer Build a vocal chain on track 3` |
+| 🔥 | **`/critique`** | "Roast my mix." A measured report of what to fix. **Changes nothing.** | `/critique What's holding this mix back?` |
+| ✂️ | **`/editing`** | Edits notes, arrangement and timing, and compares two versions of a part in lanes | `/editing Make the chorus half-time` |
+| 💿 | **`/mastering`** | A mastering chain on the mix bus, aimed at a platform's loudness | `/mastering Master this for Spotify` |
+| 🎓 | **`/learn-plugin`** | Researches a plugin you own, tests it live and saves it to LoreKit, asking you only what it can't work out | `/learn-plugin JST Gain Reduction Deluxe` |
+| 🧩 | **`/new-extension`** | Builds or updates an [extension](#-extensions-teach-it-your-plugin) that edits a plugin's internals (wavetables, mod matrix, patch state) and proves it live on a scratch track | `/new-extension Serum` |
+| 🗂️ | **`/mix-memory`** | Shows what it remembers, and tidies it up | `/mix-memory What do you know about Pro-C 2?` |
 
-```bash
-npx @mthines/reaper-mcp doctor
-```
+---
 
-Checks that the bridge is connected, knowledge is installed, and MCP config exists.
-
-## MCP Tools (80)
-
-### Project & Tracks
-
-| Tool | Description |
-|------|-------------|
-| `get_project_info` | Project name, tempo, time sig, sample rate, transport state |
-| `list_tracks` | All tracks with volume, pan, mute/solo, arm, phase, FX count, routing |
-| `get_track_properties` | Detailed track info + full FX chain list |
-| `set_track_property` | Set volume (dB), pan, mute, solo, recordArm, phase, input |
-
-### FX Management
-
-| Tool | Description |
-|------|-------------|
-| `add_fx` | Add FX by name (partial match: "ReaEQ", "Pro-Q 3") |
-| `remove_fx` | Remove FX from chain by index |
-| `get_fx_parameters` | List all FX params with values and ranges |
-| `set_fx_parameter` | Set FX parameter (normalized 0.0-1.0) |
-| `set_fx_enabled` | Enable or disable (bypass) an FX plugin |
-| `set_fx_offline` | Set FX online/offline (offline = no CPU, preserves settings) |
-| `list_available_fx` | Discover all installed plugins (VST, VST3, JS, CLAP, AU) |
-| `search_fx` | Fuzzy search installed plugins by name |
-| `get_fx_preset_list` | List available presets for an FX |
-| `set_fx_preset` | Load a preset by name |
-
-### Transport
-
-| Tool | Description |
-|------|-------------|
-| `play` | Start playback |
-| `stop` | Stop playback/recording |
-| `record` | Start recording |
-| `get_transport_state` | Play/record/pause, cursor positions, tempo, time sig |
-| `set_cursor_position` | Move edit cursor to position (seconds) |
-
-### Selection & Navigation
-
-| Tool | Description |
-|------|-------------|
-| `get_selected_tracks` | Currently selected tracks with indices and names |
-| `get_time_selection` | Time/loop selection start, end, length |
-| `set_time_selection` | Set the time selection range |
-
-### Markers & Regions
-
-| Tool | Description |
-|------|-------------|
-| `list_markers` | All project markers (index, name, position, color) |
-| `list_regions` | All regions (index, name, start/end, color) |
-| `add_marker` | Add marker at position with optional name/color |
-| `add_region` | Add region with start/end, optional name/color |
-| `delete_marker` | Delete a marker by index |
-| `delete_region` | Delete a region by index |
-
-### Tempo Map
-
-| Tool | Description |
-|------|-------------|
-| `get_tempo_map` | All tempo/time sig changes (position, BPM, time sig, linear) |
-
-### Envelopes / Automation
-
-| Tool | Description |
-|------|-------------|
-| `get_track_envelopes` | List envelopes on a track (name, point count, active/visible/armed) |
-| `get_envelope_points` | Get automation points with pagination |
-| `insert_envelope_point` | Insert automation point (time, value, shape, tension) |
-| `delete_envelope_point` | Delete an automation point by index |
-
-### Metering & Analysis
-
-| Tool | Description |
-|------|-------------|
-| `read_track_meters` | Peak/RMS L/R in dB |
-| `read_track_spectrum` | FFT frequency bins (auto-inserts analyzer) |
-| `read_track_lufs` | Integrated/short-term/momentary LUFS + true peak |
-| `read_track_correlation` | Stereo correlation, width, mid/side levels |
-| `read_track_crest` | Crest factor (peak-to-RMS ratio) |
-
-### MIDI Editing (14 tools)
-
-| Tool | Description |
-|------|-------------|
-| `create_midi_item` | Create empty MIDI item on a track |
-| `list_midi_items` | List MIDI items with position, length, note/CC counts |
-| `get_midi_notes` | Get notes with pagination (offset/limit) |
-| `analyze_midi` | Per-pitch velocity stats, histogram, machine gun detection |
-| `insert_midi_note` / `insert_midi_notes` | Insert single or batch notes |
-| `edit_midi_note` / `edit_midi_notes` | Edit single or batch notes |
-| `delete_midi_note` | Delete a note by index |
-| `get_midi_cc` / `insert_midi_cc` / `delete_midi_cc` | CC event management |
-| `get_midi_item_properties` / `set_midi_item_properties` | MIDI item props |
-
-### Media Item Editing (11 tools)
-
-| Tool | Description |
-|------|-------------|
-| `list_media_items` | List items on a track (position, length, name, volume, type) |
-| `get_media_item_properties` | Detailed properties (fades, play rate, pitch, source) |
-| `set_media_item_properties` / `set_media_items_properties` | Set single or batch |
-| `split_media_item` | Split at position, returns left/right info |
-| `delete_media_item` / `move_media_item` / `trim_media_item` | Edit operations |
-| `add_stretch_marker` / `get_stretch_markers` / `delete_stretch_marker` | Time-stretching |
-
-### Snapshots (A/B Testing)
-
-Snapshots capture your full mixer state: track volumes, pans, mute/solo, FX chains (all parameter values, enabled/offline states, presets), and send levels. Use them to A/B compare mix decisions or revert to a known-good state.
-
-| Tool | Description |
-|------|-------------|
-| `snapshot_save` | Save current mixer state (volumes, pans, FX params, sends, mutes) |
-| `snapshot_restore` | Restore a saved snapshot (smart FX matching — only restores params if plugin names match) |
-| `snapshot_list` | List all saved snapshots with metadata |
-| `snapshot_delete` | Delete a saved snapshot by name |
-
-You can also manage snapshots directly in REAPER using the **Snapshot Manager** GUI (`mcp_snapshot_manager.lua`) — load it as a ReaScript action for a visual list with save/restore/delete buttons.
-
-For quick A/B testing, bind these action scripts to keyboard shortcuts in REAPER:
-
-| Script | Purpose | Suggested Key |
-|--------|---------|---------------|
-| `mcp_snapshot_quick_save.lua` | Save snapshot instantly (auto-named) | `Ctrl+Shift+S` |
-| `mcp_snapshot_next.lua` | Restore next snapshot (wraps around) | `Ctrl+Right` |
-| `mcp_snapshot_prev.lua` | Restore previous snapshot (wraps around) | `Ctrl+Left` |
+## 🧰 What it can control
 
-### Routing
+Almost everything in your session. That's **130+ tools**, so it can do the job
+instead of just giving advice:
 
-| Tool | Description |
-|------|-------------|
-| `get_track_routing` | Sends, receives, parent/folder info for a track |
+| | | |
+|---|---|---|
+| 🎚️ **Tracks & mixer**: volume, pan, mute/solo, folders, colors, groups & VCAs | 🎛️ **FX & plugins**: add, tweak, bypass, presets, FX chains, track templates | 📈 **Metering**: LUFS, true peak, spectrum, stereo correlation, crest factor |
+| 🔀 **Routing**: sends, buses, sidechains, hardware outputs | 🎹 **MIDI**: write, edit and analyze notes & CC, live MIDI out | ✂️ **Editing**: split, trim, move, fades, takes, stretch markers |
+| 📍 **Arrangement**: markers, regions, tempo map | 〰️ **Automation**: envelopes, points and pooled automation items | 💾 **Project**: save, render, undo/redo, snapshots, REAPER actions |
 
-## Using the Mix Agents
+👉 The main tools by area: **[docs/TOOLS.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/TOOLS.md)**
 
-Once you've run `init` (or `setup` + `install-skills`), open Claude Code. Four specialized mix agents are available:
+### 🎸 Genre-aware out of the box
 
-### Available Agents
+| Genre | Loudness target | What it leans into |
+|---|---|---|
+| 🎸 Rock | −11 to −9 LUFS | Parallel drum compression, hard-panned guitars |
+| 🎤 Pop | −14 to −10 LUFS | Vocal-forward, two-stage compression, bus glue |
+| 🎧 Hip-Hop | −10 to −7 LUFS | 808 saturation, aggressive vocal comp, mono sub |
+| 🎛️ Electronic | −10 to −6 LUFS | Sidechain pump, mono sub, stereo width |
+| 🎻 Orchestral | −23 to −16 LUFS | Preserved dynamics, hall reverb staging |
+| 🤘 Metal | −11 to −8 LUFS | Scooped guitars, tight drums, four-guitar wall |
 
-| Agent            | Invocation      | What it does                                                              |
-| ---------------- | --------------- | ------------------------------------------------------------------------- |
-| **Mix Engineer** | `@mix-engineer` | General-purpose mix agent — analyzes, suggests, and executes any mix task |
-| **Gain Stage**   | `@gain-stage`   | Perceived-loudness-aware gain staging with proper headroom                |
-| **Mix Analyzer** | `@mix-analyzer` | "Roast my mix" — analysis only, no changes, produces detailed report      |
-| **Master**       | `@master`       | Mastering chain targeting specific LUFS/platform standards                |
+---
 
-### How to use them
+## 🧩 Extensions: teach it your plugin
 
-Just mention the agent by name in Claude Code:
+Out of the box it controls any plugin through its knobs. But some of what makes a sound
+isn't a knob: a synth's **wavetables**, its **modulation matrix**, a guitar rig's **preset
+file**. **Extensions** reach that. They're small add-ons you switch on, and you can have
+Claude build one for the plugin *you* use.
 
-```
-@mix-engineer Please gain stage all my tracks
-@mix-engineer Build a vocal chain on track 3
-@mix-engineer The low end is muddy — can you fix it?
-@mix-analyzer Roast my mix — what could be improved?
-@master Master this for Spotify
-@gain-stage Set proper levels on everything
-```
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/extensions.svg" alt="Extensions plug into reaper-mcp through a small versioned API: the core on the left, and the Vital, Helix and your-own extensions on the right." width="100%">
+
+> 🎹 *"On the Vital on track 2, route LFO 2 to the filter cutoff at 40% and make it a slow triangle."*
+>
+> 🎸 *"Build me a djent rhythm tone in Helix with a clean, a crunch and a lead snapshot."*
+>
+> 🌊 *"Give this synth a wavetable that morphs from a sine to a bright saw over 64 frames."*
 
-Or start a full session as the mix engineer:
+| | Extension | What Claude can do with it |
+|---|---|---|
+| 🎹 | **`vital`** | Read a Vital patch and edit its settings, **mod matrix** and **LFO shapes**; build **wavetables** (1-256 frames) from classic shapes or harmonic recipes |
+| 🎸 | **`helix`** | Build and edit Line 6 **Helix presets** with up to 8 snapshots, check them against real models, and load them into Helix Native, **backed up and rolled back** if anything else changed |
+| 🧩 | **yours** | `/new-extension Serum`: Claude researches the plugin's format, probes it on a scratch track, writes the tools **with tests** and proves they change the sound |
+
+**Switch one on**, then restart Claude Code:
 
 ```bash
-claude --agent mix-engineer
+reaper-mcp extension add vital      # or: helix
+reaper-mcp extension list           # what's installed, and why one can't load
 ```
 
-### What happens under the hood
+- 🔌 **Opt-in.** Nothing loads unless you add it. `reaper-mcp extension remove vital` takes it out.
+- 🛟 **Same safety as the rest.** Every edit is one undo step, and write tools can preview with a dry run.
+- 🛡️ **A broken extension is skipped**, never a crash, and `reaper-mcp doctor` tells you why.
+- 🧪 **Proven live.** `/new-extension` doesn't finish until the edit shows up in the plugin *and* in the audio.
 
-Each agent has:
+📖 Full guide (the API, Lua handlers, testing, sharing, troubleshooting): **[docs/EXTENSIONS.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/EXTENSIONS.md)**
 
-- **Its own system prompt** — thinks like a mix engineer, not a general assistant
-- **Pre-approved REAPER tools** — no permission prompts for every MCP call
-- **Scoped MCP access** — only the `reaper` MCP server is loaded
-- **Embedded reference data** — frequency bands, LUFS targets, compression settings
+---
 
-The workflow is always:
+## 🛟 Safe by design
 
-1. **Save a snapshot** (so you can always A/B or undo)
-2. **Analyze** — read meters, spectrum, LUFS, correlation, crest factor
-3. **Reason** — apply genre rules, frequency knowledge, and plugin expertise
-4. **Act** — add FX, set parameters, adjust levels using the best available plugins
-5. **Verify** — re-read meters to confirm the change had the intended effect
-6. **Report** — explain what it did and why in audio engineering terms
+- 📸 **Snapshots around every mix task.** The mix skills save one before and after; A/B them in the
+  bridge window, or bind `mcp_snapshot_next` / `_prev` / `_quick_save` to keys (setup adds them to the Action List).
+- ↩️ **One change, one undo.** Each edit is labelled `MCP: …` in REAPER's undo history.
+- 🚫 **No surprise pop-ups.** It won't run anything that opens a dialog unless you allow
+  it, and it never closes your project or quits REAPER.
+- 👀 **Advice-only mode.** `/critique` never changes your project. The bridge window
+  also has a read-only switch and a pause button.
+- 📊 **Bridge status window.** See every action as it happens, with timing and errors,
+  in a small window next to REAPER ([see what it shows](#-see-what-your-agent-is-doing)).
 
-### A/B Comparison
+📖 What it can and can't do to a session, and what isn't covered: **[docs/SAFETY.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/SAFETY.md)**.
 
-Every change is bracketed by snapshots:
+---
 
-1. Agent saves a "Before" snapshot automatically
-2. Makes all changes
-3. Saves an "After" snapshot
-4. You can restore either with `snapshot_restore` to A/B compare, or use the Snapshot Manager GUI in REAPER
+## 🔭 See what your agent is doing
 
-### Genre Awareness
+You shouldn't have to take its word for it. The **bridge window** opens next to REAPER and
+logs every move the agent makes, as it happens: what it did, how long it took and anything
+that went wrong. With several Claude sessions connected, you can see which one did what.
 
-Tell the agent the genre and it adjusts its approach:
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/bridge-status.png" alt="The MCP Bridge status window: uptime, command count, errors, latency, a commands-per-minute timeline, and a live log of tool calls such as read_track_spectrum, set_track_property and snapshot_save, tagged by session." width="100%">
 
-```
-@mix-engineer This is a hip-hop track — please gain stage and check the 808
-@mix-engineer Mix this rock song — make sure the guitars are wide and the drums punch
-```
+<sub>Demo data. Add <code>?demo</code> to the window's address to explore it without REAPER.</sub>
 
-The agent reads `knowledge/genres/{genre}.md` for genre-specific conventions.
+### Click any call to see what it did
 
-## AI Mix Engineer Knowledge
+Every call opens a drawer in plain words (*"midnight-drive wrote new points into the Volume
+automation on track 5"*) with a picture of the change: **before → after** for edits, a
+readout against your target for measurements.
 
-The knowledge base is what makes this more than just a remote control — it's a mix engineer's brain.
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/bridge-drawer.png" alt="The bridge window with a call open in the drawer: Write automation, with a volume envelope drawn before and after, and the params the agent sent." width="100%">
 
-### Plugin Knowledge
+### 📈 What it measured
 
-Ships with knowledge for stock REAPER plugins and popular third-party suites:
+<table>
+<tr>
+<td width="50%" valign="top">
 
-| Plugin                                               | Category                | Preference |
-| ---------------------------------------------------- | ----------------------- | ---------- |
-| ReaEQ, ReaComp, ReaDelay, ReaVerb, ReaGate, ReaLimit | Stock                   | 30-50      |
-| FabFilter Pro-Q 3, Pro-C 2, Pro-L 2                  | Premium EQ/Comp/Limiter | 85-92      |
-| Line 6 Helix Native                                  | Amp Sim                 | 82         |
-| JS: 1175 Compressor                                  | Character Comp          | 50         |
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/spectrum.png" alt="The spectrum view: third-octave bands from 25 Hz to 16 kHz as bars, hot bands in amber." width="100%">
 
-The agent automatically discovers your installed plugins and uses the best available option for each task. If you have Pro-Q 3, it uses that. If not, it falls back to ReaEQ.
+**Spectrum**<br><sub>Where the energy sits, band by band, judged by perceived loudness. Hot bands turn amber.</sub>
 
-### Adding Your Own Plugins
+</td>
+<td width="50%" valign="top">
 
-Use the `/learn-plugin` skill in Claude Code:
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/loudness.png" alt="The loudness view: integrated LUFS against a target range on a scale, with short-term, momentary and true peak readouts and the change since the previous call." width="100%">
 
-```
-You: /learn-plugin
-Claude: What plugin would you like me to learn about?
-You: JST Gain Reduction Deluxe — it's a VCA compressor from Joey Sturgis Tones
-Claude: [asks about parameters, presets, usage]
-Claude: Created knowledge/plugins/jst/gain-reduction-deluxe.md
-```
+**Loudness**<br><sub>LUFS against your target, true peak, and how it moved since the last measurement.</sub>
 
-Or manually add a markdown file to `knowledge/plugins/`. See `knowledge/plugins/_template.md` for the format.
-
-### Genre Rules
-
-Processing decisions adapt to the genre:
-
-| Genre      | LUFS Target | Key Characteristics                             |
-| ---------- | ----------- | ----------------------------------------------- |
-| Rock       | -11 to -9   | Parallel drum compression, hard-panned guitars  |
-| Pop        | -14 to -10  | Vocal-forward, two-stage compression, bus glue  |
-| Hip-Hop    | -10 to -7   | 808 saturation, aggressive vocal comp, mono sub |
-| Electronic | -10 to -6   | Sidechain pump, sub mono, stereo width          |
-| Orchestral | -23 to -16  | Preserve dynamics, hall reverb staging          |
-| Metal      | -11 to -8   | V-scoop guitars, tight drums, 4-guitar wall     |
-
-## Autonomous Mode (Allow All Tools)
-
-By default Claude Code asks permission for each MCP tool call. The `init` command (and `install-skills`) automatically configures `settings.json` to allow all 80 REAPER tools. If you need to set this up manually, add to your project's `.claude/settings.json` (or `~/.claude/settings.json` for global):
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "mcp__reaper__get_project_info",
-      "mcp__reaper__list_tracks",
-      "mcp__reaper__get_track_properties",
-      "mcp__reaper__set_track_property",
-      "mcp__reaper__add_fx",
-      "mcp__reaper__remove_fx",
-      "mcp__reaper__get_fx_parameters",
-      "mcp__reaper__set_fx_parameter",
-      "mcp__reaper__list_available_fx",
-      "mcp__reaper__search_fx",
-      "mcp__reaper__get_fx_preset_list",
-      "mcp__reaper__set_fx_preset",
-      "mcp__reaper__play",
-      "mcp__reaper__stop",
-      "mcp__reaper__record",
-      "mcp__reaper__get_transport_state",
-      "mcp__reaper__set_cursor_position",
-      "mcp__reaper__read_track_meters",
-      "mcp__reaper__read_track_spectrum",
-      "mcp__reaper__read_track_lufs",
-      "mcp__reaper__read_track_correlation",
-      "mcp__reaper__read_track_crest",
-      "mcp__reaper__snapshot_save",
-      "mcp__reaper__snapshot_restore",
-      "mcp__reaper__snapshot_list",
-      "mcp__reaper__snapshot_delete",
-      "mcp__reaper__get_track_routing",
-      "mcp__reaper__set_fx_enabled",
-      "mcp__reaper__set_fx_offline",
-      "mcp__reaper__get_selected_tracks",
-      "mcp__reaper__get_time_selection",
-      "mcp__reaper__set_time_selection",
-      "mcp__reaper__list_markers",
-      "mcp__reaper__list_regions",
-      "mcp__reaper__add_marker",
-      "mcp__reaper__add_region",
-      "mcp__reaper__delete_marker",
-      "mcp__reaper__delete_region",
-      "mcp__reaper__get_tempo_map",
-      "mcp__reaper__get_track_envelopes",
-      "mcp__reaper__get_envelope_points",
-      "mcp__reaper__insert_envelope_point",
-      "mcp__reaper__delete_envelope_point",
-      "mcp__reaper__create_midi_item",
-      "mcp__reaper__list_midi_items",
-      "mcp__reaper__get_midi_notes",
-      "mcp__reaper__analyze_midi",
-      "mcp__reaper__insert_midi_note",
-      "mcp__reaper__insert_midi_notes",
-      "mcp__reaper__edit_midi_note",
-      "mcp__reaper__edit_midi_notes",
-      "mcp__reaper__delete_midi_note",
-      "mcp__reaper__get_midi_cc",
-      "mcp__reaper__insert_midi_cc",
-      "mcp__reaper__delete_midi_cc",
-      "mcp__reaper__get_midi_item_properties",
-      "mcp__reaper__set_midi_item_properties",
-      "mcp__reaper__list_media_items",
-      "mcp__reaper__get_media_item_properties",
-      "mcp__reaper__set_media_item_properties",
-      "mcp__reaper__set_media_items_properties",
-      "mcp__reaper__split_media_item",
-      "mcp__reaper__delete_media_item",
-      "mcp__reaper__move_media_item",
-      "mcp__reaper__trim_media_item",
-      "mcp__reaper__add_stretch_marker",
-      "mcp__reaper__get_stretch_markers",
-      "mcp__reaper__delete_stretch_marker"
-    ]
-  }
-}
-```
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
 
-The format is `mcp__reaper__{tool_name}`. Once added, Claude Code will run these tools without prompting.
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/loudness-curve.png" alt="The loudness curve view: short-term loudness over the length of a song against a target line, with the spans over target shaded." width="100%">
 
-## CLI Commands
+**Loudness over time**<br><sub>The whole song's loudness, with the stretches that run over target shaded.</sub>
 
-| Command | Description |
-|---------|-------------|
-| `npx @mthines/reaper-mcp init` | Interactive guided setup (recommended for new users) |
-| `npx @mthines/reaper-mcp init --yes` | Non-interactive setup — install everything with defaults |
-| `npx @mthines/reaper-mcp init --yes --project` | Non-interactive setup + create `.mcp.json` in current directory |
-| `npx @mthines/reaper-mcp serve` | Start MCP server in stdio mode (default when no command given) |
-| `npx @mthines/reaper-mcp setup` | Install Lua bridge + JSFX into REAPER |
-| `npx @mthines/reaper-mcp install-skills` | Install AI knowledge + agents globally |
-| `npx @mthines/reaper-mcp install-skills --project` | Install into current project directory |
-| `npx @mthines/reaper-mcp doctor` | Verify everything is configured correctly |
-| `npx @mthines/reaper-mcp status` | Check bridge connection |
+</td>
+<td width="50%" valign="top">
 
-Or install globally for shorter commands:
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/masking.png" alt="The masking view: a heat map of track pairs against frequency bands, with the worst conflicts and which track to cut." width="100%">
 
-```bash
-npm install -g @mthines/reaper-mcp
-reaper-mcp init
-```
+**Masking**<br><sub>Which tracks fight, at which frequency, and which one should give way.</sub>
 
-## Claude Code Integration
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
 
-After `install-skills --project`, your project has a `.mcp.json`:
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/stereo-bands.png" alt="The stereo view: correlation per frequency band on a minus one to plus one scale." width="100%">
 
-```json
-{
-  "mcpServers": {
-    "reaper": {
-      "command": "npx",
-      "args": ["@mthines/reaper-mcp", "serve"]
-    }
-  }
-}
-```
+**Stereo, per band**<br><sub>Phase correlation per band. Catches a wide or out-of-phase low end before it hurts.</sub>
 
-Claude Code reads this automatically. Open Claude Code in your project and the REAPER tools are available.
+</td>
+<td width="50%" valign="top">
 
-### Running from source (development)
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/waveform.png" alt="The waveform view: a rendered track drawn on a decibel scale with its peak, RMS and clipped sample count." width="100%">
 
-If you're developing reaper-mcp and want changes reflected immediately without rebuilding, point your `.mcp.json` at the TypeScript source using `npx tsx`:
+**Waveform**<br><sub>What a rendered track really looks like, with clipping counted.</sub>
 
-```json
-{
-  "mcpServers": {
-    "reaper": {
-      "command": "npx",
-      "args": ["tsx", "/path/to/reaper-mcp/apps/reaper-mcp-server/src/main.ts", "serve"]
-    }
-  }
-}
-```
+</td>
+</tr>
+</table>
 
-See [DEVELOPMENT.md](DEVELOPMENT.md) for the full dev workflow.
+### 🎛️ What it changed
 
-## Environment Variables
+Every edit is drawn **before → after**: new in blue, old dashed or ghosted, removed struck through.
 
-| Variable               | Description                        | Default              |
-| ---------------------- | ---------------------------------- | -------------------- |
-| `REAPER_RESOURCE_PATH` | Override REAPER resource directory | Auto-detected per OS |
+<table>
+<tr>
+<td width="50%" valign="top">
 
-Platform defaults:
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/mixer.png" alt="The mixer view: every track as a fader with its level in dB, pan, and mute, solo and arm badges, grouped by folder." width="100%">
 
-- **macOS**: `~/Library/Application Support/REAPER`
-- **Windows**: `%APPDATA%/REAPER`
-- **Linux**: `~/.config/REAPER`
+**Mixer**<br><sub>The session as a mixer: folders, levels, pans, mute, solo and arm.</sub>
 
-## Project Structure
+</td>
+<td width="50%" valign="top">
 
-```
-reaper-mcp/
-├── apps/
-│   ├── reaper-mcp-server/        # MCP server (80 tools, esbuild bundle)
-│   └── reaper-mix-agent/         # AI mix agent (knowledge loader, plugin resolver)
-├── libs/protocol/                # Shared TypeScript types
-├── knowledge/                    # AI mix engineer knowledge base
-│   ├── plugins/                  # Plugin-specific knowledge (extensible)
-│   ├── genres/                   # Genre mixing conventions
-│   ├── workflows/                # Step-by-step mixing workflows
-│   └── reference/                # Frequency, compression, metering, perceived loudness cheat sheets
-├── reaper/                       # Files installed into REAPER
-│   ├── mcp_bridge.lua            # Persistent Lua bridge
-│   ├── mcp_snapshot_manager.lua  # Snapshot manager GUI (save/restore/delete)
-│   ├── mcp_snapshot_*.lua        # Snapshot action scripts (next/prev/quick-save + shared lib)
-│   ├── mcp_analyzer.jsfx         # FFT spectrum analyzer
-│   ├── mcp_lufs_meter.jsfx       # LUFS meter (BS.1770)
-│   ├── mcp_correlation_meter.jsfx # Stereo correlation meter
-│   └── mcp_crest_factor.jsfx     # Crest factor meter
-├── docs/TESTING.md               # End-to-end testing guide
-└── nx.json                       # Nx workspace config
-```
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/routing.png" alt="The routing view: a signal-flow diagram of a track's sends, receives and hardware outputs, with added, changed and removed routes marked." width="100%">
 
-## Updating the Lua Bridge
+**Routing**<br><sub>Sends, receives and outputs as signal flow. Thicker wire means louder.</sub>
 
-The MCP server (TypeScript) and the Lua bridge (REAPER) are two separate components. After updating to a new version — or after adding new tools during development — you need to reinstall the bridge files and reload the script in REAPER:
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
 
-```bash
-# Reinstall bridge files into REAPER
-npx @mthines/reaper-mcp setup
-```
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/automation.png" alt="The automation view: a volume envelope with pooled automation items drawn as blocks tinted by pool." width="100%">
 
-Then in REAPER:
+**Automation**<br><sub>Envelope points and pooled automation items, before and after.</sub>
 
-1. **Stop** the running bridge: Actions > Running Scripts > stop `mcp_bridge.lua`
-2. **Reload** the updated script: Actions > Load ReaScript > select `mcp_bridge.lua` > Run
+</td>
+<td width="50%" valign="top">
 
-If existing tools (like `get_project_info`) work but new tools fail or timeout, this is almost always because the Lua bridge needs to be updated and reloaded.
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/piano-roll.png" alt="The piano roll view: added notes in blue, unchanged notes in grey, removed notes dashed, and a velocity lane." width="100%">
 
-## Development
+**Piano roll**<br><sub>MIDI edits as a piano roll: added, kept and removed notes, with velocity.</sub>
 
-```bash
-pnpm install
-pnpm nx run-many --target=build      # Build all
-pnpm nx run-many --target=lint       # Lint all
-pnpm nx run-many --target=test       # Test all (200+ tests)
-pnpm nx run-many --target=build,lint,test  # Everything
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/pins.png" alt="The plugin pins view: track channels wired into a compressor's input pins, with a newly connected sidechain highlighted." width="100%">
+
+**Plugin pins**<br><sub>Which track channels feed which plugin pins. Here, a sidechain just got wired in.</sub>
+
+</td>
+<td width="50%" valign="top">
+
+<img src="https://raw.githubusercontent.com/mthines/reaper-mcp/v0.70.3-beta.86.1/docs/assets/views/render.png" alt="The render view: three rendered versions of a song with a waveform, LUFS, peak and length for each, against a loudness target." width="100%">
+
+**Renders**<br><sub>Every rendered file with its LUFS, peak and length against your target.</sub>
+
+</td>
+</tr>
+</table>
+
+<sub>Illustrative data, drawn by the same components the bridge window uses. There's a view for nearly every tool
+that reads or writes your session.</sub>
+
+---
+
+## 🔒 Privacy & telemetry
+
+Hi 👋 reaper-mcp isn't a company — it's just me. I'm a developer who loves making music,
+and I build this in my spare time because it's the tool I wanted for my own sessions 🎛️
+
+The catch: I can only test it on my own setup. To make sure it also works on yours —
+other REAPER versions, other plugins, other OSes — reaper-mcp sends **pseudonymous usage
+data** by default: which tools run, whether they fail, and how long they take. A random
+install id groups one machine's calls together. It isn't tied to your name, account or
+computer.
+
+**Never sent:** your projects, track or plugin names, settings, file paths, error
+messages, audio or MIDI. I respect your privacy 🙏
+
+You're in control: setup asks before anything is sent, and `reaper-mcp telemetry off`
+turns it off for good — no hard feelings. Everything that's collected, and where it
+goes, is in [TELEMETRY.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/TELEMETRY.md).
+
+---
+
+## ❓ FAQ
+
+<details>
+<summary><b>Do I need to know how to code?</b></summary>
+<br>
+No. You paste one command to install. After that you type in plain words, the way you
+would say it to an engineer.
+</details>
+
+<details>
+<summary><b>Is this voice control?</b></summary>
+<br>
+No. You type to it in Claude Code, like any chat. "Talking" means plain language, not
+a microphone. Nothing listens to you. If you'd rather speak, use your OS dictation or a
+voice-to-text tool; the agent just sees the text.
+</details>
+
+<details>
+<summary><b>Will it replace me?</b></summary>
+<br>
+No. It handles the tedious, measurable parts: gain staging, cleaning up clashing
+frequencies, hitting loudness targets. Taste and the final call stay with you, and it
+explains its reasoning so you can push back.
+</details>
+
+<details>
+<summary><b>Can it wreck my project?</b></summary>
+<br>
+Every edit is a single undo step, and the mix skills snapshot before and after a task. Use
+<code>/critique</code> or read-only mode if you only want advice. Saving a copy of your project
+before a big session never hurts. <a href="https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/SAFETY.md">What is and isn't guarded</a>.
+</details>
+
+<details>
+<summary><b>Which plugins does it work with?</b></summary>
+<br>
+Any plugin REAPER can load (VST, VST3, AU, CLAP, JS). It finds what you have installed
+and reaches for the best tool for each job. The ones it already knows are in the
+<a href="https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/PLUGINS.md">built-in plugin list</a>. When it meets a plugin it doesn't know, it
+researches it, inspects its controls live and saves what it learns to LoreKit. You can
+also teach it one up front with <code>/learn-plugin</code>.
+</details>
+
+<details>
+<summary><b>It doesn't support my plugin's patches, wavetables or presets. Now what?</b></summary>
+<br>
+Host parameters already work for any plugin. For anything deeper, build an
+<a href="#-extensions-teach-it-your-plugin">extension</a>: run <code>/new-extension YourPlugin</code> and
+Claude researches the format, writes the tools and tests, and proves them on a scratch track. Today there are
+extensions for Vital and Line 6 Helix.
+</details>
+
+<details>
+<summary><b>What does it cost?</b></summary>
+<br>
+reaper-mcp is free and open source (MIT), and so is LoreKit. You need REAPER and a
+Claude plan that includes Claude Code.
+</details>
+
+<details>
+<summary><b>Do my audio files get uploaded?</b></summary>
+<br>
+No. It reads meter values and settings from your running session, not your audio files.
+</details>
+
+---
+
+## 🛠️ For developers
+
+- 📖 **[docs/REFERENCE.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/REFERENCE.md)**: architecture, install internals, CLI,
+  environment variables, telemetry, project structure
+- 🧰 **[docs/TOOLS.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/TOOLS.md)**: the main tools by area
+- 🧩 **[docs/EXTENSIONS.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/EXTENSIONS.md)**: write, test and share an extension (the API, Lua handlers, Vital and Helix)
+- 🧑‍💻 **[DEVELOPMENT.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/DEVELOPMENT.md)**: build, test, run from source, MCP Inspector
+- 🧪 **[docs/TESTING.md](https://github.com/mthines/reaper-mcp/blob/v0.70.3-beta.86.1/docs/TESTING.md)**: end-to-end testing guide
+
+```
+Claude Code ⇄ MCP server (TypeScript) ⇄ file IPC ⇄ Lua bridge in REAPER ⇄ ReaScript API + JSFX meters
 ```
 
-See [DEVELOPMENT.md](DEVELOPMENT.md) for the full dev workflow including running from source, MCP Inspector, and bridge update details.
+<div align="center">
+
+<br>
+
+**Made for people who'd rather be making music.** 🎶
 
-## License
+MIT License
 
-MIT
+</div>