@mthines/reaper-mcp 0.7.0 → 0.8.0

package/README.md

@@ -17,8 +17,7 @@ npx @mthines/reaper-mcp setup
 
 # 2. In REAPER: Actions > Load ReaScript > select mcp_bridge.lua > Run
 
-# 3. Install AI mix knowledge in your project
-cd your-project
+# 3. Install AI mix knowledge (globally by default, or --project for local)
 npx @mthines/reaper-mcp install-skills
 
 # 4. Open Claude Code — you're ready to mix
@@ -94,19 +93,27 @@ This copies into your REAPER resource folder:
 
 You should see in REAPER's console: `MCP Bridge: Started`
 
-### Step 3: Install AI mix knowledge in your project
+### Step 3: Install AI mix knowledge
 
 ```bash
-cd your-music-project
+# Install globally (default) — available from any directory
 npx @mthines/reaper-mcp install-skills
+
+# Or install into a specific project
+cd your-music-project
+npx @mthines/reaper-mcp install-skills --project
 ```
 
-This creates in your project:
+**Global install** (`--global`, default) installs to `~/.claude/`:
+
+- `~/.claude/agents/` — mix engineer subagents (`@mix-engineer`, `@gain-stage`, `@mix-analyzer`, `@master`)
+- `~/.claude/rules/` — architecture and development rules
+- `~/.claude/skills/` — skills like `/learn-plugin`
+- `~/.claude/knowledge/` — plugin knowledge, genre rules, workflows, reference data
+
+**Project install** (`--project`) installs to your current directory:
 
-- `.claude/agents/` — mix engineer subagents (`@mix-engineer`, `@gain-stage`, `@mix-analyzer`, `@master`)
-- `.claude/rules/` — architecture and development rules
-- `.claude/skills/` — skills like `/learn-plugin`
-- `knowledge/` — plugin knowledge, genre rules, workflows, reference data
+- `.claude/agents/`, `.claude/rules/`, `.claude/skills/`, `knowledge/` — same as above, scoped to the project
 - `.mcp.json` — MCP server configuration for Claude Code
 
 ### Step 4: Verify
@@ -238,7 +245,7 @@ Checks that the bridge is connected, knowledge is installed, and MCP config exis
 
 ## Using the Mix Agents
 
-Once you've run `setup` and `install-skills`, open Claude Code in your project directory. Four specialized mix agents are available:
+Once you've run `setup` and `install-skills`, open Claude Code. Four specialized mix agents are available:
 
 ### Available Agents
 
@@ -440,7 +447,8 @@ The format is `mcp__reaper__{tool_name}`. Once added, Claude Code will run these
 npx @mthines/reaper-mcp                  # Start MCP server (default)
 npx @mthines/reaper-mcp serve            # Start MCP server (stdio mode)
 npx @mthines/reaper-mcp setup            # Install Lua bridge + JSFX into REAPER
