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.

docs/internal/agents/ai-modularity.md

@@ -0,0 +1,100 @@
+# AI & gRPC Modularity Blueprint
+
+*Date: November 16, 2025 – Author: GPT-5.1 Codex*
+
+## 1. Scope & Goals
+
+- Make AI/gRPC features optional without scattering `#ifdef` guards.
+- Ensure Windows builds succeed regardless of whether AI tooling is enabled.
+- Provide a migration path toward relocatable dependencies (`ext/`) and cleaner preset defaults for macOS + custom tiling window manager workflows (sketchybar/yabai/skhd, Emacs/Spacemacs).
+
+## 2. Current Touchpoints
+
+| Surface | Key Paths | Notes |
+| --- | --- | --- |
+| Editor UI | `src/app/editor/agent/**`, `app/gui/app/agent_chat_widget.cc`, `app/editor/agent/agent_chat_history_popup.cc` | Widgets always compile when `YAZE_ENABLE_GRPC=ON`, but they include protobuf types directly. |
+| Core Services | `src/app/service/grpc_support.cmake`, `app/service/*.cc`, `app/test/test_recorder.cc` | `yaze_grpc_support` bundles servers, generated protos, and even CLI code (`cli/service/planning/tile16_proposal_generator.cc`). |
+| CLI / z3ed | `src/cli/agent.cmake`, `src/cli/service/agent/*.cc`, `src/cli/service/ai/*.cc`, `src/cli/service/gui/*.cc` | gRPC, Gemeni/Ollama (JSON + httplib/OpenSSL) all live in one static lib. |
+| Build Flags | `cmake/options.cmake`, scattered `#ifdef Z3ED_AI` and `#ifdef Z3ED_AI_AVAILABLE` | Flags do not describe GUI vs CLI vs runtime needs, so every translation unit drags in gRPC headers once `YAZE_ENABLE_GRPC=ON`. |
+| Tests & Automation | `src/app/test/test_manager.cc`, `scripts/agent_test_suite.sh`, `.github/workflows/ci.yml` | Tests assume AI features exist; Windows agents hit linker issues when that assumption breaks. |
+
+## 3. Coupling Pain Points
+
+1. **Single Monolithic `yaze_agent`** – Links SDL, GUI, emulator, Abseil, yaml, nlohmann_json, httplib, OpenSSL, and gRPC simultaneously. No stubs exist when only CLI or GUI needs certain services (`src/cli/agent.cmake`).
+2. **Editor Hard Links** – `yaze_editor` unconditionally links `yaze_agent` when `YAZE_MINIMAL_BUILD` is `OFF`, so even ROM-editing-only builds drag in AI dependencies (`src/app/editor/editor_library.cmake`).
+3. **Shared Proto Targets** – `yaze_grpc_support` consumes CLI proto files, so editor-only builds still compile CLI automation code (`src/app/service/grpc_support.cmake`).
+4. **Preprocessor Guards** – UI code mixes `Z3ED_AI` and `Z3ED_AI_AVAILABLE`; CLI code checks `Z3ED_AI` while build system only defines `Z3ED_AI` when `YAZE_ENABLE_AI=ON`. These mismatches cause dead code paths and missing symbols.
+
+## 4. Windows Build Blockers
+
+- **Runtime library mismatch** – yaml-cpp and other dependencies are built `/MT` while `yaze_emu` uses `/MD`, causing cascades of `LNK2038` and `_Lockit`/`libcpmt` conflicts (`logs/windows_ci_linker_error.log`).
+- **OpenSSL duplication** – `yaze_agent` links cpp-httplib with OpenSSL while gRPC pulls BoringSSL, leading to duplicate symbol errors (`libssl.lib` vs `ssl.lib`) in the same log.
+- **Missing native dialogs** – `FileDialogWrapper` symbols fail to link when macOS-specific implementations are not excluded on Windows (also visible in the same log).
+- **Preset drift** – `win-ai` enables GRPC/AI without guaranteeing vcpkg/clang-cl or ROM assets; `win-dbg` disables gRPC entirely so editor agents fail to compile because of unconditional includes.
+
+## 5. Proposed Modularization
+
+| Proposed CMake Option | Purpose | Default | Notes |
+| --- | --- | --- | --- |
+| `YAZE_BUILD_AGENT_UI` | Compile ImGui agent widgets (editor). | `ON` for GUI presets, `OFF` elsewhere. | Controls `app/editor/agent/**` sources. |
+| `YAZE_ENABLE_REMOTE_AUTOMATION` | Build/ship gRPC servers & automation bridges. | `ON` in `*-ai` presets. | Owns `yaze_grpc_support` + proto generation. |
+| `YAZE_ENABLE_AI_RUNTIME` | Include AI runtime (Gemini/Ollama, CLI planners). | `ON` in CLI/AI presets. | Governs `cli/service/ai/**`. |
+| `YAZE_ENABLE_AGENT_CLI` | Build `z3ed` with full agent features. | `ON` when CLI requested. | Allows `z3ed` to be disabled independently. |
+
+Implementation guidelines:
+
+1. **Split Targets**
+   - `yaze_agent_core`: command routing, ROM helpers, no AI.
+   - `yaze_agent_ai`: depends on JSON + OpenSSL + remote automation.
+   - `yaze_agent_ui_bridge`: tiny facade that editor links only when `YAZE_BUILD_AGENT_UI=ON`.
+2. **Proto Ownership**
+   - Keep proto generation under `yaze_grpc_support`, but do not add CLI sources to that target. Instead, expose headers/libs and let CLI link them conditionally.
+3. **Stub Providers**
+   - Provide header-compatible no-op classes (e.g., `AgentChatWidgetBridge::Create()` returning `nullptr`) when UI is disabled, removing the need for `#ifdef` in ImGui panels.
+4. **Dependency Injection**
+   - Replace `#ifdef Z3ED_AI_AVAILABLE` in `agent_chat_widget.cc` with an interface returned from `AgentFeatures::MaybeCreateChatPanel()`.
+
+## 6. Preset & Feature Matrix
+
+| Preset | GUI | CLI | GRPC | AI Runtime | Agent UI |
+| --- | --- | --- | --- | --- | --- |
+| `mac-dbg` | ✅ | ✅ | ⚪ | ⚪ | ✅ |
+| `mac-ai` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `lin-dbg` | ✅ | ✅ | ⚪ | ⚪ | ✅ |
+| `ci-windows` | ✅ | ✅ | ⚪ | ⚪ | ⚪ (core only) |
+| `ci-windows-ai` (new nightly) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `win-dbg` | ✅ | ✅ | ⚪ | ⚪ | ✅ |
+| `win-ai` | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+Legend: ✅ enabled, ⚪ disabled.
+
+## 7. Migration Steps
+
+1. **Define Options** in `cmake/options.cmake` and propagate via presets.
+2. **Restructure Libraries**:
+   - Move CLI AI/runtime code into `yaze_agent_ai`.
+   - Add `yaze_agent_stub` for builds without AI.
+   - Make `yaze_editor` link against stub/real target via generator expressions.
+3. **CMake Cleanup**:
+   - Limit `yaze_grpc_support` to gRPC-only code.
+   - Guard JSON/OpenSSL includes behind `YAZE_ENABLE_AI_RUNTIME`.
+4. **Windows Hardening**:
+   - Force `/MD` everywhere and ensure yaml-cpp inherits `CMAKE_MSVC_RUNTIME_LIBRARY`.
+   - Allow only one SSL provider based on feature set.
+   - Add preset validation in `scripts/verify-build-environment.ps1`.
+5. **CI/CD Split**:
+   - Current `.github/workflows/ci.yml` runs GRPC on all platforms; adjust to run minimal Windows build plus nightly AI build to save time and reduce flakiness.
+6. **Docs + Scripts**:
+   - Update build guides to describe new options.
+   - Document how macOS users can integrate headless builds with sketchybar/yabai/skhd (focus on CLI usage + automation).
+7. **External Dependencies**:
+   - Relocate submodules to `ext/` and update scripts so the new layout is enforced before toggling feature flags.
+
+## 8. Deliverables
+
+- This blueprint (`docs/internal/agents/ai-modularity.md`).
+- Updated CMake options, presets, and stubs.
+- Hardened Windows build scripts/logging.
+- CI/CD workflow split + release automation updates.
+- Documentation refresh & dependency relocation.
+

