Update CLAUDE.md — reflect Sprint 2 complete, fix API notes, update status

CLAUDE.md

@@ -7,14 +7,22 @@ A JUCE-based VST3/AU plugin that:
 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
 
+## Current Status
+- **Sprint 1:** ✅ Done — plugin shell + MCP server responding
+- **Sprint 2:** ✅ Done — hosts Pro-Q 4 (737 params), routes audio, MCP tools wired
+- **Sprint 3:** Next — full MCP client integration test from Claude Code
+- **Sprint 4:** Pending — real-time audio analysis
+
 ## Project Decisions (Confirmed)
 - **Platform:** macOS only (for now)
-- **License:** GPL (JUCE GPL mode — no commercial license needed)
+- **License:** GPL (JUCE GPL mode — no commercial license needed, doesn't hamper project)
 - **VST3 install path:** `~/Library/Audio/Plug-Ins/VST3/`
 - **AU install path:** `~/Library/Audio/Plug-Ins/Components/`
-- **Test plugins:** FabFilter Pro-Q 4 (EQ, many params), LA-2A compressor (fewer params)
-- **Xcode:** 14+ required (user should verify with `xcode-select --version`)
+- **Test plugins:** FabFilter Pro-Q 4 (EQ, 737 params), LA-2A compressor (fewer params)
+- **Xcode:** CLI tools 2410+ (no full Xcode.app needed)
+- **CMake:** 3.28 via pip (system CMake 4.x incompatible with JUCE 8)
 - **DAW:** Ableton Live (primary), Logic Pro (secondary AU test)
+- **Build generator:** Unix Makefiles or Ninja (NOT Xcode generator — no Xcode.app)
 
 ## Architecture (Single Plugin Host, Not a Graph)
 ```
@@ -23,39 +31,49 @@ PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
   ├── 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
+        buffer → hostManager.processBlock(buffer, midi)
+               → output (audio routed through hosted plugin)
 ```
 
 ## 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)
+- **LUFSMeter** — 4 files in `Source/LufsMeter/` (MIT, from klangfreund/LUFSMeter) — Sprint 4
 - **Target formats:** VST3 + AU (macOS only)
-- **Build:** `mkdir build && cd build && cmake .. && cmake --build .`
-- **Install:** `COPY_PLUGIN_AFTER_BUILD=TRUE` in CMake copies to system plugin dirs
+- **Build:** `cd build && cmake .. -DCMAKE_C_COMPILER=/usr/bin/cc -DCMAKE_CXX_COMPILER=/usr/bin/c++ && cmake --build . --config Release`
+- **Install:** `COPY_PLUGIN_AFTER_BUILD=TRUE` copies to `~/Library/Audio/Plug-Ins/VST3/`
 
 ## MCP Protocol
 - Transport: Streamable HTTP (NOT stdio — we're inside a DAW process)
 - Endpoint: `POST http://127.0.0.1:16620/mcp`
+- Health check: `GET http://127.0.0.1:16620/health`
 - 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`
-- Session: Server returns `Mcp-Session-Id` header on init, client echoes it back
-- Security: bind 127.0.0.1 only, validate Origin header
+- 5 tools: `list_plugins`, `search_param`, `get_params`, `set_params`, `get_analysis`
 
-## Key JUCE APIs (Correct, Verified Against JUCE 8 Source)
-- `addDefaultFormatsToManager(formatManager)` — NOT deprecated `addDefaultFormats()`
-- `formatManager.createPluginInstanceAsync(desc, sr, bs, callback)` — ALWAYS async (AU requires it)
+## Key JUCE 8 APIs (Verified — these WORK)
+- `formatManager.addFormat(new juce::VST3PluginFormat())` — explicit registration
+- `formatManager.addFormat(new juce::AudioUnitPluginFormat())` — explicit registration
 - `instance->enableAllBuses()` — MUST call before using
 - `plugin->getParameters()` → `Array<AudioProcessorParameter*>`
-- Cast to `AudioPluginInstance::HostedParameter*` for `getParameterID()` (stable string ID)
-- `param->beginChangeGesture()` / `setValueNotifyingHost(val)` / `endChangeGesture()` — for DAW automation
-- `juce::dsp::FFT` for spectral analysis (NOT KissFFT, NOT Gist — those are GPL)
-- `juce::dsp::Oversampling<float>` for True Peak measurement (4× oversample)
-- `juce::dsp::WindowingFunction<float>::hann` for FFT windowing
+- Cast to `juce::AudioPluginInstance::HostedParameter*` for `getParameterID()`
+- `param->beginChangeGesture()` / `setValueNotifyingHost(val)` / `endChangeGesture()`
+- `juce::dsp::FFT` for spectral analysis
+- `juce::PluginDirectoryScanner` for system plugin scan
+- `juce::KnownPluginList` for storing scan results
+
+## Key JUCE 8 APIs (BROKEN — do NOT use)
+- ❌ `addDefaultFormats()` — deleted in JUCE 8, use explicit addFormat() calls
+- ❌ `addDefaultFormatsToManager()` — also deleted
+- ❌ `getParameter(int)` / `setParameter(int, float)` — deprecated, asserts
+
+## Plugin Discovery UX
+- Click "Select Plugin..." button → first click triggers background scan
+- Button shows "Scanning..." while scanning (background thread, non-blocking)
+- After scan: popup menu grouped by manufacturer → plugin name
+- Subsequent clicks: instant menu (cached scan results)
+- NO file browser — clean DAW-style UX
 
 ## Design Laws (Non-Negotiable)
 - Never return all parameters — search first, fetch by ID
@@ -67,58 +85,35 @@ PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
 
 ## 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
-- Cap httplib thread pool to 2-4 threads (reduce OS pressure in plugin host)
+- Plugin scan runs in background thread — NOT message thread (crashes DAW otherwise)
+- Use `CriticalSection` / `ScopedLock` for plugin hot-swap in processBlock
+- Cap httplib thread pool to 2 threads
 - `httplib::Server` lifecycle: constructor starts thread, destructor calls stop()+join()
 
-## Sprint Order
-1. **Sprint 1**: Empty plugin shell + httplib server responding to curl ← START HERE
-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 conflict (we're already GPL but want MIT deps)
+- Don't scan plugins on editor open — scan only on button click, in background thread
+- Don't use `addDefaultFormats()` — deleted in JUCE 8
 - Don't use stdio MCP transport — plugin is inside DAW, not a subprocess
-- Don't use `getParameter(int)` / `setParameter(int, float)` — deprecated, asserts in debug
 - Don't target Windows yet — macOS only for now
-- Don't scan system plugins on load — use file picker for explicit selection
-
-## First Steps for Claude Code
-1. Run `xcode-select --version` to verify Xcode 14+
-2. Run `cmake --version` to verify CMake 3.22+
-3. Clone JUCE 8 as submodule: `git submodule add https://github.com/juce-framework/JUCE.git`
-4. Download `httplib.h` from yhirose/cpp-httplib into `libs/`
-5. Download `json.hpp` from nlohmann/json into `libs/`
-6. Create CMakeLists.txt (see ROADMAP.md for skeleton)
-7. Create Source/ files (empty stubs first)
-8. Build: `mkdir build && cd build && cmake .. -G Xcode && cmake --build . --config Release`
-9. Verify plugin appears in `~/Library/Audio/Plug-Ins/VST3/`
-10. Load in Ableton → verify audio passthrough
-11. Verify `curl -X POST http://localhost:16620/mcp -d '{}'` gets a response
 
 ## Repo Structure
 ```
 pluginbridge/
-├── CLAUDE.md              ← this file (Claude Code reads automatically)
-├── ROADMAP.md             ← full technical roadmap with code samples
-├── CMakeLists.txt
+├── CLAUDE.md              ← this file
+├── ROADMAP.md             ← full technical roadmap
+├── SYNC.md               ← coordination between HF Claude and Claude Code
+├── CMakeLists.txt         ← JUCE 8 CMake (LANGUAGES C CXX)
+├── .gitignore
 ├── JUCE/                  ← git submodule
 ├── libs/
-│   ├── httplib.h          ← cpp-httplib (yhirose/cpp-httplib)
+│   ├── README.md          ← download instructions
+│   ├── httplib.h          ← cpp-httplib
 │   └── json.hpp           ← nlohmann/json
 └── Source/
-    ├── PluginBridgeProcessor.h/.cpp
-    ├── PluginBridgeEditor.h/.cpp
-    ├── HostedPluginManager.h/.cpp
-    ├── McpServer.h/.cpp
-    ├── AudioAnalyser.h/.cpp
-    └── LufsMeter/
-        ├── Ebu128LoudnessMeter.h/.cpp
-        └── SecondOrderIIRFilter.h/.cpp
+    ├── PluginBridgeProcessor.h/.cpp  ← main AudioProcessor, owns HostedPluginManager + McpServer
+    ├── PluginBridgeEditor.h/.cpp     ← GUI: status + plugin selector popup menu
+    ├── HostedPluginManager.h/.cpp    ← loads VST3/AU, enumerates params, routes audio
+    ├── McpServer.h/.cpp              ← HTTP server, JSON-RPC dispatch, 5 tools
+    └── AudioAnalyser.h/.cpp          ← stub (Sprint 4)
 ```