add MACHINE-CONTEXT.md — template for Claude Code to fill before I write code

MACHINE-CONTEXT.md

@@ -0,0 +1,117 @@
+# Machine Context — Fill This Before Remote Coding
+> ML Intern (HuggingFace) writes code but CANNOT run it.
+> Claude Code (local) CAN run code but follows this file for coordination.
+>
+> **RULE:** Before ML Intern writes any platform-specific code,
+> Claude Code fills this file and pushes it. ML Intern reads it first.
+
+---
+
+## SYSTEM INFO (Claude Code: fill once, update when OS/Xcode changes)
+
+```bash
+# Run these and paste output below:
+sw_vers
+xcodebuild -version
+xcrun --show-sdk-version
+uname -m
+sysctl -n machdep.cpu.brand_string
+system_profiler SPMemoryDataType | head -5
+```
+
+**macOS version:**  
+**Xcode version:**  
+**SDK version:**  
+**Architecture:**  
+**CPU:**  
+**RAM:**  
+
+---
+
+## CURRENT BUILD STATE (Claude Code: update after every build)
+
+**Last build:** [timestamp]  
+**Result:** ✅ or ❌  
+**Errors (if any):**  
+
+---
+
+## RUNTIME STATE (Claude Code: update after every test)
+
+**What happens when plugin loads:**  
+**What user sees:**  
+**Ableton log (relevant lines):**  
+```
+[paste grep output here]
+```
+
+**Helper process running:** yes/no  
+**Helper PID:**  
+
+---
+
+## API VERIFICATION (Claude Code: test before ML Intern uses any API)
+
+When ML Intern says "I want to use [API X]", Claude Code:
+1. Write a minimal test (5-10 lines)
+2. Compile and run it
+3. Report: works / doesn't work / crashes
+
+### Verified APIs:
+| API | Works? | Notes |
+|---|---|---|
+| `CAContext contextWithCGSConnection:options:` | | |
+| `CALayerHost` | | |
+| `CGSMainConnectionID()` | | |
+| `NSMachBootstrapServer registerPort:name:` | | |
+| `CARemoteLayerServer sharedServer` | | |
+| `posix_spawn` | | |
+| `shm_open` / `mmap` | | |
+| `sem_open` | | |
+
+---
+
+## ABLETON LOG COMMANDS (Claude Code: run when asked)
+
+```bash
+# Full plugin bridge log
+grep -i "pluginbridge\|helper\|contextId\|CALayerHost\|gui_ready\|layer\|GUI\|loaded\|crashed" \
+  ~/Library/Preferences/Ableton/Live\ 12.4/Log.txt | tail -30
+
+# Helper process check  
+ps aux | grep PluginBridgeHelper
+
+# Blocklist content
+cat ~/Library/PluginBridge/blocklist.txt 2>/dev/null || echo "(empty)"
+
+# Find helper binary
+find ~/Library/Audio/Plug-Ins/VST3/PluginBridge.vst3 -name "PluginBridgeHelper" -type f
+
+# Test helper manually
+~/Library/Audio/Plug-Ins/VST3/PluginBridge.vst3/Contents/Resources/PluginBridgeHelper.app/Contents/MacOS/PluginBridgeHelper --test "/Library/Audio/Plug-Ins/VST3/FabFilter Pro-Q 4.vst3"; echo "EXIT: $?"
+```
+
+---
+
+## WORKFLOW
+
+```
+1. ML Intern wants to write code using [API/approach]
+2. ML Intern asks: "Claude Code — verify [API] works. Fill MACHINE-CONTEXT.md"
+3. Claude Code: writes test, runs it, fills this file, pushes to HF repo
+4. ML Intern: reads this file, writes code KNOWING it works on the target machine
+5. ML Intern: pushes code to HF repo
+6. Claude Code: pulls, builds, tests, updates this file with results
+7. Repeat until working
+```
+
+---
+
+## NOTES FOR ML INTERN
+
+- **Never assume an API works** — always ask Claude Code to verify first
+- **Never use deprecated macOS APIs** without Claude Code confirming they still function
+- **Always check Ableton log** after runtime test — silent failures are common
+- **ObjC++ (.mm) files** — only use if Claude Code confirms the ObjC API is available in current SDK
+- **Window management on macOS** — always ask Claude Code to test the specific approach (fullscreen is tricky)
+- **JUCE version matters** — APIs change between JUCE 7 and 8. Claude Code can check `JUCE/modules/` headers