docs/internal/legacy/BUILD-GUIDE.md

@@ -108,7 +108,7 @@ Add `-v` suffix (e.g., `mac-dbg-v`) for verbose compiler warnings.
 **Problem**: Conflicting ImGui versions (bundled vs CPM download)
 
 **Fixes**:
-- Used bundled ImGui from `src/lib/imgui/` instead of downloading
+- Used bundled ImGui from `ext/imgui/` instead of downloading
 - Created proper ImGui static library target
 - Added `imgui_stdlib.cpp` for std::string support
 - Exported with `PARENT_SCOPE`
@@ -118,7 +118,7 @@ Add `-v` suffix (e.g., `mac-dbg-v`) for verbose compiler warnings.
 
 **Fixes**:
 - Created `cmake/dependencies/json.cmake`
-- Set up bundled `third_party/json/`
+- Set up bundled `ext/json/`
 - Added include directories to all targets that need JSON
 
 #### 7. GTest and GMock ✅

docs/public/build/build-from-source.md

@@ -13,6 +13,7 @@ yaze uses a modern CMake build system with presets for easy configuration. This
 # With automatic fixes
 .\scripts\verify-build-environment.ps1 -FixIssues
 ```
+> Tip: After verification, run `.\scripts\setup-vcpkg-windows.ps1` to bootstrap vcpkg, ensure `clang-cl`/Ninja are installed, and cache the `x64-windows` triplet.
 
 ### macOS & Linux (Bash)
 ```bash