-npx @mthines/reaper-mcp install-skills   # Install AI knowledge + agents into your project
+npx @mthines/reaper-mcp install-skills   # Install AI knowledge + agents (globally by default)
+npx @mthines/reaper-mcp install-skills --project  # Install into current project directory
 npx @mthines/reaper-mcp doctor           # Verify everything is configured
 npx @mthines/reaper-mcp status           # Check bridge connection
 ```
@@ -454,7 +462,7 @@ reaper-mcp setup
 
 ## Claude Code Integration
 
-After `install-skills`, your project has a `.mcp.json`:
+After `install-skills --project`, your project has a `.mcp.json`:
 
 ```json
 {

package/knowledge/CLAUDE.md

@@ -0,0 +1,71 @@
+# Knowledge Base
+
+Audio engineering knowledge consumed by `reaper-mix-agent` at runtime. Markdown files with YAML frontmatter.
+
+## File Organization
+
+```
+knowledge/
+  plugins/{vendor-slug}/{plugin-slug}.md   # Plugin knowledge (fx_match, parameters, presets)
+  genres/{genre-id}.md                      # Genre mixing conventions (targets, EQ, compression)
+  workflows/{workflow-id}.md                # Step-by-step mixing workflows
+  reference/{topic}.md                      # Reference material (frequencies, metering, etc.)
+```
+
+## How Files Are Loaded
+
+`knowledge-loader.ts` in `reaper-mix-agent`:
+- Recursively collects all `.md` files
+- Categorizes by first path segment (`plugins/` → plugin, `genres/` → genre, etc.)
+- Skips files with `_template` in the path
+- Parses frontmatter with a simple line-by-line parser (NOT full YAML)
+
+## Frontmatter Constraints
+
+The parser is simple — respect these limitations:
+- Arrays must be single-line: `fx_match: ["Pro-Q 3", "VST3: FabFilter Pro-Q 3"]`
+- No multi-line values or nested objects
+- `#` in frontmatter is treated as a comment — don't use in values
+- Numbers parse automatically; booleans must be `true`/`false` (lowercase)
+
+## Required Frontmatter by Type
+
+### Plugins
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name |
+| `fx_match` | Yes | Array of strings for case-insensitive substring match against REAPER FX list |
+| `category` | Yes | `eq`, `compressor`, `limiter`, `reverb`, `delay`, `gate`, etc. |
+| `vendor` | Yes | Vendor name |
+| `preference` | Yes | 0-100 score (stock: 30-50, third-party: 70-85, industry-standard: 85-95) |
+| `style` | No | `transparent`, `character`, `vintage`, `modern`, `surgical` |
+| `replaces` | No | Array of stock plugin IDs this replaces |
+
+### Genres
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Genre display name |
+| `id` | Yes | Must match filename (e.g., `rock.md` → `id: rock`) |
+| `lufs_target` | Yes | Array `[-13, -10]` for min/max LUFS |
+| `true_peak` | Yes | dBTP ceiling (e.g., `-1.0`) |
+| `parent` | No | Inherits from parent genre |
+
+### Workflows
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Workflow display name |
+| `id` | Yes | Must match filename |
+
+## fx_match Pattern Guide
+
+Patterns are matched as case-insensitive substrings against REAPER's installed FX names:
+- `"Pro-Q 3"` matches `"VST3: FabFilter Pro-Q 3 (FabFilter)"`, `"AU: Pro-Q 3"`, etc.
+- Include multiple patterns for VST/VST3/AU variants if needed
+- Check REAPER's FX Browser for exact names
+
+## Coupled Code
+
+Changes here may require updates in `apps/reaper-mix-agent/`:
+- New knowledge type → update `typeFromPath()` in `knowledge-loader.ts`
+- New frontmatter fields → update consumers in `agent.ts` or `plugin-resolver.ts`
+- New workflow file → should have a matching mode in `modes/`

package/knowledge/workflows/learn-plugin.md

@@ -0,0 +1,143 @@
+---
+name: Learn Plugin
+id: learn-plugin
+description: Discover an unknown plugin by reading its parameters, researching online, and creating a knowledge file
+---
+
+# 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.
+
+## Prerequisites
+
+- The plugin must be loaded on a track in the current session (so you can read its parameters)
+- You need the track index and FX index of the plugin
+
+## Steps
+
+### Step 1: Read the plugin's parameters
+
+```
+tool: get_fx_parameters
+params:
+  trackIndex: N
+  fxIndex: M
+```
+
+Examine the parameter list carefully. Parameter names are strong clues:
+- **Frequency, Q, Gain, Bandwidth, Slope** → EQ
+- **Threshold, Ratio, Attack, Release, Knee, Makeup** → Compressor
+- **Ceiling, Lookahead, True Peak** → Limiter
+- **Pre-delay, Decay, Damping, Room Size, Diffusion** → Reverb
+- **Time, Feedback, Mix, Sync, Ping-pong** → Delay
+- **Drive, Saturation, Harmonics, Warmth** → Saturator
+- **Range, Hold, Hysteresis** → Gate
+- **Frequency, Sensitivity, Reduction** → De-esser
+- **Amp Model, Cabinet, Gain** → Amp sim
+- **Width, Mid/Side, Rotation** → Stereo imager
+- **Pitch, Formant, Speed, Correction** → Pitch correction
+
+Record the full parameter list with names, current values, and ranges.
+
+### Step 2: Check factory presets
+
+```
+tool: get_fx_preset_list
+params:
+  trackIndex: N
+  fxIndex: M
+```
+
+Preset names often reveal intended use cases and the plugin's character. Look for:
+- Category hints (e.g., "Vocal", "Drum Bus", "Mastering")
+- Character hints (e.g., "Warm", "Transparent", "Aggressive", "Vintage")
+- Genre hints (e.g., "Hip Hop Vocal", "Rock Guitar")
+
+### Step 3: Research the plugin (if still unclear)
+
+If the parameter names and presets don't clearly identify the plugin, do a web search:
+
+```
+Search: "{plugin name}" audio plugin parameters guide
+```
+
+Look for:
+- Official product page (features, description)
+- Manual or parameter reference
+- Professional reviews describing the plugin's character and best use cases
+- Forum discussions about recommended settings
+
+### Step 4: Determine metadata
+
+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) |
+| `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
+
+Create the file at `knowledge/plugins/{vendor-slug}/{plugin-slug}.md` using the template structure:
+
+```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
+
+After writing the file, confirm:
+- `fx_match` patterns 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
+
+## Tips
+
+- When multiple parameters share a prefix (e.g., "Band 1 Frequency", "Band 2 Frequency"), document the pattern once with "Band N" notation
+- Include the normalized value range (0.0-1.0) alongside the human-readable range when the mapping isn't obvious
+- If the plugin has multiple modes or routing options, document each mode separately
+- For channel-strip plugins with multiple sections (EQ + comp + gate), consider documenting under the most prominent category but mention all capabilities

