Add CLAUDE.md context file for Claude Code

CLAUDE.md

@@ -0,0 +1,100 @@
+# PluginBridge — Claude Code Context
+
+## What This Is
+A JUCE-based VST3/AU plugin that:
+1. Hosts any third-party VST3/AU plugin inside itself (audio passes through)
+2. Exposes ALL hosted plugin parameters via a local MCP server (port 16620)
+3. Provides real-time audio analysis (LUFS, FFT bands, stereo width)
+4. Any AI that speaks MCP (Claude Code, Codex CLI, Gemini CLI) can control any plugin
+
+## Architecture (Single Plugin Host, Not a Graph)
+```
+PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
+  ├── HostedPluginManager     → loads ONE inner VST3/AU, enumerates params
+  ├── McpServer (httplib)     → JSON-RPC 2.0 on http://127.0.0.1:16620/mcp
+  ├── AudioAnalyser           → LUFS + 7-band FFT + stereo width in processBlock
+  └── processBlock():
+        buffer → analyser.process(buffer)
+               → hostedPlugin->processBlock(buffer, midi)
+               → output
+```
+
+## Build System
+- **JUCE 8** via CMake (git submodule at `/JUCE`)
+- **cpp-httplib** — single header `libs/httplib.h` (MIT)
+- **nlohmann/json** — single header `libs/json.hpp` (MIT)
+- **LUFSMeter** — 4 files in `Source/LufsMeter/` (MIT, from klangfreund/LUFSMeter)
+- Targets: VST3 + AU, macOS (Xcode) + Windows (MSVC)
+
+## MCP Protocol
+- Transport: Streamable HTTP (NOT stdio — we're inside a DAW process)
+- Endpoint: `POST http://127.0.0.1:16620/mcp`
+- Wire format: JSON-RPC 2.0
+- Handshake: `initialize` → `notifications/initialized` → then tools/list, tools/call
+- 5 tools only: `list_plugins`, `search_param`, `get_params`, `set_params`, `get_analysis`
+
+## Key JUCE APIs (Correct, Verified)
+- `addDefaultFormatsToManager(formatManager)` — NOT deprecated `addDefaultFormats()`
+- `formatManager.createPluginInstanceAsync(desc, sr, bs, callback)` — ALWAYS async
+- `instance->enableAllBuses()` — MUST call before using
+- `plugin->getParameters()` → `Array<AudioProcessorParameter*>`
+- Cast to `AudioPluginInstance::HostedParameter*` for `getParameterID()` (stable ID)
+- `param->beginChangeGesture()` / `setValueNotifyingHost(val)` / `endChangeGesture()`
+- `juce::dsp::FFT` for spectral analysis (NOT KissFFT, NOT Gist — those are GPL)
+
+## Design Laws
+- Never return all parameters — search first, fetch by ID
+- Delta only after param changes
+- Single-line compact responses (numbers only)
+- Batch operations (set 10 params in one call)
+- Silence detection (no analysis if RMS < -60dB)
+- Target: <2,000 tokens per full mixing session
+
+## Thread Safety Rules
+- HTTP handlers run on httplib's thread pool — NOT audio thread
+- Use `std::atomic<float>` for analysis values queried by HTTP
+- Use `CriticalSection` / `ScopedLock` for plugin hot-swap
+- Never call `getValue()` directly from HTTP thread — read from atomic cache
+- `httplib::Server` lifecycle: constructor starts thread, destructor calls stop()+join()
+
+## Sprint Order
+1. **Sprint 1**: Empty plugin shell + httplib server responding to curl
+2. **Sprint 2**: Host Pro-Q 4, route audio, enumerate params
+3. **Sprint 3**: MCP JSON-RPC dispatch, all 5 tools working from Claude Code
+4. **Sprint 4**: Audio analysis (LUFS, FFT bands, stereo, True Peak)
+
+## What NOT To Do
+- Don't use `AudioProcessorGraph` — we host ONE plugin, not a graph
+- Don't use `AudioPluginHost`'s settings file — use runtime file picker
+- Don't fork `getdunne/juce-plugin-wrapper` — dead, GPL, JUCE 6
+- Don't use Gist or Sound-Analyser code — GPL license
+- Don't use stdio MCP transport — plugin is inside DAW, not a subprocess
+- Don't use `getParameter(int)` / `setParameter(int, float)` — deprecated, asserts
+
+## Questions Before Building (Ask Adi)
+1. macOS only for now, or Windows too? (affects CMake targets + code signing)
+2. Do you have a JUCE license, or are we building under GPL for now?
+3. Where on your Mac should the built .vst3 be installed? (default: ~/Library/Audio/Plug-Ins/VST3/)
+4. Which plugin should we test with first? (Pro-Q 4 assumed — confirm)
+5. Your Xcode version? (need 14+ for JUCE 8)
+
+## Repo Structure
+```
+pluginbridge/
+├── CLAUDE.md              ← this file (Claude Code reads automatically)
+├── ROADMAP.md             ← full technical roadmap with code samples
+├── CMakeLists.txt         ← (to be created)
+├── JUCE/                  ← git submodule (to be added locally)
+├── libs/
+│   ├── httplib.h
+│   └── json.hpp
+└── Source/
+    ├── PluginBridgeProcessor.h/.cpp
+    ├── PluginBridgeEditor.h/.cpp
+    ├── HostedPluginManager.h/.cpp
+    ├── McpServer.h/.cpp
+    ├── AudioAnalyser.h/.cpp
+    └── LufsMeter/
+        ├── Ebu128LoudnessMeter.h/.cpp
+        └── SecondOrderIIRFilter.h/.cpp
+```