@@ -53,6 +54,10 @@ cmake --preset win-dbg
 
 # Build the project
 cmake --build --preset win-dbg
+
+# Enable the full AI/gRPC stack
+cmake --preset win-ai
+cmake --build --preset win-ai
 ```
 
 ### AI-Enabled Build (All Platforms)
@@ -67,10 +72,31 @@ cmake --preset win-ai
 cmake --build --preset win-ai
 ```
 
+## Feature Toggles & Windows Profiles
+
+### Windows Presets
+
+| Preset | Purpose |
+| --- | --- |
+| `win-dbg`, `win-rel`, `ci-windows` | Core builds without agent UI, gRPC, or AI runtimes. Fastest option for MSVC/clang-cl. |
+| `win-ai`, `win-vs-ai` | Full agent stack for local development (UI panels + remote automation + AI runtime). |
+| `ci-windows-ai` | Nightly/weekly CI preset that exercises the entire automation stack on Windows. |
+
+### Agent Feature Flags
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `YAZE_BUILD_AGENT_UI` | `ON` when `YAZE_BUILD_GUI=ON` | Builds the ImGui widgets used by the chat/agent panels. |
+| `YAZE_ENABLE_REMOTE_AUTOMATION` | `ON` for `*-ai` presets | Adds gRPC/protobuf services plus GUI automation clients. |
+| `YAZE_ENABLE_AI_RUNTIME` | `ON` for `*-ai` presets | Enables Gemini/Ollama transports, proposal planning, and advanced routing logic. |
+| `YAZE_ENABLE_AGENT_CLI` | `ON` when `YAZE_BUILD_CLI=ON` | Compiles the conversational agent stack consumed by `z3ed`. |
+
+Combine these switches to match your workflow: keep everything `OFF` for lightweight GUI hacking or turn them `ON` for automation-heavy work with sketchybar/yabai/skhd, tmux, or remote runners.
+
 ## 3. Dependencies
 
 -   **Required**: CMake 3.16+, C++23 Compiler (GCC 13+, Clang 16+, MSVC 2019+), Git.
--   **Bundled**: All other dependencies (SDL2, ImGui, Abseil, Asar, GoogleTest, etc.) are included as Git submodules or managed by CMake's `FetchContent`. No external package manager is required for a basic build.
+-   **Bundled**: All other dependencies (SDL2, ImGui, Asar, nlohmann/json, cpp-httplib, GoogleTest, etc.) live under the `ext/` directory or are managed by CMake's `FetchContent`. No external package manager is required for a basic build.
 -   **Optional**: 
     -   **gRPC**: For GUI test automation. Can be enabled with `-DYAZE_WITH_GRPC=ON`.
     -   **vcpkg (Windows)**: Can be used for faster gRPC builds on Windows (optional).
@@ -95,7 +121,8 @@ sudo apt-get install -y build-essential cmake ninja-build pkg-config \
 
 ### Windows
 -   **Visual Studio 2022** is required, with the "Desktop development with C++" workload.
