Update CLAUDE.md with confirmed project decisions

CLAUDE.md

@@ -7,6 +7,15 @@ 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
 
+## Project Decisions (Confirmed)
+- **Platform:** macOS only (for now)
+- **License:** GPL (JUCE GPL mode — no commercial license needed)
+- **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`)
+- **DAW:** Ableton Live (primary), Logic Pro (secondary AU test)
+
 ## Architecture (Single Plugin Host, Not a Graph)
 ```
 PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
@@ -24,7 +33,9 @@ PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
 - **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)
+- **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
 
 ## MCP Protocol
 - Transport: Streamable HTTP (NOT stdio — we're inside a DAW process)
@@ -32,17 +43,21 @@ PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
 - 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
 
-## Key JUCE APIs (Correct, Verified)
+## Key JUCE APIs (Correct, Verified Against JUCE 8 Source)
 - `addDefaultFormatsToManager(formatManager)` — NOT deprecated `addDefaultFormats()`
-- `formatManager.createPluginInstanceAsync(desc, sr, bs, callback)` — ALWAYS async
+- `formatManager.createPluginInstanceAsync(desc, sr, bs, callback)` — ALWAYS async (AU requires it)
 - `instance->enableAllBuses()` — MUST call before using
 - `plugin->getParameters()` → `Array<AudioProcessorParameter*>`
-- Cast to `AudioPluginInstance::HostedParameter*` for `getParameterID()` (stable ID)
-- `param->beginChangeGesture()` / `setValueNotifyingHost(val)` / `endChangeGesture()`
+- 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
 
-## Design Laws
+## Design Laws (Non-Negotiable)
 - Never return all parameters — search first, fetch by ID
 - Delta only after param changes
 - Single-line compact responses (numbers only)
@@ -55,10 +70,11 @@ PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
 - 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)
 - `httplib::Server` lifecycle: constructor starts thread, destructor calls stop()+join()
 
 ## Sprint Order
-1. **Sprint 1**: Empty plugin shell + httplib server responding to curl
+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)
@@ -67,27 +83,35 @@ PluginBridgeProcessor (AudioProcessor — the outer VST3/AU shell)
 - 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 Gist or Sound-Analyser code — GPL license conflict (we're already GPL but want MIT deps)
 - Don't use stdio MCP transport — plugin is inside DAW, not a subprocess
-- Don't use `getParameter(int)` / `setParameter(int, float)` — deprecated, asserts
+- 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
 
-## 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)
+## 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         ← (to be created)
-├── JUCE/                  ← git submodule (to be added locally)
+├── CMakeLists.txt
+├── JUCE/                  ← git submodule
 ├── libs/
-│   ├── httplib.h
-│   └── json.hpp
+│   ├── httplib.h          ← cpp-httplib (yhirose/cpp-httplib)
+│   └── json.hpp           ← nlohmann/json
 └── Source/
     ├── PluginBridgeProcessor.h/.cpp
     ├── PluginBridgeEditor.h/.cpp