package/main.js

@@ -1456,6 +1456,109 @@ function registerEnvelopeTools(server) {
       return { content: [{ type: "text", text: `Deleted envelope point ${pointIndex}` }] };
     }
   );
+  server.tool(
+    "create_track_envelope",
+    "Create/show an automation envelope on a track. Use envelopeName for built-in envelopes (Volume, Pan, Mute, Width, Trim Volume) or fxIndex+paramIndex for FX parameter envelopes. The envelope is made visible and active.",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeName: z14.string().optional().describe('Built-in envelope name: "Volume", "Pan", "Mute", "Width", "Trim Volume"'),
+      fxIndex: z14.coerce.number().int().min(0).optional().describe("FX chain index (for FX parameter envelopes)"),
+      paramIndex: z14.coerce.number().int().min(0).optional().describe("FX parameter index (required if fxIndex provided)")
+    },
+    async ({ trackIndex, envelopeName, fxIndex, paramIndex }) => {
+      const res = await sendCommand("create_track_envelope", {
+        trackIndex,
+        envelopeName,
+        fxIndex,
+        paramIndex
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "set_envelope_properties",
+    "Set properties (active, visible, armed) on a track envelope. Requires SWS extension for full support.",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeIndex: z14.coerce.number().int().min(0).describe("Zero-based envelope index on the track"),
+      active: z14.boolean().optional().describe("Set envelope active/inactive"),
+      visible: z14.boolean().optional().describe("Set envelope visible/hidden in arrange view"),
+      armed: z14.boolean().optional().describe("Set envelope armed for writing automation")
+    },
+    async ({ trackIndex, envelopeIndex, active, visible, armed }) => {
+      const res = await sendCommand("set_envelope_properties", {
+        trackIndex,
+        envelopeIndex,
+        active,
+        visible,
+        armed
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "clear_envelope",
+    "Delete ALL automation points from an envelope, resetting it to its default state",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeIndex: z14.coerce.number().int().min(0).describe("Zero-based envelope index on the track")
+    },
+    async ({ trackIndex, envelopeIndex }) => {
+      const res = await sendCommand("clear_envelope", { trackIndex, envelopeIndex });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "remove_envelope_points",
+    "Delete automation points in a time range from a track envelope. Use to surgically remove a section of automation.",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeIndex: z14.coerce.number().int().min(0).describe("Zero-based envelope index on the track"),
+      timeStart: z14.coerce.number().describe("Start of time range in seconds (inclusive)"),
+      timeEnd: z14.coerce.number().describe("End of time range in seconds (exclusive)")
+    },
+    async ({ trackIndex, envelopeIndex, timeStart, timeEnd }) => {
+      const res = await sendCommand("remove_envelope_points", {
+        trackIndex,
+        envelopeIndex,
+        timeStart,
+        timeEnd
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "insert_envelope_points",
+    "Batch insert multiple automation points on a track envelope. Much faster than repeated insert_envelope_point calls.",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeIndex: z14.coerce.number().int().min(0).describe("Zero-based envelope index on the track"),
+      points: z14.string().describe("JSON array of point objects: [{time, value, shape?, tension?}, ...]")
+    },
+    async ({ trackIndex, envelopeIndex, points }) => {
+      const res = await sendCommand("insert_envelope_points", {
+        trackIndex,
+        envelopeIndex,
+        points
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
 }
 
 // apps/reaper-mcp-server/src/server.ts
@@ -1669,7 +1772,12 @@ var MCP_TOOL_NAMES = [
   "get_track_envelopes",
   "get_envelope_points",
   "insert_envelope_point",
-  "delete_envelope_point"
+  "insert_envelope_points",
+  "delete_envelope_point",
+  "create_track_envelope",
+  "set_envelope_properties",
+  "clear_envelope",
+  "remove_envelope_points"
 ];
 function ensureClaudeSettings(settingsPath) {
   const allowList = MCP_TOOL_NAMES.map((t) => `mcp__reaper__${t}`);
@@ -1708,7 +1816,7 @@ async function setup() {
   } else {
     console.log(`  Not found: ${luaSrc}`);
   }
-  const effectsDir = getReaperEffectsPath();
+  const effectsDir = join4(getReaperEffectsPath(), "reaper-mcp");
   mkdirSync2(effectsDir, { recursive: true });
   console.log("\nInstalling JSFX analyzers...");
   for (const jsfx of REAPER_ASSETS) {
@@ -1716,7 +1824,7 @@ async function setup() {
     const src = join4(reaperDir, jsfx);
     const dest = join4(effectsDir, jsfx);
     if (installFile(src, dest)) {
-      console.log(`  Installed: ${jsfx}`);
+      console.log(`  Installed: reaper-mcp/${jsfx}`);
     } else {
       console.log(`  Not found: ${src}`);
     }
@@ -1729,70 +1837,66 @@ async function setup() {
   console.log("  4. Run the script (it will keep running in background via defer loop)");
   console.log("  5. Add reaper-mcp to your Claude Code config (see: npx @mthines/reaper-mcp doctor)");
 }
-async function installSkills() {
-  console.log("REAPER MCP \u2014 Install AI Mix Engineer Skills\n");
-  const targetDir = process.cwd();
-  const globalClaudeDir = join4(homedir2(), ".claude");
+function parseInstallScope(args) {
+  if (args.includes("--project")) return "project";
+  return "global";
+}
+async function installSkills(scope) {
+  console.log(`REAPER MCP \u2014 Install AI Mix Engineer Skills (scope: ${scope})
+`);
+  const isGlobal = scope === "global";
+  const baseDir = isGlobal ? join4(homedir2(), ".claude") : process.cwd();
+  const claudeDir = isGlobal ? baseDir : join4(baseDir, ".claude");
   const knowledgeSrc = resolveAssetDir(__dirname, "knowledge");
-  const knowledgeDest = join4(targetDir, "knowledge");
   if (existsSync2(knowledgeSrc)) {
-    const count = copyDirSync(knowledgeSrc, knowledgeDest);
-    console.log(`Installed knowledge base: ${count} files \u2192 ${knowledgeDest}`);
+    const dest = join4(baseDir, "knowledge");
+    const count = copyDirSync(knowledgeSrc, dest);
+    console.log(`Installed knowledge base: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Knowledge base not found in package. Skipping.");
   }
   const rulesSrc = resolveAssetDir(__dirname, "claude-rules");
-  const rulesDir = join4(targetDir, ".claude", "rules");
   if (existsSync2(rulesSrc)) {
-    const count = copyDirSync(rulesSrc, rulesDir);
-    console.log(`Installed Claude rules: ${count} files \u2192 ${rulesDir}`);
+    const dest = join4(claudeDir, "rules");
+    const count = copyDirSync(rulesSrc, dest);
+    console.log(`Installed Claude rules: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude rules not found in package. Skipping.");
   }
   const skillsSrc = resolveAssetDir(__dirname, "claude-skills");
-  const skillsDir = join4(targetDir, ".claude", "skills");
   if (existsSync2(skillsSrc)) {
-    const count = copyDirSync(skillsSrc, skillsDir);
-    console.log(`Installed Claude skills: ${count} files \u2192 ${skillsDir}`);
+    const dest = join4(claudeDir, "skills");
+    const count = copyDirSync(skillsSrc, dest);
+    console.log(`Installed Claude skills: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude skills not found in package. Skipping.");
   }
   const agentsSrc = resolveAssetDir(__dirname, "claude-agents");
-  const agentsDir = join4(targetDir, ".claude", "agents");
   if (existsSync2(agentsSrc)) {
-    const count = copyDirSync(agentsSrc, agentsDir);
-    console.log(`Installed Claude agents: ${count} files \u2192 ${agentsDir}`);
+    const dest = join4(claudeDir, "agents");
+    const count = copyDirSync(agentsSrc, dest);
+    console.log(`Installed Claude agents: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude agents not found in package. Skipping.");
   }
-  const globalAgentsDir = join4(globalClaudeDir, "agents");
-  if (existsSync2(agentsSrc)) {
-    const count = copyDirSync(agentsSrc, globalAgentsDir);
-    console.log(`Installed Claude agents (global): ${count} files \u2192 ${globalAgentsDir}`);
-  }
-  const localSettingsPath = join4(targetDir, ".claude", "settings.json");
-  const localResult = ensureClaudeSettings(localSettingsPath);
-  if (localResult === "created") {
-    console.log(`Created Claude settings: ${localSettingsPath}`);
-  } else if (localResult === "updated") {
-    console.log(`Updated Claude settings with new REAPER tools: ${localSettingsPath}`);
+  const settingsPath = join4(claudeDir, "settings.json");
+  const result = ensureClaudeSettings(settingsPath);
+  if (result === "created") {
+    console.log(`Created Claude settings: ${settingsPath}`);
+  } else if (result === "updated") {
+    console.log(`Updated Claude settings with new REAPER tools: ${settingsPath}`);
   } else {
-    console.log(`Claude settings already has all REAPER tools: ${localSettingsPath}`);
-  }
-  const globalSettingsPath = join4(globalClaudeDir, "settings.json");
-  const globalResult = ensureClaudeSettings(globalSettingsPath);
-  if (globalResult === "created") {
-    console.log(`Created Claude settings (global): ${globalSettingsPath}`);
-  } else if (globalResult === "updated") {
-    console.log(`Updated Claude settings (global) with new REAPER tools: ${globalSettingsPath}`);
+    console.log(`Claude settings already has all REAPER tools: ${settingsPath}`);
   }
-  const mcpJsonPath = join4(targetDir, ".mcp.json");
-  if (createMcpJson(mcpJsonPath)) {
-    console.log(`
+  if (!isGlobal) {
+    const mcpJsonPath = join4(baseDir, ".mcp.json");
+    if (createMcpJson(mcpJsonPath)) {
+      console.log(`
 Created: ${mcpJsonPath}`);
-  } else {
-    console.log(`
+    } else {
+      console.log(`
 .mcp.json already exists \u2014 add the reaper server config manually if needed.`);
+    }
   }
   console.log("\nDone! Claude Code now has mix engineer agents, knowledge, and REAPER MCP tools.");
   console.log("All 48 REAPER tools are pre-approved \u2014 agents work autonomously.");
@@ -1806,20 +1910,27 @@ async function doctor() {
   if (!bridgeRunning) {
     console.log('  \u2192 Run "npx @mthines/reaper-mcp setup" then load mcp_bridge.lua in REAPER');
   }
-  const agentsExist = existsSync2(join4(process.cwd(), ".claude", "agents"));
-  console.log(`Mix agents:    ${agentsExist ? "\u2713 Found (.claude/agents/)" : "\u2717 Not installed"}`);
+  const globalClaudeDir = join4(homedir2(), ".claude");
+  const localAgents = existsSync2(join4(process.cwd(), ".claude", "agents"));
+  const globalAgents = existsSync2(join4(globalClaudeDir, "agents"));
+  const agentsExist = localAgents || globalAgents;
+  const agentsLocation = localAgents ? ".claude/agents/" : globalAgents ? "~/.claude/agents/" : "";
+  console.log(`Mix agents:    ${agentsExist ? `\u2713 Found (${agentsLocation})` : "\u2717 Not installed"}`);
   if (!agentsExist) {
-    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" in your project directory');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills"');
   }
-  const knowledgeExists = existsSync2(join4(process.cwd(), "knowledge"));
-  console.log(`Knowledge base: ${knowledgeExists ? "\u2713 Found in project" : "\u2717 Not installed"}`);
+  const localKnowledge = existsSync2(join4(process.cwd(), "knowledge"));
+  const globalKnowledge = existsSync2(join4(globalClaudeDir, "knowledge"));
+  const knowledgeExists = localKnowledge || globalKnowledge;
+  const knowledgeLocation = localKnowledge ? "project" : globalKnowledge ? "~/.claude/" : "";
+  console.log(`Knowledge base: ${knowledgeExists ? `\u2713 Found (${knowledgeLocation})` : "\u2717 Not installed"}`);
   if (!knowledgeExists) {
-    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" in your project directory');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills"');
   }
   const mcpJsonExists = existsSync2(join4(process.cwd(), ".mcp.json"));
   console.log(`MCP config:    ${mcpJsonExists ? "\u2713 .mcp.json found" : "\u2717 .mcp.json missing"}`);
   if (!mcpJsonExists) {
-    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" to create .mcp.json');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills --project" to create .mcp.json');
   }
   console.log('\nTo check SWS Extensions, start REAPER and use the "list_available_fx" tool.');
   console.log("SWS provides enhanced plugin discovery and snapshot support.\n");
@@ -1884,7 +1995,7 @@ switch (command) {
     });
     break;
   case "install-skills":
-    installSkills().catch((err) => {
+    installSkills(parseInstallScope(process.argv.slice(3))).catch((err) => {
       console.error("Install failed:", err);
       process.exit(1);
     });
@@ -1917,14 +2028,16 @@ Usage:
   npx @mthines/reaper-mcp                  Start MCP server (stdio mode)
   npx @mthines/reaper-mcp serve            Start MCP server (stdio mode)
   npx @mthines/reaper-mcp setup            Install Lua bridge + JSFX analyzers into REAPER
-  npx @mthines/reaper-mcp install-skills   Install AI mix engineer knowledge + agents into your project
+  npx @mthines/reaper-mcp install-skills   Install AI knowledge + agents globally (default)
+  npx @mthines/reaper-mcp install-skills --project  Install into current project directory
+  npx @mthines/reaper-mcp install-skills --global   Install into ~/.claude/ (default)
   npx @mthines/reaper-mcp doctor           Check that everything is configured correctly
   npx @mthines/reaper-mcp status           Check if Lua bridge is running in REAPER
 
 Quick Start:
   1. npx @mthines/reaper-mcp setup            # install REAPER components
   2. Load mcp_bridge.lua in REAPER (Actions > Load ReaScript > Run)
-  3. npx @mthines/reaper-mcp install-skills   # install AI knowledge + agents
+  3. npx @mthines/reaper-mcp install-skills   # install AI knowledge + agents (globally)
   4. Open Claude Code \u2014 REAPER tools + mix engineer agents are ready
 
 Tip: install globally for shorter commands:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "MCP server for controlling REAPER DAW — real-time mixing, FX control, and frequency analysis for AI agents",
   "license": "MIT",

package/reaper/CLAUDE.md

@@ -0,0 +1,60 @@
+# REAPER Scripts
+
+Files installed INTO the REAPER DAW by the `setup` command. These run inside REAPER's scripting environment.
+
+## Files
+
+| File | Language | Purpose |
+|------|----------|---------|
+| `mcp_bridge.lua` | Lua | Persistent bridge: polls for JSON commands, executes ReaScript API, writes responses |
+| `mcp_analyzer.jsfx` | JSFX/EEL2 | Real-time FFT spectrum analyzer, writes to gmem[] |
+| `mcp_lufs_meter.jsfx` | JSFX/EEL2 | LUFS loudness metering |
+| `mcp_correlation_meter.jsfx` | JSFX/EEL2 | Stereo correlation and width analysis |
+| `mcp_crest_factor.jsfx` | JSFX/EEL2 | Crest factor (peak-to-RMS) measurement |
+| `install.sh` | Shell | Manual install helper |
+
+## Lua Bridge (`mcp_bridge.lua`)
+
+### How It Works
+1. Runs as a persistent `reaper.defer()` loop (polls every ~30ms)
+2. Reads `command_{uuid}.json` from bridge directory
+3. Dispatches to handler function in the `handlers` table
+4. Writes `response_{uuid}.json` with results
+5. Writes `heartbeat.json` every 1s for liveness detection
+
+### Adding a Handler
+```lua
+handlers["command_type"] = function(params)
+  local result = reaper.SomeApiCall(params.paramName)
+  return { field = result }
+end
+```
+
+The command type string must exactly match `CommandType` in `libs/protocol/src/commands.ts`.
+
+### Key Constraints
+- REAPER Lua is sandboxed: **no sockets, no HTTP, no stdin/stdout** — file-based IPC only
+- JSON parsing: uses `CF_Json_Parse` if available (REAPER 7+), falls back to custom Lua parser
+- Track indices are 0-based (same as ReaScript)
+- Volume values: bridge converts between dB (MCP protocol) and linear (ReaScript internally)
+- Always wrap file reads in `pcall` for resilience
+
+## JSFX Meters
+
+- Run in REAPER's **audio thread** (not scripting thread)
+- Communicate with Lua via `gmem[]` shared memory
+- Each JSFX uses a unique gmem namespace (e.g., `MCPAnalyzer`, `MCPLufsMeter`)
+- Must pass audio through unmodified (transparent inserts)
+- Auto-inserted by corresponding MCP tools (`read_track_spectrum`, `read_track_lufs`, etc.)
+
+## Testing
+
+- **No automated tests possible** — REAPER's Lua/JSFX environment cannot be unit tested outside REAPER
+- Test manually: install bridge, run MCP Inspector, exercise commands
+- Server-side tests mock `sendCommand()` in `bridge.ts`
+
+## Installation
+
+Files are copied to `{REAPER_RESOURCE_PATH}/Scripts/` by:
+- `node dist/apps/reaper-mcp-server/main.js setup` (programmatic)
+- `install.sh` (manual)

package/reaper/install.sh

@@ -29,11 +29,15 @@ mkdir -p "$SCRIPTS_DIR"
 cp "$SCRIPT_DIR/mcp_bridge.lua" "$SCRIPTS_DIR/mcp_bridge.lua"
 echo "Installed: $SCRIPTS_DIR/mcp_bridge.lua"
 
-# Install JSFX analyzer
-EFFECTS_DIR="$REAPER_PATH/Effects"
+# Install JSFX analyzers
+EFFECTS_DIR="$REAPER_PATH/Effects/reaper-mcp"
 mkdir -p "$EFFECTS_DIR"
-cp "$SCRIPT_DIR/mcp_analyzer.jsfx" "$EFFECTS_DIR/mcp_analyzer.jsfx"
-echo "Installed: $EFFECTS_DIR/mcp_analyzer.jsfx"
+for jsfx in "$SCRIPT_DIR"/*.jsfx; do
+  [ -f "$jsfx" ] || continue
+  fname="$(basename "$jsfx")"
+  cp "$jsfx" "$EFFECTS_DIR/$fname"
+  echo "Installed: $EFFECTS_DIR/$fname"
+done
 
 # Create bridge data directory
 BRIDGE_DIR="$SCRIPTS_DIR/mcp_bridge_data"

package/reaper/mcp_bridge.lua

@@ -11,7 +11,7 @@
 
 local POLL_INTERVAL = 0.030 -- 30ms between polls
 local HEARTBEAT_INTERVAL = 1.0 -- write heartbeat every 1s
-local MCP_ANALYZER_FX_NAME = "mcp_analyzer" -- JSFX analyzer name
+local MCP_ANALYZER_FX_NAME = "reaper-mcp/mcp_analyzer" -- JSFX analyzer name
 
 -- Determine bridge directory (REAPER resource path / Scripts / mcp_bridge_data)
 local bridge_dir = reaper.GetResourcePath() .. "/Scripts/mcp_bridge_data/"
@@ -1007,9 +1007,9 @@ end
 -- Phase 4: Custom JSFX analyzer handlers
 -- =============================================================================
 
-local MCP_LUFS_METER_FX_NAME        = "mcp_lufs_meter"
-local MCP_CORRELATION_METER_FX_NAME = "mcp_correlation_meter"
-local MCP_CREST_FACTOR_FX_NAME      = "mcp_crest_factor"
+local MCP_LUFS_METER_FX_NAME        = "reaper-mcp/mcp_lufs_meter"
+local MCP_CORRELATION_METER_FX_NAME = "reaper-mcp/mcp_correlation_meter"
+local MCP_CREST_FACTOR_FX_NAME      = "reaper-mcp/mcp_crest_factor"
 
 -- Helper: find or auto-insert a named JSFX on a track.
 -- Returns the FX index (0-based) on success, or nil + error message on failure.
@@ -2396,6 +2396,234 @@ function handlers.delete_envelope_point(params)
   return { success = true, totalPoints = reaper.CountEnvelopePoints(env) }
 end
 
+function handlers.create_track_envelope(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+
+  local env = nil
+  local env_name = nil
+
+  if params.fxIndex ~= nil then
+    -- FX parameter envelope
+    if params.paramIndex == nil then
+      return nil, "paramIndex is required when fxIndex is provided"
+    end
+    local fx_count = reaper.TrackFX_GetNumParms(track)
+    if fx_count == 0 then
+      return nil, "Track " .. params.trackIndex .. " has no FX"
+    end
+    -- create=true to create the envelope if it doesn't exist
+    env = reaper.GetFXEnvelope(track, params.fxIndex, params.paramIndex, true)
+    if not env then
+      return nil, "Failed to create FX parameter envelope (fxIndex=" .. params.fxIndex .. ", paramIndex=" .. params.paramIndex .. ")"
+    end
+    local _, pname = reaper.TrackFX_GetParamName(track, params.fxIndex, params.paramIndex)
+    local _, fname = reaper.TrackFX_GetFXName(track, params.fxIndex)
+    env_name = fname .. " / " .. pname
+  elseif params.envelopeName then
+    -- Built-in envelope: use GetTrackEnvelopeByName + show via state chunk
+    env = reaper.GetTrackEnvelopeByName(track, params.envelopeName)
+    if not env then
+      -- Some envelopes need to be activated first via the track state chunk
+      -- Toggle the envelope visibility via action or chunk editing
+      local env_map = {
+        ["Volume"] = "VOLENV",
+        ["Pan"] = "PANENV",
+        ["Mute"] = "MUTEENV",
+        ["Width"] = "WIDTHENV",
+        ["Trim Volume"] = "VOLENV2",
+      }
+      local chunk_key = env_map[params.envelopeName]
+      if not chunk_key then
+        return nil, "Unknown envelope name: " .. params.envelopeName .. ". Use Volume, Pan, Mute, Width, or Trim Volume"
+      end
+      -- Get track chunk, insert envelope chunk if missing
+      local _, chunk = reaper.GetTrackStateChunk(track, "", false)
+      if not chunk:find(chunk_key) then
+        -- Insert a minimal envelope chunk before the closing >
+        local env_chunk = "\n<" .. chunk_key .. "\nACT 1 -1\nVIS 1 1 1\nLANEHEIGHT 0 0\nARM 0\nDEFSHAPE 0 -1 -1\n>\n"
+        chunk = chunk:gsub("\n>$", env_chunk .. ">")
+        reaper.SetTrackStateChunk(track, chunk, false)
+      else
+        -- Envelope exists in chunk but may be hidden; make it visible
+        chunk = chunk:gsub("(" .. chunk_key .. "[^\n]*\n)ACT 0", "%1ACT 1")
+        chunk = chunk:gsub("(" .. chunk_key .. "[^\n]*\n[^\n]*\n)VIS 0", "%1VIS 1")
+        reaper.SetTrackStateChunk(track, chunk, false)
+      end
+      env = reaper.GetTrackEnvelopeByName(track, params.envelopeName)
+      if not env then
+        return nil, "Failed to create envelope: " .. params.envelopeName
+      end
+    else
+      -- Envelope exists, ensure it's visible and active
+      local _, chunk = reaper.GetEnvelopeStateChunk(env, "", false)
+      chunk = chunk:gsub("ACT 0", "ACT 1")
+      chunk = chunk:gsub("VIS 0", "VIS 1")
+      reaper.SetEnvelopeStateChunk(env, chunk, false)
+    end
+    env_name = params.envelopeName
+  else
+    return nil, "Must provide either envelopeName or fxIndex+paramIndex"
+  end
+
+  -- Find the index of the newly created envelope
+  local env_count = reaper.CountTrackEnvelopes(track)
+  local env_index = -1
+  for i = 0, env_count - 1 do
+    if reaper.GetTrackEnvelope(track, i) == env then
+      env_index = i
+      break
+    end
+  end
+
+  reaper.TrackList_AdjustWindows(false)
+  reaper.UpdateArrange()
+
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = env_index,
+    name = env_name,
+    pointCount = reaper.CountEnvelopePoints(env),
+  }
+end
+
+function handlers.set_envelope_properties(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+
+  if reaper.BR_EnvAlloc then
+    -- SWS extension available: use BR_Env* functions
+    local br_env = reaper.BR_EnvAlloc(env, false)
+    local cur_active, cur_visible, cur_armed = reaper.BR_EnvGetProperties(br_env)
+    local new_active = params.active ~= nil and params.active or cur_active
+    local new_visible = params.visible ~= nil and params.visible or cur_visible
+    local new_armed = params.armed ~= nil and params.armed or cur_armed
+    reaper.BR_EnvSetProperties(br_env, new_active, new_visible, new_armed, false)
+    reaper.BR_EnvFree(br_env, true) -- commit=true
+  else
+    -- Fallback: modify envelope state chunk directly
+    local _, chunk = reaper.GetEnvelopeStateChunk(env, "", false)
+    if params.active ~= nil then
+      local val = params.active and "1" or "0"
+      chunk = chunk:gsub("ACT %d", "ACT " .. val)
+    end
+    if params.visible ~= nil then
+      local val = params.visible and "1" or "0"
+      chunk = chunk:gsub("VIS %d", "VIS " .. val)
+    end
+    if params.armed ~= nil then
+      local val = params.armed and "1" or "0"
+      chunk = chunk:gsub("ARM %d", "ARM " .. val)
+    end
+    reaper.SetEnvelopeStateChunk(env, chunk, false)
+  end
+
+  reaper.TrackList_AdjustWindows(false)
+  reaper.UpdateArrange()
+
+  local _, name = reaper.GetEnvelopeName(env)
+  -- Re-read properties
+  local active, visible, armed = true, true, false
+  if reaper.BR_EnvAlloc then
+    local br_env = reaper.BR_EnvAlloc(env, false)
+    active, visible, armed = reaper.BR_EnvGetProperties(br_env)
+    reaper.BR_EnvFree(br_env, false)
+  end
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    name = name,
+    active = active,
+    visible = visible,
+    armed = armed,
+  }
+end
+
+function handlers.clear_envelope(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+  local prev_count = reaper.CountEnvelopePoints(env)
+  -- Delete all points by using a range from -infinity to +infinity
+  reaper.DeleteEnvelopePointRange(env, -math.huge, math.huge)
+  reaper.Envelope_SortPoints(env)
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    deletedPoints = prev_count,
+    totalPoints = reaper.CountEnvelopePoints(env),
+  }
+end
+
+function handlers.remove_envelope_points(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+  local prev_count = reaper.CountEnvelopePoints(env)
+  reaper.DeleteEnvelopePointRange(env, params.timeStart, params.timeEnd)
+  reaper.Envelope_SortPoints(env)
+  local new_count = reaper.CountEnvelopePoints(env)
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    timeStart = params.timeStart,
+    timeEnd = params.timeEnd,
+    deletedPoints = prev_count - new_count,
+    totalPoints = new_count,
+  }
+end
+
+function handlers.insert_envelope_points(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+
+  -- Parse the points JSON string
+  local points_str = params.points
+  local points = nil
+  if type(points_str) == "string" then
+    points = json_decode(points_str)
+  elseif type(points_str) == "table" then
+    points = points_str
+  end
+  if not points then return nil, "Failed to parse points JSON" end
+
+  local inserted = 0
+  for _, pt in ipairs(points) do
+    if pt.time and pt.value then
+      local shape = pt.shape or 0
+      local tension = pt.tension or 0
+      reaper.InsertEnvelopePoint(env, pt.time, pt.value, shape, tension, false, true)
+      inserted = inserted + 1
+    end
+  end
+
+  reaper.Envelope_SortPoints(env)
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    insertedPoints = inserted,
+    totalPoints = reaper.CountEnvelopePoints(env),
+  }
+end
+
 -- =============================================================================
 -- Command dispatcher
 -- =============================================================================