refactor: reorganize submodule structure and enhance CMake configuration

- Moved all third-party libraries (SDL, ImGui, Asar, etc.) from `src/lib/` and `third_party/` to a new `ext/` directory for better organization and clarity in dependency management.
- Updated CMake configuration to reflect the new paths, ensuring all targets and includes point to the `ext/` directory.
- Enhanced CMake presets to support new build options for AI and gRPC features, improving modularity and build flexibility.
- Added new feature flags for agent UI and remote automation, allowing for more granular control over build configurations.
- Updated documentation to reflect changes in the project structure and build options, ensuring clarity for contributors and users.

scripts/README.md

@@ -115,3 +115,25 @@ cmake --build build --target build_cleaner
 - Other: `YAZE_AGENT_SOURCES`, `YAZE_TEST_SOURCES`
 
 The script intelligently preserves conditional blocks (if/endif) and excludes conditional files from the main source list.
+
+## verify-build-environment.\*
+
+`verify-build-environment.ps1` (Windows) and `verify-build-environment.sh` (macOS/Linux) are the primary diagnostics for contributors. They now:
+
+- Check for `clang-cl`, Ninja, NASM, Visual Studio workloads, and VS Code (optional).
+- Validate vcpkg bootstrap status plus `vcpkg/installed` cache contents.
+- Warn about missing ROM assets (`zelda3.sfc`, `assets/zelda3.sfc`, etc.).
+- Offer `-FixIssues` and `-CleanCache` switches to repair Git config, resync submodules, and wipe stale build directories.
+
+Run the script once per machine (and rerun after major toolchain updates) to ensure presets such as `win-dbg`, `win-ai`, `mac-ai`, and `ci-windows-ai` have everything they need.
+
+## setup-vcpkg-windows.ps1
+
+Automates the vcpkg bootstrap flow on Windows:
+
+1. Clones and bootstraps vcpkg (if not already present).
+2. Verifies that `git`, `clang-cl`, and Ninja are available, printing friendly instructions when they are missing.
+3. Installs the default triplet (`x64-windows` or `arm64-windows` when detected) and confirms that `vcpkg/installed/<triplet>` is populated.
+4. Reminds you to rerun `.\scripts\verify-build-environment.ps1 -FixIssues` to double-check the environment.
+
+Use it immediately after cloning the repository or whenever you need to refresh your local dependency cache before running `win-ai` or `ci-windows-ai` presets.

scripts/setup-vcpkg-windows.ps1

