feat: Consolidate AI agent build flags and enhance JSON support handling

CMakeLists.txt

@@ -56,12 +56,25 @@ option(YAZE_ENABLE_UI_TESTS "Enable ImGui Test Engine UI testing" ON)
 option(YAZE_MINIMAL_BUILD "Minimal build for CI (disable optional features)" OFF)
 option(YAZE_USE_MODULAR_BUILD "Use modularized library build system for faster builds" OFF)
 
-# Optional JSON support (required for Gemini and structured agent responses)
+# ============================================================================
+# AI Agent Build Flags (Consolidated)
+# ============================================================================
+# Z3ED_AI: Master flag for z3ed AI agent features (Ollama + Gemini support)
+# Enables: JSON parsing, YAML config, httplib for API calls, prompt builder
+option(Z3ED_AI "Enable z3ed AI agent features (Gemini/Ollama integration)" OFF)
+
+# YAZE_WITH_JSON: JSON support (auto-enabled by Z3ED_AI)
 option(YAZE_WITH_JSON "Enable JSON support for AI integrations" OFF)
 
-# Optional gRPC support for ImGuiTestHarness (z3ed agent mode)
+# YAZE_WITH_GRPC: gRPC for GUI automation (auto-enables JSON)
 option(YAZE_WITH_GRPC "Enable gRPC-based ImGuiTestHarness for automated GUI testing (experimental)" OFF)
 
+# Dependency resolution
+if(Z3ED_AI)
+    message(STATUS "Z3ED_AI enabled: Activating AI agent dependencies (JSON, YAML, httplib)")
+    set(YAZE_WITH_JSON ON CACHE BOOL "Enable JSON support" FORCE)
+endif()
+
 if(YAZE_WITH_GRPC AND NOT YAZE_WITH_JSON)
     message(STATUS "Enabling JSON support because gRPC is enabled")
     set(YAZE_WITH_JSON ON CACHE BOOL "Enable JSON support" FORCE)

docs/z3ed/README.md

@@ -21,14 +21,24 @@
 # Basic z3ed (CLI only, no AI/testing features)
 cmake --build build --target z3ed
 
