Add comprehensive documentation and developer onboarding materials

CMakeLists.txt

@@ -1,48 +1,115 @@
 # ==============================================================================
-# Wingman VST3 with WebView2 Integration - PRODUCTION READY
+# Wingman VST3 Plugin - CMake Build Configuration
 # ==============================================================================
-# This CMakeLists includes:
-# - Automatic React UI building
-# - Full WebView2 Integration with DELAYLOAD
-# - Automatic moduleinfo.json fix (prevents detection issues)
-# - Comprehensive post-build verification
+# 
+# PROJECT: Wingman AI Music Production Assistant
+# COMPONENT: VST3 Plugin (JUCE + WebView2)
+# STATUS: Experimental (loads but UI integration incomplete)
+# 
+# This CMakeLists configures:
+#   1. React UI automatic building (from actual ui/vocal-muse-sidecar-main)
+#   2. JUCE audio plugin framework integration
+#   3. WebView2 embedded browser (Windows only)
+#   4. VST3 bundle creation with proper structure
+#   5. Post-build fixes (moduleinfo.json, resource copying)
+# 
+# PLATFORMS:
+#   - Windows: Primary (Visual Studio 2019+, WebView2 SDK required)
+#   - macOS: Partial (Xcode 13+, WebView2 N/A)
+#   - Linux: Untested (GCC 9+/Clang 10+)
+# 
+# BUILD INSTRUCTIONS:
+#   See docs/BUILD_SETUP.md for complete instructions per platform
+# 
+# REQUIREMENTS:
+#   - CMake 3.22+
+#   - Node.js 18+ (for React UI build)
+#   - JUCE 8.0.9+ (submodule)
+#   - [Windows] WebView2 SDK 1.0.2210.55 (via NuGet)
+#   - [Windows] Visual Studio 2019+ with C++ workload
+#   - [macOS] Xcode 13+ with command line tools
+# 
 # ==============================================================================
 
 cmake_minimum_required(VERSION 3.22)
-project(Wingman VERSION 1.0.0)
+project(Wingman VERSION 1.0.0 LANGUAGES CXX)
 
+# ==============================================================================
+# Compiler Configuration
+# ==============================================================================
+
+# Require C++17 for modern features (auto, lambdas, std::optional, etc.)
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
-# Static runtime
+# Use static runtime to avoid DLL dependencies on target systems
+# MultiThreaded (Release) or MultiThreadedDebug (Debug)
 set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
 
-# --- Build React UI ---
+# ==============================================================================
+# React UI Build Step
+# ==============================================================================
+# 
+# The plugin embeds a React-based UI using WebView2 (Windows) or native 
+# web components (macOS/Linux future). This target ensures the UI is built
+# before the plugin compiles.
+# 
+# BUILD PROCESS:
+#   1. npm install - Install dependencies
+#   2. npm run build - Vite builds React app to dist/
+#   3. Post-build copies dist/ to plugin bundle Resources/webui/
+# 
+# OUTPUT: actual ui/vocal-muse-sidecar-main/dist/
+#   - index.html (entry point)
+#   - assets/*.js (bundled JavaScript)
+#   - assets/*.css (bundled styles)
+# 
+# ==============================================================================
+
 set(REACT_UI_DIR "${CMAKE_SOURCE_DIR}/actual ui/vocal-muse-sidecar-main")
 set(REACT_UI_SOURCE_DIR "${REACT_UI_DIR}/dist")
 
 add_custom_target(BuildReactUI ALL
     COMMAND npm install
     COMMAND npm run build
     WORKING_DIRECTORY "${REACT_UI_DIR}"
-    COMMENT "Building React UI with cache verification..."
+    COMMENT "Building React UI from source..."
+    VERBATIM
 )
 
-# =====================================================================================
-# 🚨 WEBVIEW2 SCHEME HANDLER GUARDRAIL - BUILD VERIFICATION
-# =====================================================================================
-# This CMake configuration ensures WEBVIEW2 SCHEME HANDLERs are registered at the correct time.
-#
-# CRITICAL REQUIREMENT: Scheme handlers MUST be registered BEFORE WebView2 initialization()
-# Build Process Order:
-# 1. CMake configures build order
-# 2. WebView2Handler.cpp scheme registration happens BEFORE WebView2 initialization()
-# 3. If this order is violated, the plugin will show "404 resource not found" errors
-#
-# NEVER modify WebView2Handler.cpp to move scheme registration after WebView2 initialization()!
-# =====================================================================================
-
-# JUCE
+# ==============================================================================
+# 🚨 CRITICAL IMPLEMENTATION NOTE - WebView2 Scheme Handler Registration
+# ==============================================================================
+# 
+# PROBLEM:
+#   WebView2 scheme handlers (used to serve local files to the embedded browser)
+#   MUST be registered BEFORE WebView2 initialization. If registered after,
+#   the plugin will show "404 resource not found" errors for all UI files.
+# 
+# SOLUTION:
+#   The build system enforces correct build order:
+#     1. CMake configures dependencies
+#     2. React UI builds (BuildReactUI target)
+#     3. C++ compilation happens (includes WebView2Handler.cpp)
+#     4. WebView2Handler.cpp registers scheme handler in constructor
+#     5. WebView2 initialization happens AFTER handler registration
+# 
+# DO NOT MODIFY:
+#   - Build order dependencies (add_dependencies below)
+#   - WebView2Handler.cpp scheme registration timing
+#   - Initialization sequence in PluginEditor.cpp
+# 
+# IF YOU MODIFY AND BREAK THIS:
+#   Symptom: Plugin loads but shows blank/white screen
+#   Fix: Restore proper initialization order
+#   Debug: Check Ableton Log.txt for "Failed to load resource" errors
+# 
+# This guardrail comment ensures future developers understand the critical
+# dependency between scheme handler registration and WebView2 initialization.
+# 
+# ==============================================================================
+
+# Add JUCE framework (submodule at ./JUCE)
 add_subdirectory(JUCE juce)
 
 # VST3 Plugin Configuration