@@ -65,6 +65,22 @@ if (-not (Test-Command "git")) {
 
 Write-Status "✓ Git found" "Success"
 
+# Check for clang-cl
+if (Test-Command "clang-cl") {
+    $clangVersion = & clang-cl --version 2>&1 | Select-Object -First 1
+    Write-Status "✓ clang-cl detected: $clangVersion" "Success"
+} else {
+    Write-Status "⚠ clang-cl not found. Install the \"LLVM tools for Visual Studio\" component for faster builds." "Warning"
+}
+
+# Check for Ninja
+if (Test-Command "ninja") {
+    $ninjaVersion = & ninja --version 2>&1
+    Write-Status "✓ Ninja detected: version $ninjaVersion" "Success"
+} else {
+    Write-Status "⚠ Ninja not found. Install via: choco install ninja (required for win-dbg/win-ai presets)" "Warning"
+}
+
 # Clone vcpkg if needed
 if (-not (Test-Path "vcpkg")) {
     Write-Status "Cloning vcpkg..." "Warning"
@@ -102,6 +118,12 @@ Write-Status "Installing dependencies for triplet: $Triplet" "Warning"
 & $vcpkgExe install --triplet $Triplet
 if ($LASTEXITCODE -eq 0) {
     Write-Status "✓ Dependencies installed successfully" "Success"
+    $installedPath = "vcpkg\installed\$Triplet"
+    if (Test-Path $installedPath) {
+        Write-Status "✓ Cached packages under $installedPath" "Success"
+    } else {
+        Write-Status "⚠ vcpkg install folder missing (expected $installedPath). Builds may rebuild dependencies on first run." "Warning"
+    }
 } else {
     Write-Status "⚠ Some dependencies may not have installed correctly" "Warning"
 }
@@ -112,4 +134,6 @@ Write-Status "========================================" "Info"
 Write-Status ""
 Write-Status "You can now build YAZE using:" "Warning"
 Write-Status "  .\scripts\build-windows.ps1" "White"
+Write-Status ""
+Write-Status "For ongoing diagnostics run: .\scripts\verify-build-environment.ps1 -FixIssues" "Info"
 Write-Status ""

scripts/verify-build-environment.ps1

@@ -56,12 +56,14 @@ function Get-CMakeVersion {
 
 function Test-GitSubmodules {
     $submodules = @(
-        "src/lib/SDL",
+        "ext/SDL",
         "src/lib/abseil-cpp",
-        "src/lib/asar",
-        "src/lib/imgui",
-        "third_party/json",
-        "third_party/httplib"
+        "ext/asar",
+        "ext/imgui",
+        "ext/json",
+        "ext/httplib",
+        "ext/imgui_test_engine",
+        "ext/nativefiledialog-extended"
     )
     
     $allPresent = $true
@@ -165,6 +167,36 @@ function Test-Vcpkg {
     }
 }
 
+function Test-VcpkgCache {
+    $vcpkgPath = Join-Path $PSScriptRoot ".." "vcpkg"
+    $installedDir = Join-Path $vcpkgPath "installed"
+
+    if (-not (Test-Path $installedDir)) {
+        return
+    }
+
+    $triplets = @("x64-windows", "arm64-windows")
+    $hasPackages = $false
+
+    foreach ($triplet in $triplets) {
+        $tripletDir = Join-Path $installedDir $triplet
+        if (Test-Path $tripletDir) {
+            $count = (Get-ChildItem $tripletDir -Force | Measure-Object).Count
+            if ($count -gt 0) {
+                $hasPackages = $true
+                Write-Status "vcpkg cache populated for $triplet" "Success"
+            }
+        }
+    }
+
+    if (-not $hasPackages) {
+        Write-Status "vcpkg/installed is empty. Run scripts\\setup-vcpkg-windows.ps1 to prefetch dependencies." "Warning"
+        $script:warnings += "vcpkg cache empty - builds may spend extra time compiling dependencies."
+    } else {
+        $script:success += "vcpkg cache ready for Windows presets"
+    }
+}
+
 function Test-CMakeCache {
     $buildDirs = @("build", "build-windows", "build-test", "build-ai", "out/build")
     $cacheIssues = $false
@@ -279,6 +311,25 @@ function Test-Ninja {
     }
 }
 
+function Test-ClangCL {
+    Write-Status "Checking clang-cl compiler..." "Step"
+    if (Test-Command "clang-cl") {
+        try {
+            $clangVersion = & clang-cl --version 2>&1 | Select-Object -First 1
+            Write-Status "clang-cl found: $clangVersion" "Success"
+            $script:success += "clang-cl available (recommended for win-* presets)"
+            return $true
+        } catch {
+            Write-Status "clang-cl command exists but version check failed" "Warning"
+            return $true
+        }
+    } else {
+        Write-Status "clang-cl not found (LLVM toolset for MSVC missing?)" "Warning"
+        $script:warnings += "Install the \"LLVM tools for Visual Studio\" component or enable clang-cl via Visual Studio Installer."
+        return $false
+    }
+}
+
 function Test-NASM {
     Write-Status "Checking NASM assembler..." "Step"
     if (Test-Command "nasm") {
@@ -346,6 +397,28 @@ function Test-VSCode {
     }
 }
 
+function Test-RomAssets {
+    Write-Status "Checking for local Zelda 3 ROM assets..." "Step"
+    $romPaths = @(
+        "zelda3.sfc",
+        "assets/zelda3.sfc",
+        "assets/zelda3.yaze",
+        "Roms/zelda3.sfc"
+    )
+
+    foreach ($relativePath in $romPaths) {
+        $fullPath = Join-Path $PSScriptRoot ".." $relativePath
+        if (Test-Path $fullPath) {
+            Write-Status "Found ROM asset at '$relativePath'" "Success"
+            $script:success += "ROM asset available for GUI/editor smoke tests"
+            return
+        }
+    }
+
+    Write-Status "No ROM asset detected. Place a clean 'zelda3.sfc' in the repo root or assets/ directory." "Warning"
+    $script:warnings += "ROM assets missing - GUI workflows that load ROMs will fail until one is provided."
+}
+
 function Test-CMakePresets {
     Write-Status "Validating CMakePresets.json..." "Step"
     
@@ -492,8 +565,9 @@ if (Test-Command "git") {
     $script:issuesFound += "Git not installed or not in PATH"
 }
 
-# Step 3: Check Build Tools (Ninja and NASM)
+# Step 3: Check Build Tools (Ninja, clang-cl, NASM)
 Test-Ninja | Out-Null
+Test-ClangCL | Out-Null
 Test-NASM | Out-Null
 
 # Step 4: Check Visual Studio
@@ -528,6 +602,7 @@ Test-CMakePresets | Out-Null
 
 # Step 7: Check vcpkg
 Test-Vcpkg | Out-Null
+Test-VcpkgCache | Out-Null
 
 # Step 8: Check Git Submodules
 Write-Status "Checking git submodules..." "Step"
@@ -564,6 +639,9 @@ if (Test-CMakeCache) {
     }
 }
 
+# Step 10: Check ROM assets
+Test-RomAssets | Out-Null
+
 # ============================================================================
 # Summary Report
 # ============================================================================

scripts/verify-build-environment.sh

@@ -90,12 +90,14 @@ function get_cmake_version() {
 
 function test_git_submodules() {
     local submodules=(
-        "src/lib/SDL"
-        "src/lib/abseil-cpp"
-        "src/lib/asar"
-        "src/lib/imgui"
-        "third_party/json"
-        "third_party/httplib"
+    "ext/SDL"
+    "src/lib/abseil-cpp"
+    "ext/asar"
+    "ext/imgui"
+    "ext/json"
+    "ext/httplib"
+    "ext/imgui_test_engine"
+    "ext/nativefiledialog-extended"
     )
     
     local all_present=1
@@ -242,14 +244,14 @@ function test_dependency_compatibility() {
     write_status "Testing dependency configuration..." "Step"
     
     # Check httplib configuration
-    if [[ -f "third_party/httplib/CMakeLists.txt" ]]; then
-        write_status "httplib found in third_party" "Success"
+    if [[ -f "ext/httplib/CMakeLists.txt" ]]; then
+        write_status "httplib found in ext/" "Success"
         SUCCESS+=("httplib header-only library available")
     fi
     
     # Check json library
-    if [[ -d "third_party/json/include" ]]; then
-        write_status "nlohmann/json found in third_party" "Success"
+    if [[ -d "ext/json/include" ]]; then
+        write_status "nlohmann/json found in ext/" "Success"
         SUCCESS+=("nlohmann/json header-only library available")
     fi
 }