--   The `verify-build-environment.ps1` script will help identify any missing components.
+-   The updated `verify-build-environment.ps1` script checks clang-cl, Ninja, vcpkg caches, and ROM assets.
+-   Run `.\scripts\setup-vcpkg-windows.ps1` once per machine to bootstrap vcpkg and prefetch SDL2/yaml-cpp.
 -   For building with gRPC, see the "Windows Build Optimization" section below.
 
 ## 5. Testing
@@ -171,6 +198,7 @@ open build/yaze.xcodeproj
 - **vcpkg**: Only fast packages (SDL2, yaml-cpp) - 2 minutes
 - **gRPC**: Built via FetchContent (v1.75.1) - cached after first build
 - **Caching**: Aggressive multi-tier caching (vcpkg + FetchContent + sccache)
+- **Agent matrix**: A dedicated `ci-windows-ai` job runs outside pull requests to exercise the full gRPC + AI runtime stack.
 - **Expected time**: 
   - First build: ~10-15 minutes
   - Cached build: ~3-5 minutes
@@ -188,9 +216,8 @@ open build/yaze.xcodeproj
 For desktop development, you can use vcpkg for faster gRPC builds:
 
 ```powershell
-# Install vcpkg
-git clone https://github.com/Microsoft/vcpkg.git
-cd vcpkg && .\bootstrap-vcpkg.bat
+# Bootstrap vcpkg and prefetch packages
+.\scripts\setup-vcpkg-windows.ps1
 
 # Configure with vcpkg
 cmake -B build -DYAZE_USE_VCPKG_GRPC=ON -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake

docs/public/developer/dependency-architecture.md

@@ -18,6 +18,10 @@ can treat it as a quick reference while editing.
 | `YAZE_ENABLE_GRPC` | `OFF` | Pulls in gRPC/protobuf for automation and remote control features. |
 | `YAZE_MINIMAL_BUILD` | `OFF` | Skips optional editors/assets. Useful for CI smoke builds. |
 | `YAZE_BUILD_LIB` | `OFF` | Produces the `yaze_core` INTERFACE target used by external tooling. |
+| `YAZE_BUILD_AGENT_UI` | `ON` when `YAZE_BUILD_GUI` is `ON` | Compiles ImGui chat widgets. Disable for lighter GUI builds. |
+| `YAZE_ENABLE_REMOTE_AUTOMATION` | `OFF` in `win-*` core presets | Builds gRPC servers/clients plus proto generation. |
+| `YAZE_ENABLE_AI_RUNTIME` | `OFF` in `win-*` core presets | Enables Gemini/Ollama transports, proposal planning, and advanced routing code. |
+| `YAZE_ENABLE_AGENT_CLI` | `ON` when `YAZE_BUILD_CLI` is `ON` | Compiles the conversational agent stack used by `z3ed`. |
 
 Use the canned presets from `CMakePresets.json` so these options stay consistent across
 platforms: `mac-dbg`, `mac-ai`, `lin-dbg`, `win-dbg`, etc. The `*-ai` presets enable both
@@ -58,12 +62,13 @@ alone. Touching editor UI code does **not** require rebuilding `yaze_emulator`.
 
 ### 4. Tooling & Export Targets
 - **`yaze_agent`** (`src/cli/agent`): shared logic behind the CLI and AI workflows. Built whenever
-  `YAZE_BUILD_Z3ED` is enabled.
+  `YAZE_ENABLE_AGENT_CLI` is enabled (automatically true when `YAZE_BUILD_Z3ED=ON`). When both the CLI and the agent UI are disabled, CMake now emits a lightweight stub target so GUI-only builds don't drag in unnecessary dependencies.
 - **`z3ed` binary** (`src/cli/z3ed.cmake`): links `yaze_agent`, `yaze_zelda3`, `yaze_gfx`, and
   Abseil/FTXUI.
 - **`yaze_core_lib`** (`src/core`): static library that exposes project management helpers and the
   Asar integration. When `YAZE_BUILD_LIB=ON` it can be consumed by external tools.
 - **`yaze_test_support`** (`src/app/test`): harness for the in-editor dashboard and `yaze_test`.
+- **`yaze_grpc_support`**: server-only aggregation of gRPC/protobuf code, gated by `YAZE_ENABLE_REMOTE_AUTOMATION`. CLI clients (`cli/service/gui/**`, `cli/service/planning/**`) now live solely in `yaze_agent` so GUI builds can opt out entirely.
 
 ### 5. Final Binaries
 - **`yaze`**: GUI editor. Links every layer plus `yaze_test_support` when tests are enabled.