-# Full build with AI agent and testing suite
+# Full build with AI agent (RECOMMENDED - uses consolidated flag)
-cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON -DYAZE_WITH_JSON=ON
+cmake -B build -DZ3ED_AI=ON
-cmake --build build-grpc-test --target z3ed
+cmake --build build --target z3ed
+
+# Full build with AI agent AND testing suite
+cmake -B build -DZ3ED_AI=ON -DYAZE_WITH_GRPC=ON
+cmake --build build --target z3ed
 ```
 
-**Dependencies for Full Build**:
+**Build Flags Explained**:
-- gRPC (GUI automation)
+- `Z3ED_AI=ON` - **Master flag** for AI features (enables JSON, YAML, httplib for Ollama + Gemini)
-- nlohmann/json (AI service communication)
+- `YAZE_WITH_GRPC=ON` - Optional GUI automation and test harness (also enables JSON)
+- `YAZE_WITH_JSON=ON` - Lower-level flag (auto-enabled by Z3ED_AI or GRPC)
+
+**Dependencies for AI Features** (auto-managed by Z3ED_AI):
+- nlohmann/json (JSON parsing for AI responses)
+- yaml-cpp (Config file loading)
+- httplib (HTTP/HTTPS API calls)
 - OpenSSL (optional, for Gemini HTTPS - auto-detected on macOS/Linux)
 
 ### AI Agent Commands
@@ -275,13 +285,21 @@ AI agent features require:
 ### "OpenSSL not found" warning
 **Impact**: Gemini API won't work (HTTPS required)  
 **Solutions**:
-- Use Ollama instead (no SSL needed, runs locally)
+- Use Ollama instead (no SSL needed, runs locally) - **RECOMMENDED**
 - Install OpenSSL: `brew install openssl` (macOS) or `apt-get install libssl-dev` (Linux)
-- Windows: Build without gRPC/JSON, use Ollama
+- Windows: Use Ollama (localhost) instead of Gemini
+
+### "Build with -DZ3ED_AI=ON" warning
+**Impact**: AI agent features disabled (no Ollama or Gemini)  
+**Solution**: Rebuild with AI support:
+```bash
+cmake -B build -DZ3ED_AI=ON
+cmake --build build --target z3ed
+```
 
 ### "gRPC not available" error
 **Impact**: GUI testing and automation disabled  
-**Solution**: Rebuild with `-DYAZE_WITH_GRPC=ON`
+**Solution**: Rebuild with `-DYAZE_WITH_GRPC=ON` (also requires Z3ED_AI)
 
 ### AI generates invalid commands
 **Causes**: Vague prompt, unfamiliar tile IDs, missing context  

src/cli/agent.cmake

@@ -119,6 +119,22 @@ endif()
 if(YAZE_WITH_JSON)
   target_link_libraries(yaze_agent PUBLIC nlohmann_json::nlohmann_json)
   target_compile_definitions(yaze_agent PUBLIC YAZE_WITH_JSON)
+
+  find_package(OpenSSL)
+  if(OpenSSL_FOUND)
+    target_compile_definitions(yaze_agent PUBLIC CPPHTTPLIB_OPENSSL_SUPPORT)
+    target_link_libraries(yaze_agent PUBLIC OpenSSL::SSL OpenSSL::Crypto)
+
+    if(APPLE)
+      target_compile_definitions(yaze_agent PUBLIC CPPHTTPLIB_USE_CERTS_FROM_MACOSX_KEYCHAIN)
+      target_link_libraries(yaze_agent PUBLIC "-framework CoreFoundation" "-framework Security")
+    endif()
+
+    message(STATUS "✓ SSL/HTTPS support enabled for yaze_agent (Gemini + HTTPS)")
+  else()
+    message(WARNING "OpenSSL not found - Gemini HTTPS features disabled")
+    message(STATUS "  Install OpenSSL to enable Gemini: brew install openssl (macOS) or apt-get install libssl-dev (Linux)")
+  endif()
 endif()
 
 set_target_properties(yaze_agent PROPERTIES POSITION_INDEPENDENT_CODE ON)

src/cli/service/ai/ollama_ai_service.cc

@@ -7,26 +7,9 @@
 #include "absl/strings/str_format.h"
 #include "cli/service/agent/conversational_agent_service.h"
 
-// Check if we have httplib available (from vcpkg or bundled)
+#ifdef YAZE_WITH_JSON
-#if __has_include("httplib.h")
-#define YAZE_HAS_HTTPLIB 1
 #include "httplib.h"
-#elif __has_include("incl/httplib.h")
+#include "nlohmann/json.hpp"
-#define YAZE_HAS_HTTPLIB 1
-#include "incl/httplib.h"
-#else
-#define YAZE_HAS_HTTPLIB 0
-#endif
-
-// Check if we have JSON library available
-#if __has_include("third_party/json/src/json.hpp")
-#define YAZE_HAS_JSON 1
-#include "third_party/json/src/json.hpp"
-#elif __has_include("json.hpp")
-#define YAZE_HAS_JSON 1
-#include "json.hpp"
-#else
-#define YAZE_HAS_JSON 0
 #endif
 
 namespace yaze {
@@ -60,10 +43,10 @@ void OllamaAIService::SetRomContext(Rom* rom) {
 }
 
 absl::Status OllamaAIService::CheckAvailability() {
-#if !YAZE_HAS_HTTPLIB || !YAZE_HAS_JSON
+#ifndef YAZE_WITH_JSON
   return absl::UnimplementedError(
-      "Ollama service requires httplib and JSON support. "
+      "Ollama service requires JSON support. "
-      "Install vcpkg dependencies or use bundled libraries.");
+      "Build with -DZ3ED_AI=ON or -DYAZE_WITH_JSON=ON");
 #else
   try {
     httplib::Client cli(config_.base_url);

src/cli/service/ai/prompt_builder.cc

@@ -125,6 +125,13 @@ absl::StatusOr<std::string> PromptBuilder::ResolveCataloguePath(
 }
 
 absl::Status PromptBuilder::LoadResourceCatalogue(const std::string& yaml_path) {
+#ifndef YAZE_WITH_JSON
+  // Gracefully degrade if JSON support not available
+  std::cerr << "⚠️  PromptBuilder requires JSON support for catalogue loading\n"
+            << "   Build with -DZ3ED_AI=ON or -DYAZE_WITH_JSON=ON\n"
+            << "   AI features will use basic prompts without tool definitions\n";
+  return absl::OkStatus();  // Don't fail, just skip catalogue loading
+#else
   auto resolved_or = ResolveCataloguePath(yaml_path);
   if (!resolved_or.ok()) {
     ClearCatalogData();
@@ -175,6 +182,7 @@ absl::Status PromptBuilder::LoadResourceCatalogue(const std::string& yaml_path)
 
   catalogue_loaded_ = true;
   return absl::OkStatus();
+#endif  // YAZE_WITH_JSON
 }
 
 absl::Status PromptBuilder::ParseCommands(const nlohmann::json& commands) {

src/cli/service/ai/prompt_builder.h

@@ -1,6 +1,12 @@
 #ifndef YAZE_CLI_SERVICE_PROMPT_BUILDER_H_
 #define YAZE_CLI_SERVICE_PROMPT_BUILDER_H_
 
+// PromptBuilder requires JSON and YAML support for catalogue loading
+// If you see linker errors, enable Z3ED_AI or YAZE_WITH_JSON in CMake
+#if !defined(YAZE_WITH_JSON)
+#warning "PromptBuilder requires JSON support. Build with -DZ3ED_AI=ON or -DYAZE_WITH_JSON=ON"
+#endif
+
 #include <map>
 #include <string>
 #include <vector>

src/cli/z3ed.cmake

@@ -78,16 +78,23 @@ add_executable(
   cli/service/testing/test_suite_writer.cc
 )
 
-if(YAZE_WITH_JSON)
+# ============================================================================
+# AI Agent Support (Consolidated via Z3ED_AI flag)
+# ============================================================================
+if(Z3ED_AI OR YAZE_WITH_JSON)
   target_compile_definitions(z3ed PRIVATE YAZE_WITH_JSON)
+  message(STATUS "✓ z3ed AI agent enabled (Ollama + Gemini support)")
+  
+  # Link nlohmann_json (already fetched in main CMakeLists if YAZE_WITH_JSON)
+  target_link_libraries(z3ed PRIVATE nlohmann_json::nlohmann_json)
 endif()
 
 # ============================================================================
-# SSL/HTTPS Support (Optional - Required for Gemini API and collaborative features)
+# SSL/HTTPS Support (Optional - Required for Gemini API)
 # ============================================================================
-# SSL is only enabled when building with gRPC+JSON (the full agent/testing suite)
+# SSL is only enabled when AI features are active
-# This ensures Windows builds without these dependencies still work
+# Ollama (localhost) works without SSL, Gemini (HTTPS) requires it
-if(YAZE_WITH_GRPC AND YAZE_WITH_JSON)
+if((Z3ED_AI OR YAZE_WITH_JSON) AND (YAZE_WITH_GRPC OR Z3ED_AI))
   find_package(OpenSSL)
   
   if(OpenSSL_FOUND)
@@ -103,13 +110,16 @@ if(YAZE_WITH_GRPC AND YAZE_WITH_JSON)
       target_link_libraries(z3ed PRIVATE "-framework CoreFoundation" "-framework Security")
     endif()
     
-    message(STATUS "✓ SSL/HTTPS support enabled for z3ed (required for Gemini API)")
+    message(STATUS "✓ SSL/HTTPS support enabled for z3ed (Gemini API ready)")
   else()
-    message(WARNING "OpenSSL not found - Gemini API will not work (Ollama will still function)")
+    message(WARNING "OpenSSL not found - Gemini API will not work")
-    message(STATUS "  Install OpenSSL to enable Gemini: brew install openssl (macOS) or apt-get install libssl-dev (Linux)")
+    message(STATUS "  • Ollama (local) still works without SSL")
+    message(STATUS "  • Install OpenSSL for Gemini: brew install openssl (macOS) or apt install libssl-dev (Linux)")
   endif()
 else()
-  message(STATUS "Building z3ed without gRPC/JSON - AI agent features disabled")
+  if(NOT Z3ED_AI AND NOT YAZE_WITH_JSON)
+    message(STATUS "○ z3ed AI agent disabled (set -DZ3ED_AI=ON to enable Gemini/Ollama)")
+  endif()
 endif()
 
 target_include_directories(