backend-infra-engineer: Release v0.3.9-hotfix7 snapshot

.clang-tidy

@@ -1,34 +1,74 @@
-# YAZE clang-tidy configuration
-# More lenient configuration for easier compliance
+# YAZE ROM Editor - clang-tidy configuration
+# Optimized for Google C++ style, Abseil/gRPC, and ROM hacking workflows
 
 Checks: >
   -*-,
+  # Core static analysis
   clang-analyzer-*,
   -clang-analyzer-alpha*,
+  -clang-analyzer-deadcode.DeadStores,
+  
+  # Performance checks (critical for ROM emulation)
   performance-*,
   -performance-unnecessary-value-param,
+  -performance-for-range-copy,
+  -performance-move-const-arg,
+  
+  # Readability (adapted for ROM hacking)
   readability-*,
-  -readability-magic-numbers,
+  -readability-magic-numbers,  # ROM hacking uses many magic numbers
   -readability-braces-around-statements,
   -readability-named-parameter,
   -readability-function-cognitive-complexity,
   -readability-avoid-const-params-in-decls,
+  -readability-identifier-naming,  # Allow ROM-specific naming patterns
+  -readability-uppercase-literal-suffix,
+  -readability-function-size,
+  
+  # Modernize (selective for ROM compatibility)
   modernize-*,
   -modernize-use-trailing-return-type,
-  -modernize-use-auto,
-  -modernize-avoid-c-arrays,
+  -modernize-use-auto,  # ROM hacking needs explicit types
+  -modernize-avoid-c-arrays,  # ROM data structures use C arrays
   -modernize-use-default-member-init,
+  -modernize-use-nodiscard,
+  -modernize-use-override,
+  -modernize-use-equals-default,
+  -modernize-use-equals-delete,
+  
+  # Bug-prone checks (ROM-specific exceptions)
   bugprone-*,
   -bugprone-easily-swappable-parameters,
   -bugprone-exception-escape,
-  -bugprone-narrowing-conversions,
+  -bugprone-narrowing-conversions,  # ROM data often requires narrowing
   -bugprone-implicit-widening-of-multiplication-result,
+  -bugprone-signed-char-misuse,
+  -bugprone-branch-clone,
+  
+  # Miscellaneous checks
   misc-*,
   -misc-no-recursion,
   -misc-non-private-member-variables-in-classes,
-  -misc-const-correctness
+  -misc-const-correctness,
+  -misc-no-recursion,
+  -misc-redundant-expression,
+  
+  # Abseil-specific checks
+  abseil-*,
+  
+  # Google C++ style enforcement
+  google-*,
+  -google-readability-casting,
+  -google-readability-todo,
+  -google-runtime-int,
+  -google-runtime-references,
+  -google-build-using-namespace,
+  -google-explicit-constructor,
+  -google-global-names-in-headers,
+  -google-readability-braces-around-statements
 
 CheckOptions:
+  # Naming conventions (Google C++ style)
   - key: readability-identifier-naming.VariableCase
     value: lower_case
   - key: readability-identifier-naming.FunctionCase  
@@ -41,13 +81,50 @@ CheckOptions:
     value: lower_case
   - key: readability-identifier-naming.MacroCase
     value: UPPER_CASE
+  - key: readability-identifier-naming.EnumCase
+    value: CamelCase
+  - key: readability-identifier-naming.EnumConstantCase
+    value: UPPER_CASE
+  
+  # Function size limits (relaxed for ROM hacking)
   - key: readability-function-size.LineThreshold
-    value: 150
+    value: 200
   - key: readability-function-size.StatementThreshold
-    value: 100
+    value: 150
+  - key: readability-function-size.BranchThreshold
+    value: 20
+  
+  # Performance optimizations
   - key: performance-unnecessary-value-param.AllowedTypes
-    value: 'std::function;std::unique_ptr;std::shared_ptr'
+    value: 'std::function;std::unique_ptr;std::shared_ptr;absl::StatusOr;absl::string_view'
+  - key: performance-for-range-copy.WarnOnAllAutoCopies
+    value: false
+  
+  # ROM hacking specific options
+  - key: readability-magic-numbers.IgnoredValues
+    value: '0,1,2,4,8,16,32,64,128,256,512,1024,2048,4096,8192,16384,32768,65536'
+  - key: readability-magic-numbers.IgnorePowersOf2IntegerValues
+    value: true
+  - key: readability-magic-numbers.IgnorePowersOf2FloatingValues
+    value: true
+  
+  # Abseil-specific options
+  - key: abseil-string-find-startswith.AllowedFunctions
+    value: 'absl::StartsWith;absl::EndsWith'
+  
+  # Google style options
+  - key: google-readability-casting.AllowedTypes
+    value: 'uint8_t;uint16_t;uint32_t;uint64_t;int8_t;int16_t;int32_t;int64_t'
+  - key: google-runtime-int.SignedIntegerMaxBits
+    value: 64
+  - key: google-runtime-int.UnsignedIntegerMaxBits
+    value: 64
 
 WarningsAsErrors: ''
-HeaderFilterRegex: '(src|test)\/.*\.(h|hpp|hxx)$'
+HeaderFilterRegex: '(src|test|incl)\/.*\.(h|hpp|hxx)$'
 FormatStyle: google
+
+# Additional ROM hacking specific configurations
+UseColor: true
+SystemHeaders: false
+User: ''

.clangd

@@ -1,11 +1,34 @@
+# YAZE ROM Editor - clangd configuration
+# Optimized for C++23, Google style, Abseil/gRPC, and ROM hacking workflows
+
 CompileFlags:
+  CompilationDatabase: build
   Add:
+    # Additional include paths for better IntelliSense
+    - -I/Users/scawful/Code/yaze/src
+    - -I/Users/scawful/Code/yaze/src/lib
+    - -I/Users/scawful/Code/yaze/src/lib/imgui
+    - -I/Users/scawful/Code/yaze/src/lib/imgui/backends
+    - -I/Users/scawful/Code/yaze/src/lib/SDL/include
+    - -I/Users/scawful/Code/yaze/incl
+    - -I/Users/scawful/Code/yaze/third_party
+    - -I/Users/scawful/Code/yaze/third_party/json/include
+    - -I/Users/scawful/Code/yaze/third_party/httplib
+    - -I/Users/scawful/Code/yaze/build
+    - -I/Users/scawful/Code/yaze/build/src/lib/SDL/include
+    - -I/Users/scawful/Code/yaze/build/src/lib/SDL/include-config-Debug
+    # Feature flags
+    - -DYAZE_WITH_GRPC
+    - -DYAZE_WITH_JSON
+    - -DZ3ED_AI
+    # Standard library
     - -std=c++23
-    - -Wall
-    - -Wextra
+    # Platform detection
+    - -DMACOS
   Remove:
     - -mllvm
     - -xclang
+    - -w  # Remove warning suppression for better diagnostics
 
 Index:
   Background: Build
@@ -20,16 +43,45 @@ Hover:
   ShowAKA: Yes
 
 Diagnostics:
+  MissingIncludes: Strict
+  UnusedIncludes: Strict
   ClangTidy:
     Add: 
+      # Core checks for ROM hacking software
+      - performance-*
+      - bugprone-*
       - readability-*
       - modernize-*
-      - performance-*
+      - misc-*
+      - clang-analyzer-*
+      # Abseil-specific checks
+      - abseil-*
+      # Google C++ style enforcement
+      - google-*
     Remove:
+      # Disable overly strict checks for ROM hacking workflow
       - modernize-use-trailing-return-type
       - readability-braces-around-statements
-      - readability-magic-numbers
+      - readability-magic-numbers  # ROM hacking uses many magic numbers
       - readability-implicit-bool-conversion
-      - readability-identifier-naming
+      - readability-identifier-naming  # Allow ROM-specific naming
       - readability-function-cognitive-complexity
       - readability-function-size
+      - readability-uppercase-literal-suffix
+      # Disable checks that conflict with ROM data structures
+      - modernize-use-auto  # ROM hacking needs explicit types
+      - modernize-avoid-c-arrays  # ROM data often uses C arrays
+      - bugprone-easily-swappable-parameters
+      - bugprone-exception-escape
+      - bugprone-narrowing-conversions  # ROM data often requires narrowing
+      - bugprone-implicit-widening-of-multiplication-result
+      - misc-no-recursion
+      - misc-non-private-member-variables-in-classes
+      - misc-const-correctness
+
+Completion:
+  AllScopes: Yes
+
+SemanticTokens:
+  DisabledKinds: []
+  DisabledModifiers: []

.githooks/pre-commit

@@ -0,0 +1,126 @@
+#!/bin/bash
+# Pre-commit Hook - Quick symbol conflict detection
+#
+# This hook runs on staged changes and warns if duplicate symbol definitions
+# are detected in affected object files.
+#
+# Bypass with: git commit --no-verify
+
+set -euo pipefail
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${BLUE}[Pre-Commit]${NC} Checking for symbol conflicts..."
+
+# Get the repository root
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+SCRIPTS_DIR="${REPO_ROOT}/scripts"
+BUILD_DIR="${REPO_ROOT}/build"
+
+# Check if build directory exists
+if [[ ! -d "${BUILD_DIR}" ]]; then
+    echo -e "${YELLOW}[Pre-Commit]${NC} Build directory not found - skipping symbol check"
+    exit 0
+fi
+
+# Get list of changed .cc and .h files
+CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(cc|h)$' || echo "")
+
+if [[ -z "${CHANGED_FILES}" ]]; then
+    echo -e "${YELLOW}[Pre-Commit]${NC} No C++ source changes detected"
+    exit 0
+fi
+
+echo -e "${CYAN}Changed files:${NC}"
+echo "${CHANGED_FILES}" | sed 's/^/  /'
+echo ""
+
+# Quick symbol database check (only on changed files)
+# Find object files that might be affected by the changes
+AFFECTED_OBJ_FILES=""
+for file in ${CHANGED_FILES}; do
+    # Convert source file path to likely object file names
+    # e.g., src/cli/flags.cc -> *flags.cc.o
+    filename=$(basename "${file}" | sed 's/\.[ch]$//')
+
+    # Find matching object files in build directory
+    matching=$(find "${BUILD_DIR}" -name "*${filename}*.o" -o -name "*${filename}*.obj" 2>/dev/null | head -5)
+    if [[ -n "${matching}" ]]; then
+        AFFECTED_OBJ_FILES+=$'\n'"${matching}"
+    fi
+done
+
+if [[ -z "${AFFECTED_OBJ_FILES}" ]]; then
+    echo -e "${YELLOW}[Pre-Commit]${NC} No compiled objects found for changed files (might not be built yet)"
+    exit 0
+fi
+
+echo -e "${CYAN}Affected object files:${NC}"
+echo "${AFFECTED_OBJ_FILES}" | grep -v '^$' | sed 's/^/  /' || echo "  (none found)"
+echo ""
+
+# Extract symbols from affected files
+echo -e "${CYAN}Analyzing symbols...${NC}"
+
+TEMP_SYMBOLS="/tmp/yaze_precommit_symbols_$$.txt"
+trap "rm -f ${TEMP_SYMBOLS}" EXIT
+
+: > "${TEMP_SYMBOLS}"
+
+# Platform detection
+UNAME_S=$(uname -s)
+SYMBOL_CONFLICTS=0
+
+while IFS= read -r obj_file; do
+    [[ -z "${obj_file}" ]] && continue
+    [[ ! -f "${obj_file}" ]] && continue
+
+    # Extract symbols using nm (Unix/macOS)
+    if [[ "${UNAME_S}" == "Darwin"* ]] || [[ "${UNAME_S}" == "Linux"* ]]; then
+        nm -P "${obj_file}" 2>/dev/null | while read -r sym rest; do
+            [[ -z "${sym}" ]] && continue
+            # Skip undefined symbols (contain 'U')
+            [[ "${rest}" == *"U"* ]] && continue
+            echo "${sym}|${obj_file##*/}"
+        done >> "${TEMP_SYMBOLS}" || true
+    fi
+done < <(echo "${AFFECTED_OBJ_FILES}" | grep -v '^$')
+
+# Check for duplicates
+if [[ -f "${TEMP_SYMBOLS}" ]]; then
+    SYMBOL_CONFLICTS=$(cut -d'|' -f1 "${TEMP_SYMBOLS}" | sort | uniq -d | wc -l)
+fi
+
+# Report results
+if [[ ${SYMBOL_CONFLICTS} -gt 0 ]]; then
+    echo -e "${RED}WARNING: Symbol conflicts detected!${NC}\n"
+    echo "Duplicate symbols in affected files:"
+
+    cut -d'|' -f1 "${TEMP_SYMBOLS}" | sort | uniq -d | while read -r symbol; do
+        echo -e "  ${CYAN}${symbol}${NC}"
+        grep "^${symbol}|" "${TEMP_SYMBOLS}" | cut -d'|' -f2 | sort | uniq | sed 's/^/    - /'
+    done
+
+    echo ""
+    echo -e "${YELLOW}You can:${NC}"
+    echo "  1. Fix the conflicts before committing"
+    echo "  2. Skip this check: git commit --no-verify"
+    echo "  3. Run full analysis: ./scripts/extract-symbols.sh && ./scripts/check-duplicate-symbols.sh"
+    echo ""
+    echo -e "${YELLOW}Common fixes:${NC}"
+    echo "  - Add 'static' keyword to make it internal linkage"
+    echo "  - Use anonymous namespace in .cc files"
+    echo "  - Use 'inline' keyword for function/variable definitions"
+    echo ""
+
+    exit 1
+else
+    echo -e "${GREEN}No symbol conflicts in changed files${NC}"
+    exit 0
+fi

.github/actions/README.md

@@ -0,0 +1,84 @@
+# GitHub Actions - Composite Actions
+
+This directory contains reusable composite actions for the YAZE CI/CD pipeline.
+
+## Available Actions
+
+### 1. `setup-build`
+Sets up the build environment with dependencies and caching.
+
+**Inputs:**
+- `platform` (required): Target platform (linux, macos, windows)
+- `preset` (required): CMake preset to use
+- `cache-key` (optional): Cache key for dependencies
+
+**What it does:**
+- Configures CPM cache
+- Installs platform-specific build dependencies
+- Sets up sccache/ccache for faster builds
+
+### 2. `build-project`
+Builds the project with CMake and caching.
+
+**Inputs:**
+- `platform` (required): Target platform (linux, macos, windows)
+- `preset` (required): CMake preset to use
+- `build-type` (optional): Build type (Debug, Release, RelWithDebInfo)
+
+**What it does:**
+- Caches build artifacts
+- Configures the project with CMake
+- Builds the project with optimal parallel settings
+- Shows build artifacts for verification
+
+### 3. `run-tests`
+Runs the test suite with appropriate filtering.
+
+**Inputs:**
+- `test-type` (required): Type of tests to run (stable, unit, integration, all)
+- `preset` (optional): CMake preset to use (default: ci)
+
+**What it does:**
+- Runs the specified test suite(s)
+- Generates JUnit XML test results
+- Uploads test results as artifacts
+
+## Usage
+
+These composite actions are used in the main CI workflow (`.github/workflows/ci.yml`). They must be called after checking out the repository:
+
+```yaml
+steps:
+  - name: Checkout code
+    uses: actions/checkout@v4
+    with:
+      submodules: recursive
+
+  - name: Setup build environment
+    uses: ./.github/actions/setup-build
+    with:
+      platform: linux
+      preset: ci
+      cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+```
+
+## Important Notes
+
+1. **Repository checkout required**: The repository must be checked out before calling any of these composite actions. They do not include a checkout step themselves.
+
+2. **Platform-specific behavior**: Each action adapts to the target platform (Linux, macOS, Windows) and runs appropriate commands for that environment.
+
+3. **Caching**: The actions use GitHub Actions caching to speed up builds by caching:
+   - CPM dependencies (~/.cpm-cache)
+   - Build artifacts (build/)
+   - Compiler cache (sccache/ccache)
+
+4. **Dependencies**: The Linux CI packages are listed in `.github/workflows/scripts/linux-ci-packages.txt`.
+
+## Maintenance
+
+When updating these actions:
+- Test on all three platforms (Linux, macOS, Windows)
+- Ensure shell compatibility (bash for Linux/macOS, pwsh for Windows)
+- Update this README if inputs or behavior changes
+

.github/actions/build-project/action.yml

@@ -0,0 +1,58 @@
+name: 'Build Project'
+description: 'Build the project with CMake and caching'
+inputs:
+  platform:
+    description: 'Target platform (linux, macos, windows)'
+    required: true
+  preset:
+    description: 'CMake preset to use'
+    required: true
+  build-type:
+    description: 'Build type (Debug, Release, RelWithDebInfo)'
+    required: false
+    default: 'RelWithDebInfo'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Cache build artifacts
+      uses: actions/cache@v4
+      with:
+        path: build
+        key: build-${{ inputs.platform }}-${{ github.sha }}
+        restore-keys: |
+          build-${{ inputs.platform }}-
+
+    - name: Configure project
+      shell: bash
+      run: |
+        cmake --preset "${{ inputs.preset }}"
+
+    - name: Build project (Linux/macOS)
+      if: inputs.platform != 'windows'
+      shell: bash
+      run: |
+        if command -v nproc >/dev/null 2>&1; then
+          CORES=$(nproc)
+        elif command -v sysctl >/dev/null 2>&1; then
+          CORES=$(sysctl -n hw.ncpu)
+        else
+          CORES=2
+        fi
+        echo "Using $CORES parallel jobs"
+        cmake --build build --config "${{ inputs.build-type }}" --parallel "$CORES"
+
+    - name: Build project (Windows)
+      if: inputs.platform == 'windows'
+      shell: pwsh
+      run: |
+        $JOBS = ${env:CMAKE_BUILD_PARALLEL_LEVEL:-4}
+        echo "Using $JOBS parallel jobs"
+        cmake --build build --config "${{ inputs.build-type }}" --parallel "$JOBS"
+
+    - name: Show build artifacts
+      shell: bash
+      run: |
+        echo "Build artifacts:"
+        find build -name "*.exe" -o -name "yaze" -o -name "*.app" | head -10
+

.github/actions/run-tests/action.yml

@@ -0,0 +1,61 @@
+name: 'Run Tests'
+description: 'Run test suite with appropriate filtering'
+inputs:
+  test-type:
+    description: 'Type of tests to run (stable, unit, integration, all)'
+    required: true
+  preset:
+    description: 'CMake preset to use (for reference, tests use minimal preset)'
+    required: false
+    default: 'minimal'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Select test preset suffix
+      shell: bash
+      run: |
+        if [ "${{ inputs.preset }}" = "ci-windows-ai" ]; then
+          echo "CTEST_SUFFIX=-ai" >> $GITHUB_ENV
+        else
+          echo "CTEST_SUFFIX=" >> $GITHUB_ENV
+        fi
+
+    - name: Run stable tests
+      if: inputs.test-type == 'stable' || inputs.test-type == 'all'
+      shell: bash
+      run: |
+        cd build
+        ctest --preset stable${CTEST_SUFFIX} \
+          --output-on-failure \
+          --timeout 300 \
+          --output-junit stable_test_results.xml || true
+
+    - name: Run unit tests
+      if: inputs.test-type == 'unit' || inputs.test-type == 'all'
+      shell: bash
+      run: |
+        cd build
+        ctest --preset unit${CTEST_SUFFIX} \
+          --output-on-failure \
+          --timeout 300 \
+          --output-junit unit_test_results.xml || true
+
+    - name: Run integration tests
+      if: inputs.test-type == 'integration' || inputs.test-type == 'all'
+      shell: bash
+      run: |
+        cd build
+        ctest --preset integration${CTEST_SUFFIX} \
+          --output-on-failure \
+          --timeout 300 \
+          --output-junit integration_test_results.xml || true
+
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      with:
+        name: test-results-${{ inputs.test-type }}
+        path: build/*test_results.xml
+        if-no-files-found: ignore
+        retention-days: 7
+

.github/actions/setup-build/action.yml

@@ -0,0 +1,77 @@
+name: 'Setup Build Environment'
+description: 'Setup build environment with dependencies and caching'
+inputs:
+  platform:
+    description: 'Target platform (linux, macos, windows)'
+    required: true
+  preset:
+    description: 'CMake preset to use'
+    required: true
+  cache-key:
+    description: 'Cache key for dependencies'
+    required: false
+    default: ''
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup CPM cache
+      if: inputs.cache-key != ''
+      uses: actions/cache@v4
+      with:
+        path: ~/.cpm-cache
+        key: cpm-${{ inputs.platform }}-${{ inputs.cache-key }}
+        restore-keys: |
+          cpm-${{ inputs.platform }}-
+
+    - name: Setup build environment (Linux)
+      if: inputs.platform == 'linux'
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y $(tr '\n' ' ' < .github/workflows/scripts/linux-ci-packages.txt) gcc-12 g++-12
+        sudo apt-get clean
+
+    - name: Setup build environment (macOS)
+      if: inputs.platform == 'macos'
+      shell: bash
+      run: |
+        brew install ninja pkg-config ccache
+        if ! command -v cmake &> /dev/null; then
+          brew install cmake
+        fi
+
+    - name: Setup build environment (Windows)
+      if: inputs.platform == 'windows'
+      shell: pwsh
+      run: |
+        choco install --no-progress -y nasm ccache
+        if ($env:ChocolateyInstall) {
+          $profilePath = Join-Path $env:ChocolateyInstall "helpers\chocolateyProfile.psm1"
+          if (Test-Path $profilePath) {
+            Import-Module $profilePath
+            refreshenv
+          }
+        }
+        # Ensure Git can handle long paths and cached directories when cloning gRPC dependencies
+        git config --global core.longpaths true
+        git config --global --add safe.directory '*'
+
+    - name: Setup sccache
+      uses: hendrikmuhs/ccache-action@v1.2
+      with:
+        key: ${{ inputs.platform }}-${{ github.sha }}
+        restore-keys: |
+          ${{ inputs.platform }}-
+        max-size: 500M
+        variant: sccache
+
+    - name: Configure compiler for Windows
+      if: inputs.platform == 'windows'
+      shell: pwsh
+      run: |
+        echo "CC=clang-cl" >> $env:GITHUB_ENV
+        echo "CXX=clang-cl" >> $env:GITHUB_ENV
+        echo "CMAKE_CXX_COMPILER_LAUNCHER=sccache" >> $env:GITHUB_ENV
+        echo "CMAKE_C_COMPILER_LAUNCHER=sccache" >> $env:GITHUB_ENV
+

.github/scripts/validate-actions.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# Validate GitHub Actions composite action structure
+
+set -e
+
+echo "Validating GitHub Actions composite actions..."
+
+ACTIONS_DIR=".github/actions"
+REQUIRED_FIELDS=("name" "description" "runs")
+
+validate_action() {
+    local action_file="$1"
+    local action_name=$(basename $(dirname "$action_file"))
+    
+    echo "Checking $action_name..."
+    
+    # Check if file exists
+    if [ ! -f "$action_file" ]; then
+        echo "  ✗ action.yml not found"
+        return 1
+    fi
+    
+    # Check required fields
+    for field in "${REQUIRED_FIELDS[@]}"; do
+        if ! grep -q "^${field}:" "$action_file"; then
+            echo "  ✗ Missing required field: $field"
+            return 1
+        fi
+    done
+    
+    # Check for 'using: composite'
+    if ! grep -q "using: 'composite'" "$action_file"; then
+        echo "  ✗ Not marked as composite action"
+        return 1
+    fi
+    
+    echo "  ✓ Valid composite action"
+    return 0
+}
+
+# Validate all actions
+all_valid=true
+for action_yml in "$ACTIONS_DIR"/*/action.yml; do
+    if ! validate_action "$action_yml"; then
+        all_valid=false
+    fi
+done
+
+# Check that CI workflow references actions correctly
+echo ""
+echo "Checking CI workflow..."
+CI_FILE=".github/workflows/ci.yml"
+
+if [ ! -f "$CI_FILE" ]; then
+    echo "  ✗ CI workflow not found"
+    all_valid=false
+else
+    # Check for checkout before action usage
+    if grep -q "uses: actions/checkout@v4" "$CI_FILE"; then
+        echo "  ✓ Repository checkout step present"
+    else
+        echo "  ✗ Missing checkout step"
+        all_valid=false
+    fi
+    
+    # Check for composite action references
+    action_refs=$(grep -c "uses: ./.github/actions/" "$CI_FILE" || echo "0")
+    if [ "$action_refs" -gt 0 ]; then
+        echo "  ✓ Found $action_refs composite action references"
+    else
+        echo "  ✗ No composite action references found"
+        all_valid=false
+    fi
+fi
+
+echo ""
+if [ "$all_valid" = true ]; then
+    echo "✓ All validations passed!"
+    exit 0
+else
+    echo "✗ Some validations failed"
+    exit 1
+fi
+

.github/workflows/build-windows-fallback.yml

@@ -1,151 +0,0 @@
-name: Windows Build Fallback
-
-on:
-  workflow_call:
-    inputs:
-      build_type:
-        description: 'Build type (Debug/Release)'
-        required: true
-        type: string
-        default: 'Release'
-      platform:
-        description: 'Platform (x64/x86)'
-        required: true
-        type: string
-        default: 'x64'
-
-env:
-  BUILD_TYPE: ${{ inputs.build_type }}
-  PLATFORM: ${{ inputs.platform }}
-
-jobs:
-  build-windows-fallback:
-    name: Windows ${{ inputs.platform }} ${{ inputs.build_type }} (Fallback)
-    runs-on: windows-2022
-    
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        submodules: recursive
-
-    # Try vcpkg first
-    - name: Set up vcpkg (Primary)
-      id: vcpkg_primary
-      uses: lukka/run-vcpkg@v11
-      continue-on-error: true
-      with:
-        vcpkgGitCommitId: 'c8696863d371ab7f46e213d8f5ca923c4aef2a00'
-        runVcpkgInstall: true
-        vcpkgJsonGlob: '**/vcpkg.json'
-        vcpkgDirectory: '${{ github.workspace }}/vcpkg'
-      env:
-        VCPKG_FORCE_SYSTEM_BINARIES: 1
-        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
-        VCPKG_DEFAULT_TRIPLET: '${{ inputs.platform }}-windows'
-        VCPKG_INSTALL_OPTIONS: '--x-install-root="${{ github.workspace }}/vcpkg_installed"'
-
-    # Fallback to newer baseline if primary fails
-    - name: Set up vcpkg (Fallback)
-      if: steps.vcpkg_primary.outcome == 'failure'
-      uses: lukka/run-vcpkg@v11
-      with:
-        vcpkgGitCommitId: '2024.01.12'
-        runVcpkgInstall: true
-        vcpkgJsonGlob: '**/vcpkg.json.backup'
-        vcpkgDirectory: '${{ github.workspace }}/vcpkg'
-      env:
-        VCPKG_FORCE_SYSTEM_BINARIES: 1
-        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
-        VCPKG_DEFAULT_TRIPLET: '${{ inputs.platform }}-windows'
-        VCPKG_INSTALL_OPTIONS: '--x-install-root="${{ github.workspace }}/vcpkg_installed"'
-
-    # Fallback to manual dependency installation if both vcpkg attempts fail
-    - name: Install dependencies manually
-      if: steps.vcpkg_primary.outcome == 'failure'
-      shell: pwsh
-      run: |
-        Write-Host "Installing dependencies manually using Chocolatey and pre-built libraries..."
-        
-        # Install Chocolatey if not present
-        if (-not (Get-Command choco -ErrorAction SilentlyContinue)) {
-          Set-ExecutionPolicy Bypass -Scope Process -Force
-          [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
-          iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
-        }
-        
-        # Install basic dependencies
-        choco install -y cmake ninja
-        
-        # Create a minimal build configuration
-        Write-Host "Creating minimal build configuration for CI..."
-        
-        # Set up environment variables for minimal build
-        echo "YAZE_MINIMAL_BUILD=ON" >> $env:GITHUB_ENV
-        echo "CMAKE_PREFIX_PATH=$env:GITHUB_WORKSPACE\vcpkg_installed\${{ inputs.platform }}-windows" >> $env:GITHUB_ENV
-
-    - name: Configure CMake
-      shell: cmd
-      run: |
-        if exist "${{ github.workspace }}\vcpkg_installed" (
-          echo "Using vcpkg installation..."
-          cmake -B build ^
-            -DCMAKE_BUILD_TYPE=%BUILD_TYPE% ^
-            -DCMAKE_POLICY_VERSION_MINIMUM=3.16 ^
-            -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake" ^
-            -DYAZE_BUILD_TESTS=OFF ^
-            -DYAZE_BUILD_EMU=OFF ^
-            -DYAZE_BUILD_Z3ED=OFF ^
-            -DYAZE_ENABLE_ROM_TESTS=OFF ^
-            -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF ^
-            -DYAZE_INSTALL_LIB=OFF ^
-            -DYAZE_MINIMAL_BUILD=ON ^
-            -G "Visual Studio 17 2022" ^
-            -A %PLATFORM%
-        ) else (
-          echo "Using minimal build configuration..."
-          cmake -B build ^
-            -DCMAKE_BUILD_TYPE=%BUILD_TYPE% ^
-            -DCMAKE_POLICY_VERSION_MINIMUM=3.16 ^
-            -DYAZE_BUILD_TESTS=OFF ^
-            -DYAZE_BUILD_EMU=OFF ^
-            -DYAZE_BUILD_Z3ED=OFF ^
-            -DYAZE_ENABLE_ROM_TESTS=OFF ^
-            -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF ^
-            -DYAZE_INSTALL_LIB=OFF ^
-            -DYAZE_MINIMAL_BUILD=ON ^
-            -G "Visual Studio 17 2022" ^
-            -A %PLATFORM%
-        )
-
-    - name: Build
-      run: cmake --build build --config %BUILD_TYPE% --parallel
-
-    - name: Test executable
-      shell: pwsh
-      run: |
-        $exePath = "build\bin\$env:BUILD_TYPE\yaze.exe"
-        if (Test-Path $exePath) {
-          Write-Host "✓ Executable created: $exePath" -ForegroundColor Green
-          
-          # Test that it's not the test main
-          $testResult = & $exePath --help 2>&1
-          if ($testResult -match "Google Test" -or $testResult -match "gtest") {
-            Write-Error "Executable is running test main instead of app main!"
-            exit 1
-          }
-          
-          Write-Host "✓ Executable runs correctly" -ForegroundColor Green
-        } else {
-          Write-Error "Executable not found at: $exePath"
-          exit 1
-        }
-
-    - name: Upload build artifacts
-      uses: actions/upload-artifact@v4
-      if: always()
-      with:
-        name: yaze-${{ inputs.platform }}-${{ inputs.build_type }}-fallback
-        path: |
-          build/bin/${{ inputs.build_type }}/
-        retention-days: 7

.github/workflows/ci.yml

@@ -1,5 +1,19 @@
 name: CI/CD Pipeline
 
+# Test Strategy:
+# - PR/Push: Run lean test set (stable tests + smoke tests) for fast feedback
+# - Nightly: Run comprehensive suite including ROM-dependent, experimental, benchmarks
+# - See .github/workflows/nightly.yml for extended test coverage
+#
+# Test Labels:
+# - stable: Core functionality tests that should always pass
+# - unit: Fast isolated component tests (subset of stable)
+# - integration: Multi-component tests (subset of stable)
+# - rom_dependent: Tests requiring Zelda3 ROM file (nightly only)
+# - experimental: AI and experimental feature tests (nightly only)
+# - gui: GUI/E2E tests with ImGuiTestEngine (nightly only)
+# - benchmark: Performance benchmarks (nightly only)
+
 on:
   push:
     branches: [ "master", "develop" ]
@@ -17,412 +31,279 @@ on:
       - 'cmake/**'
       - 'CMakeLists.txt'
       - '.github/workflows/**'
+  workflow_dispatch:
+    inputs:
+      build_type:
+        description: 'Build Type (Debug, Release, RelWithDebInfo)'
+        required: false
+        default: 'RelWithDebInfo'
+        type: choice
+        options:
+          - Debug
+          - Release
+          - RelWithDebInfo
+      run_sanitizers:
+        description: 'Run memory sanitizers'
+        required: false
+        default: false
+        type: boolean
+      upload_artifacts:
+        description: 'Upload build artifacts'
+        required: false
+        default: false
+        type: boolean
+      enable_http_api_tests:
+        description: 'Enable HTTP API tests'
+        required: false
+        default: false
+        type: boolean
 
 env:
-  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
-  BUILD_TYPE: RelWithDebInfo
-  VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
+  BUILD_TYPE: ${{ github.event.inputs.build_type || 'RelWithDebInfo' }}
 
 jobs:
-  build-and-test:
+  build:
+    name: "Build - ${{ matrix.name }}"
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         include:
           - name: "Ubuntu 22.04 (GCC-12)"
             os: ubuntu-22.04
-            cc: gcc-12
-            cxx: g++-12
-            vcpkg_triplet: x64-linux
-            
-          - name: "Ubuntu 22.04 (Clang)"
-            os: ubuntu-22.04
-            cc: clang-15
-            cxx: clang++-15
-            vcpkg_triplet: x64-linux
-            
-          - name: "macOS 13 (Clang)"
-            os: macos-13
-            cc: clang
-            cxx: clang++
-            vcpkg_triplet: x64-osx
-            
+            platform: linux
+            preset: ci-linux
           - name: "macOS 14 (Clang)"
             os: macos-14
-            cc: clang
-            cxx: clang++
-            vcpkg_triplet: arm64-osx
-            
-          - name: "Windows 2022 (MSVC x64)"
+            platform: macos
+            preset: ci-macos
+          - name: "Windows 2022 (Core)"
             os: windows-2022
-            cc: cl
-            cxx: cl
-            vcpkg_triplet: x64-windows
-            cmake_generator: "Visual Studio 17 2022"
-            cmake_generator_platform: x64
-            
-          - name: "Windows 2022 (MSVC x86)"
-            os: windows-2022
-            cc: cl
-            cxx: cl
-            vcpkg_triplet: x86-windows
-            cmake_generator: "Visual Studio 17 2022"
-            cmake_generator_platform: Win32
-
-    name: ${{ matrix.name }}
-    runs-on: ${{ matrix.os }}
+            platform: windows
+            preset: ci-windows
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           submodules: recursive
-        fetch-depth: 0
 
-    - name: Export GitHub Actions cache environment variables
-      uses: actions/github-script@v7
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
         with:
-        script: |
-          core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
-          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ github.sha }}
 
-    - name: Set up vcpkg cache
-      if: runner.os == 'Windows'
-      uses: actions/cache@v4
+      - name: Build project
+        uses: ./.github/actions/build-project
         with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: ${{ env.BUILD_TYPE }}
+
+      - name: Upload build artifacts (Windows)
+        if: matrix.platform == 'windows' && (github.event.inputs.upload_artifacts == 'true' || github.event_name == 'push')
+        uses: actions/upload-artifact@v4
+        with:
+          name: yaze-windows-ci-${{ github.run_number }}
           path: |
-          ${{ github.workspace }}/vcpkg
-          ${{ github.workspace }}/vcpkg_installed
-        key: vcpkg-${{ matrix.vcpkg_triplet }}-${{ hashFiles('vcpkg.json') }}
-        restore-keys: |
-          vcpkg-${{ matrix.vcpkg_triplet }}-
+            build/bin/*.exe
+            build/bin/*.dll
+            build/bin/${{ env.BUILD_TYPE }}/*.exe
+            build/bin/${{ env.BUILD_TYPE }}/*.dll
+          if-no-files-found: warn
+          retention-days: 3
 
-    # Linux-specific setup
-    - name: Install Linux dependencies
-      if: runner.os == 'Linux'
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y \
-          build-essential \
-          ninja-build \
-          pkg-config \
-          libglew-dev \
-          libxext-dev \
-          libwavpack-dev \
-          libabsl-dev \
-          libboost-all-dev \
-          libboost-python-dev \
-          libpng-dev \
-          python3-dev \
-          libpython3-dev \
-          libasound2-dev \
-          libpulse-dev \
-          libaudio-dev \
-          libx11-dev \
-          libxrandr-dev \
-          libxcursor-dev \
-          libxinerama-dev \
-          libxi-dev \
-          libxss-dev \
-          libxxf86vm-dev \
-          libxkbcommon-dev \
-          libwayland-dev \
-          libdecor-0-dev \
-          libgtk-3-dev \
-          libdbus-1-dev \
-          gcc-12 \
-          g++-12 \
-          clang-15
+  test:
+    name: "Test - ${{ matrix.name }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: "Ubuntu 22.04"
+            os: ubuntu-22.04
+            platform: linux
+            preset: ci-linux
+          - name: "macOS 14"
+            os: macos-14
+            platform: macos
+            preset: ci-macos
+          - name: "Windows 2022 (Core)"
+            os: windows-2022
+            platform: windows
+            preset: ci-windows
 
-    - name: Set up Linux compilers
-      if: runner.os == 'Linux'
-      run: |
-        sudo update-alternatives --install /usr/bin/cc cc /usr/bin/${{ matrix.cc }} 100
-        sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/${{ matrix.cxx }} 100
-
-    # macOS-specific setup
-    - name: Install macOS dependencies
-      if: runner.os == 'macOS'
-      run: |
-        # Install Homebrew dependencies if needed
-        # brew install pkg-config libpng boost abseil
-
-    # Windows-specific setup (skip vcpkg for CI builds)
-    - name: Set up vcpkg (non-CI builds only)
-      if: runner.os == 'Windows' && github.event_name != 'push' && github.event_name != 'pull_request'
-      uses: lukka/run-vcpkg@v11
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
         with:
-        vcpkgGitCommitId: 'c8696863d371ab7f46e213d8f5ca923c4aef2a00'
-        runVcpkgInstall: true
-        vcpkgJsonGlob: '**/vcpkg.json'
-        vcpkgDirectory: '${{ github.workspace }}/vcpkg'
-    - name: Configure CMake (Linux/macOS)
-      if: runner.os != 'Windows'
+          submodules: recursive
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ github.sha }}
+
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: ${{ env.BUILD_TYPE }}
+
+      - name: Run stable tests only
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: stable
+          preset: ${{ matrix.preset }}
+
+      - name: Run smoke tests (GUI framework validation)
+        if: matrix.platform == 'linux'
         run: |
-        cmake -B ${{ github.workspace }}/build \
-          -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
-          -DCMAKE_C_COMPILER=${{ matrix.cc }} \
-          -DCMAKE_CXX_COMPILER=${{ matrix.cxx }} \
-          -DCMAKE_POLICY_VERSION_MINIMUM=3.16 \
-          -DYAZE_MINIMAL_BUILD=ON \
-          -DYAZE_ENABLE_ROM_TESTS=OFF \
-          -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF \
-          -DYAZE_ENABLE_UI_TESTS=OFF \
-          -Wno-dev \
-          -GNinja
-
-    - name: Configure CMake (Windows)
-      if: runner.os == 'Windows'
-      shell: cmd
-      run: |
-        cmake -B ${{ github.workspace }}/build -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} -DCMAKE_POLICY_VERSION_MINIMUM=3.16 -DYAZE_MINIMAL_BUILD=ON -DYAZE_ENABLE_ROM_TESTS=OFF -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF -DYAZE_ENABLE_UI_TESTS=OFF -Wno-dev -G "${{ matrix.cmake_generator }}" -A ${{ matrix.cmake_generator_platform }}
-
-    # Build
-    - name: Build
-      run: cmake --build ${{ github.workspace }}/build --config ${{ env.BUILD_TYPE }} --parallel
-
-    # Test (stable core functionality only for CI)
-    - name: Run Core Tests
-      working-directory: ${{ github.workspace }}/build
-      run: ctest --build-config ${{ env.BUILD_TYPE }} --output-on-failure -j1 -R "AsarWrapperTest|SnesTileTest|CompressionTest|SnesPaletteTest|HexTest"
-      
-    # Run experimental tests separately (allowed to fail for information only)
-    - name: Run Additional Tests (Informational)
-      working-directory: ${{ github.workspace }}/build
+          cd build
+          # Run just the smoke tests to validate GUI framework is working
+          ./bin/yaze_test_gui -nogui --gtest_filter="*Smoke*" || true
         continue-on-error: true
-      run: ctest --build-config ${{ env.BUILD_TYPE }} --output-on-failure --parallel -E "AsarWrapperTest|SnesTileTest|CompressionTest|SnesPaletteTest|HexTest|CpuTest|Spc700Test|ApuTest|MessageTest|.*IntegrationTest"
 
-    # Package (only on successful builds)
-    - name: Package artifacts
-      if: success()
-      run: |
-        cmake --build ${{ github.workspace }}/build --config ${{ env.BUILD_TYPE }} --target package
+      - name: Run HTTP API tests
+        if: github.event.inputs.enable_http_api_tests == 'true'
+        run: scripts/agents/test-http-api.sh
 
-    # Upload artifacts
-    - name: Upload build artifacts
-      if: success()
-      uses: actions/upload-artifact@v4
+  windows-agent:
+    name: "Windows Agent (Full Stack)"
+    runs-on: windows-2022
+    needs: [build, test]
+    if: github.event_name != 'pull_request'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
         with:
-        name: yaze-${{ matrix.name }}-${{ github.sha }}
-        path: |
-          ${{ github.workspace }}/build/bin/
-          ${{ github.workspace }}/build/lib/
-        retention-days: 7
+          submodules: recursive
 
-    # Upload packages for release candidates
-    - name: Upload package artifacts
-      if: success() && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/'))
-      uses: actions/upload-artifact@v4
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
         with:
-        name: yaze-package-${{ matrix.name }}-${{ github.sha }}
-        path: |
-          ${{ github.workspace }}/build/*.tar.gz
-          ${{ github.workspace }}/build/*.zip
-          ${{ github.workspace }}/build/*.dmg
-          ${{ github.workspace }}/build/*.msi
-        retention-days: 30
+          platform: windows
+          preset: ci-windows-ai
+          cache-key: ${{ github.sha }}
+
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: windows
+          preset: ci-windows-ai
+          build-type: ${{ env.BUILD_TYPE }}
+
+      - name: Run stable tests only (agent stack)
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: stable
+          preset: ci-windows-ai
 
   code-quality:
-    name: Code Quality Checks
+    name: "Code Quality"
     runs-on: ubuntu-22.04
-    # Relaxed requirements for releases and master branch:
-    # - Formatting errors become warnings
-    # - Fewer cppcheck categories enabled  
-    # - Reduced clang-tidy file count
-    # - Job failure won't block releases
     continue-on-error: ${{ github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/') }}
     
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        submodules: recursive
+    - uses: actions/checkout@v4
     
-    - name: Install dependencies
+    - name: Install Tools
       run: |
         sudo apt-get update
-        sudo apt-get install -y \
-          clang-format-14 \
-          clang-tidy-14 \
-          cppcheck
+        sudo apt-get install -y clang-format-14 clang-tidy-14 cppcheck
     
-    - name: Check code formatting
-      run: |
-        # Relaxed formatting check for releases and master branch
-        if [[ "${{ github.ref }}" == "refs/heads/master" ]] || [[ "${{ github.ref }}" == refs/tags/* ]] || [[ "${{ github.event_name }}" == "pull_request" && "${{ github.base_ref }}" == "master" ]]; then
-          echo "🔄 Running relaxed formatting check for release/master branch..."
-          find src test -name "*.cc" -o -name "*.h" | \
-          xargs clang-format-14 --dry-run --Werror || {
-            echo "⚠️  Code formatting issues found, but allowing for release builds"
-            echo "📝 Consider running 'make format' to fix formatting before next release"
-            exit 0
-          }
-        else
-          echo "🔍 Running strict formatting check for development..."
-          find src test -name "*.cc" -o -name "*.h" | \
-          xargs clang-format-14 --dry-run --Werror
-        fi
+    - name: Check Formatting
+      run: find src test -name "*.cc" -o -name "*.h" | xargs clang-format-14 --dry-run --Werror
     
     - name: Run cppcheck
       run: |
-        if [[ "${{ github.ref }}" == "refs/heads/master" ]] || [[ "${{ github.ref }}" == refs/tags/* ]]; then
-          echo "🔄 Running relaxed cppcheck for release/master branch..."
-          cppcheck --enable=warning \
-            --error-exitcode=0 \
-            --suppress=missingIncludeSystem \
-            --suppress=unusedFunction \
-            --suppress=unmatchedSuppression \
-            --suppress=variableScope \
-            --suppress=cstyleCast \
-            --suppress=unreadVariable \
-            --suppress=unusedStructMember \
-            --suppress=constParameter \
-            --suppress=constVariable \
-            --suppress=useStlAlgorithm \
-            --suppress=noExplicitConstructor \
-            --suppress=passedByValue \
-            --suppress=functionStatic \
-            src/ || echo "Cppcheck completed (non-blocking for releases)"
-        else
-          echo "🔍 Running standard cppcheck for development..."
-          cppcheck --enable=warning,style,performance \
-            --error-exitcode=0 \
-            --suppress=missingIncludeSystem \
-            --suppress=unusedFunction \
-            --suppress=unmatchedSuppression \
-            --suppress=variableScope \
-            --suppress=cstyleCast \
-            --suppress=unreadVariable \
-            --suppress=unusedStructMember \
-            --suppress=constParameter \
-            --suppress=constVariable \
-            --suppress=useStlAlgorithm \
-            --inconclusive \
-            src/ || echo "Cppcheck completed with warnings (non-blocking)"
-        fi
+        cppcheck --enable=warning,style,performance --error-exitcode=0 \
+          --suppress=missingIncludeSystem --suppress=unusedFunction --inconclusive src/
     
-    - name: Run clang-tidy (lenient)
+    - name: Run clang-tidy
       run: |
-        if [[ "${{ github.ref }}" == "refs/heads/master" ]] || [[ "${{ github.ref }}" == refs/tags/* ]]; then
-          echo "🔄 Running minimal clang-tidy for release/master branch..."
-          # Only check a small subset of critical files for releases
-          find src -name "*.cc" -not -path "*/lib/*" -not -path "*/gui/*" | head -10 | \
-          xargs clang-tidy-14 --config-file=.clang-tidy \
-          --header-filter='src/.*\.(h|hpp)$' || echo "Clang-tidy completed (non-blocking for releases)"
-        else
-          echo "🔍 Running standard clang-tidy for development..."
-          # Run clang-tidy on a subset of files to avoid overwhelming output
         find src -name "*.cc" -not -path "*/lib/*" | head -20 | \
-          xargs clang-tidy-14 --config-file=.clang-tidy \
-          --header-filter='src/.*\.(h|hpp)$' || echo "Clang-tidy completed with warnings (non-blocking)"
-        fi
+          xargs clang-tidy-14 --header-filter='src/.*\.(h|hpp)$'
 
   memory-sanitizer:
-    name: Memory Sanitizer (Linux)
+    name: "Memory Sanitizer"
     runs-on: ubuntu-22.04
-    if: github.event_name == 'pull_request'
+    if: |
+      github.event_name == 'pull_request' || 
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.run_sanitizers == 'true')
     
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
+    - uses: actions/checkout@v4
       with:
         submodules: recursive
     
-    - name: Install dependencies
+    - name: Install Dependencies
       run: |
         sudo apt-get update
         sudo apt-get install -y \
-          build-essential \
-          ninja-build \
-          clang-14 \
-          libc++-14-dev \
-          libc++abi-14-dev \
-          libglew-dev \
-          libxext-dev \
-          libwavpack-dev \
-          libpng-dev \
-          libgtk-3-dev \
-          libdbus-1-dev
+          build-essential ninja-build clang-14 libc++-14-dev libc++abi-14-dev \
+          libglew-dev libxext-dev libwavpack-dev libpng-dev libgtk-3-dev libdbus-1-dev
     
     - name: Configure with AddressSanitizer
       run: |
-        cmake -B ${{ github.workspace }}/build \
+        cmake -B build -G Ninja \
           -DCMAKE_BUILD_TYPE=Debug \
           -DCMAKE_C_COMPILER=clang-14 \
           -DCMAKE_CXX_COMPILER=clang++-14 \
           -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
-          -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
-          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address" \
-          -DYAZE_MINIMAL_BUILD=ON \
-          -DYAZE_ENABLE_ROM_TESTS=OFF \
-          -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF \
-          -GNinja
+          -DYAZE_BUILD_TESTS=ON
     
     - name: Build
-      run: cmake --build ${{ github.workspace }}/build --parallel
+      run: cmake --build build --parallel
     
-    - name: Test with AddressSanitizer
-      working-directory: ${{ github.workspace }}/build
+    - name: Test
+      working-directory: build
       env:
         ASAN_OPTIONS: detect_leaks=1:abort_on_error=1
       run: ctest --output-on-failure
 
-  coverage:
-    name: Code Coverage
-    runs-on: ubuntu-22.04
-    if: github.event_name == 'pull_request'
+  z3ed-agent-test:
+    name: "z3ed Agent"
+    runs-on: macos-14
+    # Only run on master/develop push, not on PRs (moved to nightly for PRs)
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/develop')
 
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
+    - uses: actions/checkout@v4
       with:
         submodules: recursive
     
-    - name: Install dependencies
+    - name: Install Dependencies
+      run: brew install ollama ninja
+    
+    - name: Build z3ed
       run: |
-        sudo apt-get update
-        sudo apt-get install -y \
-          build-essential \
-          ninja-build \
-          gcov \
-          lcov \
-          libglew-dev \
-          libxext-dev \
-          libwavpack-dev \
-          libpng-dev \
-          libgtk-3-dev \
-          libdbus-1-dev
+        cmake -B build_test -G Ninja \
+          -DCMAKE_BUILD_TYPE=Release \
+          -DZ3ED_AI=ON \
+          -DYAZE_BUILD_Z3ED=ON \
+          -DYAZE_ENABLE_AI_RUNTIME=ON \
+          -DYAZE_ENABLE_REMOTE_AUTOMATION=ON \
+          -DYAZE_BUILD_AGENT_UI=ON
+        cmake --build build_test --target z3ed
     
-    - name: Configure with coverage
+    - name: Start Ollama
+      env:
+        OLLAMA_MODEL: qwen2.5-coder:0.5b
       run: |
-        cmake -B ${{ github.workspace }}/build \
-          -DCMAKE_BUILD_TYPE=Debug \
-          -DCMAKE_CXX_FLAGS="--coverage" \
-          -DCMAKE_C_FLAGS="--coverage" \
-          -DCMAKE_EXE_LINKER_FLAGS="--coverage" \
-          -DYAZE_MINIMAL_BUILD=ON \
-          -DYAZE_ENABLE_ROM_TESTS=OFF \
-          -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF \
-          -GNinja
+        ollama serve & 
+        sleep 10
+        ollama pull "$OLLAMA_MODEL"
     
-    - name: Build
-      run: cmake --build ${{ github.workspace }}/build --parallel
-
-    - name: Test
-      working-directory: ${{ github.workspace }}/build
-      run: ctest --output-on-failure
-
-    - name: Generate coverage report
+    - name: Run Test Suite
+      env:
+        OLLAMA_MODEL: qwen2.5-coder:0.5b
       run: |
-        lcov --capture --directory ${{ github.workspace }}/build --output-file coverage.info
-        lcov --remove coverage.info '/usr/*' --output-file coverage.info
-        lcov --remove coverage.info '**/test/**' --output-file coverage.info
-        lcov --remove coverage.info '**/lib/**' --output-file coverage.info
-
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
-      with:
-        file: ./coverage.info
-        flags: unittests
-        name: codecov-umbrella
-        fail_ci_if_error: false
+        chmod +x ./scripts/agent_test_suite.sh
+        ./scripts/agent_test_suite.sh ollama

.github/workflows/claude-code-review.yml

@@ -0,0 +1,57 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

.github/workflows/code-quality.yml

@@ -0,0 +1,61 @@
+name: Code Quality
+
+on:
+  pull_request:
+    branches: [ "master", "develop" ]
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - 'cmake/**'
+      - 'CMakeLists.txt'
+  workflow_dispatch:
+
+jobs:
+  format-lint:
+    name: "Format & Lint"
+    runs-on: ubuntu-22.04
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install tooling
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y clang-format-14 clang-tidy-14 cppcheck
+
+    - name: Check Formatting
+      run: |
+        find src test -name "*.cc" -o -name "*.h" | xargs clang-format-14 --dry-run --Werror
+
+    - name: Run cppcheck
+      run: |
+        cppcheck --enable=warning,style,performance --error-exitcode=0 \
+          --suppress=missingIncludeSystem --suppress=unusedFunction --inconclusive src/
+
+    - name: Run clang-tidy
+      run: |
+        find src -name "*.cc" -not -path "*/lib/*" | head -20 | \
+          xargs clang-tidy-14 --header-filter='src/.*\.(h|hpp)$'
+
+  build-check:
+    name: "Build Check"
+    runs-on: ubuntu-22.04
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+    
+    - name: Setup build environment
+      uses: ./.github/actions/setup-build
+      with:
+        platform: linux
+        preset: ci
+        cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+    
+    - name: Build project
+      uses: ./.github/actions/build-project
+      with:
+        platform: linux
+        preset: ci
+        build-type: RelWithDebInfo

.github/workflows/doxy.yml

@@ -54,7 +54,7 @@ jobs:
 
     - name: Clean previous build
       if: steps.changes.outputs.docs_changed == 'true'
-      run: rm -rf html
+      run: rm -rf build/docs
 
     - name: Generate Doxygen documentation
       if: steps.changes.outputs.docs_changed == 'true'
@@ -68,7 +68,7 @@ jobs:
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./html
+        publish_dir: ./build/docs/html
         commit_message: 'docs: update API documentation'
         
     - name: Summary

.github/workflows/matrix-test.yml

@@ -0,0 +1,334 @@
+name: Configuration Matrix Testing
+
+on:
+  schedule:
+    # Run nightly at 2 AM UTC
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+    inputs:
+      tier:
+        description: 'Test tier to run'
+        required: false
+        default: 'tier2'
+        type: choice
+        options:
+          - all
+          - tier1
+          - tier2
+          - tier2-linux
+          - tier2-macos
+          - tier2-windows
+      verbose:
+        description: 'Verbose output'
+        required: false
+        default: false
+        type: boolean
+
+env:
+  BUILD_TYPE: RelWithDebInfo
+  CMAKE_BUILD_PARALLEL_LEVEL: 4
+
+jobs:
+  matrix-linux:
+    name: "Config Matrix - Linux - ${{ matrix.name }}"
+    runs-on: ubuntu-22.04
+    if: |
+      github.event_name == 'schedule' ||
+      github.event_name == 'workflow_dispatch' ||
+      contains(github.event.head_commit.message, '[matrix]')
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Tier 2: Feature Combination Tests
+          - name: "Minimal (no AI, no gRPC)"
+            config: minimal
+            preset: minimal
+            cflags: "-DYAZE_ENABLE_GRPC=OFF -DYAZE_ENABLE_AI=OFF -DYAZE_ENABLE_JSON=ON"
+
+          - name: "gRPC Only"
+            config: grpc-only
+            preset: ci-linux
+            cflags: "-DYAZE_ENABLE_GRPC=ON -DYAZE_ENABLE_REMOTE_AUTOMATION=OFF -DYAZE_ENABLE_AI_RUNTIME=OFF"
+
+          - name: "Full AI Stack"
+            config: full-ai
+            preset: ci-linux
+            cflags: "-DYAZE_ENABLE_GRPC=ON -DYAZE_ENABLE_REMOTE_AUTOMATION=ON -DYAZE_ENABLE_AI_RUNTIME=ON -DYAZE_ENABLE_JSON=ON"
+
+          - name: "CLI Only (no gRPC)"
+            config: cli-only-no-grpc
+            preset: minimal
+            cflags: "-DYAZE_ENABLE_GRPC=OFF -DYAZE_BUILD_GUI=OFF -DYAZE_BUILD_EMU=OFF"
+
+          - name: "HTTP API (gRPC + JSON)"
+            config: http-api
+            preset: ci-linux
+            cflags: "-DYAZE_ENABLE_GRPC=ON -DYAZE_ENABLE_HTTP_API=ON -DYAZE_ENABLE_JSON=ON"
+
+          - name: "No JSON (Ollama only)"
+            config: no-json
+            preset: ci-linux
+            cflags: "-DYAZE_ENABLE_JSON=OFF -DYAZE_ENABLE_GRPC=ON"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: linux
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+
+      - name: Configure CMake
+        run: |
+          cmake --preset ${{ matrix.preset }} \
+            -B build_matrix_${{ matrix.config }} \
+            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
+            ${{ matrix.cflags }}
+
+      - name: Verify configuration
+        run: |
+          # Print resolved configuration
+          echo "=== Configuration Summary ==="
+          grep "YAZE_BUILD\|YAZE_ENABLE" build_matrix_${{ matrix.config }}/CMakeCache.txt | sort || true
+          echo "=============================="
+
+      - name: Build project
+        run: |
+          cmake --build build_matrix_${{ matrix.config }} \
+            --config ${{ env.BUILD_TYPE }} \
+            --parallel 4
+
+      - name: Run unit tests (if built)
+        if: ${{ hashFiles(format('build_matrix_{0}/bin/yaze_test', matrix.config)) != '' }}
+        run: |
+          ./build_matrix_${{ matrix.config }}/bin/yaze_test --unit 2>&1 | head -100
+        continue-on-error: true
+
+      - name: Run stable tests
+        if: ${{ hashFiles(format('build_matrix_{0}/bin/yaze_test', matrix.config)) != '' }}
+        run: |
+          ./build_matrix_${{ matrix.config }}/bin/yaze_test --stable 2>&1 | head -100
+        continue-on-error: true
+
+      - name: Report results
+        if: always()
+        run: |
+          if [ -f build_matrix_${{ matrix.config }}/CMakeCache.txt ]; then
+            echo "✓ Configuration: ${{ matrix.name }}"
+            echo "✓ Build: SUCCESS"
+          else
+            echo "✗ Configuration: ${{ matrix.name }}"
+            echo "✗ Build: FAILED"
+            exit 1
+          fi
+
+  matrix-macos:
+    name: "Config Matrix - macOS - ${{ matrix.name }}"
+    runs-on: macos-14
+    if: |
+      github.event_name == 'schedule' ||
+      github.event_name == 'workflow_dispatch' ||
+      contains(github.event.head_commit.message, '[matrix]')
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Tier 2: macOS-specific tests
+          - name: "Minimal (GUI only, no AI)"
+            config: minimal
+            preset: mac-dbg
+            cflags: "-DYAZE_ENABLE_GRPC=OFF -DYAZE_ENABLE_AI=OFF"
+
+          - name: "Full Stack (gRPC + AI)"
+            config: full-ai
+            preset: mac-ai
+            cflags: "-DYAZE_ENABLE_GRPC=ON -DYAZE_ENABLE_AI_RUNTIME=ON"
+
+          - name: "Agent UI Only"
+            config: agent-ui
+            preset: mac-dbg
+            cflags: "-DYAZE_BUILD_AGENT_UI=ON -DYAZE_ENABLE_GRPC=OFF -DYAZE_ENABLE_AI=OFF"
+
+          - name: "Universal Binary (Intel + ARM)"
+            config: universal
+            preset: mac-uni
+            cflags: "-DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' -DYAZE_ENABLE_GRPC=OFF"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: macos
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+
+      - name: Configure CMake
+        run: |
+          cmake --preset ${{ matrix.preset }} \
+            -B build_matrix_${{ matrix.config }} \
+            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
+            ${{ matrix.cflags }}
+
+      - name: Verify configuration
+        run: |
+          echo "=== Configuration Summary ==="
+          grep "YAZE_BUILD\|YAZE_ENABLE" build_matrix_${{ matrix.config }}/CMakeCache.txt | sort || true
+          echo "=============================="
+
+      - name: Build project
+        run: |
+          cmake --build build_matrix_${{ matrix.config }} \
+            --config ${{ env.BUILD_TYPE }} \
+            --parallel 4
+
+      - name: Run unit tests
+        if: ${{ hashFiles(format('build_matrix_{0}/bin/yaze_test', matrix.config)) != '' }}
+        run: |
+          ./build_matrix_${{ matrix.config }}/bin/yaze_test --unit 2>&1 | head -100
+        continue-on-error: true
+
+      - name: Report results
+        if: always()
+        run: |
+          if [ -f build_matrix_${{ matrix.config }}/CMakeCache.txt ]; then
+            echo "✓ Configuration: ${{ matrix.name }}"
+            echo "✓ Build: SUCCESS"
+          else
+            echo "✗ Configuration: ${{ matrix.name }}"
+            echo "✗ Build: FAILED"
+            exit 1
+          fi
+
+  matrix-windows:
+    name: "Config Matrix - Windows - ${{ matrix.name }}"
+    runs-on: windows-2022
+    if: |
+      github.event_name == 'schedule' ||
+      github.event_name == 'workflow_dispatch' ||
+      contains(github.event.head_commit.message, '[matrix]')
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Tier 2: Windows-specific tests
+          - name: "Minimal (no AI, no gRPC)"
+            config: minimal
+            preset: win-dbg
+            cflags: "-DYAZE_ENABLE_GRPC=OFF -DYAZE_ENABLE_AI=OFF"
+
+          - name: "Full AI Stack"
+            config: full-ai
+            preset: win-ai
+            cflags: "-DYAZE_ENABLE_GRPC=ON -DYAZE_ENABLE_AI_RUNTIME=ON"
+
+          - name: "gRPC + Remote Automation"
+            config: grpc-remote
+            preset: ci-windows
+            cflags: "-DYAZE_ENABLE_GRPC=ON -DYAZE_ENABLE_REMOTE_AUTOMATION=ON"
+
+          - name: "z3ed CLI Only"
+            config: z3ed-cli
+            preset: win-z3ed
+            cflags: "-DYAZE_BUILD_Z3ED=ON -DYAZE_BUILD_GUI=OFF -DYAZE_ENABLE_GRPC=ON"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: windows
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+
+      - name: Configure CMake
+        run: |
+          cmake --preset ${{ matrix.preset }} `
+            -B build_matrix_${{ matrix.config }} `
+            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} `
+            ${{ matrix.cflags }}
+
+      - name: Verify configuration
+        run: |
+          Write-Output "=== Configuration Summary ==="
+          Select-String "YAZE_BUILD|YAZE_ENABLE" build_matrix_${{ matrix.config }}/CMakeCache.txt | Sort-Object | Write-Output
+          Write-Output "==============================="
+
+      - name: Build project
+        run: |
+          cmake --build build_matrix_${{ matrix.config }} `
+            --config ${{ env.BUILD_TYPE }} `
+            --parallel 4
+
+      - name: Run unit tests
+        if: ${{ hashFiles(format('build_matrix_{0}\bin\{1}\yaze_test.exe', matrix.config, env.BUILD_TYPE)) != '' }}
+        run: |
+          .\build_matrix_${{ matrix.config }}\bin\${{ env.BUILD_TYPE }}\yaze_test.exe --unit 2>&1 | Select-Object -First 100
+        continue-on-error: true
+
+      - name: Report results
+        if: always()
+        run: |
+          if (Test-Path build_matrix_${{ matrix.config }}/CMakeCache.txt) {
+            Write-Output "✓ Configuration: ${{ matrix.name }}"
+            Write-Output "✓ Build: SUCCESS"
+          } else {
+            Write-Output "✗ Configuration: ${{ matrix.name }}"
+            Write-Output "✗ Build: FAILED"
+            exit 1
+          }
+
+  # Aggregation job that depends on all matrix jobs
+  matrix-summary:
+    name: Matrix Test Summary
+    runs-on: ubuntu-latest
+    if: always()
+    needs: [matrix-linux, matrix-macos, matrix-windows]
+    steps:
+      - name: Check all matrix tests
+        run: |
+          echo "=== Matrix Test Results ==="
+          if [ "${{ needs.matrix-linux.result }}" == "failure" ]; then
+            echo "✗ Linux tests FAILED"
+            exit 1
+          else
+            echo "✓ Linux tests passed"
+          fi
+
+          if [ "${{ needs.matrix-macos.result }}" == "failure" ]; then
+            echo "✗ macOS tests FAILED"
+            exit 1
+          else
+            echo "✓ macOS tests passed"
+          fi
+
+          if [ "${{ needs.matrix-windows.result }}" == "failure" ]; then
+            echo "✗ Windows tests FAILED"
+            exit 1
+          else
+            echo "✓ Windows tests passed"
+          fi
+          echo "==============================="
+
+      - name: Report success
+        if: success()
+        run: echo "✓ All matrix tests passed!"
+
+      - name: Post to coordination board (if configured)
+        if: always()
+        run: |
+          echo "Matrix testing complete. Update coordination-board.md if needed."

.github/workflows/nightly.yml

@@ -0,0 +1,506 @@
+name: Nightly Test Suite
+
+on:
+  schedule:
+    # Run nightly at 3 AM UTC
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+    inputs:
+      test_suites:
+        description: 'Test suites to run'
+        required: false
+        default: 'all'
+        type: choice
+        options:
+          - all
+          - rom_dependent
+          - experimental
+          - benchmarks
+          - gui_e2e
+          - extended_integration
+      rom_path:
+        description: 'ROM path for ROM-dependent tests (optional)'
+        required: false
+        default: ''
+        type: string
+
+env:
+  BUILD_TYPE: RelWithDebInfo
+
+jobs:
+  rom-dependent-tests:
+    name: "ROM-Dependent Tests - ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    if: |
+      github.event_name == 'schedule' ||
+      github.event.inputs.test_suites == 'all' ||
+      github.event.inputs.test_suites == 'rom_dependent'
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-14, windows-2022]
+        include:
+          - os: ubuntu-22.04
+            platform: linux
+            preset: ci-linux
+          - os: macos-14
+            platform: macos
+            preset: ci-macos
+          - os: windows-2022
+            platform: windows
+            preset: ci-windows
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Compute dependency lock hash
+        id: deps-hash
+        shell: bash
+        run: |
+          python_cmd="$(command -v python3 || command -v python || true)"
+          if [ -z "$python_cmd" ]; then
+            echo "hash=none" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          hash=$("$python_cmd" - <<'PY'
+import hashlib
+import pathlib
+path = pathlib.Path("cmake/dependencies.lock")
+if path.is_file():
+    print(hashlib.sha256(path.read_bytes()).hexdigest())
+else:
+    print("none")
+PY
+)
+          echo "hash=$hash" >> "$GITHUB_OUTPUT"
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
+
+      - name: Configure with ROM tests enabled
+        run: |
+          cmake --preset ${{ matrix.preset }} \
+            -B build_nightly \
+            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
+            -DYAZE_ENABLE_ROM_TESTS=ON \
+            -DYAZE_TEST_ROM_PATH="${{ github.event.inputs.rom_path || 'test_rom.sfc' }}"
+
+      - name: Build project
+        run: |
+          cmake --build build_nightly \
+            --config ${{ env.BUILD_TYPE }} \
+            --target yaze_test_rom_dependent \
+            --parallel
+
+      - name: Download test ROM (if available)
+        if: secrets.TEST_ROM_URL != ''
+        run: |
+          # This would download a test ROM from a secure location
+          # For now, this is a placeholder for ROM acquisition
+          echo "ROM acquisition would happen here"
+        continue-on-error: true
+
+      - name: Run ROM-dependent tests
+        if: hashFiles('test_rom.sfc') != '' || github.event.inputs.rom_path != ''
+        run: |
+          cd build_nightly
+          ctest -L rom_dependent \
+            --output-on-failure \
+            --output-junit rom_dependent_results.xml
+        continue-on-error: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: rom-test-results-${{ matrix.platform }}
+          path: build_nightly/rom_dependent_results.xml
+          retention-days: 30
+
+  experimental-ai-tests:
+    name: "Experimental AI Tests - ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    if: |
+      github.event_name == 'schedule' ||
+      github.event.inputs.test_suites == 'all' ||
+      github.event.inputs.test_suites == 'experimental'
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-14, windows-2022]
+        include:
+          - os: ubuntu-22.04
+            platform: linux
+            preset: ci-linux
+          - os: macos-14
+            platform: macos
+            preset: ci-macos
+          - os: windows-2022
+            platform: windows
+            preset: ci-windows-ai
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Compute dependency lock hash
+        id: deps-hash
+        shell: bash
+        run: |
+          python_cmd="$(command -v python3 || command -v python || true)"
+          if [ -z "$python_cmd" ]; then
+            echo "hash=none" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          hash=$("$python_cmd" - <<'PY'
+import hashlib
+import pathlib
+path = pathlib.Path("cmake/dependencies.lock")
+if path.is_file():
+    print(hashlib.sha256(path.read_bytes()).hexdigest())
+else:
+    print("none")
+PY
+)
+          echo "hash=$hash" >> "$GITHUB_OUTPUT"
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
+
+      - name: Configure with AI runtime enabled
+        run: |
+          cmake --preset ${{ matrix.preset }} \
+            -B build_nightly \
+            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
+            -DYAZE_ENABLE_AI_RUNTIME=ON \
+            -DYAZE_ENABLE_GRPC=ON \
+            -DYAZE_BUILD_AGENT_UI=ON
+
+      - name: Build project
+        run: |
+          cmake --build build_nightly \
+            --config ${{ env.BUILD_TYPE }} \
+            --target yaze_test_experimental \
+            --parallel
+
+      - name: Setup Ollama (Linux/macOS)
+        if: runner.os != 'Windows'
+        run: |
+          if [ "${{ runner.os }}" = "macOS" ]; then
+            brew install ollama || true
+          else
+            curl -fsSL https://ollama.com/install.sh | sh || true
+          fi
+          ollama serve &
+          sleep 10
+          ollama pull qwen2.5-coder:0.5b || true
+        continue-on-error: true
+
+      - name: Run experimental AI tests
+        run: |
+          cd build_nightly
+          ctest -L experimental \
+            --output-on-failure \
+            --timeout 600 \
+            --output-junit experimental_results.xml
+        continue-on-error: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: experimental-test-results-${{ matrix.platform }}
+          path: build_nightly/experimental_results.xml
+          retention-days: 30
+
+  gui-e2e-tests:
+    name: "GUI E2E Tests - ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    if: |
+      github.event_name == 'schedule' ||
+      github.event.inputs.test_suites == 'all' ||
+      github.event.inputs.test_suites == 'gui_e2e'
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-14]  # Windows GUI tests are flaky in CI
+        include:
+          - os: ubuntu-22.04
+            platform: linux
+            preset: ci-linux
+          - os: macos-14
+            platform: macos
+            preset: ci-macos
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Compute dependency lock hash
+        id: deps-hash
+        shell: bash
+        run: |
+          python_cmd="$(command -v python3 || command -v python || true)"
+          if [ -z "$python_cmd" ]; then
+            echo "hash=none" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          hash=$("$python_cmd" - <<'PY'
+import hashlib
+import pathlib
+path = pathlib.Path("cmake/dependencies.lock")
+if path.is_file():
+    print(hashlib.sha256(path.read_bytes()).hexdigest())
+else:
+    print("none")
+PY
+)
+          echo "hash=$hash" >> "$GITHUB_OUTPUT"
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
+
+      - name: Install GUI dependencies (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y xvfb libgl1-mesa-dev libglu1-mesa-dev
+
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: ${{ env.BUILD_TYPE }}
+
+      - name: Run GUI E2E tests (Linux with Xvfb)
+        if: runner.os == 'Linux'
+        run: |
+          xvfb-run -a ./build/bin/yaze_test_gui \
+            --e2e \
+            --nogui \
+            --output-junit gui_e2e_results.xml
+        continue-on-error: true
+
+      - name: Run GUI E2E tests (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          ./build/bin/yaze_test_gui \
+            --e2e \
+            --nogui \
+            --output-junit gui_e2e_results.xml
+        continue-on-error: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: gui-e2e-results-${{ matrix.platform }}
+          path: gui_e2e_results.xml
+          retention-days: 30
+
+  benchmark-tests:
+    name: "Performance Benchmarks"
+    runs-on: ubuntu-22.04
+    if: |
+      github.event_name == 'schedule' ||
+      github.event.inputs.test_suites == 'all' ||
+      github.event.inputs.test_suites == 'benchmarks'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: linux
+          preset: ci-linux
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
+
+      - name: Build benchmarks
+        run: |
+          cmake --preset ci-linux \
+            -B build_bench \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DYAZE_BUILD_TESTS=ON
+          cmake --build build_bench \
+            --config Release \
+            --target yaze_test_benchmark \
+            --parallel
+
+      - name: Run benchmarks
+        run: |
+          ./build_bench/bin/yaze_test_benchmark \
+            --benchmark_format=json \
+            --benchmark_out=benchmark_results.json
+        continue-on-error: true
+
+      - name: Upload benchmark results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark_results.json
+          retention-days: 90
+
+      - name: Compare with baseline (if exists)
+        if: hashFiles('benchmark_baseline.json') != ''
+        run: |
+          # Compare current results with baseline
+          # This would use a tool like google/benchmark's compare.py
+          echo "Benchmark comparison would happen here"
+        continue-on-error: true
+
+  extended-integration-tests:
+    name: "Extended Integration Tests"
+    runs-on: ubuntu-22.04
+    if: |
+      github.event_name == 'schedule' ||
+      github.event.inputs.test_suites == 'all' ||
+      github.event.inputs.test_suites == 'extended_integration'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: linux
+          preset: ci-linux
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
+
+      - name: Build with full features
+        run: |
+          cmake --preset ci-linux \
+            -B build_extended \
+            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
+            -DYAZE_ENABLE_GRPC=ON \
+            -DYAZE_ENABLE_JSON=ON \
+            -DYAZE_ENABLE_HTTP_API=ON \
+            -DYAZE_BUILD_AGENT_UI=ON
+          cmake --build build_extended \
+            --config ${{ env.BUILD_TYPE }} \
+            --parallel
+
+      - name: Run extended integration tests
+        run: |
+          cd build_extended
+          # Run all integration tests with extended timeout
+          ctest -L integration \
+            --output-on-failure \
+            --timeout 1200 \
+            --output-junit extended_integration_results.xml
+
+      - name: Run HTTP API tests
+        if: hashFiles('scripts/agents/test-http-api.sh') != ''
+        run: |
+          chmod +x scripts/agents/test-http-api.sh
+          scripts/agents/test-http-api.sh
+        continue-on-error: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: extended-integration-results
+          path: build_extended/extended_integration_results.xml
+          retention-days: 30
+
+  nightly-summary:
+    name: "Nightly Test Summary"
+    runs-on: ubuntu-latest
+    if: always()
+    needs: [
+      rom-dependent-tests,
+      experimental-ai-tests,
+      gui-e2e-tests,
+      benchmark-tests,
+      extended-integration-tests
+    ]
+
+    steps:
+      - name: Generate summary
+        run: |
+          echo "# Nightly Test Results - $(date +'%Y-%m-%d')" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          # ROM-Dependent Tests
+          if [ "${{ needs.rom-dependent-tests.result }}" == "success" ]; then
+            echo "✅ **ROM-Dependent Tests:** Passed" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ needs.rom-dependent-tests.result }}" == "skipped" ]; then
+            echo "⏭️ **ROM-Dependent Tests:** Skipped" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ **ROM-Dependent Tests:** Failed" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          # Experimental AI Tests
+          if [ "${{ needs.experimental-ai-tests.result }}" == "success" ]; then
+            echo "✅ **Experimental AI Tests:** Passed" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ needs.experimental-ai-tests.result }}" == "skipped" ]; then
+            echo "⏭️ **Experimental AI Tests:** Skipped" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ **Experimental AI Tests:** Failed" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          # GUI E2E Tests
+          if [ "${{ needs.gui-e2e-tests.result }}" == "success" ]; then
+            echo "✅ **GUI E2E Tests:** Passed" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ needs.gui-e2e-tests.result }}" == "skipped" ]; then
+            echo "⏭️ **GUI E2E Tests:** Skipped" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ **GUI E2E Tests:** Failed" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          # Benchmark Tests
+          if [ "${{ needs.benchmark-tests.result }}" == "success" ]; then
+            echo "✅ **Performance Benchmarks:** Completed" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ needs.benchmark-tests.result }}" == "skipped" ]; then
+            echo "⏭️ **Performance Benchmarks:** Skipped" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ **Performance Benchmarks:** Failed" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          # Extended Integration Tests
+          if [ "${{ needs.extended-integration-tests.result }}" == "success" ]; then
+            echo "✅ **Extended Integration Tests:** Passed" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ needs.extended-integration-tests.result }}" == "skipped" ]; then
+            echo "⏭️ **Extended Integration Tests:** Skipped" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ **Extended Integration Tests:** Failed" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "---" >> $GITHUB_STEP_SUMMARY
+          echo "*Nightly tests include comprehensive suites not run during PR/push CI.*" >> $GITHUB_STEP_SUMMARY
+
+      - name: Send notification (if configured)
+        if: failure() && vars.SLACK_WEBHOOK_URL != ''
+        run: |
+          # Send notification about nightly test failures
+          echo "Notification would be sent here"
+        continue-on-error: true

.github/workflows/release-complex.yml

@@ -1,712 +0,0 @@
-name: Release-Complex
-
-on:
-  push:
-    tags:
-      - 'v[0-9]+.[0-9]+.[0-9]+'
-      - 'v[0-9]+.[0-9]+.[0-9]+-*'
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Release tag (must start with v and follow semantic versioning)'
-        required: true
-        default: 'v0.3.0'
-        type: string
-
-env:
-  BUILD_TYPE: Release
-
-jobs:
-  validate-and-prepare:
-    name: Validate Release
-    runs-on: ubuntu-latest
-    outputs:
-      tag_name: ${{ steps.validate.outputs.tag_name }}
-      release_notes: ${{ steps.notes.outputs.content }}
-    
-    steps:
-    - name: Validate tag format
-      id: validate
-      run: |
-        # Debug information
-        echo "Event name: ${{ github.event_name }}"
-        echo "Ref: ${{ github.ref }}"
-        echo "Ref name: ${{ github.ref_name }}"
-        echo "Ref type: ${{ github.ref_type }}"
-        
-        # Determine the tag based on trigger type
-        if [[ "${{ github.event_name }}" == "push" ]]; then
-          if [[ "${{ github.ref_type }}" != "tag" ]]; then
-            echo "❌ Error: Release workflow triggered by push to ${{ github.ref_type }} '${{ github.ref_name }}'"
-            echo "This workflow should only be triggered by pushing version tags (v1.2.3)"
-            echo "Use: git tag v0.3.0 && git push origin v0.3.0"
-            exit 1
-          fi
-          TAG="${{ github.ref_name }}"
-        elif [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-          TAG="${{ github.event.inputs.tag }}"
-          if [[ -z "$TAG" ]]; then
-            echo "❌ Error: No tag specified for manual workflow dispatch"
-            exit 1
-          fi
-        else
-          echo "❌ Error: Unsupported event type: ${{ github.event_name }}"
-          exit 1
-        fi
-        
-        echo "Validating tag: $TAG"
-        
-        # Check if tag follows semantic versioning pattern
-        if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-.*)?$ ]]; then
-          echo "❌ Error: Tag '$TAG' does not follow semantic versioning format (v1.2.3 or v1.2.3-beta)"
-          echo "Valid examples: v0.3.0, v1.0.0, v2.1.3-beta, v1.0.0-rc1"
-          echo ""
-          echo "To create a proper release:"
-          echo "1. Use the helper script: ./scripts/create_release.sh 0.3.0"
-          echo "2. Or manually: git tag v0.3.0 && git push origin v0.3.0"
-          exit 1
-        fi
-        
-        echo "✅ Tag format is valid: $TAG"
-        echo "VALIDATED_TAG=$TAG" >> $GITHUB_ENV
-        echo "tag_name=$TAG" >> $GITHUB_OUTPUT
-    
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-
-    - name: Generate release notes
-      id: release_notes
-      run: |
-        # Extract release version from validated tag
-        VERSION="${VALIDATED_TAG}"
-        VERSION_NUM=$(echo "$VERSION" | sed 's/^v//')
-        
-        # Generate release notes using the dedicated script
-        echo "Extracting changelog for version: $VERSION_NUM"
-        if python3 scripts/extract_changelog.py "$VERSION_NUM" > release_notes.md; then
-          echo "Changelog extracted successfully"
-          echo "Release notes content:"
-          cat release_notes.md
-        else
-          echo "Failed to extract changelog, creating default release notes"
-          echo "# Yaze $VERSION Release Notes\n\nPlease see the full changelog at docs/C1-changelog.md" > release_notes.md
-        fi
-
-    - name: Store release notes
-      id: notes
-      run: |
-        # Store release notes content for later use
-        echo "content<<EOF" >> $GITHUB_OUTPUT
-        cat release_notes.md >> $GITHUB_OUTPUT
-        echo "EOF" >> $GITHUB_OUTPUT
-
-  build-release:
-    name: Build Release
-    needs: validate-and-prepare
-    strategy:
-      matrix:
-        include:
-          - name: "Windows x64"
-            os: windows-2022
-            vcpkg_triplet: x64-windows
-            cmake_generator: "Visual Studio 17 2022"
-            cmake_generator_platform: x64
-            artifact_name: "yaze-windows-x64"
-            artifact_path: "build/bin/Release/"
-            package_cmd: |
-              mkdir -p package
-              cp -r build/bin/Release/* package/ 2>/dev/null || echo "No Release binaries found, trying Debug..."
-              cp -r build/bin/Debug/* package/ 2>/dev/null || echo "No Debug binaries found"
-              cp -r assets package/ 2>/dev/null || echo "assets directory not found"
-              cp LICENSE package/ 2>/dev/null || echo "LICENSE not found"
-              cp README.md package/ 2>/dev/null || echo "README.md not found"
-              cd package && zip -r ../yaze-windows-x64.zip *
-            
-          - name: "Windows ARM64"
-            os: windows-2022
-            vcpkg_triplet: arm64-windows
-            cmake_generator: "Visual Studio 17 2022"
-            cmake_generator_platform: ARM64
-            artifact_name: "yaze-windows-arm64"
-            artifact_path: "build/bin/Release/"
-            package_cmd: |
-              mkdir -p package
-              cp -r build/bin/Release/* package/ 2>/dev/null || echo "No Release binaries found, trying Debug..."
-              cp -r build/bin/Debug/* package/ 2>/dev/null || echo "No Debug binaries found"
-              cp -r assets package/ 2>/dev/null || echo "assets directory not found"
-              cp LICENSE package/ 2>/dev/null || echo "LICENSE not found"
-              cp README.md package/ 2>/dev/null || echo "README.md not found"
-              cd package && zip -r ../yaze-windows-arm64.zip *
-            
-          - name: "macOS Universal"
-            os: macos-14
-            vcpkg_triplet: arm64-osx
-            artifact_name: "yaze-macos"
-            artifact_path: "build/bin/"
-            package_cmd: |
-              # Debug: List what was actually built
-              echo "Contents of build/bin/:"
-              ls -la build/bin/ || echo "build/bin/ does not exist"
-              
-              # Check if we have a bundle or standalone executable
-              if [ -d "build/bin/yaze.app" ]; then
-                echo "Found macOS bundle, using it directly"
-                # Use the existing bundle and just update it
-                cp -r build/bin/yaze.app ./Yaze.app
-                # Add additional resources to the bundle
-                cp -r assets "Yaze.app/Contents/Resources/" 2>/dev/null || echo "assets directory not found"
-                # Update Info.plist with correct version
-                if [ -f "cmake/yaze.plist.in" ]; then
-                  VERSION_NUM=$(echo "${{ needs.validate-and-prepare.outputs.tag_name }}" | sed 's/^v//')
-                  sed "s/@yaze_VERSION@/$VERSION_NUM/g" cmake/yaze.plist.in > "Yaze.app/Contents/Info.plist"
-                fi
-              else
-                echo "No bundle found, creating manual bundle"
-                # Create bundle structure manually
-                mkdir -p "Yaze.app/Contents/MacOS"
-                mkdir -p "Yaze.app/Contents/Resources"
-                cp build/bin/yaze "Yaze.app/Contents/MacOS/"
-                cp -r assets "Yaze.app/Contents/Resources/" 2>/dev/null || echo "assets directory not found"
-                # Create Info.plist with correct version
-                if [ -f "cmake/yaze.plist.in" ]; then
-                  VERSION_NUM=$(echo "${{ needs.validate-and-prepare.outputs.tag_name }}" | sed 's/^v//')
-                  sed "s/@yaze_VERSION@/$VERSION_NUM/g" cmake/yaze.plist.in > "Yaze.app/Contents/Info.plist"
-                else
-                  # Create a basic Info.plist
-                  VERSION_NUM=$(echo "${{ needs.validate-and-prepare.outputs.tag_name }}" | sed 's/^v//')
-                  echo '<?xml version="1.0" encoding="UTF-8"?>' > "Yaze.app/Contents/Info.plist"
-                  echo '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' >> "Yaze.app/Contents/Info.plist"
-                  echo '<plist version="1.0">' >> "Yaze.app/Contents/Info.plist"
-                  echo '<dict>' >> "Yaze.app/Contents/Info.plist"
-                  echo '<key>CFBundleExecutable</key>' >> "Yaze.app/Contents/Info.plist"
-                  echo '<string>yaze</string>' >> "Yaze.app/Contents/Info.plist"
-                  echo '<key>CFBundleIdentifier</key>' >> "Yaze.app/Contents/Info.plist"
-                  echo '<string>com.yaze.editor</string>' >> "Yaze.app/Contents/Info.plist"
-                  echo '<key>CFBundleName</key>' >> "Yaze.app/Contents/Info.plist"
-                  echo '<string>Yaze</string>' >> "Yaze.app/Contents/Info.plist"
-                  echo '<key>CFBundleVersion</key>' >> "Yaze.app/Contents/Info.plist"
-                  echo "<string>$VERSION_NUM</string>" >> "Yaze.app/Contents/Info.plist"
-                  echo '<key>CFBundleShortVersionString</key>' >> "Yaze.app/Contents/Info.plist"
-                  echo "<string>$VERSION_NUM</string>" >> "Yaze.app/Contents/Info.plist"
-                  echo '<key>CFBundlePackageType</key>' >> "Yaze.app/Contents/Info.plist"
-                  echo '<string>APPL</string>' >> "Yaze.app/Contents/Info.plist"
-                  echo '</dict>' >> "Yaze.app/Contents/Info.plist"
-                  echo '</plist>' >> "Yaze.app/Contents/Info.plist"
-                fi
-              fi
-              
-              # Create DMG
-              mkdir dmg_staging
-              cp -r Yaze.app dmg_staging/
-              cp LICENSE dmg_staging/ 2>/dev/null || echo "LICENSE not found"
-              cp README.md dmg_staging/ 2>/dev/null || echo "README.md not found"
-              cp -r docs dmg_staging/ 2>/dev/null || echo "docs directory not found"
-              hdiutil create -srcfolder dmg_staging -format UDZO -volname "Yaze ${{ needs.validate-and-prepare.outputs.tag_name }}" yaze-macos.dmg
-            
-          - name: "Linux x64"
-            os: ubuntu-22.04
-            artifact_name: "yaze-linux-x64"
-            artifact_path: "build/bin/"
-            package_cmd: |
-              mkdir package
-              cp build/bin/yaze package/
-              cp -r assets package/ 2>/dev/null || echo "assets directory not found"
-              cp -r docs package/ 2>/dev/null || echo "docs directory not found"
-              cp LICENSE package/ 2>/dev/null || echo "LICENSE not found"
-              cp README.md package/ 2>/dev/null || echo "README.md not found"
-              tar -czf yaze-linux-x64.tar.gz -C package .
-
-    runs-on: ${{ matrix.os }}
-    
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        submodules: recursive
-
-    # Clean up any potential vcpkg issues (Windows only)
-    - name: Clean vcpkg state (Windows)
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        Write-Host "Cleaning up any existing vcpkg state..."
-        if (Test-Path "vcpkg") {
-          Remove-Item -Recurse -Force "vcpkg" -ErrorAction SilentlyContinue
-        }
-        if (Test-Path "vcpkg_installed") {
-          Remove-Item -Recurse -Force "vcpkg_installed" -ErrorAction SilentlyContinue
-        }
-        Write-Host "Cleanup completed"
-
-    # Platform-specific dependency installation
-    - name: Install Linux dependencies
-      if: runner.os == 'Linux'
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y \
-          build-essential \
-          ninja-build \
-          pkg-config \
-          libglew-dev \
-          libxext-dev \
-          libwavpack-dev \
-          libabsl-dev \
-          libboost-all-dev \
-          libpng-dev \
-          python3-dev \
-          libpython3-dev \
-          libasound2-dev \
-          libpulse-dev \
-          libx11-dev \
-          libxrandr-dev \
-          libxcursor-dev \
-          libxinerama-dev \
-          libxi-dev
-
-    - name: Install macOS dependencies
-      if: runner.os == 'macOS'
-      run: |
-        # Install Homebrew dependencies needed for UI tests and full builds
-        brew install pkg-config libpng boost abseil ninja gtk+3
-
-    - name: Setup build environment
-      run: |
-        echo "Using streamlined release build configuration for all platforms"
-        echo "Linux/macOS: UI tests enabled with full dependency support"
-        echo "Windows: Full build with vcpkg integration for proper releases"
-        echo "All platforms: Emulator and developer tools disabled for clean releases"
-
-    # Configure CMake
-    - name: Configure CMake (Linux/macOS)
-      if: runner.os != 'Windows'
-      run: |
-        cmake -B build \
-          -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
-          -DCMAKE_POLICY_VERSION_MINIMUM=3.16 \
-          -DYAZE_BUILD_TESTS=OFF \
-          -DYAZE_BUILD_EMU=OFF \
-          -DYAZE_BUILD_Z3ED=OFF \
-          -DYAZE_ENABLE_UI_TESTS=ON \
-          -DYAZE_ENABLE_ROM_TESTS=OFF \
-          -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF \
-          -DYAZE_INSTALL_LIB=OFF \
-          -DYAZE_MINIMAL_BUILD=OFF \
-          -GNinja
-
-    # Set up vcpkg for Windows builds with fallback
-    - name: Set up vcpkg (Windows)
-      id: vcpkg_setup
-      if: runner.os == 'Windows'
-      uses: lukka/run-vcpkg@v11
-      continue-on-error: true
-      with:
-        vcpkgGitCommitId: 'c8696863d371ab7f46e213d8f5ca923c4aef2a00'
-        runVcpkgInstall: true
-        vcpkgJsonGlob: '**/vcpkg.json'
-        vcpkgDirectory: '${{ github.workspace }}/vcpkg'
-      env:
-        VCPKG_FORCE_SYSTEM_BINARIES: 1
-        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
-        VCPKG_DISABLE_METRICS: 1
-        VCPKG_DEFAULT_TRIPLET: ${{ matrix.vcpkg_triplet }}
-        VCPKG_ROOT: ${{ github.workspace }}/vcpkg
-
-    # Debug vcpkg failure (Windows only)
-    - name: Debug vcpkg failure (Windows)
-      if: runner.os == 'Windows' && steps.vcpkg_setup.outcome == 'failure'
-      shell: pwsh
-      run: |
-        Write-Host "=== vcpkg Setup Failed - Debug Information ===" -ForegroundColor Red
-        Write-Host "vcpkg directory exists: $(Test-Path 'vcpkg')"
-        Write-Host "vcpkg_installed directory exists: $(Test-Path 'vcpkg_installed')"
-        if (Test-Path "vcpkg") {
-          Write-Host "vcpkg directory contents:"
-          Get-ChildItem "vcpkg" | Select-Object -First 10
-        }
-        Write-Host "Git status:"
-        git status --porcelain
-        Write-Host "=============================================" -ForegroundColor Red
-
-    # Fallback: Install dependencies manually if vcpkg fails
-    - name: Install dependencies manually (Windows fallback)
-      if: runner.os == 'Windows' && steps.vcpkg_setup.outcome == 'failure'
-      shell: pwsh
-      run: |
-        Write-Host "vcpkg setup failed, installing dependencies manually..."
-        
-        # Install Chocolatey if not present
-        if (-not (Get-Command choco -ErrorAction SilentlyContinue)) {
-          Write-Host "Installing Chocolatey..."
-          Set-ExecutionPolicy Bypass -Scope Process -Force
-          [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
-          iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
-        }
-        
-        # Install basic build tools and dependencies
-        Write-Host "Installing build tools and dependencies..."
-        try {
-            choco install -y cmake ninja git python3
-            Write-Host "Successfully installed build tools via Chocolatey"
-        } catch {
-            Write-Host "Chocolatey installation failed, trying individual packages..."
-            choco install -y cmake || Write-Host "CMake installation failed"
-            choco install -y ninja || Write-Host "Ninja installation failed" 
-            choco install -y git || Write-Host "Git installation failed"
-            choco install -y python3 || Write-Host "Python3 installation failed"
-        }
-        
-        # Set up basic development environment
-        Write-Host "Setting up basic development environment..."
-        $env:Path += ";C:\Program Files\Git\bin"
-        
-        # Verify installations
-        Write-Host "Verifying installations..."
-        cmake --version
-        ninja --version
-        git --version
-        
-        # Set environment variable to indicate minimal build
-        echo "YAZE_MINIMAL_BUILD=ON" >> $env:GITHUB_ENV
-        echo "VCPKG_AVAILABLE=false" >> $env:GITHUB_ENV
-        
-        Write-Host "Manual dependency installation completed"
-        Write-Host "Build will proceed with minimal configuration (no vcpkg dependencies)"
-
-    # Set vcpkg availability flag when vcpkg succeeds
-    - name: Set vcpkg availability flag
-      if: runner.os == 'Windows' && steps.vcpkg_setup.outcome == 'success'
-      shell: pwsh
-      run: |
-        echo "VCPKG_AVAILABLE=true" >> $env:GITHUB_ENV
-        Write-Host "vcpkg setup successful"
-
-    - name: Configure CMake (Windows)
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        Write-Host "Configuring CMake for Windows build..."
-        
-        # Check if vcpkg is available
-        if ((Test-Path "${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake") -and ($env:VCPKG_AVAILABLE -ne "false")) {
-          Write-Host "Using vcpkg toolchain..."
-          cmake -B build `
-            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} `
-            -DCMAKE_POLICY_VERSION_MINIMUM=3.16 `
-            -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake" `
-            -DYAZE_BUILD_TESTS=OFF `
-            -DYAZE_BUILD_EMU=OFF `
-            -DYAZE_BUILD_Z3ED=OFF `
-            -DYAZE_ENABLE_ROM_TESTS=OFF `
-            -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF `
-            -DYAZE_INSTALL_LIB=OFF `
-            -DYAZE_MINIMAL_BUILD=OFF `
-            -G "${{ matrix.cmake_generator }}" `
-            -A ${{ matrix.cmake_generator_platform }}
-        } else {
-          Write-Host "Using minimal build configuration (vcpkg not available)..."
-          cmake -B build `
-            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} `
-            -DCMAKE_POLICY_VERSION_MINIMUM=3.16 `
-            -DYAZE_BUILD_TESTS=OFF `
-            -DYAZE_BUILD_EMU=OFF `
-            -DYAZE_BUILD_Z3ED=OFF `
-            -DYAZE_ENABLE_ROM_TESTS=OFF `
-            -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF `
-            -DYAZE_INSTALL_LIB=OFF `
-            -DYAZE_MINIMAL_BUILD=ON `
-            -G "${{ matrix.cmake_generator }}" `
-            -A ${{ matrix.cmake_generator_platform }}
-        }
-        
-        Write-Host "CMake configuration completed successfully"
-
-    # Verify CMake configuration (Windows only)
-    - name: Verify CMake configuration (Windows)
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        Write-Host "Verifying CMake configuration..."
-        if (Test-Path "build/CMakeCache.txt") {
-          Write-Host "✓ CMakeCache.txt found"
-          Write-Host "Build type: $(Select-String -Path 'build/CMakeCache.txt' -Pattern 'CMAKE_BUILD_TYPE' | ForEach-Object { $_.Line.Split('=')[1] })"
-          Write-Host "Minimal build: $(Select-String -Path 'build/CMakeCache.txt' -Pattern 'YAZE_MINIMAL_BUILD' | ForEach-Object { $_.Line.Split('=')[1] })"
-        } else {
-          Write-Error "CMakeCache.txt not found - CMake configuration failed!"
-          exit 1
-        }
-
-    # Build
-    - name: Build
-      run: |
-        echo "Building YAZE for ${{ matrix.name }}..."
-        cmake --build build --config ${{ env.BUILD_TYPE }} --parallel
-        echo "Build completed successfully!"
-
-    # Validate Visual Studio project builds (Windows only)
-    # Generate yaze_config.h for Visual Studio builds
-    - name: Generate yaze_config.h
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        $version = "${{ needs.validate-and-prepare.outputs.tag_name }}" -replace '^v', ''
-        $versionParts = $version -split '\.'
-        $major = if ($versionParts.Length -gt 0) { $versionParts[0] } else { "0" }
-        $minor = if ($versionParts.Length -gt 1) { $versionParts[1] } else { "0" }
-        $patch = if ($versionParts.Length -gt 2) { $versionParts[2] -split '-' | Select-Object -First 1 } else { "0" }
-        
-        Write-Host "Generating yaze_config.h with version: $major.$minor.$patch"
-        Copy-Item "src\yaze_config.h.in" "yaze_config.h"
-        (Get-Content 'yaze_config.h') -replace '@yaze_VERSION_MAJOR@', $major -replace '@yaze_VERSION_MINOR@', $minor -replace '@yaze_VERSION_PATCH@', $patch | Set-Content 'yaze_config.h'
-        Write-Host "Generated yaze_config.h:"
-        Get-Content 'yaze_config.h'
-
-    - name: Validate Visual Studio Project Build
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        $ErrorActionPreference = "Stop"
-        
-        Write-Host "========================================" -ForegroundColor Cyan
-        Write-Host "Validating Visual Studio Project Build" -ForegroundColor Cyan
-        Write-Host "Platform: ${{ matrix.cmake_generator_platform }}" -ForegroundColor Yellow
-        Write-Host "Configuration: ${{ env.BUILD_TYPE }}" -ForegroundColor Yellow
-        Write-Host "========================================" -ForegroundColor Cyan
-        
-        # Check if we're in the right directory
-        if (-not (Test-Path "yaze.sln")) {
-            Write-Error "yaze.sln not found. Please run this script from the project root directory."
-            exit 1
-        }
-        
-        Write-Host "✓ yaze.sln found" -ForegroundColor Green
-        
-        # Build using MSBuild
-        Write-Host "Building with MSBuild..." -ForegroundColor Yellow
-        $msbuildArgs = @(
-            "yaze.sln"
-            "/p:Configuration=${{ env.BUILD_TYPE }}"
-            "/p:Platform=${{ matrix.cmake_generator_platform }}"
-            "/p:VcpkgEnabled=true"
-            "/p:VcpkgManifestInstall=true"
-            "/m"  # Multi-processor build
-            "/verbosity:minimal"
-        )
-        
-        Write-Host "MSBuild command: msbuild $($msbuildArgs -join ' ')" -ForegroundColor Gray
-        & msbuild @msbuildArgs
-        
-        if ($LASTEXITCODE -ne 0) {
-            Write-Error "MSBuild failed with exit code $LASTEXITCODE"
-            exit 1
-        }
-        
-        Write-Host "✓ Visual Studio build completed successfully" -ForegroundColor Green
-        
-        # Verify executable was created
-        $exePath = "build\bin\${{ env.BUILD_TYPE }}\yaze.exe"
-        if (-not (Test-Path $exePath)) {
-            Write-Error "Executable not found at expected path: $exePath"
-            exit 1
-        }
-        
-        Write-Host "✓ Executable created: $exePath" -ForegroundColor Green
-        
-        # Test that the executable runs (basic test)
-        Write-Host "Testing executable startup..." -ForegroundColor Yellow
-        $testResult = & $exePath --help 2>&1
-        $exitCode = $LASTEXITCODE
-        
-        # Check if it's the test main or app main
-        if ($testResult -match "Google Test" -or $testResult -match "gtest") {
-            Write-Error "Executable is running test main instead of app main!"
-            Write-Host "Output: $testResult" -ForegroundColor Red
-            exit 1
-        }
-        
-        Write-Host "✓ Executable runs correctly (exit code: $exitCode)" -ForegroundColor Green
-        
-        Write-Host "========================================" -ForegroundColor Cyan
-        Write-Host "✓ Visual Studio build validation PASSED" -ForegroundColor Green
-        Write-Host "========================================" -ForegroundColor Cyan
-
-    # Test executable functionality (Windows)
-    - name: Test executable functionality (Windows)
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        $ErrorActionPreference = "Stop"
-        
-        # Debug: List build directory contents
-        Write-Host "Build directory contents:" -ForegroundColor Cyan
-        if (Test-Path "build") {
-            Get-ChildItem -Recurse build -Name | Select-Object -First 20
-        } else {
-            Write-Host "build directory does not exist" -ForegroundColor Red
-        }
-        
-        # Determine executable path for Windows
-        $exePath = "build\bin\${{ env.BUILD_TYPE }}\yaze.exe"
-        
-        if (Test-Path $exePath) {
-            Write-Host "✓ Executable found: $exePath" -ForegroundColor Green
-            
-            # Test that it's not the test main
-            $testResult = & $exePath --help 2>&1
-            $exitCode = $LASTEXITCODE
-            
-            if ($testResult -match "Google Test" -or $testResult -match "gtest") {
-                Write-Error "Executable is running test main instead of app main!"
-                Write-Host "Output: $testResult" -ForegroundColor Red
-                exit 1
-            }
-            
-            Write-Host "✓ Executable runs correctly (exit code: $exitCode)" -ForegroundColor Green
-            
-            # Display file info
-            $exeInfo = Get-Item $exePath
-            Write-Host "Executable size: $([math]::Round($exeInfo.Length / 1MB, 2)) MB" -ForegroundColor Cyan
-        } else {
-            Write-Error "Executable not found at: $exePath"
-            exit 1
-        }
-
-    # Test executable functionality (macOS)
-    - name: Test executable functionality (macOS)
-      if: runner.os == 'macOS'
-      shell: bash
-      run: |
-        set -e
-        
-        echo "Build directory contents:"
-        if [ -d "build" ]; then
-            find build -name "*.app" -o -name "yaze" | head -10
-        else
-            echo "build directory does not exist"
-            exit 1
-        fi
-        
-        # Determine executable path for macOS
-        exePath="build/bin/yaze.app/Contents/MacOS/yaze"
-        
-        if [ -f "$exePath" ]; then
-            echo "✓ Executable found: $exePath"
-            
-            # Test that it's not the test main
-            testResult=$($exePath --help 2>&1 || true)
-            exitCode=$?
-            
-            if echo "$testResult" | grep -q "Google Test\|gtest"; then
-                echo "ERROR: Executable is running test main instead of app main!"
-                echo "Output: $testResult"
-                exit 1
-            fi
-            
-            echo "✓ Executable runs correctly (exit code: $exitCode)"
-            
-            # Display file info
-            fileSize=$(stat -f%z "$exePath")
-            fileSizeMB=$(echo "scale=2; $fileSize / 1024 / 1024" | bc -l)
-            echo "Executable size: ${fileSizeMB} MB"
-        else
-            echo "ERROR: Executable not found at: $exePath"
-            exit 1
-        fi
-
-    # Test executable functionality (Linux)
-    - name: Test executable functionality (Linux)
-      if: runner.os == 'Linux'
-      shell: bash
-      run: |
-        set -e
-        
-        echo "Build directory contents:"
-        if [ -d "build" ]; then
-            find build -type f -name "yaze" | head -10
-        else
-            echo "build directory does not exist"
-            exit 1
-        fi
-        
-        # Determine executable path for Linux
-        exePath="build/bin/yaze"
-        
-        if [ -f "$exePath" ]; then
-            echo "✓ Executable found: $exePath"
-            
-            # Test that it's not the test main
-            testResult=$($exePath --help 2>&1 || true)
-            exitCode=$?
-            
-            if echo "$testResult" | grep -q "Google Test\|gtest"; then
-                echo "ERROR: Executable is running test main instead of app main!"
-                echo "Output: $testResult"
-                exit 1
-            fi
-            
-            echo "✓ Executable runs correctly (exit code: $exitCode)"
-            
-            # Display file info
-            fileSize=$(stat -c%s "$exePath")
-            fileSizeMB=$(echo "scale=2; $fileSize / 1024 / 1024" | bc -l)
-            echo "Executable size: ${fileSizeMB} MB"
-        else
-            echo "ERROR: Executable not found at: $exePath"
-            exit 1
-        fi
-
-    # Verify build artifacts
-    - name: Verify build artifacts
-      shell: bash
-      run: |
-        echo "Verifying build artifacts for ${{ matrix.name }}..."
-        if [ -d "build/bin" ]; then
-          echo "Build directory contents:"
-          find build/bin -type f -name "yaze*" -o -name "*.exe" -o -name "*.app" | head -10
-        else
-          echo "ERROR: build/bin directory not found!"
-          exit 1
-        fi
-
-    # Package
-    - name: Package
-      shell: bash
-      run: |
-        set -e
-        echo "Packaging for ${{ matrix.name }}..."
-        ${{ matrix.package_cmd }}
-        echo "Packaging completed successfully!"
-
-    # Create release with artifacts (will create release if it doesn't exist)
-    - name: Upload to Release
-      uses: softprops/action-gh-release@v1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      with:
-        tag_name: ${{ needs.validate-and-prepare.outputs.tag_name }}
-        name: Yaze ${{ needs.validate-and-prepare.outputs.tag_name }}
-        body: ${{ needs.validate-and-prepare.outputs.release_notes }}
-        draft: false
-        prerelease: ${{ contains(needs.validate-and-prepare.outputs.tag_name, 'beta') || contains(needs.validate-and-prepare.outputs.tag_name, 'alpha') || contains(needs.validate-and-prepare.outputs.tag_name, 'rc') }}
-        files: |
-          ${{ matrix.artifact_name }}.*
-        fail_on_unmatched_files: false
-
-  publish-packages:
-    name: Publish Packages
-    needs: [validate-and-prepare, build-release]
-    runs-on: ubuntu-latest
-    if: success()
-    
-    steps:
-    - name: Update release status
-      run: |
-        echo "Release has been published successfully"
-        echo "All build artifacts have been uploaded"
-
-    - name: Announce release
-      run: |
-        echo "🎉 Yaze ${{ needs.validate-and-prepare.outputs.tag_name }} has been released!"
-        echo "📦 Packages are now available for download"
-        echo "🔗 Release URL: https://github.com/${{ github.repository }}/releases/tag/${{ needs.validate-and-prepare.outputs.tag_name }}"

.github/workflows/release-simplified.yml

@@ -1,414 +0,0 @@
-name: Release-Simplified
-
-on:
-  push:
-    tags:
-      - 'v[0-9]+.[0-9]+.[0-9]+'
-      - 'v[0-9]+.[0-9]+.[0-9]+-*'
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Release tag (must start with v and follow semantic versioning)'
-        required: true
-        default: 'v0.3.0'
-        type: string
-
-env:
-  BUILD_TYPE: Release
-
-jobs:
-  validate-and-prepare:
-    name: Validate Release
-    runs-on: ubuntu-latest
-    outputs:
-      tag_name: ${{ steps.validate.outputs.tag_name }}
-      release_notes: ${{ steps.notes.outputs.content }}
-    
-    steps:
-    - name: Validate tag format
-      id: validate
-      run: |
-        # Determine the tag based on trigger type
-        if [[ "${{ github.event_name }}" == "push" ]]; then
-          if [[ "${{ github.ref_type }}" != "tag" ]]; then
-            echo "❌ Error: Release workflow triggered by push to ${{ github.ref_type }} '${{ github.ref_name }}'"
-            echo "This workflow should only be triggered by pushing version tags (v1.2.3)"
-            echo "Use: git tag v0.3.0 && git push origin v0.3.0"
-            exit 1
-          fi
-          TAG="${{ github.ref_name }}"
-        elif [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-          TAG="${{ github.event.inputs.tag }}"
-          if [[ -z "$TAG" ]]; then
-            echo "❌ Error: No tag specified for manual workflow dispatch"
-            exit 1
-          fi
-        else
-          echo "❌ Error: Unsupported event type: ${{ github.event_name }}"
-          exit 1
-        fi
-        
-        echo "Validating tag: $TAG"
-        
-        # Check if tag follows semantic versioning pattern
-        if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-.*)?$ ]]; then
-          echo "❌ Error: Tag '$TAG' does not follow semantic versioning format (v1.2.3 or v1.2.3-beta)"
-          echo "Valid examples: v0.3.0, v1.0.0, v2.1.3-beta, v1.0.0-rc1"
-          echo ""
-          echo "To create a proper release:"
-          echo "1. Use the helper script: ./scripts/create_release.sh 0.3.0"
-          echo "2. Or manually: git tag v0.3.0 && git push origin v0.3.0"
-          exit 1
-        fi
-        
-        echo "✅ Tag format is valid: $TAG"
-        echo "VALIDATED_TAG=$TAG" >> $GITHUB_ENV
-        echo "tag_name=$TAG" >> $GITHUB_OUTPUT
-    
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-
-    - name: Generate release notes
-      id: release_notes
-      run: |
-        # Extract release version from validated tag
-        VERSION="${VALIDATED_TAG}"
-        VERSION_NUM=$(echo "$VERSION" | sed 's/^v//')
-        
-        # Generate release notes using the dedicated script
-        echo "Extracting changelog for version: $VERSION_NUM"
-        if python3 scripts/extract_changelog.py "$VERSION_NUM" > release_notes.md; then
-          echo "Changelog extracted successfully"
-          echo "Release notes content:"
-          cat release_notes.md
-        else
-          echo "Failed to extract changelog, creating default release notes"
-          echo "# Yaze $VERSION Release Notes\n\nPlease see the full changelog at docs/C1-changelog.md" > release_notes.md
-        fi
-
-    - name: Store release notes
-      id: notes
-      run: |
-        # Store release notes content for later use
-        echo "content<<EOF" >> $GITHUB_OUTPUT
-        cat release_notes.md >> $GITHUB_OUTPUT
-        echo "EOF" >> $GITHUB_OUTPUT
-
-  build-release:
-    name: Build Release
-    needs: validate-and-prepare
-    strategy:
-      matrix:
-        include:
-          - name: "Windows x64"
-            os: windows-2022
-            vcpkg_triplet: x64-windows
-            cmake_generator: "Visual Studio 17 2022"
-            cmake_generator_platform: x64
-            artifact_name: "yaze-windows-x64"
-            
-          - name: "Windows ARM64"
-            os: windows-2022
-            vcpkg_triplet: arm64-windows
-            cmake_generator: "Visual Studio 17 2022"
-            cmake_generator_platform: ARM64
-            artifact_name: "yaze-windows-arm64"
-            
-          - name: "macOS Universal"
-            os: macos-14
-            vcpkg_triplet: arm64-osx
-            artifact_name: "yaze-macos"
-            
-          - name: "Linux x64"
-            os: ubuntu-22.04
-            artifact_name: "yaze-linux-x64"
-
-    runs-on: ${{ matrix.os }}
-    
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        submodules: recursive
-
-    # Platform-specific dependency installation
-    - name: Install Linux dependencies
-      if: runner.os == 'Linux'
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y \
-          build-essential \
-          ninja-build \
-          pkg-config \
-          libglew-dev \
-          libxext-dev \
-          libwavpack-dev \
-          libabsl-dev \
-          libboost-all-dev \
-          libpng-dev \
-          python3-dev \
-          libpython3-dev \
-          libasound2-dev \
-          libpulse-dev \
-          libx11-dev \
-          libxrandr-dev \
-          libxcursor-dev \
-          libxinerama-dev \
-          libxi-dev
-
-    - name: Install macOS dependencies
-      if: runner.os == 'macOS'
-      run: |
-        # Install Homebrew dependencies needed for UI tests and full builds
-        brew install pkg-config libpng boost abseil ninja gtk+3
-
-    # Set up vcpkg for Windows builds with fallback
-    - name: Set up vcpkg (Windows)
-      id: vcpkg_setup
-      if: runner.os == 'Windows'
-      uses: lukka/run-vcpkg@v11
-      continue-on-error: true
-      with:
-        vcpkgGitCommitId: 'c8696863d371ab7f46e213d8f5ca923c4aef2a00'
-        runVcpkgInstall: true
-        vcpkgJsonGlob: '**/vcpkg.json'
-        vcpkgDirectory: '${{ github.workspace }}/vcpkg'
-      env:
-        VCPKG_FORCE_SYSTEM_BINARIES: 1
-        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
-        VCPKG_DISABLE_METRICS: 1
-        VCPKG_DEFAULT_TRIPLET: ${{ matrix.vcpkg_triplet }}
-        VCPKG_ROOT: ${{ github.workspace }}/vcpkg
-
-    # Set vcpkg availability flag when vcpkg succeeds
-    - name: Set vcpkg availability flag
-      if: runner.os == 'Windows' && steps.vcpkg_setup.outcome == 'success'
-      shell: pwsh
-      run: |
-        echo "VCPKG_AVAILABLE=true" >> $env:GITHUB_ENV
-        Write-Host "vcpkg setup successful"
-
-    # Fallback: Set minimal build flag when vcpkg fails
-    - name: Set minimal build flag (Windows fallback)
-      if: runner.os == 'Windows' && steps.vcpkg_setup.outcome == 'failure'
-      shell: pwsh
-      run: |
-        echo "VCPKG_AVAILABLE=false" >> $env:GITHUB_ENV
-        echo "YAZE_MINIMAL_BUILD=ON" >> $env:GITHUB_ENV
-        Write-Host "vcpkg setup failed, using minimal build configuration"
-
-    # Configure CMake
-    - name: Configure CMake (Linux/macOS)
-      if: runner.os != 'Windows'
-      run: |
-        cmake -B build \
-          -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
-          -DCMAKE_POLICY_VERSION_MINIMUM=3.16 \
-          -DYAZE_BUILD_TESTS=OFF \
-          -DYAZE_BUILD_EMU=OFF \
-          -DYAZE_BUILD_Z3ED=OFF \
-          -DYAZE_ENABLE_UI_TESTS=ON \
-          -DYAZE_ENABLE_ROM_TESTS=OFF \
-          -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF \
-          -DYAZE_INSTALL_LIB=OFF \
-          -DYAZE_MINIMAL_BUILD=OFF \
-          -GNinja
-
-    - name: Configure CMake (Windows)
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        Write-Host "Configuring CMake for Windows build..."
-        
-        # Check if vcpkg is available
-        if ((Test-Path "${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake") -and ($env:VCPKG_AVAILABLE -ne "false")) {
-          Write-Host "Using vcpkg toolchain..."
-          cmake -B build `
-            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} `
-            -DCMAKE_POLICY_VERSION_MINIMUM=3.16 `
-            -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake" `
-            -DYAZE_BUILD_TESTS=OFF `
-            -DYAZE_BUILD_EMU=OFF `
-            -DYAZE_BUILD_Z3ED=OFF `
-            -DYAZE_ENABLE_ROM_TESTS=OFF `
-            -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF `
-            -DYAZE_INSTALL_LIB=OFF `
-            -DYAZE_MINIMAL_BUILD=OFF `
-            -G "${{ matrix.cmake_generator }}" `
-            -A ${{ matrix.cmake_generator_platform }}
-        } else {
-          Write-Host "Using minimal build configuration (vcpkg not available)..."
-          cmake -B build `
-            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} `
-            -DCMAKE_POLICY_VERSION_MINIMUM=3.16 `
-            -DYAZE_BUILD_TESTS=OFF `
-            -DYAZE_BUILD_EMU=OFF `
-            -DYAZE_BUILD_Z3ED=OFF `
-            -DYAZE_ENABLE_ROM_TESTS=OFF `
-            -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF `
-            -DYAZE_INSTALL_LIB=OFF `
-            -DYAZE_MINIMAL_BUILD=ON `
-            -G "${{ matrix.cmake_generator }}" `
-            -A ${{ matrix.cmake_generator_platform }}
-        }
-        
-        Write-Host "CMake configuration completed successfully"
-
-    # Build
-    - name: Build
-      run: |
-        echo "Building YAZE for ${{ matrix.name }}..."
-        cmake --build build --config ${{ env.BUILD_TYPE }} --parallel
-        echo "Build completed successfully!"
-
-    # Test executable functionality
-    - name: Test executable functionality
-      shell: bash
-      run: |
-        set -e
-        
-        echo "Testing executable for ${{ matrix.name }}..."
-        
-        # Determine executable path based on platform
-        if [[ "${{ runner.os }}" == "Windows" ]]; then
-          exePath="build/bin/${{ env.BUILD_TYPE }}/yaze.exe"
-        elif [[ "${{ runner.os }}" == "macOS" ]]; then
-          exePath="build/bin/yaze.app/Contents/MacOS/yaze"
-        else
-          exePath="build/bin/yaze"
-        fi
-        
-        if [ -f "$exePath" ]; then
-          echo "✓ Executable found: $exePath"
-          
-          # Test that it's not the test main
-          testResult=$($exePath --help 2>&1 || true)
-          exitCode=$?
-          
-          if echo "$testResult" | grep -q "Google Test\|gtest"; then
-            echo "ERROR: Executable is running test main instead of app main!"
-            echo "Output: $testResult"
-            exit 1
-          fi
-          
-          echo "✓ Executable runs correctly (exit code: $exitCode)"
-          
-          # Display file info
-          if [[ "${{ runner.os }}" == "Windows" ]]; then
-            fileSize=$(stat -c%s "$exePath" 2>/dev/null || echo "0")
-          else
-            fileSize=$(stat -f%z "$exePath" 2>/dev/null || stat -c%s "$exePath" 2>/dev/null || echo "0")
-          fi
-          fileSizeMB=$(echo "scale=2; $fileSize / 1024 / 1024" | bc -l 2>/dev/null || echo "0")
-          echo "Executable size: ${fileSizeMB} MB"
-        else
-          echo "ERROR: Executable not found at: $exePath"
-          exit 1
-        fi
-
-    # Package
-    - name: Package
-      shell: bash
-      run: |
-        set -e
-        echo "Packaging for ${{ matrix.name }}..."
-        
-        if [[ "${{ runner.os }}" == "Windows" ]]; then
-          # Windows packaging
-          mkdir -p package
-          cp -r build/bin/${{ env.BUILD_TYPE }}/* package/ 2>/dev/null || echo "No Release binaries found, trying Debug..."
-          cp -r build/bin/Debug/* package/ 2>/dev/null || echo "No Debug binaries found"
-          cp -r assets package/ 2>/dev/null || echo "assets directory not found"
-          cp LICENSE package/ 2>/dev/null || echo "LICENSE not found"
-          cp README.md package/ 2>/dev/null || echo "README.md not found"
-          cd package && zip -r ../${{ matrix.artifact_name }}.zip *
-          
-        elif [[ "${{ runner.os }}" == "macOS" ]]; then
-          # macOS packaging
-          if [ -d "build/bin/yaze.app" ]; then
-            echo "Found macOS bundle, using it directly"
-            cp -r build/bin/yaze.app ./Yaze.app
-            # Add additional resources to the bundle
-            cp -r assets "Yaze.app/Contents/Resources/" 2>/dev/null || echo "assets directory not found"
-            # Update Info.plist with correct version
-            if [ -f "cmake/yaze.plist.in" ]; then
-              VERSION_NUM=$(echo "${{ needs.validate-and-prepare.outputs.tag_name }}" | sed 's/^v//')
-              sed "s/@yaze_VERSION@/$VERSION_NUM/g" cmake/yaze.plist.in > "Yaze.app/Contents/Info.plist"
-            fi
-          else
-            echo "No bundle found, creating manual bundle"
-            mkdir -p "Yaze.app/Contents/MacOS"
-            mkdir -p "Yaze.app/Contents/Resources"
-            cp build/bin/yaze "Yaze.app/Contents/MacOS/"
-            cp -r assets "Yaze.app/Contents/Resources/" 2>/dev/null || echo "assets directory not found"
-            # Create Info.plist with correct version
-            VERSION_NUM=$(echo "${{ needs.validate-and-prepare.outputs.tag_name }}" | sed 's/^v//')
-            echo '<?xml version="1.0" encoding="UTF-8"?>' > "Yaze.app/Contents/Info.plist"
-            echo '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' >> "Yaze.app/Contents/Info.plist"
-            echo '<plist version="1.0">' >> "Yaze.app/Contents/Info.plist"
-            echo '<dict>' >> "Yaze.app/Contents/Info.plist"
-            echo '<key>CFBundleExecutable</key>' >> "Yaze.app/Contents/Info.plist"
-            echo '<string>yaze</string>' >> "Yaze.app/Contents/Info.plist"
-            echo '<key>CFBundleIdentifier</key>' >> "Yaze.app/Contents/Info.plist"
-            echo '<string>com.yaze.editor</string>' >> "Yaze.app/Contents/Info.plist"
-            echo '<key>CFBundleName</key>' >> "Yaze.app/Contents/Info.plist"
-            echo '<string>Yaze</string>' >> "Yaze.app/Contents/Info.plist"
-            echo '<key>CFBundleVersion</key>' >> "Yaze.app/Contents/Info.plist"
-            echo "<string>$VERSION_NUM</string>" >> "Yaze.app/Contents/Info.plist"
-            echo '<key>CFBundleShortVersionString</key>' >> "Yaze.app/Contents/Info.plist"
-            echo "<string>$VERSION_NUM</string>" >> "Yaze.app/Contents/Info.plist"
-            echo '<key>CFBundlePackageType</key>' >> "Yaze.app/Contents/Info.plist"
-            echo '<string>APPL</string>' >> "Yaze.app/Contents/Info.plist"
-            echo '</dict>' >> "Yaze.app/Contents/Info.plist"
-            echo '</plist>' >> "Yaze.app/Contents/Info.plist"
-          fi
-          
-          # Create DMG
-          mkdir dmg_staging
-          cp -r Yaze.app dmg_staging/
-          cp LICENSE dmg_staging/ 2>/dev/null || echo "LICENSE not found"
-          cp README.md dmg_staging/ 2>/dev/null || echo "README.md not found"
-          cp -r docs dmg_staging/ 2>/dev/null || echo "docs directory not found"
-          hdiutil create -srcfolder dmg_staging -format UDZO -volname "Yaze ${{ needs.validate-and-prepare.outputs.tag_name }}" ${{ matrix.artifact_name }}.dmg
-          
-        else
-          # Linux packaging
-          mkdir package
-          cp build/bin/yaze package/
-          cp -r assets package/ 2>/dev/null || echo "assets directory not found"
-          cp -r docs package/ 2>/dev/null || echo "docs directory not found"
-          cp LICENSE package/ 2>/dev/null || echo "LICENSE not found"
-          cp README.md package/ 2>/dev/null || echo "README.md not found"
-          tar -czf ${{ matrix.artifact_name }}.tar.gz -C package .
-        fi
-        
-        echo "Packaging completed successfully!"
-
-    # Create release with artifacts
-    - name: Upload to Release
-      uses: softprops/action-gh-release@v1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      with:
-        tag_name: ${{ needs.validate-and-prepare.outputs.tag_name }}
-        name: Yaze ${{ needs.validate-and-prepare.outputs.tag_name }}
-        body: ${{ needs.validate-and-prepare.outputs.release_notes }}
-        draft: false
-        prerelease: ${{ contains(needs.validate-and-prepare.outputs.tag_name, 'beta') || contains(needs.validate-and-prepare.outputs.tag_name, 'alpha') || contains(needs.validate-and-prepare.outputs.tag_name, 'rc') }}
-        files: |
-          ${{ matrix.artifact_name }}.*
-
-  publish-packages:
-    name: Publish Packages
-    needs: [validate-and-prepare, build-release]
-    runs-on: ubuntu-latest
-    if: success()
-    
-    steps:
-    - name: Announce release
-      run: |
-        echo "🎉 Yaze ${{ needs.validate-and-prepare.outputs.tag_name }} has been released!"
-        echo "📦 Packages are now available for download"
-        echo "🔗 Release URL: https://github.com/${{ github.repository }}/releases/tag/${{ needs.validate-and-prepare.outputs.tag_name }}"

.github/workflows/release.yml

@@ -3,129 +3,206 @@ name: Release
 on:
   push:
     tags:
-      - 'v[0-9]+.[0-9]+.[0-9]+'
-      - 'v[0-9]+.[0-9]+.[0-9]+-*'
+      - 'v*'
   workflow_dispatch:
     inputs:
-      tag:
-        description: 'Release tag (must start with v and follow semantic versioning)'
+      version:
+        description: 'Version to release (e.g., v1.0.0)'
         required: true
-        default: 'v0.3.0'
         type: string
 
 env:
-  BUILD_TYPE: Release
+  VERSION: ${{ github.event.inputs.version || github.ref_name }}
 
 jobs:
-  validate-and-prepare:
-    name: Validate Release
-    runs-on: ubuntu-latest
-    outputs:
-      tag_name: ${{ steps.validate.outputs.tag_name }}
-      release_notes: ${{ steps.notes.outputs.content }}
+  build:
+    name: "Build Release - ${{ matrix.name }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: "Ubuntu 22.04"
+            os: ubuntu-22.04
+            platform: linux
+            preset: release
+          - name: "macOS 14"
+            os: macos-14
+            platform: macos
+            preset: release
+          - name: "Windows 2022"
+            os: windows-2022
+            platform: windows
+            preset: release
 
     steps:
-    - name: Validate tag format
-      id: validate
+      - name: Free up disk space (Linux)
+        if: matrix.platform == 'linux'
         run: |
-        # Determine the tag based on trigger type
-        if [[ "${{ github.event_name }}" == "push" ]]; then
-          if [[ "${{ github.ref_type }}" != "tag" ]]; then
-            echo "❌ Error: Release workflow triggered by push to ${{ github.ref_type }} '${{ github.ref_name }}'"
-            echo "This workflow should only be triggered by pushing version tags (v1.2.3)"
-            echo "Use: git tag v0.3.0 && git push origin v0.3.0"
-            exit 1
-          fi
-          TAG="${{ github.ref_name }}"
-        elif [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-          TAG="${{ github.event.inputs.tag }}"
-          if [[ -z "$TAG" ]]; then
-            echo "❌ Error: No tag specified for manual workflow dispatch"
-            exit 1
-          fi
-        else
-          echo "❌ Error: Unsupported event type: ${{ github.event_name }}"
-          exit 1
-        fi
-        
-        echo "Validating tag: $TAG"
-        
-        # Check if tag follows semantic versioning pattern
-        if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-.*)?$ ]]; then
-          echo "❌ Error: Tag '$TAG' does not follow semantic versioning format (v1.2.3 or v1.2.3-beta)"
-          echo "Valid examples: v0.3.0, v1.0.0, v2.1.3-beta, v1.0.0-rc1"
-          echo ""
-          echo "To create a proper release:"
-          echo "1. Use the helper script: ./scripts/create_release.sh 0.3.0"
-          echo "2. Or manually: git tag v0.3.0 && git push origin v0.3.0"
-          exit 1
-        fi
-        
-        echo "✅ Tag format is valid: $TAG"
-        echo "VALIDATED_TAG=$TAG" >> $GITHUB_ENV
-        echo "tag_name=$TAG" >> $GITHUB_OUTPUT
+          echo "=== Disk space before cleanup ==="
+          df -h
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf /usr/local/lib/android
+          sudo rm -rf /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL
+          sudo docker image prune --all --force
+          echo "=== Disk space after cleanup ==="
+          df -h
 
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-        fetch-depth: 0
+          submodules: recursive
 
-    - name: Generate release notes
-      id: release_notes
+      - name: Compute dependency lock hash
+        id: deps-hash
+        shell: bash
         run: |
-        # Extract release version from validated tag
-        VERSION="${VALIDATED_TAG}"
-        VERSION_NUM=$(echo "$VERSION" | sed 's/^v//')
+          python_cmd="$(command -v python3 || command -v python || true)"
+          if [ -z "$python_cmd" ]; then
+            echo "hash=none" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          hash=$("$python_cmd" - <<'PY'
+          import hashlib
+          import pathlib
+          path = pathlib.Path("cmake/dependencies.lock")
+          if path.is_file():
+              print(hashlib.sha256(path.read_bytes()).hexdigest())
+          else:
+              print("none")
+          PY
+          )
+          echo "hash=$hash" >> "$GITHUB_OUTPUT"
 
-        # Generate release notes using the dedicated script
-        echo "Extracting changelog for version: $VERSION_NUM"
-        if python3 scripts/extract_changelog.py "$VERSION_NUM" > release_notes.md; then
-          echo "Changelog extracted successfully"
-          echo "Release notes content:"
-          cat release_notes.md
-        else
-          echo "Failed to extract changelog, creating default release notes"
-          echo "# Yaze $VERSION Release Notes\n\nPlease see the full changelog at docs/C1-changelog.md" > release_notes.md
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
+
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: Release
+
+      - name: Patch cmake_install.cmake (Unix)
+        if: matrix.platform == 'linux' || matrix.platform == 'macos'
+        shell: bash
+        run: |
+          cd build
+          # Create a Python script to patch cmake_install.cmake
+          python3 << 'EOF'
+          import re
+          with open('cmake_install.cmake', 'r') as f:
+              content = f.read()
+          # Wrap include() statements with if(EXISTS)
+          pattern = r'(\s*)include\("(.*)/_deps/([^"]+)/cmake_install\.cmake"\)'
+          replacement = r'\1if(EXISTS "\2/_deps/\3/cmake_install.cmake")\n\1  include("\2/_deps/\3/cmake_install.cmake")\n\1endif()'
+          content = re.sub(pattern, replacement, content)
+          with open('cmake_install.cmake', 'w') as f:
+              f.write(content)
+          print("Patched cmake_install.cmake to handle missing dependency install scripts")
+          EOF
+
+      - name: Clean old packages before CPack
+        shell: bash
+        run: |
+          echo "Cleaning old package files to ensure fresh generation"
+          rm -rf build/packages build/_CPack_Packages
+          rm -f build/*.deb build/*.tar.gz build/*.dmg build/*.zip build/*.exe
+          mkdir -p build/packages
+
+      - name: Package artifacts (Linux)
+        if: matrix.platform == 'linux'
+        run: |
+          cd build
+          cpack -G DEB -G TGZ
+          echo "=== Contents of packages directory ==="
+          ls -la packages/ 2>/dev/null || echo "No packages directory"
+          echo "=== Package files created ==="
+          ls -la packages/*.deb packages/*.tar.gz 2>/dev/null || echo "No packages found"
+
+      - name: Package artifacts (macOS)
+        if: matrix.platform == 'macos'
+        run: |
+          cd build
+          cpack -G DragNDrop
+          echo "=== Contents of packages directory ==="
+          ls -la packages/ 2>/dev/null || echo "No packages directory"
+          echo "=== Package files created ==="
+          ls -la packages/*.dmg 2>/dev/null || echo "No packages found"
+
+      - name: Create notarized bundle (macOS)
+        if: matrix.platform == 'macos'
+        shell: bash
+        run: |
+          chmod +x ./scripts/create-macos-bundle.sh
+          ./scripts/create-macos-bundle.sh ${{ env.VERSION }} yaze-${{ env.VERSION }}-bundle || true
+          if [ -f "yaze-${{ env.VERSION }}-bundle.dmg" ]; then
+            mkdir -p build/packages
+            mv yaze-${{ env.VERSION }}-bundle.dmg build/packages/
           fi
 
-    - name: Store release notes
-      id: notes
+      - name: Patch cmake_install.cmake (Windows)
+        if: matrix.platform == 'windows'
+        shell: pwsh
         run: |
-        # Store release notes content for later use
-        echo "content<<EOF" >> $GITHUB_OUTPUT
-        cat release_notes.md >> $GITHUB_OUTPUT
-        echo "EOF" >> $GITHUB_OUTPUT
+          cd build
+          # Wrap include() statements with if(EXISTS) to handle missing dependency install scripts
+          $nl = [Environment]::NewLine
+          $content = Get-Content cmake_install.cmake -Raw
+          $content = $content -replace '(\s+)include\("(.*)/_deps/([^"]+)/cmake_install\.cmake"\)', "`$1if(EXISTS `"`$2/_deps/`$3/cmake_install.cmake`")$nl`$1  include(`"`$2/_deps/`$3/cmake_install.cmake`")$nl`$1endif()"
+          Set-Content cmake_install.cmake $content
+          Write-Host "Patched cmake_install.cmake to handle missing dependency install scripts"
 
-  build-release:
-    name: Build Release
-    needs: validate-and-prepare
+      - name: Package artifacts (Windows)
+        if: matrix.platform == 'windows'
+        shell: pwsh
+        run: |
+          cd build
+          cpack -G NSIS -G ZIP
+          Write-Host "=== Contents of packages directory ==="
+          Get-ChildItem packages -ErrorAction SilentlyContinue
+          Write-Host "=== Package files created ==="
+          Get-ChildItem packages/*.exe, packages/*.zip -ErrorAction SilentlyContinue
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: yaze-${{ matrix.platform }}-${{ env.VERSION }}
+          path: |
+            build/packages/*.deb
+            build/packages/*.tar.gz
+            build/packages/*.dmg
+            build/packages/*.exe
+            build/packages/*.zip
+          if-no-files-found: warn
+          retention-days: 30
+
+  test:
+    name: "Test Release - ${{ matrix.name }}"
+    needs: build
+    runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         include:
-          - name: "Windows x64"
-            os: windows-2022
-            vcpkg_triplet: x64-windows
-            cmake_generator: "Visual Studio 17 2022"
-            cmake_generator_platform: x64
-            artifact_name: "yaze-windows-x64"
-            
-          - name: "Windows ARM64"
-            os: windows-2022
-            vcpkg_triplet: arm64-windows
-            cmake_generator: "Visual Studio 17 2022"
-            cmake_generator_platform: ARM64
-            artifact_name: "yaze-windows-arm64"
-            
-          - name: "macOS Universal"
-            os: macos-14
-            vcpkg_triplet: arm64-osx
-            artifact_name: "yaze-macos"
-            
-          - name: "Linux x64"
+          - name: "Ubuntu 22.04"
             os: ubuntu-22.04
-            artifact_name: "yaze-linux-x64"
-
-    runs-on: ${{ matrix.os }}
+            platform: linux
+            preset: release
+          - name: "macOS 14"
+            os: macos-14
+            platform: macos
+            preset: release
+          - name: "Windows 2022"
+            os: windows-2022
+            platform: windows
+            preset: release
 
     steps:
       - name: Checkout code
@@ -133,237 +210,131 @@ jobs:
         with:
           submodules: recursive
 
-    # Platform-specific dependency installation
-    - name: Install Linux dependencies
-      if: runner.os == 'Linux'
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y \
-          build-essential \
-          ninja-build \
-          pkg-config \
-          libglew-dev \
-          libxext-dev \
-          libwavpack-dev \
-          libabsl-dev \
-          libboost-all-dev \
-          libpng-dev \
-          python3-dev \
-          libpython3-dev \
-          libasound2-dev \
-          libpulse-dev \
-          libx11-dev \
-          libxrandr-dev \
-          libxcursor-dev \
-          libxinerama-dev \
-          libxi-dev
-
-    - name: Install macOS dependencies
-      if: runner.os == 'macOS'
-      run: |
-        # Install Homebrew dependencies needed for UI tests and full builds
-        brew install pkg-config libpng boost abseil ninja gtk+3
-
-    # Set up vcpkg for Windows builds with fallback
-    - name: Set up vcpkg (Windows)
-      id: vcpkg_setup
-      if: runner.os == 'Windows'
-      uses: lukka/run-vcpkg@v11
-      continue-on-error: true
-      with:
-        vcpkgGitCommitId: 'c8696863d371ab7f46e213d8f5ca923c4aef2a00'
-        runVcpkgInstall: true
-        vcpkgJsonGlob: '**/vcpkg.json'
-        vcpkgDirectory: '${{ github.workspace }}/vcpkg'
-      env:
-        VCPKG_FORCE_SYSTEM_BINARIES: 1
-        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
-        VCPKG_DISABLE_METRICS: 1
-        VCPKG_DEFAULT_TRIPLET: ${{ matrix.vcpkg_triplet }}
-        VCPKG_ROOT: ${{ github.workspace }}/vcpkg
-
-    # Set vcpkg availability flag when vcpkg succeeds
-    - name: Set vcpkg availability flag
-      if: runner.os == 'Windows' && steps.vcpkg_setup.outcome == 'success'
-      shell: pwsh
-      run: |
-        echo "VCPKG_AVAILABLE=true" >> $env:GITHUB_ENV
-        Write-Host "vcpkg setup successful"
-
-    # Fallback: Set minimal build flag when vcpkg fails
-    - name: Set minimal build flag (Windows fallback)
-      if: runner.os == 'Windows' && steps.vcpkg_setup.outcome == 'failure'
-      shell: pwsh
-      run: |
-        echo "VCPKG_AVAILABLE=false" >> $env:GITHUB_ENV
-        echo "YAZE_MINIMAL_BUILD=ON" >> $env:GITHUB_ENV
-        Write-Host "vcpkg setup failed, using minimal build configuration"
-
-    # Configure CMake
-    - name: Configure CMake (Linux/macOS)
-      if: runner.os != 'Windows'
-      run: |
-        cmake -B build \
-          -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
-          -DCMAKE_POLICY_VERSION_MINIMUM=3.16 \
-          -DYAZE_BUILD_TESTS=OFF \
-          -DYAZE_BUILD_EMU=OFF \
-          -DYAZE_BUILD_Z3ED=OFF \
-          -DYAZE_ENABLE_UI_TESTS=ON \
-          -DYAZE_ENABLE_ROM_TESTS=OFF \
-          -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF \
-          -DYAZE_INSTALL_LIB=OFF \
-          -DYAZE_MINIMAL_BUILD=OFF \
-          -GNinja
-
-    - name: Configure CMake (Windows)
-      if: runner.os == 'Windows'
-      shell: pwsh
-      run: |
-        Write-Host "Configuring CMake for Windows build..."
-        
-        # Check if vcpkg is available
-        if ((Test-Path "${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake") -and ($env:VCPKG_AVAILABLE -ne "false")) {
-          Write-Host "Using vcpkg toolchain..."
-          cmake -B build `
-            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} `
-            -DCMAKE_POLICY_VERSION_MINIMUM=3.16 `
-            -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake" `
-            -DYAZE_BUILD_TESTS=OFF `
-            -DYAZE_BUILD_EMU=OFF `
-            -DYAZE_ENABLE_ROM_TESTS=OFF `
-            -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF `
-            -DYAZE_INSTALL_LIB=OFF `
-            -DYAZE_MINIMAL_BUILD=OFF `
-            -G "${{ matrix.cmake_generator }}" `
-            -A ${{ matrix.cmake_generator_platform }}
-        } else {
-          Write-Host "Using minimal build configuration (vcpkg not available)..."
-          cmake -B build `
-            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} `
-            -DCMAKE_POLICY_VERSION_MINIMUM=3.16 `
-            -DYAZE_BUILD_TESTS=OFF `
-            -DYAZE_BUILD_EMU=OFF `
-            -DYAZE_ENABLE_ROM_TESTS=OFF `
-            -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF `
-            -DYAZE_INSTALL_LIB=OFF `
-            -DYAZE_MINIMAL_BUILD=ON `
-            -G "${{ matrix.cmake_generator }}" `
-            -A ${{ matrix.cmake_generator_platform }}
-        }
-        
-        Write-Host "CMake configuration completed successfully"
-
-    # Build
-    - name: Build
-      run: |
-        echo "Building YAZE for ${{ matrix.name }}..."
-        cmake --build build --config ${{ env.BUILD_TYPE }} --parallel
-        echo "Build completed successfully!"
-
-    # Test executable functionality
-    - name: Test executable functionality
+      - name: Compute dependency lock hash
+        id: deps-hash
         shell: bash
         run: |
-        set -e
-        
-        echo "Testing executable for ${{ matrix.name }}..."
-        
-        # Determine executable path based on platform
-        if [[ "${{ runner.os }}" == "Windows" ]]; then
-          exePath="build/bin/${{ env.BUILD_TYPE }}/yaze.exe"
-        elif [[ "${{ runner.os }}" == "macOS" ]]; then
-          exePath="build/bin/yaze.app/Contents/MacOS/yaze"
-        else
-          exePath="build/bin/yaze"
+          python_cmd="$(command -v python3 || command -v python || true)"
+          if [ -z "$python_cmd" ]; then
+            echo "hash=none" >> "$GITHUB_OUTPUT"
+            exit 0
           fi
+          hash=$("$python_cmd" - <<'PY'
+          import hashlib
+          import pathlib
+          path = pathlib.Path("cmake/dependencies.lock")
+          if path.is_file():
+              print(hashlib.sha256(path.read_bytes()).hexdigest())
+          else:
+              print("none")
+          PY
+          )
+          echo "hash=$hash" >> "$GITHUB_OUTPUT"
 
-        if [ -f "$exePath" ]; then
-          echo "✓ Executable found: $exePath"
-          
-          # Test that it's not the test main
-          testResult=$($exePath --help 2>&1 || true)
-          exitCode=$?
-          
-          if echo "$testResult" | grep -q "Google Test\|gtest"; then
-            echo "ERROR: Executable is running test main instead of app main!"
-            echo "Output: $testResult"
-            exit 1
-          fi
-          
-          echo "✓ Executable runs correctly (exit code: $exitCode)"
-          
-          # Display file info
-          if [[ "${{ runner.os }}" == "Windows" ]]; then
-            fileSize=$(stat -c%s "$exePath" 2>/dev/null || echo "0")
-          else
-            fileSize=$(stat -f%z "$exePath" 2>/dev/null || stat -c%s "$exePath" 2>/dev/null || echo "0")
-          fi
-          fileSizeMB=$(echo "scale=2; $fileSize / 1024 / 1024" | bc -l 2>/dev/null || echo "0")
-          echo "Executable size: ${fileSizeMB} MB"
-        else
-          echo "ERROR: Executable not found at: $exePath"
-          exit 1
-        fi
-
-    # Package
-    - name: Package
-      shell: bash
-      run: |
-        set -e
-        echo "Packaging for ${{ matrix.name }}..."
-        
-        if [[ "${{ runner.os }}" == "Windows" ]]; then
-          # Windows packaging
-          mkdir -p package
-          cp -r build/bin/${{ env.BUILD_TYPE }}/* package/ 2>/dev/null || echo "No Release binaries found, trying Debug..."
-          cp -r build/bin/Debug/* package/ 2>/dev/null || echo "No Debug binaries found"
-          cp -r assets package/ 2>/dev/null || echo "assets directory not found"
-          cp LICENSE package/ 2>/dev/null || echo "LICENSE not found"
-          cp README.md package/ 2>/dev/null || echo "README.md not found"
-          cd package && zip -r ../${{ matrix.artifact_name }}.zip *
-          
-        elif [[ "${{ runner.os }}" == "macOS" ]]; then
-          # macOS packaging using dedicated script
-          VERSION_NUM=$(echo "${{ needs.validate-and-prepare.outputs.tag_name }}" | sed 's/^v//')
-          ./scripts/create-macos-bundle.sh "$VERSION_NUM" "${{ matrix.artifact_name }}"
-          
-        else
-          # Linux packaging
-          mkdir package
-          cp build/bin/yaze package/
-          cp -r assets package/ 2>/dev/null || echo "assets directory not found"
-          cp -r docs package/ 2>/dev/null || echo "docs directory not found"
-          cp LICENSE package/ 2>/dev/null || echo "LICENSE not found"
-          cp README.md package/ 2>/dev/null || echo "README.md not found"
-          tar -czf ${{ matrix.artifact_name }}.tar.gz -C package .
-        fi
-        
-        echo "Packaging completed successfully!"
-
-    # Create release with artifacts
-    - name: Upload to Release
-      uses: softprops/action-gh-release@v1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
         with:
-        tag_name: ${{ needs.validate-and-prepare.outputs.tag_name }}
-        name: Yaze ${{ needs.validate-and-prepare.outputs.tag_name }}
-        body: ${{ needs.validate-and-prepare.outputs.release_notes }}
-        draft: false
-        prerelease: ${{ contains(needs.validate-and-prepare.outputs.tag_name, 'beta') || contains(needs.validate-and-prepare.outputs.tag_name, 'alpha') || contains(needs.validate-and-prepare.outputs.tag_name, 'rc') }}
-        files: |
-          ${{ matrix.artifact_name }}.*
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
 
-  publish-packages:
-    name: Publish Packages
-    needs: [validate-and-prepare, build-release]
-    runs-on: ubuntu-latest
-    if: success()
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: Release
+
+      - name: Run tests
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: stable
+          preset: ${{ matrix.preset }}
+
+  create-release:
+    name: "Create Release"
+    needs: [build]  # Tests are informational only in pre-1.0
+    runs-on: ubuntu-22.04
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
 
     steps:
-    - name: Announce release
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: ./artifacts
+
+      - name: Display downloaded artifacts
         run: |
-        echo "🎉 Yaze ${{ needs.validate-and-prepare.outputs.tag_name }} has been released!"
-        echo "📦 Packages are now available for download"
-        echo "🔗 Release URL: https://github.com/${{ github.repository }}/releases/tag/${{ needs.validate-and-prepare.outputs.tag_name }}"
+          echo "=== Downloaded artifacts structure ==="
+          ls -laR artifacts/
+          echo "=== Package files found ==="
+          find artifacts -type f \( -name "*.zip" -o -name "*.exe" -o -name "*.deb" -o -name "*.tar.gz" -o -name "*.dmg" \)
+
+      - name: Reorganize artifacts
+        run: |
+          # Flatten the artifact directory structure
+          mkdir -p release-files
+          find artifacts -type f \( -name "*.zip" -o -name "*.exe" -o -name "*.deb" -o -name "*.tar.gz" -o -name "*.dmg" \) -exec cp {} release-files/ \;
+          echo "=== Files in release-files ==="
+          ls -la release-files/
+
+      - name: Generate release checksums
+        run: |
+          cd release-files
+          sha256sum * > checksums.txt
+          cat checksums.txt
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ env.VERSION }}
+          name: "YAZE ${{ env.VERSION }}"
+          body: |
+            ## What's Changed
+            
+            This release includes:
+            - Cross-platform builds for Linux, macOS, and Windows
+            - Improved dependency management with CPM.cmake
+            - Enhanced CI/CD pipeline with parallel execution
+            - Automated packaging and release creation
+            
+            ## Downloads
+            
+            ### Linux
+            - **DEB Package**: `yaze-*.deb` (Ubuntu/Debian)
+            - **Tarball**: `yaze-*.tar.gz` (Generic Linux)
+            
+            ### macOS
+            - **DMG**: `yaze-*.dmg` (macOS 11.0+)
+            
+            ### Windows
+            - **Installer**: `yaze-*.exe` (Windows 10/11)
+            - **ZIP**: `yaze-*.zip` (Portable)
+            
+            ## Installation
+            
+            ### Linux (DEB)
+            ```bash
+            sudo dpkg -i yaze-*.deb
+            ```
+            
+            ### macOS
+            ```bash
+            # Mount the DMG and drag to Applications
+            open yaze-*.dmg
+            ```
+            
+            ### Windows
+            ```bash
+            # Run the installer
+            yaze-*.exe
+            ```
+          files: |
+            release-files/*
+          draft: false
+          prerelease: ${{ contains(env.VERSION, 'alpha') || contains(env.VERSION, 'beta') || contains(env.VERSION, 'rc') }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/scripts/linux-ci-packages.txt

@@ -0,0 +1,26 @@
+build-essential
+ninja-build
+pkg-config
+ccache
+libglew-dev
+libxext-dev
+libwavpack-dev
+libboost-all-dev
+libpng-dev
+python3-dev
+libasound2-dev
+libpulse-dev
+libaudio-dev
+libx11-dev
+libxrandr-dev
+libxcursor-dev
+libxinerama-dev
+libxi-dev
+libxss-dev
+libxxf86vm-dev
+libxkbcommon-dev
+libwayland-dev
+libdecor-0-dev
+libgtk-3-dev
+libdbus-1-dev
+libgtk-3-0

.github/workflows/security.yml

@@ -0,0 +1,88 @@
+name: Security Scanning
+
+on:
+  push:
+    branches: [ "master", "develop" ]
+  pull_request:
+    branches: [ "master", "develop" ]
+  schedule:
+    - cron: '0 2 * * 1'  # Weekly on Monday at 2 AM
+  workflow_dispatch:
+
+jobs:
+  codeql:
+    name: "CodeQL Analysis"
+    runs-on: ubuntu-22.04
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'cpp' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        queries: security-and-quality
+
+    - name: Setup build environment
+      uses: ./.github/actions/setup-build
+      with:
+        platform: linux
+        preset: ci
+        cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+
+    - name: Build project
+      uses: ./.github/actions/build-project
+      with:
+        platform: linux
+        preset: ci
+        build-type: RelWithDebInfo
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"
+
+  dependency-scan:
+    name: "Dependency Scan"
+    runs-on: ubuntu-22.04
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Run Trivy vulnerability scanner
+      uses: aquasecurity/trivy-action@master
+      with:
+        scan-type: 'fs'
+        scan-ref: '.'
+        format: 'sarif'
+        output: 'trivy-results.sarif'
+    
+    - name: Upload Trivy scan results to GitHub Security tab
+      uses: github/codeql-action/upload-sarif@v3
+      if: always()
+      with:
+        sarif_file: 'trivy-results.sarif'
+
+  dependabot:
+    name: "Dependabot"
+    runs-on: ubuntu-22.04
+    if: github.event_name == 'schedule'
+    
+    steps:
+    - name: Dependabot metadata
+      run: |
+        echo "Dependabot is configured via .github/dependabot.yml"
+        echo "This job runs weekly to ensure dependencies are up to date"
+

.github/workflows/symbol-detection.yml

@@ -0,0 +1,157 @@
+name: Symbol Conflict Detection
+
+on:
+  push:
+    branches: [ "master", "develop" ]
+    paths:
+      - 'src/**/*.cc'
+      - 'src/**/*.h'
+      - 'test/**/*.cc'
+      - 'test/**/*.h'
+      - '.github/workflows/symbol-detection.yml'
+  pull_request:
+    branches: [ "master", "develop" ]
+    paths:
+      - 'src/**/*.cc'
+      - 'src/**/*.h'
+      - 'test/**/*.cc'
+      - 'test/**/*.h'
+      - '.github/workflows/symbol-detection.yml'
+  workflow_dispatch:
+
+jobs:
+  symbol-detection:
+    name: "Symbol Conflict Detection"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: "Linux"
+            os: ubuntu-22.04
+            platform: linux
+            preset: ci-linux
+          - name: "macOS"
+            os: macos-14
+            platform: macos
+            preset: ci-macos
+          - name: "Windows"
+            os: windows-2022
+            platform: windows
+            preset: ci-windows
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+
+      - name: Build project (Release)
+        uses: ./.github/actions/build-project
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: Release
+
+      - name: Extract symbols (Unix/macOS)
+        if: runner.os != 'Windows'
+        run: |
+          echo "Extracting symbols from object files..."
+          ./scripts/extract-symbols.sh build
+
+      - name: Extract symbols (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          echo "Extracting symbols from object files..."
+          # Note: Windows version uses dumpbin, may require Visual Studio
+          bash ./scripts/extract-symbols.sh build
+
+      - name: Check for duplicate symbols
+        if: always()
+        run: |
+          echo "Checking for symbol conflicts..."
+          ./scripts/check-duplicate-symbols.sh build/symbol_database.json || {
+            echo "Symbol conflicts detected!"
+            exit 1
+          }
+
+      - name: Upload symbol database
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: symbol-database-${{ matrix.platform }}
+          path: build/symbol_database.json
+          if-no-files-found: warn
+          retention-days: 30
+
+      - name: Generate symbol report
+        if: always()
+        run: |
+          python3 << 'EOF'
+          import json
+          import sys
+
+          try:
+              with open("build/symbol_database.json") as f:
+                  data = json.load(f)
+          except FileNotFoundError:
+              print("Symbol database not found")
+              sys.exit(0)
+
+          meta = data.get("metadata", {})
+          conflicts = data.get("conflicts", [])
+
+          print("\n=== Symbol Analysis Report ===")
+          print(f"Platform: {meta.get('platform', '?')}")
+          print(f"Object files scanned: {meta.get('object_files_scanned', 0)}")
+          print(f"Total symbols: {meta.get('total_symbols', 0)}")
+          print(f"Total conflicts: {len(conflicts)}")
+
+          if conflicts:
+              print("\nSymbol Conflicts:")
+              for i, conflict in enumerate(conflicts[:10], 1):
+                  symbol = conflict.get("symbol", "?")
+                  count = conflict.get("count", 0)
+                  defs = conflict.get("definitions", [])
+                  print(f"\n  {i}. {symbol} (defined {count} times)")
+                  for d in defs:
+                      obj = d.get("object_file", "?")
+                      print(f"     - {obj}")
+              if len(conflicts) > 10:
+                  print(f"\n  ... and {len(conflicts) - 10} more conflicts")
+          else:
+              print("\nNo symbol conflicts detected - symbol table is clean!")
+
+          print("\n" + "="*40)
+          EOF
+
+      - name: Fail on conflicts
+        if: always()
+        run: |
+          python3 << 'EOF'
+          import json
+          import sys
+
+          try:
+              with open("build/symbol_database.json") as f:
+                  data = json.load(f)
+          except FileNotFoundError:
+              sys.exit(0)
+
+          conflicts = data.get("conflicts", [])
+          if conflicts:
+              print(f"\nFAILED: Found {len(conflicts)} symbol conflicts")
+              print("See artifact for detailed symbol database")
+              sys.exit(1)
+          else:
+              print("\nPASSED: No symbol conflicts detected")
+              sys.exit(0)
+          EOF

.github/workflows/validate-vs-build.yml

@@ -1,157 +0,0 @@
-name: Validate Visual Studio Builds
-
-on:
-  push:
-    branches: [ "master", "develop" ]
-    paths:
-      - 'vcpkg.json'
-      - 'src/**'
-      - 'scripts/generate-vs-projects.py'
-      - 'scripts/validate-vs-build.ps1'
-      - '.github/workflows/validate-vs-build.yml'
-  pull_request:
-    branches: [ "master", "develop" ]
-    paths:
-      - 'vcpkg.json'
-      - 'src/**'
-      - 'scripts/generate-vs-projects.py'
-      - 'scripts/validate-vs-build.ps1'
-      - '.github/workflows/validate-vs-build.yml'
-
-env:
-  VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
-
-jobs:
-  validate-vs-builds:
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - name: "Windows x64 Debug"
-            platform: x64
-            configuration: Debug
-            
-          - name: "Windows x64 Release"
-            platform: x64
-            configuration: Release
-            
-
-    name: ${{ matrix.name }}
-    runs-on: windows-2022
-
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        submodules: recursive
-
-    - name: Set up vcpkg
-      uses: lukka/run-vcpkg@v11
-      with:
-        vcpkgGitCommitId: 'c8696863d371ab7f46e213d8f5ca923c4aef2a00'
-        runVcpkgInstall: true
-        vcpkgJsonGlob: '**/vcpkg.json'
-        vcpkgDirectory: '${{ github.workspace }}/vcpkg'
-      env:
-        VCPKG_FORCE_SYSTEM_BINARIES: 1
-        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
-
-    - name: Validate Visual Studio Build
-      shell: pwsh
-      run: |
-        $ErrorActionPreference = "Stop"
-        
-        Write-Host "========================================" -ForegroundColor Cyan
-        Write-Host "YAZE Visual Studio Build Validation" -ForegroundColor Cyan
-        Write-Host "Platform: ${{ matrix.platform }}" -ForegroundColor Yellow
-        Write-Host "Configuration: ${{ matrix.configuration }}" -ForegroundColor Yellow
-        Write-Host "========================================" -ForegroundColor Cyan
-        
-        # Check if we're in the right directory
-        if (-not (Test-Path "yaze.sln")) {
-            Write-Error "yaze.sln not found. Please run this script from the project root directory."
-            exit 1
-        }
-        
-        Write-Host "✓ yaze.sln found" -ForegroundColor Green
-        
-        # Ensure build directory exists
-        if (-not (Test-Path "build")) {
-            New-Item -ItemType Directory -Path "build" | Out-Null
-        }
-        
-        # Build using MSBuild
-        Write-Host "Building with MSBuild..." -ForegroundColor Yellow
-        $msbuildArgs = @(
-            "yaze.sln"
-            "/p:Configuration=${{ matrix.configuration }}"
-            "/p:Platform=${{ matrix.platform }}"
-            "/p:VcpkgEnabled=true"
-            "/p:VcpkgManifestInstall=true"
-            "/m"  # Multi-processor build
-            "/verbosity:minimal"
-        )
-        
-        Write-Host "MSBuild command: msbuild $($msbuildArgs -join ' ')" -ForegroundColor Gray
-        & msbuild @msbuildArgs
-        
-        if ($LASTEXITCODE -ne 0) {
-            Write-Error "MSBuild failed with exit code $LASTEXITCODE"
-            exit 1
-        }
-        
-        Write-Host "✓ Build completed successfully" -ForegroundColor Green
-        
-        # Verify executable was created
-        $exePath = "build\bin\${{ matrix.configuration }}\yaze.exe"
-        if (-not (Test-Path $exePath)) {
-            Write-Error "Executable not found at expected path: $exePath"
-            exit 1
-        }
-        
-        Write-Host "✓ Executable created: $exePath" -ForegroundColor Green
-        
-        # Verify assets were copied
-        $assetsPath = "build\bin\${{ matrix.configuration }}\assets"
-        if (-not (Test-Path $assetsPath)) {
-            Write-Error "Assets directory not found at expected path: $assetsPath"
-            exit 1
-        }
-        
-        Write-Host "✓ Assets copied to: $assetsPath" -ForegroundColor Green
-        
-        # Test that the executable runs (basic test)
-        Write-Host "Testing executable startup..." -ForegroundColor Yellow
-        $testResult = & $exePath --help 2>&1
-        $exitCode = $LASTEXITCODE
-        
-        # Check if it's the test main or app main
-        if ($testResult -match "Google Test" -or $testResult -match "gtest") {
-            Write-Error "Executable is running test main instead of app main!"
-            Write-Host "Output: $testResult" -ForegroundColor Red
-            exit 1
-        }
-        
-        Write-Host "✓ Executable runs correctly (exit code: $exitCode)" -ForegroundColor Green
-        
-        # Display file info
-        $exeInfo = Get-Item $exePath
-        Write-Host ""
-        Write-Host "Build Summary:" -ForegroundColor Cyan
-        Write-Host "  Executable: $($exeInfo.FullName)" -ForegroundColor White
-        Write-Host "  Size: $([math]::Round($exeInfo.Length / 1MB, 2)) MB" -ForegroundColor White
-        Write-Host "  Created: $($exeInfo.CreationTime)" -ForegroundColor White
-        
-        Write-Host ""
-        Write-Host "========================================" -ForegroundColor Cyan
-        Write-Host "✓ Visual Studio build validation PASSED" -ForegroundColor Green
-        Write-Host "========================================" -ForegroundColor Cyan
-
-    - name: Upload build artifacts
-      uses: actions/upload-artifact@v4
-      if: always()
-      with:
-        name: yaze-${{ matrix.platform }}-${{ matrix.configuration }}
-        path: |
-          build/bin/${{ matrix.configuration }}/
-        retention-days: 7

.gitignore

@@ -1,21 +1,95 @@
-.favorites.json
-build/
-.cache/
+# Build directories - organized by platform (root level only)
+/build/
+/build-*/
+/build_*/
+/out/
+docs/html/
+docs/latex/
+
+# CMake
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+compile_commands.json
+CPackConfig.cmake
+CPackSourceConfig.cmake
+CTestTestfile.cmake
+
+# Build artifacts
+*.o
+*.a
+*.so
+*.dylib
+*.dll
+*.exe
+*.app
+*.out
+
+# IDE files
 .vscode/
-disasm/
-src/etc
-src/lib/
-checks.json
-assets/lib/libasar.dll
-cmake/yaze.plist.in
-etc/
-latex/
-html/
-docs/zarby_algos.md
-docs/overworld-expansion.md
-assets/asm/EditorCore.asm
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Test outputs
+test_screenshots/
+test_temp_rom.sfc
+zelda3_v3_test.sfc
+
+# Logs
+yaze_log.txt
+*.log
+
+# vcpkg
+vcpkg_installed/
+
+# Agent learned knowledge (user-specific)
+.agent_knowledge/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Backup files
+*.bak
+*.backup
+*~
+
+# Generated files
+gens/
+*.pb.h
+*.pb.cc
+*.grpc.pb.h
+*.grpc.pb.cc
+
+# Cache
+.cache/
+
+# local dependencies
+src/lib/cmake/
+src/lib/GL/
+src/lib/libpng/
+src/lib/zlib/
+src/app/gui/modules/component.h
+src/ios/macOS/Info-macOS.plist
+src/ios/macOS/MainMenu.storyboard
 src/app/emu/cpu/internal/old_cpu.cc
-build-windows
-src/lib/libpng
-src/lib/zlib
-assets/layouts/ow_toolset.zeml
+.favorites.json
+checks.json
+assets/etc/
+imgui.ini
+.gitignore
+recent_files.txt
+.vs/*
+.gitignore
+.genkit
+.claude
+scripts/__pycache__/

.gitmodules

@@ -1,24 +1,27 @@
-[submodule "src/lib/imgui"]
-	path = src/lib/imgui
+[submodule "ext/imgui"]
+	path = ext/imgui
 	url = https://github.com/ocornut/imgui.git
 [submodule "assets/asm/alttp-hacker-workspace"]
 	path = assets/asm/alttp-hacker-workspace
 	url = https://github.com/scawful/alttp-hacker-workspace.git
-[submodule "src/lib/abseil-cpp"]
-	path = src/lib/abseil-cpp
-	url = https://github.com/abseil/abseil-cpp.git
-[submodule "src/lib/SDL"]
-	path = src/lib/SDL
+[submodule "ext/SDL"]
+	path = ext/SDL
 	url = https://github.com/libsdl-org/SDL.git
-[submodule "src/lib/asar"]
-	path = src/lib/asar
+[submodule "ext/asar"]
+	path = ext/asar
 	url = https://github.com/RPGHacker/asar.git
-[submodule "src/lib/imgui_test_engine"]
-	path = src/lib/imgui_test_engine
+[submodule "ext/imgui_test_engine"]
+	path = ext/imgui_test_engine
 	url = https://github.com/ocornut/imgui_test_engine.git
-[submodule "src/lib/nativefiledialog-extended"]
-	path = src/lib/nativefiledialog-extended
+[submodule "ext/nativefiledialog-extended"]
+	path = ext/nativefiledialog-extended
 	url = https://github.com/btzy/nativefiledialog-extended.git
 [submodule "assets/asm/usdasm"]
 	path = assets/asm/usdasm
 	url = https://github.com/spannerisms/usdasm.git
+[submodule "ext/json"]
+	path = ext/json
+	url = https://github.com/nlohmann/json.git
+[submodule "ext/httplib"]
+	path = ext/httplib
+	url = https://github.com/yhirose/cpp-httplib.git

.pre-commit-config.yaml

@@ -0,0 +1,81 @@
+# Pre-commit hooks for YAZE
+# Install with: pip install pre-commit && pre-commit install
+
+repos:
+  # Clang format
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v18.1.0
+    hooks:
+      - id: clang-format
+        args: [--style=Google, -i]
+        files: \.(cc|cpp|h|hpp)$
+        exclude: ^(src/lib/|third_party/)
+
+  # Clang tidy
+  - repo: local
+    hooks:
+      - id: clang-tidy
+        name: clang-tidy
+        entry: clang-tidy
+        language: system
+        args: [--header-filter=src/.*\.(h|hpp)$]
+        files: \.(cc|cpp)$
+        exclude: ^(src/lib/|third_party/)
+
+  # Cppcheck
+  - repo: local
+    hooks:
+      - id: cppcheck
+        name: cppcheck
+        entry: cppcheck
+        language: system
+        args: [--enable=warning,style,performance, --inconclusive, --error-exitcode=0]
+        files: \.(cc|cpp|h|hpp)$
+        exclude: ^(src/lib/|third_party/)
+
+  # General hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  # CMake formatting
+  - repo: https://github.com/cheshirekow/cmake-format-precommit
+    rev: v0.6.13
+    hooks:
+      - id: cmake-format
+        args: [--config-files=cmake-format.yaml]
+        files: CMakeLists\.txt$|\.cmake$
+
+  # Shell script linting
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.9.0.6
+    hooks:
+      - id: shellcheck
+        files: \.(sh|bash)$
+
+  # Python linting (for scripts)
+  - repo: https://github.com/psf/black
+    rev: 23.12.1
+    hooks:
+      - id: black
+        files: \.py$
+        exclude: ^(third_party/|build/)
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        files: \.py$
+        exclude: ^(third_party/|build/)
+

AGENTS.md

@@ -0,0 +1,32 @@
+## Inter-Agent Protocol (Lean)
+1) **Read the board** (`docs/internal/agents/coordination-board.md`) before starting.
+2) **Log your intent** (task, scope, files) on the board with your agent ID.
+3) **Answer requests** tagged to your ID.
+4) **Record completion/handoff** with a short state note.
+5) For multi-day work, use `docs/internal/agents/initiative-template.md` and link it from your board entry.
+
+## Agent IDs (shared with Oracle-of-Secrets/.claude/agents)
+Use these canonical IDs (scopes in `docs/internal/agents/personas.md` and `.claude/agents/*`):
+
+| Agent ID                   | Focus                                                  |
+|----------------------------|--------------------------------------------------------|
+| `ai-infra-architect`       | AI/agent infra, z3ed CLI/TUI, gRPC/network             |
+| `backend-infra-engineer`   | Build/packaging, CMake/toolchains, CI reliability      |
+| `docs-janitor`             | Docs, onboarding, release notes, process hygiene       |
+| `imgui-frontend-engineer`  | ImGui/renderer/UI systems                              |
+| `snes-emulator-expert`     | Emulator core (CPU/APU/PPU), perf/debugging            |
+| `test-infrastructure-expert` | Test harness, CTest/gMock, flake triage              |
+| `zelda3-hacking-expert`    | Gameplay/ROM logic, Zelda3 data model                  |
+| `GEMINI_FLASH_AUTOM`       | Gemini automation/CLI/tests                            |
+| `CODEX`                    | Codex CLI assistant                                    |
+| `OTHER`                    | Define in entry                                        |
+
+Legacy aliases (`CLAUDE_CORE`, `CLAUDE_AIINF`, `CLAUDE_DOCS`) → use `imgui-frontend-engineer`/`snes-emulator-expert`/`zelda3-hacking-expert`, `ai-infra-architect`, and `docs-janitor`.
+
+## Helper Scripts (keep it short)
+Located in `scripts/agents/`:
+- `run-gh-workflow.sh`, `smoke-build.sh`, `run-tests.sh`, `test-http-api.sh`
+Log command results + workflow URLs on the board for traceability.
+
+## Escalation
+If overlapping on a subsystem, post `REQUEST`/`BLOCKER` on the board and coordinate; prefer small, well-defined handoffs.

CLAUDE.md

@@ -0,0 +1,323 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+> **Coordination Requirement**  
+> Before starting or handing off work, read and update the shared protocol in
+> [`docs/internal/agents/coordination-board.md`](docs/internal/agents/coordination-board.md) as
+> described in `AGENTS.md`. Always acknowledge pending `REQUEST`/`BLOCKER` entries addressed to the
+> Claude persona you are using (`CLAUDE_CORE`, `CLAUDE_AIINF`, or `CLAUDE_DOCS`). See
+> [`docs/internal/agents/personas.md`](docs/internal/agents/personas.md) for responsibilities.
+
+## Project Overview
+
+**yaze** (Yet Another Zelda3 Editor) is a modern, cross-platform ROM editor for The Legend of Zelda: A Link to the Past, built with C++23. It features:
+- Complete GUI editor for overworld, dungeons, sprites, graphics, and palettes
+- Integrated Asar 65816 assembler for ROM patching
+- SNES emulator for testing modifications
+- AI-powered CLI tool (`z3ed`) for ROM hacking assistance
+- ZSCustomOverworld v3 support for enhanced overworld editing
+
+## Build System
+
+- Use the presets defined in `CMakePresets.json` (debug: `mac-dbg` / `lin-dbg` / `win-dbg`, AI:
+  `mac-ai` / `win-ai`, release: `*-rel`, etc.). Add `-v` for verbose builds.
+- Always run builds from a dedicated directory when acting as an AI agent (`build_ai`, `build_agent`,
+  …) so you do not interfere with the user’s `build`/`build_test` trees.
+- Treat [`docs/public/build/quick-reference.md`](docs/public/build/quick-reference.md) as the single
+  source of truth for commands, presets, testing, and environment prep. Only reference the larger
+  troubleshooting docs when you need platform-specific fixes.
+
+### Test Execution
+
+See [`docs/public/build/quick-reference.md`](docs/public/build/quick-reference.md#5-testing) for complete test commands. Quick reference:
+
+```bash
+# Stable tests only (recommended for development)
+ctest --test-dir build -L stable -j4
+
+# All tests (respects preset configuration)
+ctest --test-dir build --output-on-failure
+
+# ROM-dependent tests (requires setup)
+cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=~/zelda3.sfc
+ctest --test-dir build -L rom_dependent
+
+# Experimental AI tests (with AI preset)
+cmake --preset mac-ai
+ctest --test-dir build -L experimental
+```
+
+See `test/README.md` for detailed test organization, presets, and troubleshooting.
+
+## Architecture
+
+### Core Components
+
+**ROM Management** (`src/app/rom.h`, `src/app/rom.cc`)
+- Central `Rom` class manages all ROM data access
+- Provides transaction-based read/write operations
+- Handles graphics buffer, palettes, and resource labels
+- Key methods: `LoadFromFile()`, `ReadByte()`, `WriteByte()`, `ReadTransaction()`, `WriteTransaction()`
+
+**Editor System** (`src/app/editor/`)
+- Base `Editor` class defines interface for all editor types
+- Major editors: `OverworldEditor`, `DungeonEditor`, `GraphicsEditor`, `PaletteEditor`
+- `EditorManager` coordinates multiple editor instances
+- Card-based UI system for dockable editor panels
+
+**Graphics System** (`src/app/gfx/`)
+- `gfx::Bitmap`: Core bitmap class with SDL surface integration
+- `gfx::Arena`: Centralized singleton for progressive asset loading (priority-based texture queuing)
+- `gfx::SnesPalette` and `gfx::SnesColor`: SNES color/palette management
+- `gfx::Tile16` and `gfx::SnesTile`: Tile format representations
+- Graphics sheets (223 total) loaded from ROM with compression support (LC-LZ2)
+
+**Zelda3-Specific Logic** (`src/zelda3/`)
+- `zelda3::Overworld`: Manages 160+ overworld maps (Light World, Dark World, Special World)
+- `zelda3::OverworldMap`: Individual map data (tiles, entities, properties)
+- `zelda3::Dungeon`: Dungeon room management (296 rooms)
+- `zelda3::Sprite`: Sprite and enemy data structures
+
+**Canvas System** (`src/app/gui/canvas.h`)
+- `gui::Canvas`: ImGui-based drawable canvas with pan/zoom/grid support
+- Context menu system for entity editing
+- Automation API for AI agent integration
+- Usage tracker for click/interaction statistics
+
+**Asar Integration** (`src/core/asar_wrapper.h`)
+- `core::AsarWrapper`: C++ wrapper around Asar assembler library
+- Provides patch application, symbol extraction, and error reporting
+- Used by CLI tool and GUI for assembly patching
+
+**z3ed CLI Tool** (`src/cli/`)
+- AI-powered command-line interface with Ollama and Gemini support
+- TUI (Terminal UI) components for interactive editing
+- Resource catalog system for ROM data queries
+- Test suite generation and execution
+- Network collaboration support (experimental)
+
+### Key Architectural Patterns
+
+**Pattern 1: Modular Editor Design**
+- Large editor classes decomposed into smaller, single-responsibility modules
+- Separate renderer classes (e.g., `OverworldEntityRenderer`)
+- UI panels managed by dedicated classes (e.g., `MapPropertiesSystem`)
+- Main editor acts as coordinator, not implementer
+
+**Pattern 2: Callback-Based Communication**
+- Child components receive callbacks from parent editors via `SetCallbacks()`
+- Avoids circular dependencies between modules
+- Example: `MapPropertiesSystem` calls `RefreshCallback` to notify `OverworldEditor`
+
+**Pattern 3: Progressive Loading via `gfx::Arena`**
+- All expensive asset loading performed asynchronously
+- Queue textures with priority: `gfx::Arena::Get().QueueDeferredTexture(bitmap, priority)`
+- Process in batches during `Update()`: `GetNextDeferredTextureBatch(high_count, low_count)`
+- Prevents UI freezes during ROM loading
+
+**Pattern 4: Bitmap/Surface Synchronization**
+- `Bitmap::data_` (C++ vector) and `surface_->pixels` (SDL buffer) must stay in sync
+- Use `set_data()` for bulk replacement (syncs both)
+- Use `WriteToPixel()` for single-pixel modifications
+- Never assign directly to `mutable_data()` for replacements
+
+## Development Guidelines
+
+### Naming Conventions
+- **Load**: Reading data from ROM into memory
+- **Render**: Processing graphics data into bitmaps/textures (CPU pixel operations)
+- **Draw**: Displaying textures/shapes on canvas via ImGui (GPU rendering)
+- **Update**: UI state changes, property updates, input handling
+
+### Graphics Refresh Logic
+When a visual property changes:
+1. Update the property in the data model
+2. Call relevant `Load*()` method (e.g., `map.LoadAreaGraphics()`)
+3. Force a redraw: Use `Renderer::Get().RenderBitmap()` for immediate updates (not `UpdateBitmap()`)
+
+### Graphics Sheet Management
+When modifying graphics sheets:
+1. Get mutable reference: `auto& sheet = Arena::Get().mutable_gfx_sheet(index);`
+2. Make modifications
+3. Notify Arena: `Arena::Get().NotifySheetModified(index);`
+4. Changes propagate automatically to all editors
+
+### UI Theming System
+- **Never use hardcoded colors** - Always use `AgentUITheme`
+- Fetch theme: `const auto& theme = AgentUI::GetTheme();`
+- Use semantic colors: `theme.panel_bg_color`, `theme.status_success`, etc.
+- Use helper functions: `AgentUI::PushPanelStyle()`, `AgentUI::RenderSectionHeader()`, `AgentUI::StyledButton()`
+
+### Multi-Area Map Configuration
+- **Always use** `zelda3::Overworld::ConfigureMultiAreaMap()` when changing map area size
+- Never set `area_size` property directly
+- Method handles parent ID assignment and ROM data persistence
+
+### Version-Specific Features
+- Check ROM's `asm_version` byte before showing UI for ZSCustomOverworld features
+- Display helpful messages for unsupported features (e.g., "Requires ZSCustomOverworld v3+")
+
+### Entity Visibility Standards
+Render overworld entities with high-contrast colors at 0.85f alpha:
+- **Entrances**: Bright yellow-gold
+- **Exits**: Cyan-white
+- **Items**: Bright red
+- **Sprites**: Bright magenta
+
+### Debugging with Startup Flags
+Jump directly to editors for faster development:
+```bash
+# Open specific editor with ROM
+./yaze --rom_file=zelda3.sfc --editor=Dungeon
+
+# Open with specific cards visible
+./yaze --rom_file=zelda3.sfc --editor=Dungeon --cards="Room 0,Room 1,Object Editor"
+
+# Enable debug logging
+./yaze --debug --log_file=debug.log --rom_file=zelda3.sfc --editor=Overworld
+```
+
+Available editors: Assembly, Dungeon, Graphics, Music, Overworld, Palette, Screen, Sprite, Message, Hex, Agent, Settings
+
+## Testing Strategy
+
+**For comprehensive testing documentation, see**:
+- [`test/README.md`](test/README.md) - Test structure, organization, default vs optional suites
+- [`docs/internal/ci-and-testing.md`](docs/internal/ci-and-testing.md) - CI pipeline and test infrastructure
+- [`docs/public/build/quick-reference.md`](docs/public/build/quick-reference.md#5-testing) - Test execution quick reference
+
+### Test Organization
+```
+test/
+├── unit/           # Fast, isolated component tests (no ROM required)
+├── integration/    # Multi-component tests (may require ROM)
+├── e2e/           # Full UI workflow tests (ImGui Test Engine)
+├── benchmarks/    # Performance tests
+└── mocks/         # Mock objects for isolation
+```
+
+### Test Categories
+- **Default/Stable Tests** (always enabled): Unit/integration tests, GUI smoke tests - no external dependencies
+- **ROM-Dependent Tests** (optional): Full ROM workflows, version upgrades, data integrity validation
+- **Experimental AI Tests** (optional): AI-powered features, vision models, agent automation
+- **Benchmark Tests**: Performance profiling and optimization validation
+
+### Running Tests
+
+**Quick start** (stable tests only):
+```bash
+ctest --test-dir build -L stable
+```
+
+**With ROM tests**:
+```bash
+cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=~/zelda3.sfc
+ctest --test-dir build -L rom_dependent
+```
+
+**All tests** (uses preset configuration):
+```bash
+ctest --test-dir build
+```
+
+See `test/README.md` for complete test organization, presets, and command reference.
+
+### Writing New Tests
+- New class `MyClass`? → Add `test/unit/my_class_test.cc`
+- Integration test? → Add `test/integration/my_class_test.cc`
+- GUI workflow? → Add `test/e2e/my_class_test.cc`
+- ROM-dependent? → Add `test/e2e/rom_dependent/my_rom_test.cc` (requires flag)
+- AI features? → Add `test/integration/ai/my_ai_test.cc` (requires flag)
+
+### GUI Test Automation
+- E2E framework uses `ImGuiTestEngine` for UI automation
+- All major widgets have stable IDs for discovery
+- Test helpers in `test/test_utils.h`: `LoadRomInTest()`, `OpenEditorInTest()`
+- AI agents can use `z3ed gui discover`, `z3ed gui click` for automation
+
+## Platform-Specific Notes
+
+### Windows
+- Requires Visual Studio 2022 with "Desktop development with C++" workload
+- Run `scripts\verify-build-environment.ps1` before building
+- gRPC builds take 15-20 minutes first time (use vcpkg for faster builds)
+- Watch for path length limits: Enable long paths with `git config --global core.longpaths true`
+
+### macOS
+- Supports both Apple Silicon (ARM64) and Intel (x86_64)
+- Use `mac-uni` preset for universal binaries
+- Bundled Abseil used by default to avoid deployment target mismatches
+- **ARM64 Note**: gRPC v1.67.1 is the tested stable version (see BUILD-TROUBLESHOOTING.md for details)
+
+### Linux
+- Requires GCC 13+ or Clang 16+
+- Install dependencies: `libgtk-3-dev`, `libdbus-1-dev`, `pkg-config`
+
+**Platform-specific build issues?** See `docs/BUILD-TROUBLESHOOTING.md`
+
+## CI/CD Pipeline
+
+The project uses GitHub Actions for continuous integration and deployment:
+
+### Workflows
+- **ci.yml**: Build and test on Linux, macOS, Windows (runs on push to master/develop, PRs)
+- **release.yml**: Build release artifacts and publish GitHub releases
+- **code-quality.yml**: clang-format, cppcheck, clang-tidy checks
+- **security.yml**: Security scanning and dependency audits
+
+### Composite Actions
+Reusable build steps in `.github/actions/`:
+- `setup-build` - Configure build environment with caching
+- `build-project` - Build with CMake and optimal settings
+- `run-tests` - Execute test suites with result uploads
+
+### Key Features
+- CPM dependency caching for faster builds
+- sccache/ccache for incremental compilation
+- Platform-specific test execution (stable, unit, integration)
+- Automatic artifact uploads on build/test failures
+
+## Git Workflow
+
+**Current Phase:** Pre-1.0 (Relaxed Rules)
+
+For detailed workflow documentation, see `docs/B4-git-workflow.md`.
+
+### Quick Guidelines
+- **Documentation/Small fixes**: Commit directly to `master` or `develop`
+- **Experiments/Features**: Use feature branches (`feature/<description>`)
+- **Breaking changes**: Use feature branches and document in changelog
+- **Commit messages**: Follow Conventional Commits (`feat:`, `fix:`, `docs:`, etc.)
+
+### Planned Workflow (Post-1.0)
+When the project reaches v1.0 or has multiple active contributors, we'll transition to formal Git Flow with protected branches, required PR reviews, and release branches.
+
+## Code Style
+
+- Format code with clang-format: `cmake --build build --target format`
+- Check format without changes: `cmake --build build --target format-check`
+- Style guide: Google C++ Style Guide (enforced via clang-format)
+- Use `absl::Status` and `absl::StatusOr<T>` for error handling
+- Macros: `RETURN_IF_ERROR()`, `ASSIGN_OR_RETURN()` for status propagation
+
+## Important File Locations
+
+- ROM loading: `src/app/rom.cc:Rom::LoadFromFile()`
+- Overworld editor: `src/app/editor/overworld/overworld_editor.cc`
+- Dungeon editor: `src/app/editor/dungeon/dungeon_editor.cc`
+- Graphics arena: `src/app/gfx/snes_tile.cc` and `src/app/gfx/bitmap.cc`
+- Asar wrapper: `src/core/asar_wrapper.cc`
+- Main application: `src/yaze.cc`
+- CLI tool: `src/cli/z3ed.cc`
+- Test runner: `test/yaze_test.cc`
+
+## Common Pitfalls
+
+1. **Bitmap data desync**: Always use `set_data()` for bulk updates, not `mutable_data()` assignment
+2. **Missing texture queue processing**: Call `ProcessTextureQueue()` every frame
+3. **Incorrect graphics refresh order**: Update model → Load from ROM → Force render
+4. **Skipping `ConfigureMultiAreaMap()`**: Always use this method for map size changes
+5. **Hardcoded colors**: Use `AgentUITheme` system, never raw `ImVec4` values
+6. **Blocking texture loads**: Use `gfx::Arena` deferred loading system
+7. **Missing ROM state checks**: Always verify `rom_->is_loaded()` before operations

CMakeLists.txt

@@ -2,90 +2,72 @@
 # by scawful
 cmake_minimum_required(VERSION 3.16)
 
-# Set policy version to handle compatibility issues
-if(POLICY CMP0091)
-  cmake_policy(SET CMP0091 NEW)
+# Set minimum policy version for subdirectories to allow older dependencies like yaml-cpp
+# This allows cmake_minimum_required in subdirectories to use versions < 3.5
+set(CMAKE_POLICY_VERSION_MINIMUM 3.5 CACHE STRING "Minimum policy version for subdirectories")
+
+# Set policies for compatibility
+cmake_policy(SET CMP0091 NEW)
+# CMP0091 allows CMAKE_MSVC_RUNTIME_LIBRARY to be set by presets
+# Windows presets specify dynamic CRT (/MD) to avoid linking issues
+cmake_policy(SET CMP0048 NEW)
+cmake_policy(SET CMP0077 NEW)
+
+# Enable Objective-C only on macOS where it's actually used
+if(DEFINED ENV{YAZE_VERSION_OVERRIDE})
+    set(YAZE_VERSION $ENV{YAZE_VERSION_OVERRIDE})
+elseif(DEFINED YAZE_VERSION_OVERRIDE)
+     set(YAZE_VERSION ${YAZE_VERSION_OVERRIDE})
+else()
+    set(YAZE_VERSION "0.3.9")
 endif()
 
-# Set additional policies to handle submodule compatibility
-if(POLICY CMP0048)
-  cmake_policy(SET CMP0048 NEW)
+if(CMAKE_SYSTEM_NAME MATCHES "Darwin")
+    project(yaze VERSION ${YAZE_VERSION}
+                 DESCRIPTION "Yet Another Zelda3 Editor"
+                 LANGUAGES CXX C OBJC OBJCXX)
+else()
+    project(yaze VERSION ${YAZE_VERSION}
+                 DESCRIPTION "Yet Another Zelda3 Editor"
+                 LANGUAGES CXX C)
 endif()
-if(POLICY CMP0077)
-  cmake_policy(SET CMP0077 NEW)
-endif()
-if(POLICY CMP0091)
-  cmake_policy(SET CMP0091 NEW)
+
+# Include build options first
+include(cmake/options.cmake)
+
+# Enable ccache for faster rebuilds if available
+find_program(CCACHE_FOUND ccache)
+if(CCACHE_FOUND)
+    message(STATUS "✓ ccache found, enabling for faster builds")
+    set(CMAKE_CXX_COMPILER_LAUNCHER ccache)
+    set(CMAKE_C_COMPILER_LAUNCHER ccache)
 endif()
 
+# Version is defined in project() above - use those variables
+# CMake automatically sets: yaze_VERSION, yaze_VERSION_MAJOR, yaze_VERSION_MINOR, yaze_VERSION_PATCH
+# These YAZE_VERSION_* aliases are for compatibility with existing code
+set(YAZE_VERSION_MAJOR ${yaze_VERSION_MAJOR})
+set(YAZE_VERSION_MINOR ${yaze_VERSION_MINOR})
+set(YAZE_VERSION_PATCH ${yaze_VERSION_PATCH})
+
 # Suppress deprecation warnings from submodules
 set(CMAKE_WARN_DEPRECATED OFF CACHE BOOL "Suppress deprecation warnings")
 
-# Handle pthread issues on Windows
-if(WIN32)
-    set(THREADS_PREFER_PTHREAD_FLAG OFF)
-endif()
+# Add cmake directory to module path
+set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
 
-project(yaze VERSION 0.3.1
-             DESCRIPTION "Yet Another Zelda3 Editor"
-             LANGUAGES CXX C)
+# Include utility functions
+include(cmake/utils.cmake)
 
-# Set project metadata
-set(YAZE_VERSION_MAJOR 0)
-set(YAZE_VERSION_MINOR 3)
-set(YAZE_VERSION_PATCH 1)
+# Set up dependencies using CPM.cmake
+include(cmake/dependencies.cmake)
 
-configure_file(src/yaze_config.h.in yaze_config.h @ONLY)
-
-# Build Flags
-set(YAZE_BUILD_APP ON)
-set(YAZE_BUILD_LIB ON)
-set(YAZE_BUILD_EMU ON)
-set(YAZE_BUILD_Z3ED ON)
-set(YAZE_BUILD_TESTS ON)
-set(YAZE_INSTALL_LIB OFF)
-
-# Testing and CI Configuration
-option(YAZE_ENABLE_ROM_TESTS "Enable tests that require ROM files" OFF)
-option(YAZE_ENABLE_EXPERIMENTAL_TESTS "Enable experimental/unstable tests" ON)
-option(YAZE_ENABLE_UI_TESTS "Enable ImGui Test Engine UI testing" ON)
-option(YAZE_MINIMAL_BUILD "Minimal build for CI (disable optional features)" OFF)
-
-# Configure minimal builds for CI/CD
-if(YAZE_MINIMAL_BUILD)
-  set(YAZE_ENABLE_UI_TESTS OFF CACHE BOOL "Disabled for minimal build" FORCE)
-  set(YAZE_BUILD_Z3ED OFF CACHE BOOL "Disabled for minimal build" FORCE)
-  # Keep EMU and LIB enabled for comprehensive testing
-  set(YAZE_BUILD_EMU ON CACHE BOOL "Required for test suite" FORCE)
-  set(YAZE_BUILD_LIB ON CACHE BOOL "Required for test suite" FORCE)
-  set(YAZE_INSTALL_LIB OFF CACHE BOOL "Disabled for minimal build" FORCE)
-endif()
+# Additional configuration options
+option(YAZE_SUPPRESS_WARNINGS "Suppress compiler warnings (use -v preset suffix for verbose)" ON)
 set(YAZE_TEST_ROM_PATH "${CMAKE_BINARY_DIR}/bin/zelda3.sfc" CACHE STRING "Path to test ROM file")
 
-# libpng features in bitmap.cc - conditional for minimal builds
-if(PNG_FOUND)
-    add_definitions("-DYAZE_LIB_PNG=1")
-else()
-    add_definitions("-DYAZE_LIB_PNG=0")
-    message(STATUS "Building without PNG support for minimal build")
-endif()
-
-# Modern CMake standards
-set(CMAKE_CXX_STANDARD 23)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-set(CMAKE_CXX_EXTENSIONS OFF)
-set(CMAKE_C_STANDARD 99)
-set(CMAKE_C_STANDARD_REQUIRED ON)
-
-# Output directories
-include(GNUInstallDirs)
-set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
-set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
-set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_BINDIR})
-set(CMAKE_POSITION_INDEPENDENT_CODE ON)
-set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
-set(BUILD_SHARED_LIBS OFF)
-set(CMAKE_FIND_FRAMEWORK LAST)
+# Export compile commands for clangd/LSP
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 # Platform detection
 if(CMAKE_SYSTEM_NAME MATCHES "Darwin")
@@ -94,107 +76,41 @@ elseif(CMAKE_SYSTEM_NAME MATCHES "Linux")
     set(YAZE_PLATFORM_LINUX ON)
 elseif(CMAKE_SYSTEM_NAME MATCHES "Windows")
     set(YAZE_PLATFORM_WINDOWS ON)
-    # Enable vcpkg integration for Windows builds
-    if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
-        set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
-            CACHE STRING "Vcpkg toolchain file")
-    elseif(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake" AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
-        set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
-            CACHE STRING "Vcpkg toolchain file")
-    endif()
 endif()
 
-# Create a common interface target for shared settings
-add_library(yaze_common INTERFACE)
-target_compile_features(yaze_common INTERFACE cxx_std_23)
+# Setup compiler flags and common interface target
+yaze_add_compiler_flags()
 
-# Platform-specific configurations
-if(YAZE_PLATFORM_LINUX)
-    target_compile_definitions(yaze_common INTERFACE linux stricmp=strcasecmp)
-elseif(YAZE_PLATFORM_MACOS)
-    set(CMAKE_INSTALL_PREFIX /usr/local)
-    target_compile_definitions(yaze_common INTERFACE MACOS)
-elseif(YAZE_PLATFORM_WINDOWS)
-    include(cmake/vcpkg.cmake)
-    target_compile_definitions(yaze_common INTERFACE WINDOWS)
+# Configure yaze_config.h
+configure_file(
+  ${CMAKE_CURRENT_SOURCE_DIR}/src/yaze_config.h.in
+  ${CMAKE_CURRENT_BINARY_DIR}/yaze_config.h
+  @ONLY
+)
 
-    # Windows-specific architecture detection and configuration
-    if(CMAKE_SYSTEM_PROCESSOR MATCHES "ARM64|aarch64")
-        target_compile_definitions(yaze_common INTERFACE YAZE_ARCH_ARM64)
-        message(STATUS "Building for Windows ARM64")
-    elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "AMD64|x86_64")
-        target_compile_definitions(yaze_common INTERFACE YAZE_ARCH_X64)
-        message(STATUS "Building for Windows x64")
-    elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "i386|i686|x86")
-        target_compile_definitions(yaze_common INTERFACE YAZE_ARCH_X86)
-        message(STATUS "Building for Windows x86")
-    else()
-        message(WARNING "Unknown Windows architecture: ${CMAKE_SYSTEM_PROCESSOR}")
-    endif()
-endif()
+# Output directories
+include(GNUInstallDirs)
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_BINDIR})
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+set(BUILD_SHARED_LIBS OFF)
 
-# Compiler-specific settings
-if(MSVC)
-    target_compile_options(yaze_common INTERFACE 
-        /W4 /permissive-
-        /bigobj  # Support large object files
-        /utf-8   # Use UTF-8 encoding
-    )
-    target_compile_definitions(yaze_common INTERFACE 
-        _CRT_SECURE_NO_WARNINGS
-        _CRT_NONSTDC_NO_WARNINGS
-        SILENCE_CXX23_DEPRECATIONS
-        _SILENCE_CXX23_DEPRECATION_WARNING
-        _SILENCE_ALL_CXX23_DEPRECATION_WARNINGS
-        NOMINMAX  # Disable min/max macros
-        WIN32_LEAN_AND_MEAN  # Reduce Windows header bloat
-        strncasecmp=_strnicmp
-        strcasecmp=_stricmp
-    )
-else()
-    target_compile_options(yaze_common INTERFACE 
-        -Wall -Wextra -Wpedantic
-        -Wno-deprecated-declarations  # Silence deprecation warnings
-        -Wno-c++23-compat             # Silence C++23 compatibility warnings
-    )
-    # Add C++23 deprecation silencing for GCC/Clang
-    target_compile_definitions(yaze_common INTERFACE 
-        _SILENCE_CXX23_DEPRECATION_WARNING
-        _SILENCE_ALL_CXX23_DEPRECATION_WARNINGS
-        ABSL_HAVE_INTRINSIC_INT128=1  # Enable intrinsic int128 support
-    )
-endif()
-
-# Abseil Standard Specifications
-include(cmake/absl.cmake)
-
-# SDL2 and PNG
-include(cmake/sdl2.cmake)
-
-# Asar
-include(cmake/asar.cmake)
-
-# Google Test (if needed for main app integration)
-if (YAZE_BUILD_TESTS)
-include(cmake/gtest.cmake)
-endif()
-
-# ImGui (after minimal build flags are set)
-include(cmake/imgui.cmake)
+# Handle dependencies
 
 # Project Files
-# Copy theme files to build directory (for development)
-file(GLOB THEME_FILES "${CMAKE_SOURCE_DIR}/assets/themes/*.theme")
-file(COPY ${THEME_FILES} DESTINATION "${CMAKE_BINARY_DIR}/assets/themes/")
-
-# IMPORTANT: Also ensure themes are included in macOS bundles
-# This is handled in src/CMakeLists.txt via YAZE_RESOURCE_FILES
-
 add_subdirectory(src)
 
+# Tools
+option(YAZE_BUILD_TOOLS "Build development utility tools" OFF)
+if(YAZE_BUILD_TOOLS)
+  message(STATUS "Building development tools")
+  add_subdirectory(tools)
+endif()
+
 # Tests
-if (YAZE_BUILD_TESTS)
-add_subdirectory(test)
+if(YAZE_BUILD_TESTS)
+  add_subdirectory(test)
 endif()
 
 # Code quality targets
@@ -206,17 +122,25 @@ if(CLANG_FORMAT)
        "${CMAKE_SOURCE_DIR}/test/*.cc"
        "${CMAKE_SOURCE_DIR}/test/*.h")
 
-  add_custom_target(format
+  # Exclude third-party library directories from formatting
+  list(FILTER ALL_SOURCE_FILES EXCLUDE REGEX "src/lib/.*")
+
+  add_custom_target(yaze-format
     COMMAND ${CLANG_FORMAT} -i --style=Google ${ALL_SOURCE_FILES}
     COMMENT "Running clang-format on source files"
   )
 
-  add_custom_target(format-check
+  add_custom_target(yaze-format-check
     COMMAND ${CLANG_FORMAT} --dry-run --Werror --style=Google ${ALL_SOURCE_FILES}
     COMMENT "Checking code format"
   )
 endif()
 
 # Packaging configuration
-include(cmake/packaging.cmake)
+include(cmake/packaging/cpack.cmake)
 
+add_custom_target(build_cleaner
+  COMMAND ${CMAKE_COMMAND} -E echo "Running scripts/build_cleaner.py --dry-run"
+  COMMAND ${CMAKE_COMMAND} -E chdir ${CMAKE_SOURCE_DIR} ${Python3_EXECUTABLE} scripts/build_cleaner.py --dry-run
+  COMMENT "Validate CMake source lists and includes"
+)

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to YAZE
+
+The YAZE project reserves **master** for promoted releases and uses **develop**
+for day‑to‑day work. Larger efforts should branch from `develop` and rebase
+frequently. Follow the existing Conventional Commit subject format when pushing
+history (e.g. `feat: add sprite tab filtering`, `fix: guard null rom path`).
+
+The repository ships a clang-format and clang-tidy configuration (Google style,
+2-space indentation, 80-column wrap). Always run formatter and address
+clang-tidy warnings on the files you touch.
+
+## Engineering Expectations
+
+1. **Refactor deliberately**
+   - Break work into reviewable patches.
+   - Preserve behaviour while moving code; add tests before/after when possible.
+   - Avoid speculative abstractions—prove value in the PR description.
+   - When deleting or replacing major systems, document the migration (see
+     `handbook/blueprints/editor-manager-architecture.md` for precedent).
+
+2. **Verify changes**
+   - Use the appropriate CMake preset for your platform (`mac-dbg`, `lin-dbg`,
+     `win-dbg`, etc.).
+   - Run the targeted test slice: `ctest --preset dev` for fast coverage; add new
+     GoogleTest cases where feasible.
+   - For emulator-facing work, exercise relevant UI flows manually before
+     submitting.
+   - Explicitly call out remaining manual-verification items in the PR.
+
+3. **Work with the build & CI**
+   - Honour the existing `cmake --preset` structure; avoid hardcoding paths.
+   - Keep `vcpkg.json` and the CI workflows in sync when adding dependencies.
+   - Use the deferred texture queue and arena abstractions rather than talking to
+     SDL directly.
+
+## Documentation Style
+
+YAZE documentation is concise and factual. When updating `docs/public/`:
+
+- Avoid marketing language, emojis, or decorative status badges.
+- Record the actual project state (e.g., mark editors as **stable** vs
+  **experimental** based on current source).
+- Provide concrete references (file paths, function names) when describing
+  behaviour.
+- Prefer bullet lists and short paragraphs; keep quick-start examples runnable.
+- Update cross-references when moving or renaming files.
+- For review handoffs, capture what remains to be done instead of transfusing raw
+  planning logs.
+
+If you notice obsolete or inaccurate docs, fix them in the same change rather
+than layering new “note” files.
+
+## Pull Request Checklist
+
+- [ ] Tests and builds succeed on your platform (note the preset/command used).
+- [ ] New code is formatted (`clang-format`) and clean (`clang-tidy`).
+- [ ] Documentation and comments reflect current behaviour.
+- [ ] Breaking changes are mentioned in the PR and, if relevant, `docs/public/reference/changelog.md`.
+- [ ] Any new assets or scripts are referenced in the repo’s structure guides.
+
+Respect these guidelines and we can keep the codebase approachable, accurate,
+and ready for the next set of contributors.

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = "yaze"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "0.3.1"
+PROJECT_NUMBER         = "0.3.2"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -61,20 +61,20 @@ PROJECT_BRIEF          = Link to the Past ROM Editor
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = "src/win32/yaze.ico"
+PROJECT_LOGO           = "assets/yaze.ico"
 
 # With the PROJECT_ICON tag one can specify an icon that is included in the tabs
 # when the HTML document is shown. Doxygen will copy the logo to the output
 # directory.
 
-PROJECT_ICON           = "src/win32/yaze.ico"
+PROJECT_ICON           = "assets/yaze.ico"
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = 
+OUTPUT_DIRECTORY       = build/docs
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -85,7 +85,7 @@ OUTPUT_DIRECTORY       =
 # control the number of sub-directories.
 # The default value is: NO.
 
-CREATE_SUBDIRS         = NO
+CREATE_SUBDIRS         = YES 
 
 # Controls the number of sub-directories that will be created when
 # CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every
@@ -949,7 +949,9 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  =
+INPUT                  = docs/public \
+                         src \
+                         incl
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1057,7 +1059,10 @@ RECURSIVE              = YES
 EXCLUDE                = assets/ \
                          build/ \
                          cmake/ \
-                          src/lib/ \         
+                         docs/html/ \
+                         docs/latex/ \
+                         docs/internal/ \
+                         src/lib/
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1168,7 +1173,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = getting-started.md
+USE_MDFILE_AS_MAINPAGE = docs/public/index.md
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common

GEMINI.md

@@ -0,0 +1,215 @@
+# Gemini Workflow Instructions for the `yaze` Project
+
+This document provides a summary of the `yaze` project to guide an AI assistant in understanding the codebase, architecture, and development workflows.
+
+> **Coordination Requirement**  
+> Gemini-based agents must read and update the shared coordination board
+> (`docs/internal/agents/coordination-board.md`) before making changes. Follow the protocol in
+> `AGENTS.md`, use the appropriate persona ID (e.g., `GEMINI_AUTOM`), and respond to any pending
+> entries targeting you.
+
+## User Profile
+
+- **User**: A Google programmer working on ROM hacking projects on macOS.
+- **IDE**: Visual Studio Code with the CMake Tools extension.
+- **Build System**: CMake with a preference for the "Unix Makefiles" generator.
+- **Workflow**: Uses CMake presets and a separate `build_test` directory for test builds.
+- **AI Assistant Build Policy**: When the AI assistant needs to build the project, it must use a dedicated build directory (e.g., `build_ai` or `build_agent`) to avoid interrupting the user's active builds. Never use `build` or `build_test` directories.
+
+## Project Overview
+
+- **`yaze`**: A cross-platform GUI editor for "The Legend of Zelda: A Link to the Past" (ALTTP) ROMs. It is designed for compatibility with ZScream projects.
+- **`z3ed`**: A powerful command-line interface (CLI) for `yaze`. It features a resource-oriented design (`z3ed <resource> <action>`) and serves as the primary API for an AI-driven conversational agent.
+- **`yaze.org`**: The file `docs/yaze.org` is an Emacs Org-Mode file used as a development tracker for active issues and features.
+
+## Build Instructions
+
+- Use the presets in `CMakePresets.json` (debug, AI, release, dev, CI, etc.). Always run the verifier
+  script before the first build on a machine.
+- Gemini agents must configure/build in dedicated directories (`build_ai`, `build_agent`, …) to avoid
+  touching the user’s `build` or `build_test` folders.
+- Consult [`docs/public/build/quick-reference.md`](docs/public/build/quick-reference.md) for the
+  canonical command list, preset overview, and testing guidance.
+
+## Testing
+
+- **Framework**: GoogleTest.
+- **Test Categories**:
+    - `STABLE`: Fast, reliable, run in CI.
+    - `ROM_DEPENDENT`: Require a ROM file, skipped in CI unless a ROM is provided.
+    - `EXPERIMENTAL`: May be unstable, allowed to fail.
+- **Running Tests**:
+  ```bash
+  # Run stable tests using ctest and presets
+  ctest --preset dev
+
+  # Run comprehensive overworld tests (requires a ROM)
+  ./scripts/run_overworld_tests.sh /path/to/zelda3.sfc
+  ```
+- **E2E GUI Testing**: The project includes a sophisticated end-to-end testing framework using `ImGuiTestEngine`, accessible via a gRPC service. The `z3ed agent test` command can execute natural language prompts as GUI tests.
+
+## Core Architecture & Features
+
+- **Overworld Editor**: Full support for vanilla and `ZSCustomOverworld` v2/v3 ROMs, ensuring compatibility with ZScream projects.
+- **Dungeon Editor**: A modular, component-based system for editing rooms, objects, sprites, and more. See `docs/E2-dungeon-editor-guide.md` and `docs/E3-dungeon-editor-design.md`.
+- **Graphics System**: A performant system featuring:
+    - `Arena`-based resource management.
+    - `Bitmap` class for SNES-specific graphics formats.
+    - `Tilemap` with an LRU cache.
+    - `AtlasRenderer` for batched drawing.
+- **Asar Integration**: Built-in support for the Asar 65816 assembler to apply assembly patches to the ROM.
+
+## Editor System Architecture
+
+The editor system is designed around a central `EditorManager` that orchestrates multiple editors and UI components.
+
+- **`EditorManager`**: The top-level class that manages multiple `RomSession`s, the main menu, and all editor windows. It handles the application's main update loop.
+- **`RomSession`**: Each session encapsulates a `Rom` instance and a corresponding `EditorSet`, allowing multiple ROMs to be open simultaneously.
+- **`EditorSet`**: A container for all individual editor instances (Overworld, Dungeon, etc.) associated with a single ROM session.
+- **`Editor` (Base Class)**: A virtual base class (`src/app/editor/editor.h`) that defines a common interface for all editors, including methods like `Initialize`, `Load`, `Update`, and `Save`.
+
+### Component-Based Editors
+The project is moving towards a component-based architecture to improve modularity and maintainability. This is most evident in the Dungeon Editor.
+
+- **Dungeon Editor**: Refactored into a collection of single-responsibility components orchestrated by `DungeonEditor`:
+    - `DungeonRoomSelector`: Manages the UI for selecting rooms and entrances.
+    - `DungeonCanvasViewer`: Handles the rendering of the dungeon room on the main canvas.
+    - `DungeonObjectSelector`: Provides the UI for browsing and selecting objects, sprites, and other editable elements.
+    - `DungeonObjectInteraction`: Manages mouse input, selection, and drag-and-drop on the canvas.
+    - `DungeonToolset`: The main toolbar for the editor.
+    - `DungeonRenderer`: A dedicated rendering engine for dungeon objects, featuring a cache for performance.
+    - `DungeonRoomLoader`: Handles the logic for loading all room data from the ROM, now optimized with parallel processing.
+    - `DungeonUsageTracker`: Analyzes and displays statistics on resource usage (blocksets, palettes, etc.).
+
+- **Overworld Editor**: Also employs a component-based approach with helpers like `OverworldEditorManager` for ZSCustomOverworld v3 features and `MapPropertiesSystem` for UI panels.
+
+### Specialized Editors
+- **Code Editors**: `AssemblyEditor` (a full-featured text editor) and `MemoryEditor` (a hex viewer).
+- **Graphics Editors**: `GraphicsEditor`, `PaletteEditor`, `GfxGroupEditor`, `ScreenEditor`, and the highly detailed `Tile16Editor` provide tools for all visual assets.
+- **Content Editors**: `SpriteEditor`, `MessageEditor`, and `MusicEditor` manage specific game content.
+
+### System Components
+Located in `src/app/editor/system/`, these components provide the core application framework:
+- `SettingsEditor`: Manages global and project-specific feature flags.
+- `PopupManager`, `ToastManager`: Handle all UI dialogs and notifications.
+- `ShortcutManager`, `CommandManager`: Manage keyboard shortcuts and command palette functionality.
+- `ProposalDrawer`, `AgentChatWidget`: Key UI components for the AI Agent Workflow, allowing for proposal review and conversational interaction.
+
+## Game Data Models (`zelda3` Namespace)
+
+The logic and data structures for ALTTP are primarily located in `src/zelda3/`.
+
+- **`Rom` Class (`app/rom.h`)**: This is the most critical data class. It holds the entire ROM content in a `std::vector<uint8_t>` and provides the central API for all data access.
+    - **Responsibilities**: Handles loading/saving ROM files, stripping SMC headers, and providing low-level read/write primitives (e.g., `ReadByte`, `WriteWord`).
+    - **Game-Specific Loading**: The `LoadZelda3` method populates game-specific data structures like palettes (`palette_groups_`) and graphics groups.
+    - **State**: Manages a `dirty_` flag to track unsaved changes.
+
+- **Overworld Model (`zelda3/overworld/`)**:
+    - `Overworld`: The main container class that orchestrates the loading of all overworld data, including maps, tiles, and entities. It correctly handles logic for both vanilla and `ZSCustomOverworld` ROMs.
+    - `OverworldMap`: Represents a single overworld screen, loading its own properties (palettes, graphics, music) based on the ROM version.
+    - `GameEntity`: A base class in `zelda3/common.h` for all interactive overworld elements like `OverworldEntrance`, `OverworldExit`, `OverworldItem`, and `Sprite`.
+
+- **Dungeon Model (`zelda3/dungeon/`)**:
+    - `DungeonEditorSystem`: A high-level API that serves as the backend for the UI, managing all dungeon editing logic (adding/removing sprites, items, doors, etc.).
+    - `Room`: Represents a single dungeon room, containing its objects, sprites, layout, and header information.
+    - `RoomObject` & `RoomLayout`: Define the structural elements of a room.
+    - `ObjectParser` & `ObjectRenderer`: High-performance components for directly parsing object data from the ROM and rendering them, avoiding the need for full SNES emulation.
+
+- **Sprite Model (`zelda3/sprite/`)**:
+    - `Sprite`: Represents an individual sprite (enemy, NPC).
+    - `SpriteBuilder`: A fluent API for programmatically constructing custom sprites.
+    - `zsprite.h`: Data structures for compatibility with Zarby's ZSpriteMaker format.
+
+- **Other Data Models**:
+    - `MessageData` (`message/`): Handles the game's text and dialogue system.
+    - `Inventory`, `TitleScreen`, `DungeonMap` (`screen/`): Represent specific non-gameplay screens.
+    - `music::Tracker` (`music/`): Contains legacy code from Hyrule Magic for handling SNES music data.
+
+## Graphics System (`gfx` Namespace)
+
+The `gfx` namespace contains a highly optimized graphics engine tailored for SNES ROM hacking.
+
+- **Core Concepts**:
+    - **`Bitmap`**: The fundamental class for image data. It supports SNES pixel formats, palette management, and is optimized with features like dirty-region tracking and a hash-map-based palette lookup cache for O(1) performance.
+    - **SNES Formats**: `snes_color`, `snes_palette`, and `snes_tile` provide structures and conversion functions for handling SNES-specific data (15-bit color, 4BPP/8BPP tiles, etc.).
+    - **`Tilemap`**: Represents a collection of tiles, using a texture `atlas` and a `TileCache` (with LRU eviction) for efficient rendering.
+
+- **Resource Management & Performance**:
+    - **`Arena`**: A singleton that manages all graphics resources. It pools `SDL_Texture` and `SDL_Surface` objects to reduce allocation overhead and uses custom deleters for automatic cleanup. It also manages the 223 global graphics sheets for the game.
+    - **`MemoryPool`**: A low-level, high-performance memory allocator that provides pre-allocated blocks for common graphics sizes, reducing `malloc` overhead and memory fragmentation.
+    - **`AtlasRenderer`**: A key performance component that batches draw calls by combining multiple smaller graphics onto a single large texture atlas.
+    - **Batching**: The `Arena` supports batching texture updates via `QueueTextureUpdate`, which minimizes expensive, blocking calls to the SDL rendering API.
+
+- **Format Handling & Optimization**:
+    - **`compression.h`**: Contains SNES-specific compression algorithms (LC-LZ2, Hyrule Magic) for handling graphics data from the ROM.
+    - **`BppFormatManager`**: A system for analyzing and converting between different bits-per-pixel (BPP) formats.
+    - **`GraphicsOptimizer`**: A high-level tool that uses the `BppFormatManager` to analyze graphics sheets and recommend memory and performance optimizations.
+    - **`scad_format.h`**: Provides compatibility with legacy Nintendo CAD file formats (CGX, SCR, COL) from the "gigaleak".
+
+- **Performance Monitoring**:
+    - **`PerformanceProfiler`**: A comprehensive system for timing operations using a `ScopedTimer` RAII class.
+    - **`PerformanceDashboard`**: An ImGui-based UI for visualizing real-time performance metrics collected by the profiler.
+
+## GUI System (`gui` Namespace)
+
+The `yaze` user interface is built with **ImGui** and is located in `src/app/gui`. It features a modern, component-based architecture designed for modularity, performance, and testability.
+
+### Canvas System (`gui::Canvas`)
+The canvas is the core of all visual editors. The main `Canvas` class (`src/app/gui/canvas.h`) has been refactored from a monolithic class into a coordinator that leverages a set of single-responsibility components found in `src/app/gui/canvas/`.
+
+- **`Canvas`**: The main canvas widget. It provides a modern, ImGui-style interface (`Begin`/`End`) and coordinates the various sub-components for drawing, interaction, and configuration.
+- **`CanvasInteractionHandler`**: Manages all direct user input on the canvas, such as mouse clicks, drags, and selections for tile painting and object manipulation.
+- **`CanvasContextMenu`**: A powerful, data-driven context menu system. It is aware of the current `CanvasUsage` mode (e.g., `TilePainting`, `PaletteEditing`) and displays relevant menu items dynamically.
+- **`CanvasModals`**: Handles all modal dialogs related to the canvas, such as "Advanced Properties," "Scaling Controls," and "BPP Conversion," ensuring a consistent UX.
+- **`CanvasUsageTracker` & `CanvasPerformanceIntegration`**: These components provide deep analytics and performance monitoring. They track user interactions, operation timings, and memory usage, integrating with the global `PerformanceDashboard` to identify bottlenecks.
+- **`CanvasUtils`**: A collection of stateless helper functions for common canvas tasks like grid drawing, coordinate alignment, and size calculations, promoting code reuse.
+
+### Theming and Styling
+The visual appearance of the editor is highly customizable through a robust theming system.
+
+- **`ThemeManager`**: A singleton that manages `EnhancedTheme` objects. It can load custom themes from `.theme` files, allowing users to personalize the editor's look and feel. It includes a built-in theme editor and selector UI.
+- **`BackgroundRenderer`**: Renders the animated, futuristic grid background for the main docking space, providing a polished, modern aesthetic.
+- **`style.cc` & `color.cc`**: Contain custom ImGui styling functions (`ColorsYaze`), `SnesColor` conversion utilities, and other helpers to maintain a consistent visual identity.
+
+### Specialized UI Components
+The `gui` namespace includes several powerful, self-contained widgets for specific ROM hacking tasks.
+
+- **`BppFormatUI`**: A comprehensive UI for managing SNES bits-per-pixel (BPP) graphics formats. It provides a format selector, a detailed analysis panel, a side-by-side conversion preview, and a batch comparison tool.
+- **`EnhancedPaletteEditor`**: An advanced tool for editing `SnesPalette` objects. It features a grid-based editor, a ROM palette manager for loading palettes directly from the game, and a color analysis view to inspect pixel distribution.
+- **`TextEditor`**: A full-featured text editor widget with syntax highlighting for 65816 assembly, undo/redo functionality, and standard text manipulation features.
+- **`AssetBrowser`**: A flexible, icon-based browser for viewing and managing game assets, such as graphics sheets.
+
+### Widget Registry for Automation
+A key feature for test automation and AI agent integration is the discoverability of UI elements.
+
+- **`WidgetIdRegistry`**: A singleton that catalogs all registered GUI widgets. It assigns a stable, hierarchical path (e.g., `Overworld/Canvas/Map`) to each widget, making the UI programmatically discoverable. This is the backbone of the `z3ed agent test` command.
+- **`WidgetIdScope`**: An RAII helper that simplifies the creation of hierarchical widget IDs by managing an ID stack, ensuring that widget paths are consistent and predictable.
+
+## ROM Hacking Context
+
+- **Game**: The Legend of Zelda: A Link to the Past (US/JP).
+- **`ZSCustomOverworld`**: A popular system for expanding overworld editing capabilities. `yaze` is designed to be fully compatible with ZScream's implementation of v2 and v3.
+- **Assembly**: Uses `asar` for 65816 assembly. A style guide is available at `docs/E1-asm-style-guide.md`.
+- **`usdasm` Disassembly**: The user has a local copy of the `usdasm` ALTTP disassembly at `/Users/scawful/Code/usdasm` which can be used for reference.
+
+## Git Workflow
+
+The project follows a simplified Git workflow for pre-1.0 development, with a more formal process documented for the future. For details, see `docs/B4-git-workflow.md`.
+
+- **Current (Pre-1.0)**: A relaxed model is in use. Direct commits to `develop` or `master` are acceptable for documentation and small fixes. Feature branches are used for larger, potentially breaking changes.
+- **Future (Post-1.0)**: The project will adopt a formal Git Flow model with `master`, `develop`, feature, release, and hotfix branches.
+
+## AI Agent Workflow (`z3ed agent`)
+
+A primary focus of the `yaze` project is its AI-driven agentic workflow, orchestrated by the `z3ed` CLI.
+
+- **Vision**: To create a conversational ROM hacking assistant that can inspect the ROM and perform edits based on natural language.
+- **Core Loop (MCP)**:
+    1.  **Model (Plan)**: The user provides a prompt. The agent uses an LLM (Ollama or Gemini) to create a plan, which is a sequence of `z3ed` commands.
+    2.  **Code (Generate)**: The LLM generates the commands based on a machine-readable catalog of the CLI's capabilities.
+    3.  **Program (Execute)**: The `z3ed` agent executes the commands.
+- **Proposal System**: To ensure safety, agent-driven changes are not applied directly. They are executed in a **sandboxed ROM copy** and saved as a **proposal**.
+- **Review & Acceptance**: The user can review the proposed changes via `z3ed agent diff` or a dedicated `ProposalDrawer` in the `yaze` GUI. The user must explicitly **accept** a proposal to merge the changes into the main ROM.
+- **Tool Use**: The agent can use read-only `z3ed` commands (e.g., `overworld-find-tile`, `dungeon-list-sprites`) as "tools" to inspect the ROM and gather context to answer questions or formulate a plan.
+- **API Discovery**: The agent learns the available commands and their schemas by calling `z3ed agent describe`, which exports the entire CLI surface area in a machine-readable format.
+- **Function Schemas**: The Gemini AI service uses function calling schemas defined in `assets/agent/function_schemas.json`. These schemas are automatically copied to the build directory and loaded at runtime. To modify the available functions, edit this JSON file rather than hardcoding them in the C++ source.

README.md

@@ -1,134 +1,98 @@
 # YAZE - Yet Another Zelda3 Editor
 
-A modern, cross-platform editor for The Legend of Zelda: A Link to the Past ROM hacking, built with C++23 and featuring complete Asar 65816 assembler integration.
+[![CI](https://github.com/scawful/yaze/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/scawful/yaze/actions)
+[![Code Quality](https://github.com/scawful/yaze/workflows/Code%20Quality/badge.svg)](https://github.com/scawful/yaze/actions)
+[![Security](https://github.com/scawful/yaze/workflows/Security%20Scanning/badge.svg)](https://github.com/scawful/yaze/actions)
+[![Release](https://github.com/scawful/yaze/workflows/Release/badge.svg)](https://github.com/scawful/yaze/actions)
+[![License](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE)
 
-[![Build Status](https://github.com/scawful/yaze/workflows/CI/badge.svg)](https://github.com/scawful/yaze/actions)
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+A cross-platform Zelda 3 ROM editor with a modern C++ GUI, Asar 65816 assembler integration, and an automation-friendly CLI (`z3ed`). YAZE bundles its toolchain, offers AI-assisted editing flows, and targets reproducible builds on Windows, macOS, and Linux.
 
-## Version 0.3.1 - Release
+## Highlights
+- **All-in-one editing**: Overworld, dungeon, sprite, palette, and messaging tools with live previews.
+- **Assembler-first workflow**: Built-in Asar integration, symbol extraction, and patch validation.
+- **Automation & AI**: `z3ed` exposes CLI/TUI automation, proposal workflows, and optional AI agents.
+- **Testing & CI hooks**: CMake presets, ROM-less test fixtures, and gRPC-based GUI automation support.
+- **Cross-platform toolchains**: Single source tree targeting MSVC, Clang, and GCC with identical presets.
+- **Modular AI stack**: Toggle agent UI (`YAZE_BUILD_AGENT_UI`), remote automation/gRPC (`YAZE_ENABLE_REMOTE_AUTOMATION`), and AI runtimes (`YAZE_ENABLE_AI_RUNTIME`) per preset.
 
-#### Asar 65816 Assembler Integration
-- **Cross-platform ROM patching** with assembly code support
-- **Symbol extraction** with addresses and opcodes from assembly files
-- **Assembly validation** with comprehensive error reporting
-- **Modern C++ API** with safe memory management
-
-#### ZSCustomOverworld v3
-- **Enhanced overworld editing** capabilities
-- **Advanced map properties** and metadata support
-- **Custom graphics support** and tile management
-- **Improved compatibility** with existing projects
-
-#### Advanced Features
-- **Theme Management**: Complete theme system with 5+ built-in themes and custom theme editor
-- **Multi-Session Support**: Work with multiple ROMs simultaneously in docked workspace
-- **Enhanced Welcome Screen**: Themed interface with quick access to all editors
-- **Message Editing**: Enhanced text editing interface with real-time preview
-- **GUI Docking**: Flexible workspace management with customizable layouts
-- **Modern CLI**: Enhanced z3ed tool with interactive TUI and subcommands
-- **Cross-Platform**: Full support for Windows, macOS, and Linux
-
-### 🛠️ Technical Improvements
-- **Modern CMake 3.16+**: Target-based configuration and build system
-- **CMakePresets**: Development workflow presets for better productivity
-- **Cross-platform CI/CD**: Automated builds and testing for all platforms
-- **Professional packaging**: NSIS, DMG, and DEB/RPM installers
-- **Enhanced testing**: ROM-dependent test separation for CI compatibility
+## Project Status
+`0.3.x` builds are in active development. Release automation is being reworked, so packaged builds may lag behind main. Follow `develop` for the most accurate view of current functionality.
 
 ## Quick Start
 
-### Build
+### Clone & Bootstrap
 ```bash
-# Clone with submodules
 git clone --recursive https://github.com/scawful/yaze.git
 cd yaze
-
-# Build with CMake
-cmake --preset debug        # macOS
-cmake -B build && cmake --build build  # Linux/Windows
 ```
 
-### Applications
-- **yaze**: Complete GUI editor for Zelda 3 ROM hacking
-- **z3ed**: Command-line tool with interactive interface
-- **yaze_test**: Comprehensive test suite for development
-
-## Usage
-
-### GUI Editor
-Launch the main application to edit Zelda 3 ROMs:
-- Load ROM files using native file dialogs
-- Edit overworld maps, dungeons, sprites, and graphics
-- Apply assembly patches with integrated Asar support
-- Export modifications as patches or modified ROMs
-
-### Command Line Tool
+Run the environment verifier once per machine:
 ```bash
-# Apply assembly patch
-z3ed asar patch.asm --rom=zelda3.sfc
+# macOS / Linux
+./scripts/verify-build-environment.sh --fix
 
-# Extract symbols from assembly
-z3ed extract patch.asm
-
-# Interactive mode
-z3ed --tui
+# Windows (PowerShell)
+.\scripts\verify-build-environment.ps1 -FixIssues
 ```
 
-### C++ API
-```cpp
-#include "yaze.h"
+### Configure & Build
+- Use the CMake preset that matches your platform (`mac-dbg`, `lin-dbg`, `win-dbg`, etc.).
+- Build with `cmake --build --preset <name> [--target …]`.
+- See [`docs/public/build/quick-reference.md`](docs/public/build/quick-reference.md) for the canonical
+  list of presets, AI build policy, and testing commands.
 
-// Load ROM and apply patch
-yaze_project_t* project = yaze_load_project("zelda3.sfc");
-yaze_apply_asar_patch(project, "patch.asm");
-yaze_save_project(project, "modified.sfc");
+### Agent Feature Flags
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `YAZE_BUILD_AGENT_UI` | `ON` when GUI builds are enabled | Compiles the chat/dialog widgets so the editor can host agent sessions. Turn this `OFF` when you want a lean GUI-only build. |
+| `YAZE_ENABLE_REMOTE_AUTOMATION` | `ON` for `*-ai` presets | Builds the gRPC servers/clients and protobufs that power GUI automation. |
+| `YAZE_ENABLE_AI_RUNTIME` | `ON` for `*-ai` presets | Enables Gemini/Ollama transports, proposal planning, and advanced routing logic. |
+| `YAZE_ENABLE_AGENT_CLI` | `ON` when CLI builds are enabled | Compiles the conversational agent stack consumed by `z3ed`. Disable to skip the CLI entirely. |
+
+Windows `win-*` presets keep every switch `OFF` by default (`win-dbg`, `win-rel`, `ci-windows`) so MSVC builds stay fast. Use `win-ai`, `win-vs-ai`, or the new `ci-windows-ai` preset whenever you need remote automation or AI runtime features.
+
+All bundled third-party code (SDL, ImGui, ImGui Test Engine, Asar, nlohmann/json, cpp-httplib, nativefiledialog-extended) now lives under `ext/` for easier vendoring and cleaner include paths.
+
+## Applications & Workflows
+- **`./build/bin/yaze`** – full GUI editor with multi-session dockspace, theming, and ROM patching.
+- **`./build/bin/z3ed --tui`** – CLI/TUI companion for scripting, AI-assisted edits, and Asar workflows.
+- **`./build_ai/bin/yaze_test --unit|--integration|--e2e`** – structured test runner for quick regression checks.
+- **`z3ed` + macOS automation** – pair the CLI with sketchybar/yabai/skhd or Emacs/Spacemacs to drive ROM workflows without opening the GUI.
+
+Typical commands:
+```bash
+# Launch GUI with a ROM
+./build/bin/yaze zelda3.sfc
+
+# Apply a patch via CLI
+./build/bin/z3ed asar patch.asm --rom zelda3.sfc
+
+# Run focused tests
+cmake --build --preset mac-ai --target yaze_test
+./build_ai/bin/yaze_test --unit
 ```
 
+## Testing
+- `./build_ai/bin/yaze_test --unit` for fast checks; add `--integration` or `--e2e --show-gui` for broader coverage.
+- `ctest --preset dev` mirrors CI’s stable set; `ctest --preset all` runs the full matrix.
+- Set `YAZE_TEST_ROM_PATH` or pass `--rom-path` when a test needs a real ROM image.
+
 ## Documentation
+- Human-readable docs live under `docs/public/` with an entry point at [`docs/public/index.md`](docs/public/index.md).
+- Run `doxygen Doxyfile` to generate API + guide pages (`build/docs/html` and `build/docs/latex`).
+- Agent playbooks, architecture notes, and testing recipes now live in [`docs/internal/`](docs/internal/README.md).
 
-- [Getting Started](docs/01-getting-started.md) - Setup and basic usage
-- [Build Instructions](docs/02-build-instructions.md) - Building from source
-- [API Reference](docs/04-api-reference.md) - Programming interface
-- [Contributing](docs/B1-contributing.md) - Development guidelines
-
-**[Complete Documentation](docs/index.md)**
-
-## Supported Platforms
-
-- **Windows** (MSVC 2019+, MinGW)
-- **macOS** (Intel and Apple Silicon)  
-- **Linux** (GCC 13+, Clang 16+)
-## ROM Compatibility
-
-- Original Zelda 3 ROMs (US/Japan versions)
-- ZSCustomOverworld v2/v3 enhanced overworld features
-- Community ROM hacks and modifications
-
-## Contributing
-
-See [Contributing Guide](docs/B1-contributing.md) for development guidelines.
-
-**Community**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk)
+## Contributing & Community
+- Review [`CONTRIBUTING.md`](CONTRIBUTING.md) and the build/test guides in `docs/public/`.
+- Conventional commit messages (`feat:`, `fix:`, etc.) keep history clean; use topic branches for larger work.
+- Chat with the team on [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk).
 
 ## License
+YAZE is licensed under the GNU GPL v3. See [`LICENSE`](LICENSE) for details and third-party notices.
 
-GNU GPL v3 - See [LICENSE](LICENSE) for details.
-
-## 🙏 Acknowledgments
-
-Takes inspiration from:
-- [Hyrule Magic](https://www.romhacking.net/utilities/200/) - Original Zelda 3 editor
-- [ZScream](https://github.com/Zarby89/ZScreamDungeon) - Dungeon editing capabilities
-- [Asar](https://github.com/RPGHacker/asar) - 65816 assembler integration
-
-## 📸 Screenshots
-
+## Screenshots
 ![YAZE GUI Editor](https://github.com/scawful/yaze/assets/47263509/8b62b142-1de4-4ca4-8c49-d50c08ba4c8e)
-
 ![Dungeon Editor](https://github.com/scawful/yaze/assets/47263509/d8f0039d-d2e4-47d7-b420-554b20ac626f)
-
 ![Overworld Editor](https://github.com/scawful/yaze/assets/47263509/34b36666-cbea-420b-af90-626099470ae4)
-
----
-
-**Ready to hack Zelda 3? [Get started now!](docs/01-getting-started.md)**

assets/agent/alttp_rom_hacking_guide.txt

@@ -0,0 +1,99 @@
+# ALTTP ROM Structure Expert Knowledge
+
+## Memory Map (Critical Addresses)
+- 0x00000-0x07FFF: Header + Low ROM
+- 0x08000-0x0FFFF: Character data  
+- 0x10000-0x1FFFF: Overworld maps
+- 0x1C800-0x1D7FF: Overworld tile16 data (4096 tiles * 8 bytes)
+- 0x20000-0x2FFFF: Dungeon rooms (296 rooms, 0x00-0x127)
+- 0xDE6C8-0xDEDC7: Overworld palettes (8 groups * 8 palettes * 16 colors * 2 bytes)
+- 0xDD308-0xDD3C7: Dungeon palettes
+
+## 65816 Processor Essentials
+**M Flag (bit 5)**: Accumulator size (0=16-bit, 1=8-bit)
+**X Flag (bit 4)**: Index register size (0=16-bit, 1=8-bit)
+
+Critical: SEP #$20 = 8-bit A, REP #$20 = 16-bit A
+Always use PHP/PLP when crossing function boundaries!
+
+## WRAM Key Variables
+- $7E0010 (MODE): Main game state (0x09=Overworld, 0x07=Underworld)
+- $7E0011 (SUBMODE): Sub-state for current mode
+- $7E001B (INDOORS): 0x01=inside, 0x00=outside
+- $7E005D (LINKDO): Link's state machine (0x00=walking, 0x04=swimming, etc.)
+- $7E008A (OWSCR): Current overworld screen (0x00-0x3F)
+- $7E00A0 (ROOM): Current dungeon room (0x00-0x127)
+- $7E0DD0,X (SprState): Sprite state array
+- $7E0E20,X (SprType): Sprite ID array
+- $7E0E50,X (SprHealth): Sprite health array
+
+## Data Structures
+
+### Sprite Data (3 bytes per sprite, up to 16/room)
+Byte 0: Sprite ID (0x00-0xFF)
+Byte 1: X position in room (0x00-0x1F)
+Byte 2: Y position in room (0x00-0x1F)
+Example: 09 48 56 = Sprite 0x09 at (72, 86)
+
+### Tile16 Structure (8 bytes)
+Bytes 0-1: Top-left tile8 (ID + properties)
+Bytes 2-3: Top-right tile8
+Bytes 4-5: Bottom-left tile8
+Bytes 6-7: Bottom-right tile8
+Format: HVEEEETT TTTTTTTT (H=HFlip, V=VFlip, E=Palette, T=Tile8 ID)
+
+### SNES Palette Format (16-bit, little-endian)
+Format: 0bbbbbgg gggrrrrr (5 bits per channel)
+Conversion to RGB8: R8 = (val & 0x1F) << 3
+
+## Bank Organization
+- Bank $00: Main loop, NMI, state machine
+- Bank $01: Dungeon engine (room loading, object drawing)
+- Bank $02: Overworld engine, transitions
+- Bank $06: Main sprite engine, shared helpers
+- Bank $07: Link's state machine and controls
+- Bank $09: Ancilla spawning, item giving
+- Bank $1B: Overworld entrances, hidden items, palette data
+
+## Common Patterns
+
+### Finding Sprites in ROM
+Search pattern: XX ?? ?? where XX = sprite ID
+Context: Look for 3-byte sequences with coordinate ranges 0x00-0x1F
+
+### Finding Tile Usage
+Use overworld-find-tile with tile16 ID (0x000-0xFFF)
+Cross-reference with map data to see placement
+
+### Palette Analysis
+Group/Palette format: Each group has 8 palettes, each palette has 16 colors
+Address = 0xDE6C8 + (group * 8 * 16 * 2) + (palette * 16 * 2) + (color * 2)
+
+### Room Header Structure (14 bytes)
+Byte 0: BG2 property
+Byte 1: Collision type
+Byte 2-3: Layer1 data address
+Byte 4-5: Layer2 data address
+Byte 6-7: Sprite data address
+Byte 8: Palette ID
+Byte 9: Blockset ID
+Byte 10: Spriteset ID
+Byte 11-12: Effect tags
+Byte 13: Properties
+
+## Tool Usage for ROM Analysis
+
+When user asks about sprites/enemies:
+1. dungeon-describe-room OR overworld-describe-map
+2. resource-list --type=sprite for names
+3. hex-read at sprite data address for exact data
+
+When user asks about tiles/graphics:
+1. overworld-find-tile with tile ID
+2. hex-read at 0x1C800 + (tile_id * 8) for structure
+3. palette-get-colors for color info
+
+When user asks about rooms/dungeons:
+1. resource-list --type=dungeon for IDs
+2. dungeon-describe-room with full details
+3. dungeon-list-sprites for enemy composition

assets/agent/common_tiles.txt

@@ -0,0 +1,42 @@
+# Common Tile16 Reference for AI Agents
+# This file can be customized per project
+
+[grass_tiles]
+0x020 = Grass (standard)
+0x021 = Grass variant 1
+0x0E0 = Grass (dark world)
+
+[nature_tiles]
+0x02E = Tree (standard oak)
+0x02F = Tree (palm)
+0x003 = Bush (standard)
+0x004 = Rock (standard)
+0x021 = Flower (standard)
+
+[ground_tiles]
+0x022 = Dirt (standard)
+0x023 = Sand (desert)
+0x024 = Stone path
+
+[water_tiles]
+0x14C = Water (top edge)
+0x14D = Water (middle)
+0x14E = Water (bottom edge)
+0x14F = Water (left edge)
+0x150 = Water (right edge)
+
+[structure_tiles]
+0x100 = Wall (castle, exterior)
+0x101 = Wall (castle, interior)
+0x120 = Door (standard)
+0x121 = Door (locked)
+
+[special_tiles]
+0x200 = Warp tile
+0x201 = Treasure chest
+0x202 = Switch tile
+
+# Notes:
+# - IDs are in hexadecimal (0x prefix)
+# - Customize this file for your ROM hack
+# - AI will reference these when placing tiles

assets/agent/complex_command_generation.txt

@@ -0,0 +1,11 @@
+# Test 2: Complex Command Generation
+
+# This requires knowledge of different water tiles for edges vs. center,
+# and the ability to generate a 4x4 grid of `overworld set-tile` commands.
+Create a 4x4 square of deep water on map 0 starting at coordinate 25, 30.
+
+# This tests generating a long sequence of commands for a path.
+Draw a vertical dirt path on map 1 from y=10 to y=25 at x=40.
+
+# This tests a combination of different, related tiles to form a structure.
+Build a small 2x2 house at 50, 50 on map 0 using the appropriate house tiles.

assets/agent/context_and_followup.txt

@@ -0,0 +1,15 @@
+# Test 1: Context and Follow-up Queries
+
+# The agent should use the 'resource-list' tool.
+What dungeons are defined in this ROM?
+
+# The agent must use the context from the previous answer to identify "the first one"
+# and then call the 'dungeon-list-sprites' tool for that specific room.
+Tell me about the sprites in the first dungeon listed.
+
+# The agent must remember the room from the previous query and use the 'overworld-list-warps' tool.
+Are there any warp points in that same room?
+
+# This is a complex reasoning test. The agent needs to synthesize information
+# from the last two tool calls (sprite list and warp list) to answer.
+Is there a soldier sprite located near any of the warp points in that room?

assets/agent/conversation_tests.json

@@ -0,0 +1,85 @@
+[
+  {
+    "name": "basic_dungeon_query",
+    "description": "Test basic ROM introspection with resource-list tool",
+    "prompts": [
+      "What dungeons are defined in this ROM?"
+    ],
+    "expected_keywords": ["dungeon", "palace", "castle"],
+    "expect_tool_calls": true,
+    "expect_commands": false
+  },
+  {
+    "name": "tile_search",
+    "description": "Test overworld-find-tile tool",
+    "prompts": [
+      "Find all instances of tile 0x02E in the overworld"
+    ],
+    "expected_keywords": ["tile", "0x02E", "map", "coordinates"],
+    "expect_tool_calls": true,
+    "expect_commands": false
+  },
+  {
+    "name": "map_information",
+    "description": "Test overworld-describe-map tool",
+    "prompts": [
+      "Tell me about overworld map 0"
+    ],
+    "expected_keywords": ["map", "light world", "size", "area"],
+    "expect_tool_calls": true,
+    "expect_commands": false
+  },
+  {
+    "name": "warp_enumeration",
+    "description": "Test overworld-list-warps tool",
+    "prompts": [
+      "List all entrances on map 0"
+    ],
+    "expected_keywords": ["entrance", "warp", "position"],
+    "expect_tool_calls": true,
+    "expect_commands": false
+  },
+  {
+    "name": "multi_step_exploration",
+    "description": "Test conversational follow-up questions",
+    "prompts": [
+      "What dungeons exist in this ROM?",
+      "Tell me about the sprites in the first dungeon you mentioned"
+    ],
+    "expected_keywords": ["dungeon", "sprite"],
+    "expect_tool_calls": true,
+    "expect_commands": false
+  },
+  {
+    "name": "command_generation_tree",
+    "description": "Test command generation for placing a tree",
+    "prompts": [
+      "Place a tree at position 10, 10 on map 0"
+    ],
+    "expected_keywords": ["overworld", "set-tile", "tree", "0x02E"],
+    "expect_tool_calls": false,
+    "expect_commands": true
+  },
+  {
+    "name": "command_generation_water",
+    "description": "Test command generation for water tiles",
+    "prompts": [
+      "Create a 3x3 water pond at coordinates 20, 15 on map 0"
+    ],
+    "expected_keywords": ["overworld", "set-tile", "water"],
+    "expect_tool_calls": false,
+    "expect_commands": true
+  },
+  {
+    "name": "contextual_conversation",
+    "description": "Test that agent maintains context across messages",
+    "prompts": [
+      "What is map 0?",
+      "How many tiles does it have?",
+      "Find all trees on that map"
+    ],
+    "expected_keywords": ["map", "tile", "tree"],
+    "expect_tool_calls": true,
+    "expect_commands": false
+  }
+]

assets/agent/error_handling_and_edge_cases.txt

@@ -0,0 +1,19 @@
+# Test 3: Error Handling and Edge Cases
+
+# Invalid room ID. The tool should fail, and the agent should report that failure gracefully.
+List the sprites in room 0x999.
+
+# Ambiguous query. There are many "main" palettes.
+# The agent should ideally ask for clarification or state its assumption.
+Describe the main palette.
+
+# A query that is completely outside the scope of its tools.
+# The agent should recognize it cannot answer this.
+What is the story of A Link to the Past?
+
+# A complex, multi-step request that would require both reading and writing in a loop.
+# This tests if the agent attempts such a complex plan or asks the user to simplify.
+Find all the tree tiles on map 0 and replace them with water tiles.
+
+# A nonsense query to test its ability to reject impossible questions.
+How many pixels are in a single rupee?

assets/agent/function_schemas.json

@@ -0,0 +1,552 @@
+{
+  "function_declarations": [
+    {
+      "name": "resource-list",
+      "description": "List all resources of a specific type from the ROM (rooms, sprites, dungeons, entrances, items, overlords)",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["room", "sprite", "dungeon", "entrance", "item", "overlord"],
+            "description": "Type of resource to list"
+          }
+        },
+        "required": ["type"]
+      }
+    },
+    {
+      "name": "resource-search",
+      "description": "Search for resources by name or pattern",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["room", "sprite", "dungeon", "entrance", "item"],
+            "description": "Type of resource to search"
+          },
+          "query": {
+            "type": "string",
+            "description": "Search query or pattern to match"
+          }
+        },
+        "required": ["type", "query"]
+      }
+    },
+    {
+      "name": "emulator-press-buttons",
+      "description": "Presses and immediately releases one or more buttons on the SNES controller.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "buttons": {
+            "type": "string",
+            "description": "A comma-separated list of buttons to press (e.g., 'A,Right,Start')."
+          }
+        },
+        "required": ["buttons"]
+      }
+    },
+    {
+      "name": "emulator-hold-buttons",
+      "description": "Holds down one or more buttons for a specified duration.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "buttons": {
+            "type": "string",
+            "description": "A comma-separated list of buttons to hold."
+          },
+          "duration": {
+            "type": "integer",
+            "description": "The duration in milliseconds to hold the buttons."
+          }
+        },
+        "required": ["buttons", "duration"]
+      }
+    },
+    {
+      "name": "emulator-get-state",
+      "description": "Retrieves the current state of the game from the emulator.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "screenshot": {
+            "type": "boolean",
+            "description": "Whether to include a screenshot of the current frame."
+          }
+        }
+      }
+    },
+    {
+      "name": "emulator-read-memory",
+      "description": "Reads a block of memory from the SNES WRAM.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "The memory address to read from (e.g., '0x7E0010')."
+          },
+          "length": {
+            "type": "integer",
+            "description": "The number of bytes to read."
+          }
+        },
+        "required": ["address"]
+      }
+    },
+    {
+      "name": "emulator-write-memory",
+      "description": "Writes a block of data to the SNES WRAM.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "The memory address to write to."
+          },
+          "data": {
+            "type": "string",
+            "description": "The data to write, as a hex string (e.g., 'AABBCCDD')."
+          }
+        },
+        "required": ["address", "data"]
+      }
+    },
+    {
+      "name": "emulator-set-breakpoint",
+      "description": "Set a breakpoint in the emulator to pause execution at a specific address or when specific memory is accessed. Essential for debugging game logic, input handling, and timing issues.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "Memory address in hex format (e.g., '0x0083D7' for ALTTP's NMI_ReadJoypads routine)"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["execute", "read", "write", "access"],
+            "description": "Breakpoint type: 'execute' breaks when PC reaches address, 'read'/'write'/'access' break on memory access"
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable label for this breakpoint (e.g., 'NMI handler entry')"
+          }
+        },
+        "required": ["address"]
+      }
+    },
+    {
+      "name": "emulator-clear-breakpoint",
+      "description": "Remove a breakpoint by ID",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "description": "Breakpoint ID to remove (from list-breakpoints output)"
+          }
+        },
+        "required": ["id"]
+      }
+    },
+    {
+      "name": "emulator-list-breakpoints",
+      "description": "List all active breakpoints with their addresses, types, hit counts, and states",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "emulator-step",
+      "description": "Step the emulator forward by one or more CPU instructions and return the new CPU state",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "count": {
+            "type": "integer",
+            "description": "Number of instructions to execute (default: 1)"
+          }
+        }
+      }
+    },
+    {
+      "name": "emulator-run",
+      "description": "Run the emulator until a breakpoint is hit or for a specified number of frames",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "until_break": {
+            "type": "boolean",
+            "description": "Run until breakpoint is hit (default: false)"
+          },
+          "frames": {
+            "type": "integer",
+            "description": "Number of frames to run (if not until_break)"
+          }
+        }
+      }
+    },
+    {
+      "name": "emulator-pause",
+      "description": "Pause emulator execution for inspection",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "emulator-reset",
+      "description": "Reset the emulator to initial state (hard reset)",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "emulator-get-registers",
+      "description": "Get current CPU register values (A, X, Y, PC, PB, DB, SP, flags) for debugging",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "emulator-get-metrics",
+      "description": "Get emulator performance metrics including FPS, cycle count, audio queue status",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "dungeon-list-sprites",
+      "description": "List all sprites in a specific dungeon or room",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "dungeon": {
+            "type": "string",
+            "description": "Dungeon name (e.g., 'hyrule_castle', 'eastern_palace') or leave empty for all"
+          },
+          "room_id": {
+            "type": "string",
+            "description": "Specific room ID to query (optional)"
+          }
+        }
+      }
+    },
+    {
+      "name": "dungeon-describe-room",
+      "description": "Get detailed information about a specific dungeon room including sprites, chests, layout, and connections",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "room_id": {
+            "type": "string",
+            "description": "Room ID to describe (0-296)"
+          },
+          "include_sprites": {
+            "type": "string",
+            "enum": ["true", "false"],
+            "description": "Include sprite information (default: true)"
+          }
+        },
+        "required": ["room_id"]
+      }
+    },
+    {
+      "name": "overworld-find-tile",
+      "description": "Find all locations where a specific tile16 ID appears in the overworld",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "tile_id": {
+            "type": "string",
+            "description": "Tile16 ID to search for (hex format like '0x42' or decimal)"
+          },
+          "map_id": {
+            "type": "string",
+            "description": "Specific overworld map to search (0-63, optional)"
+          }
+        },
+        "required": ["tile_id"]
+      }
+    },
+    {
+      "name": "overworld-describe-map",
+      "description": "Get detailed information about a specific overworld map including tile composition, warps, and sprites",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "map_id": {
+            "type": "string",
+            "description": "Overworld map ID (0-63 for light/dark world)"
+          },
+          "include_tiles": {
+            "type": "string",
+            "enum": ["true", "false"],
+            "description": "Include tile distribution statistics"
+          }
+        },
+        "required": ["map_id"]
+      }
+    },
+    {
+      "name": "overworld-list-warps",
+      "description": "List all warp/entrance points for a specific overworld map",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "map_id": {
+            "type": "string",
+            "description": "Overworld map ID (0-63)"
+          }
+        },
+        "required": ["map_id"]
+      }
+    },
+    {
+      "name": "overworld-list-sprites",
+      "description": "List all sprites placed on a specific overworld map",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "map_id": {
+            "type": "string",
+            "description": "Overworld map ID (0-63)"
+          }
+        },
+        "required": ["map_id"]
+      }
+    },
+    {
+      "name": "overworld-get-entrance",
+      "description": "Get detailed information about a specific entrance/exit including destination and properties",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "entrance_id": {
+            "type": "string",
+            "description": "Entrance ID to query"
+          }
+        },
+        "required": ["entrance_id"]
+      }
+    },
+    {
+      "name": "overworld-tile-stats",
+      "description": "Get statistical analysis of tile usage across overworld maps",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "map_id": {
+            "type": "string",
+            "description": "Specific map ID or 'all' for global statistics"
+          }
+        }
+      }
+    },
+    {
+      "name": "hex-read",
+      "description": "Read bytes from ROM at a specific address in hexadecimal",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "ROM address in hex format (e.g., '0x1C800')"
+          },
+          "length": {
+            "type": "integer",
+            "description": "Number of bytes to read (default: 16)"
+          },
+          "format": {
+            "type": "string",
+            "enum": ["hex", "ascii", "both"],
+            "description": "Output format (default: both)"
+          }
+        },
+        "required": ["address"]
+      }
+    },
+    {
+      "name": "hex-write",
+      "description": "Write bytes to ROM at a specific address (creates a proposal)",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "ROM address in hex format (e.g., '0x1C800')"
+          },
+          "data": {
+            "type": "string",
+            "description": "Hex data to write (space-separated bytes like 'FF 00 12 34')"
+          }
+        },
+        "required": ["address", "data"]
+      }
+    },
+    {
+      "name": "hex-search",
+      "description": "Search for a byte pattern in ROM",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "pattern": {
+            "type": "string",
+            "description": "Hex pattern to search (e.g., 'FF 00 ?? 12' where ?? is wildcard)"
+          },
+          "start_address": {
+            "type": "string",
+            "description": "Start address (default: 0x00000)"
+          },
+          "end_address": {
+            "type": "string",
+            "description": "End address (default: ROM size)"
+          }
+        },
+        "required": ["pattern"]
+      }
+    },
+    {
+      "name": "palette-get-colors",
+      "description": "Get all colors from a specific palette",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "group": {
+            "type": "integer",
+            "description": "Palette group index (0-based)"
+          },
+          "palette": {
+            "type": "integer",
+            "description": "Palette index within group (0-7)"
+          },
+          "format": {
+            "type": "string",
+            "enum": ["snes", "rgb", "hex"],
+            "description": "Color format (default: hex)"
+          }
+        },
+        "required": ["group", "palette"]
+      }
+    },
+    {
+      "name": "palette-set-color",
+      "description": "Set a specific color in a palette (creates a proposal)",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "group": {
+            "type": "integer",
+            "description": "Palette group index"
+          },
+          "palette": {
+            "type": "integer",
+            "description": "Palette index within group"
+          },
+          "color_index": {
+            "type": "integer",
+            "description": "Color index in palette (0-15)"
+          },
+          "color": {
+            "type": "string",
+            "description": "Color value in hex format (e.g., '#FF0000' or 'FF0000')"
+          }
+        },
+        "required": ["group", "palette", "color_index", "color"]
+      }
+    },
+    {
+      "name": "palette-analyze",
+      "description": "Analyze color usage and statistics for a palette or bitmap",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "target_type": {
+            "type": "string",
+            "enum": ["palette", "bitmap", "graphics_sheet"],
+            "description": "What to analyze"
+          },
+          "target_id": {
+            "type": "string",
+            "description": "ID or index of target"
+          }
+        },
+        "required": ["target_type", "target_id"]
+      }
+    },
+    {
+      "name": "todo-create",
+      "description": "Create a new TODO task for complex operations",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "Task description"
+          },
+          "category": {
+            "type": "string",
+            "description": "Task category (e.g., 'rom_edit', 'ai_task', 'build')"
+          },
+          "priority": {
+            "type": "integer",
+            "description": "Priority level (0-10, higher = more important)"
+          }
+        },
+        "required": ["description"]
+      }
+    },
+    {
+      "name": "todo-list",
+      "description": "List all TODO tasks or filter by status/category",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["pending", "in_progress", "completed", "blocked", "cancelled"],
+            "description": "Filter by status"
+          },
+          "category": {
+            "type": "string",
+            "description": "Filter by category"
+          }
+        }
+      }
+    },
+    {
+      "name": "todo-update-status",
+      "description": "Update the status of a TODO task",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "TODO ID"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "in_progress", "completed", "blocked", "cancelled"],
+            "description": "New status"
+          }
+        },
+        "required": ["id", "status"]
+      }
+    },
+    {
+      "name": "todo-next",
+      "description": "Get the next actionable TODO task (respecting dependencies and priority)",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    }
+  ]
+}

assets/agent/gui_automation_instructions.txt

@@ -0,0 +1,216 @@
+# GUI Automation with YAZE Test Harness
+
+## Overview
+You have the ability to control the YAZE GUI directly through a test harness system. This allows you to perform visual edits, interact with UI elements, and capture screenshots for multimodal analysis.
+
+## Prerequisites
+- YAZE must be running with the `--enable-test-harness` flag
+- Test harness server runs on port 50052 by default
+- GUI automation tools only work when YAZE GUI is active
+
+## Available GUI Tools
+
+### 1. gui-discover
+**Purpose**: Discover available widgets and windows in the YAZE interface
+**When to use**: Before performing any GUI actions, discover what UI elements are available
+**Example usage**:
+```json
+{
+  "tool_calls": [{
+    "tool_name": "gui-discover",
+    "args": {
+      "window": "Overworld",
+      "type": "button"
+    }
+  }]
+}
+```
+
+### 2. gui-click
+**Purpose**: Automate clicking buttons and UI elements
+**When to use**: To open editors, switch modes, or trigger actions in the GUI
+**Example usage**:
+```json
+{
+  "tool_calls": [{
+    "tool_name": "gui-click",
+    "args": {
+      "target": "ModeButton:Draw (2)",
+      "click_type": "left"
+    }
+  }]
+}
+```
+
+### 3. gui-place-tile
+**Purpose**: Automate tile placement in the overworld editor
+**When to use**: When user wants to see visual tile placement in the GUI (not just ROM data edit)
+**Example usage**:
+```json
+{
+  "tool_calls": [{
+    "tool_name": "gui-place-tile",
+    "args": {
+      "tile": "0x02E",
+      "x": "15",
+      "y": "20"
+    }
+  }]
+}
+```
+
+### 4. gui-screenshot
+**Purpose**: Capture visual state of the GUI
+**When to use**: For visual verification, multimodal analysis, or user feedback
+**Example usage**:
+```json
+{
+  "tool_calls": [{
+    "tool_name": "gui-screenshot",
+    "args": {
+      "region": "full",
+      "format": "PNG"
+    }
+  }]
+}
+```
+
+## GUI Automation Workflow
+
+### Typical Pattern for GUI Edits
+1. **Discover** - Find available widgets with `gui-discover`
+2. **Navigate** - Use `gui-click` to open the right editor or switch modes
+3. **Edit** - Use specific tools like `gui-place-tile` for the actual modification
+4. **Verify** - Capture a screenshot with `gui-screenshot` to confirm changes
+
+### Example: Place a tree tile in the overworld
+```
+User: "Use the GUI to place a tree at position 10, 15"
+
+Step 1: Call gui-place-tile
+{
+  "tool_calls": [{
+    "tool_name": "gui-place-tile",
+    "args": {
+      "tile": "0x02E",
+      "x": "10",
+      "y": "15"
+    }
+  }],
+  "reasoning": "The user wants visual GUI interaction. Tree tile is 0x02E."
+}
+
+Step 2: After receiving tool result, inform user
+{
+  "text_response": "I've generated the GUI automation script to place a tree tile at position (10, 15). The test harness will execute this action if YAZE is running with --enable-test-harness.",
+  "reasoning": "Tool call succeeded, provide confirmation to user."
+}
+```
+
+## When to Use GUI Tools vs ROM Tools
+
+### Use GUI Tools When:
+- User explicitly requests "use the GUI" or "show me"
+- User wants to see visual feedback
+- User wants to learn how to use the editor
+- Demonstrating a workflow
+
+### Use ROM Tools When:
+- User wants batch operations
+- User needs precise control over ROM data
+- GUI is not running
+- Faster automated operations needed
+
+## Important Notes
+
+1. **GUI tools require connection**: All GUI tools check if test harness is connected. If not, they return mock responses.
+
+2. **Coordinate systems**: GUI coordinates are tile-based (0-63 for overworld), matching the ROM data coordinates.
+
+3. **Widget paths**: Widget paths are hierarchical, like "ModeButton:Draw (2)" or "ToolbarAction:Toggle Tile16 Selector". Use `gui-discover` to find exact paths.
+
+4. **Error handling**: If a GUI tool fails, fall back to ROM tools to ensure user request is fulfilled.
+
+5. **Test scripts**: Tools like `gui-place-tile` generate test scripts that can be saved and replayed later.
+
+## Integration with Multimodal Features
+
+Combine GUI automation with screenshot capture for powerful multimodal workflows:
+
+```
+1. Capture before state: gui-screenshot
+2. Perform edit: gui-place-tile
+3. Capture after state: gui-screenshot
+4. Compare visually or send to vision model for verification
+```
+
+## Troubleshooting
+
+### "Connection refused" errors
+- Ensure YAZE is running with `--enable-test-harness` flag
+- Check that port 50052 is available
+- Verify no firewall blocking localhost connections
+
+### "Widget not found" errors
+- Run `gui-discover` first to get current widget list
+- Check that the right editor window is open
+- Verify widget path spelling and case
+
+### "Tool not implemented" errors
+- Ensure YAZE was built with `-DYAZE_WITH_GRPC=ON`
+- Verify z3ed binary includes gRPC support
+
+## Example Conversations
+
+### Example 1: Simple tile placement
+```
+User: "Use the GUI to place grass at 5, 10"
+Assistant: [Calls gui-place-tile with tile=0x020, x=5, y=10]
+Assistant: "I've queued a GUI action to place grass tile at position (5, 10)."
+```
+
+### Example 2: Discover and click workflow
+```
+User: "Open the Tile16 selector"
+Assistant: [Calls gui-discover with window=Overworld]
+Assistant: [Receives widget list including "ToolbarAction:Toggle Tile16 Selector"]
+Assistant: [Calls gui-click with target="ToolbarAction:Toggle Tile16 Selector"]
+Assistant: "I've clicked the Tile16 Selector button to open the selector panel."
+```
+
+### Example 3: Visual verification
+```
+User: "Show me what the current map looks like"
+Assistant: [Calls gui-screenshot with region=full]
+Assistant: "Here's a screenshot of the current editor state: /tmp/yaze_screenshot.png"
+```
+
+## Advanced Features
+
+### Chaining GUI Actions
+You can chain multiple GUI tools in a single response for complex workflows:
+
+```json
+{
+  "tool_calls": [
+    {"tool_name": "gui-discover", "args": {"window": "Overworld"}},
+    {"tool_name": "gui-click", "args": {"target": "ModeButton:Draw (2)"}},
+    {"tool_name": "gui-place-tile", "args": {"tile": "0x02E", "x": "10", "y": "10"}},
+    {"tool_name": "gui-screenshot", "args": {"region": "full"}}
+  ],
+  "reasoning": "Complete workflow: discover widgets, switch to draw mode, place tile, capture result"
+}
+```
+
+### Recording and Replay
+GUI actions can be recorded for later replay:
+1. Actions are logged as test scripts
+2. Scripts can be saved to YAML/JSON files
+3. Replay with `z3ed agent test replay <script.yaml>`
+
+## Summary
+
+GUI automation tools extend your capabilities beyond ROM data manipulation to include visual, interactive editing workflows. Use them when users want to see changes happen in real-time or when demonstrating features of the YAZE editor.
+
+Remember: Always start with `gui-discover` to understand what's available, then use specific tools for your task.
+

assets/agent/oracle_of_secrets_guide.txt

@@ -0,0 +1,98 @@
+# Oracle of Secrets ROM Hack Expert Knowledge
+
+## Custom Memory Regions
+
+### WRAM ($7E0730-$7E078F) - 96 bytes custom
+- $7E0730: MenuScrollLevelV (menu system)
+- $7E0731: MenuScrollLevelH  
+- $7E0739: GoldstarOrHookshot (item differentiation)
+- $7E073A: Neck_Index (multi-part boss sprites)
+- $7E0741-0743: Offspring IDs (boss mechanics)
+- $7E0745: FishingOrPortalRod
+
+### SRAM Custom Variables
+- $7EF3D6: OOSPROG (main progression bitfield)
+- $7EF3C6: OOSPROG2 (secondary progression)
+- $7EF347-358: Masks (Zora, Bunny, Deku, Wolf, Stone)
+- $7EF38A-3C4: Collectibles (Bananas, Seashells, Scrolls, etc.)
+- $7EF410: Dreams (Courage/Power/Wisdom collectibles)
+
+## Custom ROM Banks
+- Bank $20 ($208000): Expanded Music
+- Bank $28 ($288000): ZSCustomOverworld data/code
+- Bank $2B ($2B8000): Items
+- Bank $2C ($2C8000): Dungeons
+- Bank $2D ($2D8000): Menu
+- Bank $30-32 ($308000+): Sprites (3 banks)
+- Bank $33-3B: Mask transformation graphics
+- Bank $40-41: Custom overworld maps (LW/DW)
+
+## Namespace Architecture
+
+### Oracle Namespace
+Most custom code in `namespace Oracle {}`:
+- Items/, Menu/, Masks/, Sprites/, Core/
+
+### ZScream (No Namespace)
+ZSCustomOverworld.asm operates outside namespace
+Hook vanilla addresses directly
+
+### Cross-Namespace Pattern
+**Oracle calling ZScream:**
+```asm
+namespace Oracle {
+  JSL Oracle_ZScreamFunction  // Use Oracle_ prefix
+}
+```
+
+**ZScream calling Oracle (bridge):**
+```asm
+ZSO_BridgeFunction:
+  JSL Oracle_OracleFunction
+  RTL
+
+namespace Oracle {
+  Oracle_ZSO_BridgeFunction = ZSO_BridgeFunction
+}
+```
+
+## ZScream Tables ($288000+)
+- BGColorTable: Background colors per screen
+- MainPaletteTable: Palette group indices
+- AnimatedTable: Animated tile GFX IDs
+- OverlayTable: Weather/effect overlays (0x9F=rain, 0xFF=none)
+- OWGFXGroupTable: 8 GFX sheets per screen
+- Overworld_ActualScreenID_New: Parent screen for 2x2 areas
+- Overworld_SpritePointers_state_X: Sprite sets per game state
+
+## Day/Night System Integration
+Oracle adds time system with 6 states:
+- State 0-2: Day (base game states)
+- State 3-5: Night (parallel states)
+- CheckIfNight16Bit: Returns state offset for night
+
+Sprite loading checks time and uses offset pointers
+
+## Processor State Safety
+**CRITICAL:** Always PHP/PLP when crossing namespaces
+ZScream uses 8-bit mode, Oracle often uses 16-bit
+Mismatch = BRK crash
+
+## Common Debugging
+**BRK Crash:** Check stack with Mesen-S, look for RTL without JSL
+**Missing Graphics:** Verify GFX slot assignment (0-6)
+**Wrong Sprites:** Check sprite pointer table for current game state
+**Palette Issues:** Day/night transition may need palette reload
+
+## Tool Usage for Oracle ROMs
+When analyzing custom features:
+1. hex-read custom WRAM ($7E0730+) to check states
+2. hex-read SRAM ($7EF3D6, $7EF410) for progression
+3. hex-search for custom sprite IDs (>0xF3 often custom)
+4. palette-analyze for day/night palette differences
+
+When editing Oracle ROMs:
+1. Check OOSPROG flags before major edits
+2. Verify namespace exports exist
+3. Test day AND night variants
+4. Ensure processor state preserved across boundaries

assets/agent/oracle_of_secrets_labels.yaml

@@ -0,0 +1,158 @@
+# Oracle of Secrets Project Labels for z3ed Agent
+# Version: 1.0
+# This file provides a structured reference of in-game entities, items,
+# and memory addresses specific to the Oracle of Secrets ROM hack.
+
+project_name: "Oracle of Secrets"
+base_rom: "The Legend of Zelda: A Link to the Past (US)"
+description: "A large-scale ROM hack featuring a new story, items, dungeons, and mechanics."
+
+# --- Key Items ---
+items:
+  - name: Ocarina
+    id: 0x14
+    description: "Plays songs to affect the world (Time, Storms, Healing, Soaring)."
+  - name: RocsFeather
+    id: 0x4B # Replaces Bug Net
+    description: "Allows Link to perform a short hop. Replaces Bug Net."
+  - name: Goldstar
+    description: "Hookshot upgrade. Functions as a powerful morning star weapon."
+  - name: PortalRod
+    description: "Creates linked portals for teleporting projectiles."
+  - name: FishingRod
+    description: "Initiates a fishing minigame."
+  - name: BookOfSecrets
+    description: "Translates Hylian and reveals hidden passages by disabling BG2."
+  - name: IceRod
+    description: "Projectile freezes water tiles into temporary platforms."
+  - name_group: Magic Rings
+    description: "Passive items that grant buffs when equipped."
+    types: [Power Ring, Armor Ring, Heart Ring, Light Ring, Blast Ring, Steadfast Ring]
+
+# --- Masks ---
+masks:
+  - name: DekuMask
+    id: 0x01
+    description: "Spin attack, bubble projectile, hover from Deku Flowers."
+  - name: ZoraMask
+    id: 0x02
+    description: "Allows diving and fast swimming."
+  - name: WolfMask
+    id: 0x03
+    description: "Allows digging without a shovel."
+  - name: BunnyHood
+    id: 0x04
+    description: "Increases movement speed."
+  - name: MinishForm
+    id: 0x05
+    description: "Shrinks Link to access small areas."
+  - name: GBCForm
+    id: 0x06
+    description: "Cosmetic transformation in the Dark World."
+  - name: MooshForm
+    id: 0x07
+    description: "Hover dash ability."
+
+# --- Dungeons & Bosses ---
+dungeons:
+  - name: MushroomGrotto
+    id: D1
+    boss: Mothra
+  - name: TailPalace
+    id: D2
+    boss: BigMoldorm
+  - name: KalyxoCastle
+    id: D3
+    boss: ArmosKnights
+  - name: ZoraTemple
+    id: D4
+    boss: Arrghus
+  - name: GlaciaEstate
+    id: D5
+    boss: Twinrova
+  - name": GoronMines
+    id: D6
+    boss: KingDodongo
+  - name: DragonShip
+    id: D7
+    boss: null # Not specified in QuestFlow
+  - name: FortressOfSecrets
+    id: D8
+    boss: DarkLink
+  - name": EonCore
+    id: D_Endgame
+    boss: [Kydreeok, Ganon]
+
+# --- Key NPCs ---
+npcs:
+  - name: MakuTree
+    sprite_id: Sprite_MakuTree
+  - name: Farore
+    sprite_id: Sprite_Farore
+  - name: MaskSalesman
+    sprite_id: Sprite_MaskSalesman
+  - name: Tingle
+    sprite_id: 0x22
+  - name: Vasu
+    sprite_id: Sprite_Vasu
+  - name: ZoraPrincess
+    sprite_id: Sprite_ZoraPrincess
+  - name: BeanVendor
+    sprite_id: Sprite_BeanVendor
+  - name: DekuScrub
+    sprite_id: Sprite_DekuScrubNPCs
+  - name: EonOwl
+    sprite_id: Sprite_EonOwl
+  - name: Goron
+    sprite_id: Sprite_Goron
+  - name: Korok
+    sprite_id: Sprite_Korok
+  - name: Maple
+    sprite_id: Sprite_Mermaid # Subtype 1
+  - name: Librarian
+    sprite_id: Sprite_Mermaid # Subtype 2
+
+# --- Progression Flags (SRAM) ---
+sram_flags:
+  - name: OOSPROG
+    address: 0x7EF3D6
+    description: "Primary bitfield for major quest milestones."
+  - name: OOSPROG2
+    address: 0x7EF3C6
+    description: "Secondary bitfield for minor progression flags."
+  - name: MakuTreeQuest
+    address: 0x7EF3D4
+    description: "Flag indicating if the Maku Tree has met Link."
+  - name: Dreams
+    address: 0x7EF410
+    description: "Bitfield for collecting the three Dreams (Courage, Power, Wisdom)."
+  - name: Scrolls
+    address: 0x7EF398
+    description: "Bitfield for lore scroll collection."
+  - name: MagicBeanProg
+    address: 0x7EF39B
+    description: "Tracks the growth of the magic bean side-quest."
+  - name: ZoraMask
+    address: 0x7EF347
+    description: "Flag indicating if the player has obtained the Zora Mask."
+  - name: BunnyHood
+    address: 0x7EF348
+    description: "Flag indicating if the player has obtained the Bunny Hood."
+  - name: DekuMask
+    address: 0x7EF349
+    description: "Flag indicating if the player has obtained the Deku Mask."
+
+# --- Custom WRAM Variables ---
+wram_vars:
+  - name: GoldstarOrHookshot
+    address: 0x7E0739
+    description: "Differentiates between Hookshot and Goldstar modes."
+  - name: FishingOrPortalRod
+    address: 0x7E0745
+    description: "Differentiates between Fishing Rod and Portal Rod modes."
+  - name: CurrentMask
+    address: 0x02B2
+    description: "ID of the currently active mask."
+  - name: Hours
+    address: 0x7EE000
+    description: "Current hour for the Day/Night cycle."

assets/agent/oracle_of_secrets_system_prompt.txt

@@ -0,0 +1,67 @@
+# Yaze Agent System Prompt for Oracle of Secrets
+
+## 1. Your Role
+
+You are an expert AI assistant integrated into `z3ed`, the command-line tool for the YAZE Zelda 3 editor. Your primary function is to help users understand and modify the "Oracle of Secrets" ROM hack. You must act as a knowledgeable and safe assistant, translating natural language requests into precise `z3ed` commands and structured plans.
+
+## 2. Project Context: Oracle of Secrets
+
+- **Base Game**: A Link to the Past (US version).
+- **Project Scope**: A large-scale hack with a new story, world, dungeons, items, and characters.
+- **Key Custom Systems**:
+  - **Day/Night Cycle**: The overworld changes visually and in terms of enemy spawns based on an in-game clock (`$7EE000`).
+  - **Mask System**: Link can transform using masks, gaining new abilities. This is a core mechanic.
+  - **Custom Items**: Many vanilla items are replaced or reworked (e.g., Roc's Feather, Portal Rod), and new items exist.
+  - **ZSCustomOverworld**: The overworld is data-driven, not hardcoded. Edits must be compatible with this system.
+
+## 3. Your Primary Task: Plan Generation
+
+Your main goal is to generate a sequence of `z3ed` commands (a "plan") to fulfill a user's request. For any request that modifies the ROM, you must use the `--sandbox` flag to create a proposal that the user can review and approve.
+
+**NEVER generate commands that modify the ROM directly.**
+
+### Example Workflow:
+
+1.  **User**: "Place a Tingle sprite in the Forest of Dreams at coordinates 15, 20."
+2.  **You (Internal Thought)**: 
+    - I need to find the map ID for "Forest of Dreams".
+    - I need the sprite ID for "Tingle".
+    - I will use the `overworld set-sprite` command.
+    - I must use `--sandbox`.
+3.  **You (Generated Plan)**:
+    ```json
+    {
+      "plan": [
+        {
+          "tool": "overworld set-sprite",
+          "parameters": {
+            "map": 3, 
+            "x": 15,
+            "y": 20,
+            "sprite_id": 34
+          },
+          "reason": "Placing Tingle (ID 0x22) at the requested coordinates on the Forest of Dreams map (ID 3)."
+        }
+      ]
+    }
+    ```
+
+## 4. Key Data Sources
+
+To be effective, you **must** rely on the following sources:
+
+-   **`oracle_of_secrets_labels.yaml`**: This is your primary knowledge base. It contains structured data on items, masks, dungeons, bosses, NPCs, and memory addresses. Use it to find correct names and IDs.
+-   **Project Documentation (`Docs/`)**: For complex queries about quest logic, system interactions, or implementation details, you must reference the markdown files in the `Docs/` directory. Key documents include:
+    -   `QuestFlow.md`: For all main story and side-quest progression.
+    -   `MemoryMap.md`: For custom SRAM/WRAM variable locations.
+    -   `ZSCustomOverworldAdvanced.md`: For technical details on overworld editing.
+    -   `Sprites/` directory: For details on specific custom enemies and NPCs.
+
+## 5. Best Practices & Heuristics
+
+-   **Be Specific**: Always ask for clarification if a request is ambiguous (e.g., "Which Goron? The Kalyxo Goron or an Eon Goron?").
+-   **Reference Your Sources**: When answering a question, state where you found the information (e.g., "According to `QuestFlow.md`...").
+-   **Check Progression First**: Before modifying quest-related elements, always check the state of progression flags like `OOSPROG` (`$7EF3D6`) and `MakuTreeQuest` (`$7EF3D4`).
+-   **Respect Custom Systems**: Acknowledge the Day/Night cycle and Mask system. For example, when placing sprites, consider that different sprites may appear at night.
+-   **Use Labels**: Whenever possible, use the human-readable names from `oracle_of_secrets_labels.yaml` in your responses to the user, but use the corresponding IDs in the commands you generate.
+-   **Safety First**: Always use the `--sandbox` flag for write operations. Explain to the user that their change has been created as a proposal that they need to review and accept.

assets/agent/policies/agent.yaml

@@ -0,0 +1,33 @@
+# Policy Configuration for z3ed Agent
+# This file controls which modifications the agent is allowed to make
+
+version: 1.0
+enabled: true
+
+policies:
+  - name: limit_changes
+    type: change_constraint
+    severity: warning
+    max_bytes: 1024
+    description: Warn if proposal modifies more than 1KB
+
+  - name: protect_header
+    type: forbidden_range
+    severity: critical
+    start: 0x00
+    end: 0x7F
+    description: Never allow modifications to ROM header
+
+  - name: require_tests
+    type: test_requirement
+    severity: critical
+    enabled: true
+    description: All proposals must include passing tests
+
+  - name: review_requirements
+    type: review_requirement
+    severity: warning
+    conditions:
+      - affects_multiple_systems
+      - modifies_core_logic
+    description: Flag proposals that need extra scrutiny

assets/agent/policies/agent.yaml.example

@@ -0,0 +1,75 @@
+# Example Agent Policy Configuration
+# Copy this file to agent.yaml and customize for your project
+#
+# Policy evaluation gates the acceptance of AI-generated ROM modifications
+# Policies can be: critical (blocks accept), warning (allows override), or info
+
+version: 1.0
+enabled: true
+
+policies:
+  # Policy 1: Limit Change Scope
+  # Prevents overly large or complex changes
+  - name: limit_changes
+    type: change_constraint
+    enabled: true
+    severity: warning
+    rules:
+      - max_bytes_changed: 5120  # 5KB - keep changes focused
+      - max_commands_executed: 15  # Limit command complexity
+    message: "Keep changes small and focused for easier review"
+
+  # Policy 2: Protect ROM Header
+  # Prevents corruption of critical ROM metadata
+  - name: protect_header
+    type: forbidden_range
+    enabled: true
+    severity: critical
+    ranges:
+      - start: 0xFFB0
+        end: 0xFFFF
+        reason: "ROM header contains critical metadata"
+    message: "Cannot modify ROM header region"
+
+  # Policy 3: Require Test Validation (Optional)
+  # Ensures changes pass automated tests
+  # Note: Disabled by default until test framework is integrated
+  - name: require_tests
+    type: test_requirement
+    enabled: false
+    severity: critical
+    rules:
+      - test_suite: "smoke_test"
+        min_pass_rate: 1.0  # All smoke tests must pass
+      - test_suite: "palette_regression"
+        min_pass_rate: 0.95  # 95% pass rate for palette tests
+    message: "All required test suites must pass before acceptance"
+
+  # Policy 4: Manual Review for Large Changes
+  # Triggers human review requirements based on change size
+  - name: review_requirements
+    type: review_requirement
+    enabled: true
+    severity: warning
+    conditions:
+      - if: bytes_changed > 1024
+        then: require_diff_review
+        message: "Large change (>1KB) requires diff review"
+      - if: commands_executed > 10
+        then: require_log_review
+        message: "Complex operation (>10 commands) requires log review"
+    message: "Manual review required for this proposal"
+
+# Tips for customization:
+#
+# 1. Start with permissive limits and tighten based on experience
+# 2. Use 'warning' severity for guidelines, 'critical' for hard limits
+# 3. Adjust max_bytes_changed based on your ROM's complexity
+# 4. Enable test_requirement once you have automated tests
+# 5. Add more forbidden_ranges to protect specific data (sprite tables, etc.)
+#
+# Example bank ranges for Zelda 3:
+#   0x00-0x07: Game code
+#   0x08-0x0D: Compressed graphics
+#   0x0E-0x0F: Uncompressed graphics
+#   0x10-0x1F: Maps and data tables

assets/agent/prompt_catalogue.yaml

@@ -0,0 +1,435 @@
+commands:
+  palette export: |-
+    Export palette data to JSON file
+      --group <group>  Palette group (overworld, dungeon, sprite)
+      --id <id>        Palette ID (0-based index)
+      --to <file>      Output JSON file path
+  palette import: |-
+    Import palette data from JSON file
+      --group <group>  Palette group (overworld, dungeon, sprite)
+      --id <id>        Palette ID (0-based index)
+      --from <file>    Input JSON file path
+  palette set-color: |-
+    Modify a color in palette JSON file
+      --file <file>    Palette JSON file to modify
+      --index <index>  Color index (0-15 per palette)
+      --color <hex>    New color in hex (0xRRGGBB format)
+  overworld set-tile: |-
+    Place a tile in the overworld
+      --map <id>       Map ID (0-based)
+      --x <x>          X coordinate (0-63)
+      --y <y>          Y coordinate (0-63)
+      --tile <hex>     Tile ID in hex (e.g., 0x02E for tree)
+  sprite set-position: |-
+    Move a sprite to a new position
+      --id <id>        Sprite ID
+      --x <x>          X coordinate
+      --y <y>          Y coordinate
+  dungeon set-room-tile: |-
+    Place a tile in a dungeon room
+      --room <id>      Room ID
+      --x <x>          X coordinate
+      --y <y>          Y coordinate
+      --tile <hex>     Tile ID
+  rom validate: "Validate ROM integrity and structure"
+
+tools:
+  - name: resource-list
+    description: "List project-defined resource labels for the requested category."
+    usage_notes: "Use this whenever you need to reference project-specific labels or IDs from the ROM. Valid categories: dungeon, room, entrance, overworld, sprite, palette, item, tile16, or all."
+    arguments:
+      - name: type
+        description: "Resource category. Valid values: dungeon, room, entrance, overworld, sprite, palette, item, tile16, all."
+        required: true
+        example: dungeon
+      - name: format
+        description: "Response format (json or table). Defaults to JSON if omitted."
+        required: false
+        example: json
+  - name: resource-search
+    description: "Search resource labels by partial name or ID."
+    usage_notes: "Use to locate specific rooms, sprites, palettes, entrances, overworld maps, or tile16 entries based on fuzzy text."
+    arguments:
+      - name: query
+        description: "Search term to match against labels and IDs."
+        required: true
+        example: soldier
+      - name: type
+        description: "Optional category filter (dungeon, room, entrance, overworld, sprite, palette, item, tile16, all)."
+        required: false
+        example: sprite
+      - name: format
+        description: "Response format (json or text). Defaults to JSON."
+        required: false
+        example: json
+  - name: dungeon-list-sprites
+    description: "Inspect sprite placements for a specific dungeon room."
+    usage_notes: "Returns sprite IDs, positions, and metadata for the requested room."
+    arguments:
+      - name: room
+        description: "Room label or numeric ID (supports hex like 0x123)."
+        required: true
+        example: hyrule_castle_throne
+      - name: dungeon
+        description: "Optional dungeon ID when room names are ambiguous."
+        required: false
+        example: 0x00
+      - name: format
+        description: "Response format (json or table). Defaults to JSON if omitted."
+        required: false
+        example: json
+  - name: dungeon-describe-room
+    description: "Summarize dungeon room metadata, hazards, and object counts."
+    usage_notes: "Great for understanding room state before proposing edits. Includes lighting, effect flags, chests, staircases, and sample sprites."
+    arguments:
+      - name: room
+        description: "Room label or numeric ID (supports hex like 0x123)."
+        required: true
+        example: 0x012
+      - name: format
+        description: "Response format (json or text). Defaults to JSON if omitted."
+        required: false
+        example: json
+  - name: overworld-find-tile
+    description: "Search all overworld maps for occurrences of a specific tile16 ID."
+    usage_notes: "Ideal for tile lookup questions. Includes coordinates for each match."
+    arguments:
+      - name: tile
+        description: "Tile16 ID to search for (accepts hex or decimal)."
+        required: true
+        example: 0x02E
+      - name: map
+        description: "Optional map ID filter (0=Light World, 1=Dark World, etc.)."
+        required: false
+        example: 0
+      - name: format
+        description: "Response format (json or table). Defaults to JSON if omitted."
+        required: false
+        example: json
+  - name: overworld-describe-map
+    description: "Summarize metadata for an overworld map, including regions and labels."
+    usage_notes: "Use this before proposing edits to understand map properties and labels."
+    arguments:
+      - name: map
+        description: "Map ID or label to describe."
+        required: true
+        example: 0
+      - name: format
+        description: "Response format (json or table). Defaults to JSON if omitted."
+        required: false
+        example: json
+  - name: overworld-list-warps
+    description: "List warp entrances and exits for overworld maps, including destinations."
+    usage_notes: "Helpful for navigation questions and verifying warp destinations."
+    arguments:
+      - name: map
+        description: "Optional map filter. Defaults to all maps when omitted."
+        required: false
+        example: 1
+      - name: format
+        description: "Response format (json or table). Defaults to JSON if omitted."
+        required: false
+        example: json
+  - name: gui-place-tile
+    description: "Generate GUI automation script to place a tile in the overworld editor using mouse interactions."
+    usage_notes: "Use this when the user wants to see the tile placement happen in the GUI. Generates a test script that can be executed with agent test execute. Only works when YAZE GUI is running with --enable-test-harness flag."
+    arguments:
+      - name: tile
+        description: "Tile16 ID to place (accepts hex or decimal)."
+        required: true
+        example: 0x02E
+      - name: x
+        description: "X coordinate in the overworld map (0-63)."
+        required: true
+        example: 10
+      - name: y
+        description: "Y coordinate in the overworld map (0-63)."
+        required: true
+        example: 20
+  - name: gui-click
+    description: "Generate GUI automation script to click a button or widget in the YAZE interface."
+    usage_notes: "Use this to automate GUI interactions like opening editors, clicking toolbar buttons, or selecting tiles. Requires widget path from gui-discover."
+    arguments:
+      - name: target
+        description: "Widget path or label to click (e.g., 'ModeButton:Draw (2)' or 'ToolbarAction:Toggle Tile16 Selector')."
+        required: true
+        example: "ModeButton:Draw (2)"
+      - name: click_type
+        description: "Type of click: left, right, middle, or double. Defaults to left."
+        required: false
+        example: left
+  - name: gui-discover
+    description: "Discover available GUI widgets and windows in the running YAZE instance."
+    usage_notes: "Use this first to find widget paths before using gui-click. Helps identify what UI elements are available for automation."
+    arguments:
+      - name: window
+        description: "Optional window name filter (e.g., 'Overworld', 'Dungeon', 'Sprite')."
+        required: false
+        example: Overworld
+      - name: type
+        description: "Optional widget type filter: button, input, menu, tab, checkbox, slider, canvas, selectable."
+        required: false
+        example: button
+  - name: gui-screenshot
+    description: "Capture a screenshot of the YAZE GUI for visual inspection."
+    usage_notes: "Useful for verifying GUI state before or after automation actions. Returns the file path of the captured image."
+    arguments:
+      - name: region
+        description: "Region to capture: full, window, or element. Defaults to full."
+        required: false
+        example: full
+      - name: format
+        description: "Image format: PNG or JPEG. Defaults to PNG."
+        required: false
+        example: PNG
+  - name: dialogue-list
+    description: "List all dialogue messages in the ROM with IDs and previews."
+    usage_notes: "Use this to browse available dialogue messages. Returns message IDs and short previews."
+    arguments:
+      - name: format
+        description: "Output format: json or table. Defaults to json."
+        required: false
+        example: json
+      - name: limit
+        description: "Maximum number of messages to return. Defaults to 50."
+        required: false
+        example: 50
+  - name: dialogue-read
+    description: "Read the full text of a specific dialogue message."
+    usage_notes: "Use this to get the complete text of a dialogue message by its ID."
+    arguments:
+      - name: id
+        description: "Message ID to read (hex or decimal, e.g., 0x01 or 1)."
+        required: true
+        example: 0x01
+      - name: format
+        description: "Output format: json or text. Defaults to json."
+        required: false
+        example: json
+  - name: dialogue-search
+    description: "Search dialogue messages for specific text."
+    usage_notes: "Use this to find dialogue messages containing specific words or phrases."
+    arguments:
+      - name: query
+        description: "Search query text."
+        required: true
+        example: "Zelda"
+      - name: format
+        description: "Output format: json or text. Defaults to json."
+        required: false
+        example: json
+      - name: limit
+        description: "Maximum number of results to return. Defaults to 20."
+        required: false
+        example: 20
+  - name: music-list
+    description: "List all music tracks in the ROM with names and categories."
+    usage_notes: "Use this to see all available music tracks and their properties."
+    arguments:
+      - name: format
+        description: "Output format: json or table. Defaults to json."
+        required: false
+        example: json
+  - name: music-info
+    description: "Get detailed information about a specific music track."
+    usage_notes: "Use this to get properties of a music track like channels, tempo, and category."
+    arguments:
+      - name: id
+        description: "Track ID (hex or decimal, e.g., 0x03 or 3)."
+        required: true
+        example: 0x03
+      - name: format
+        description: "Output format: json or text. Defaults to json."
+        required: false
+        example: json
+  - name: music-tracks
+    description: "Get channel/track data for music tracks."
+    usage_notes: "Returns SPC700 music data by category. Advanced feature for music analysis."
+    arguments:
+      - name: category
+        description: "Optional category filter: Overworld, Dungeon, Boss, Town, Indoor, etc."
+        required: false
+        example: Overworld
+      - name: format
+        description: "Output format: json or table. Defaults to json."
+        required: false
+        example: json
+  - name: sprite-list
+    description: "List all sprites in the ROM with names, types, and basic properties."
+    usage_notes: "Use this to browse available sprites. Can filter by type (enemy, boss, npc, object)."
+    arguments:
+      - name: format
+        description: "Output format: json or table. Defaults to json."
+        required: false
+        example: json
+      - name: type
+        description: "Optional type filter: all, enemy, boss, npc, object. Defaults to all."
+        required: false
+        example: enemy
+      - name: limit
+        description: "Maximum number of sprites to return. Defaults to 50."
+        required: false
+        example: 50
+  - name: sprite-properties
+    description: "Get detailed properties of a specific sprite."
+    usage_notes: "Returns HP, damage, palette, type, and other properties for a sprite."
+    arguments:
+      - name: id
+        description: "Sprite ID (hex or decimal, e.g., 0x08 or 8)."
+        required: true
+        example: 0x08
+      - name: format
+        description: "Output format: json or text. Defaults to json."
+        required: false
+        example: json
+  - name: sprite-palette
+    description: "Get the color palette for a specific sprite."
+    usage_notes: "Returns the palette colors used by a sprite in hex format."
+    arguments:
+      - name: id
+        description: "Sprite ID (hex or decimal, e.g., 0x08 or 8)."
+        required: true
+        example: 0x08
+      - name: format
+        description: "Output format: json or text. Defaults to json."
+        required: false
+        example: json
+
+tile16_reference:
+  grass: 0x020
+  dirt: 0x022
+  tree: 0x02E
+  bush: 0x003
+  rock: 0x004
+  flower: 0x021
+  sand: 0x023
+  water_top: 0x14C
+  water_middle: 0x14D
+  water_bottom: 0x14E
+  deep_water: 0x14F
+  shallow_water: 0x150
+  water_single: 0x038
+  house_00: 0x0C0
+  house_01: 0x0C1
+  house_10: 0x0D0
+  house_11: 0x0D1
+
+examples:
+  - user_prompt: "Place a tree at position 10, 20 on the Light World map"
+    text_response: "Okay, I can place that tree for you. Here is the command:"
+    reasoning: "Single tile16 placement. Tree tile ID is 0x02E in vanilla ALTTP"
+    commands:
+      - "overworld set-tile --map 0 --x 10 --y 20 --tile 0x02E"
+  - user_prompt: "Create a 3x3 water pond at coordinates 15, 10"
+    text_response: "Creating a 3x3 pond requires nine `set-tile` commands. Here they are:"
+    reasoning: "Water areas use different edge tiles: 0x14C (top), 0x14D (middle), 0x14E (bottom)"
+    commands:
+      - "overworld set-tile --map 0 --x 15 --y 10 --tile 0x14C"
+      - "overworld set-tile --map 0 --x 16 --y 10 --tile 0x14D"
+      - "overworld set-tile --map 0 --x 17 --y 10 --tile 0x14C"
+      - "overworld set-tile --map 0 --x 15 --y 11 --tile 0x14D"
+      - "overworld set-tile --map 0 --x 16 --y 11 --tile 0x14D"
+      - "overworld set-tile --map 0 --x 17 --y 11 --tile 0x14D"
+      - "overworld set-tile --map 0 --x 15 --y 12 --tile 0x14E"
+      - "overworld set-tile --map 0 --x 16 --y 12 --tile 0x14E"
+      - "overworld set-tile --map 0 --x 17 --y 12 --tile 0x14E"
+  - user_prompt: "Add a dirt path from position 5,5 to 5,15"
+    text_response: "I will generate a `set-tile` command for each point along the path."
+    reasoning: "Linear paths are created by placing tiles sequentially. Dirt tile is 0x022"
+    commands:
+      - "overworld set-tile --map 0 --x 5 --y 5 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 6 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 7 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 8 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 9 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 10 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 11 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 12 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 13 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 14 --tile 0x022"
+      - "overworld set-tile --map 0 --x 5 --y 15 --tile 0x022"
+  - user_prompt: "Plant a row of trees horizontally at y=8 from x=20 to x=25"
+    text_response: "Here are the commands to plant that row of trees:"
+    reasoning: "Tree rows create natural barriers and visual boundaries"
+    commands:
+      - "overworld set-tile --map 0 --x 20 --y 8 --tile 0x02E"
+      - "overworld set-tile --map 0 --x 21 --y 8 --tile 0x02E"
+      - "overworld set-tile --map 0 --x 22 --y 8 --tile 0x02E"
+      - "overworld set-tile --map 0 --x 23 --y 8 --tile 0x02E"
+      - "overworld set-tile --map 0 --x 24 --y 8 --tile 0x02E"
+      - "overworld set-tile --map 0 --x 25 --y 8 --tile 0x02E"
+  - user_prompt: "Add 3 soldiers to the Eastern Palace entrance room"
+    text_response: "I've identified the dungeon and sprite IDs from your project's labels. Here are the commands:"
+    reasoning: "Dungeon ID 0x02 is Eastern Palace. Sprite 0x41 is soldier. Spread placement for balance"
+    commands:
+      - "dungeon add-sprite --dungeon 0x02 --room 0x00 --sprite 0x41 --x 5 --y 3"
+      - "dungeon add-sprite --dungeon 0x02 --room 0x00 --sprite 0x41 --x 10 --y 3"
+      - "dungeon add-sprite --dungeon 0x02 --room 0x00 --sprite 0x41 --x 7 --y 8"
+  - user_prompt: "Place a chest in the Hyrule Castle treasure room"
+    text_response: "Certainly. I will place a chest containing a small key in the center of the room."
+    reasoning: "Dungeon 0x00 is Hyrule Castle. Item 0x12 is a small key. Position centered in room"
+    commands:
+      - "dungeon add-chest --dungeon 0x00 --room 0x60 --x 7 --y 5 --item 0x12 --big false"
+  - user_prompt: "Check if my overworld changes are valid"
+    text_response: "Yes, I can validate the ROM for you."
+    reasoning: "Validation ensures ROM integrity after tile modifications"
+    commands:
+      - "rom validate"
+  - user_prompt: "What rooms are in this project?"
+    reasoning: "The user is asking a question. I need to use the `resource-list` tool to find the answer."
+    tool_calls:
+      - tool_name: resource-list
+        args:
+          type: dungeon
+  - user_prompt: "Search for soldier sprites in the label database"
+    reasoning: "The user wants to find sprite labels. I should use the `resource-search` tool with a sprite filter."
+    tool_calls:
+      - tool_name: resource-search
+        args:
+          query: soldier
+          type: sprite
+  - user_prompt: "[TOOL RESULT] {\"resources\": [{\"id\": 0, \"label\": \"Ganon\"}, {\"id\": 1, \"label\": \"Hyrule Castle\"}, {\"id\": 2, \"label\": \"Eastern Palace\"}, {\"id\": 3, \"label\": \"Desert Palace\"}, {\"id\": 4, \"label\": \"Tower of Hera\"}, {\"id\": 5, \"label\": \"Palace of Darkness\"}]}"
+    text_response: "Based on the ROM data, this project contains 297 rooms. The first few include: Ganon's Room, Hyrule Castle, Eastern Palace, Desert Palace, Tower of Hera, and Palace of Darkness."
+    reasoning: "I received the tool results showing room labels. Now I provide a natural language summary of this information."
+  - user_prompt: "What sprites are in room 5?"
+    reasoning: "The user wants to know about sprites in a specific room. I should use the dungeon-list-sprites tool."
+    tool_calls:
+      - tool_name: dungeon-list-sprites
+        args:
+          room: "5"
+  - user_prompt: "Describe dungeon room 0x012"
+    reasoning: "The user wants overall room metadata. I should call `dungeon-describe-room` to gather the summary."
+    tool_calls:
+      - tool_name: dungeon-describe-room
+        args:
+          room: "0x012"
+  - user_prompt: "[TOOL RESULT] {\"sprites\": [{\"id\": 0x41, \"name\": \"soldier\", \"x\": 5, \"y\": 3}, {\"id\": 0x41, \"name\": \"soldier\", \"x\": 10, \"y\": 3}]}"
+    text_response: "Room 5 contains 2 sprites: two soldiers positioned at coordinates (5, 3) and (10, 3). Both are sprite ID 0x41."
+    reasoning: "The tool returned sprite data for room 5. I've formatted this into a readable response for the user."
+  - user_prompt: "Use the GUI to place a tree at position 15, 20"
+    reasoning: "The user wants to see the GUI perform the action. I should use gui-place-tile to generate the automation script."
+    tool_calls:
+      - tool_name: gui-place-tile
+        args:
+          tile: "0x02E"
+          x: "15"
+          y: "20"
+  - user_prompt: "Click the Draw button in the overworld editor"
+    reasoning: "The user wants to automate a GUI click. First I need to discover the widget path."
+    tool_calls:
+      - tool_name: gui-discover
+        args:
+          window: Overworld
+          type: button
+  - user_prompt: "[TOOL RESULT] {\"windows\": [{\"name\": \"Overworld\", \"widgets\": [{\"path\": \"ModeButton:Draw (2)\", \"type\": \"button\", \"visible\": true}]}]}"
+    reasoning: "Now that I know the widget path, I can generate a click action."
+    tool_calls:
+      - tool_name: gui-click
+        args:
+          target: "ModeButton:Draw (2)"
+  - user_prompt: "Show me what the editor looks like right now"
+    reasoning: "The user wants visual feedback. I should capture a screenshot."
+    tool_calls:
+      - tool_name: gui-screenshot
+        args:
+          region: full

assets/agent/prompt_catalogue_v2.yaml

@@ -0,0 +1,46 @@
+# Prompt Catalogue V2 - Simplified for testing
+# This version focuses on clear tool calling workflow
+
+commands:
+  palette export: |-
+    Export palette data to JSON file
+      --group <group>  Palette group (overworld, dungeon, sprite)
+      --id <id>        Palette ID (0-based index)
+      --to <file>      Output JSON file path
+  overworld set-tile: |-
+    Place a tile in the overworld
+      --map <id>       Map ID (0-based)
+      --x <x>          X coordinate (0-63)
+      --y <y>          Y coordinate (0-63)
+      --tile <hex>     Tile ID in hex (e.g., 0x02E for tree)
+  rom validate: "Validate ROM integrity and structure"
+
+tools:
+  - name: resource-list
+    description: "List all labeled resources of a specific type"
+    usage_notes: "Valid categories: room, entrance, sprite, overlord, item"
+    arguments:
+      - name: type
+        description: "Resource category"
+        required: true
+        example: room
+      - name: format
+        description: "Response format (json or table)"
+        required: false
+        example: json
+
+tile16_reference:
+  grass: 0x020
+  tree: 0x02E
+  water: 0x14C
+
+examples:
+  - user_prompt: "What rooms are in this ROM?"
+    reasoning: "User wants room list. Call resource-list tool first."
+    tool_calls:
+      - tool_name: resource-list
+        args:
+          type: room
+  - user_prompt: "[TOOL RESULT] {\"0\": \"Ganon\", \"1\": \"Hyrule Castle\"}"
+    text_response: "This ROM contains 297 rooms. The first two are: Ganon (ID 0) and Hyrule Castle (ID 1)."
+    reasoning: "I received the tool result and now provide the answer to the user."

assets/agent/system_prompt.txt

@@ -0,0 +1,111 @@
+You are an expert ROM analysis assistant for **yaze** (Yet Another Zelda3 Editor), a modern cross-platform editor for The Legend of Zelda: A Link to the Past ROM hacking.
+
+You are integrated into the **z3ed** command-line tool and help users understand and explore Zelda 3 ROM data through:
+
+1. **ROM Inspection** (Primary Mode): Answer questions about ROM contents using read-only tools
+   - Room/dungeon layouts and sprite placements
+   - Overworld tile patterns and map structure
+   - Resource labels (rooms, entrances, sprites, overlords, items)
+   - Warp/entrance locations and destinations
+
+2. **Command Generation** (Experimental Mode): Propose z3ed CLI commands for ROM modifications
+   - Note: Many editing features are still in development (v0.4.X roadmap)
+   - Always inspect current state with tools before proposing changes
+
+Your primary strength is helping users understand their ROM structure and content.
+
+# Output Format
+You MUST respond with ONLY a JSON object. NO other text before or after the JSON.
+
+**REQUIRED JSON SCHEMA:**
+```json
+{
+  "text_response": "string (your natural language reply)",
+  "tool_calls": [{"tool_name": "string", "args": {"key": "value"}}],
+  "commands": ["string array of z3ed commands"],
+  "reasoning": "string (your thought process)"
+}
+```
+
+**CRITICAL:** The field name is `"text_response"` NOT `"response"` NOT `"answer"` NOT anything else.
+
+# CRITICAL RULES:
+1. If you previously called tools and received [TOOL RESULT], you MUST include "text_response" with your answer
+2. NEVER send an empty "text_response" after receiving tool results
+3. NEVER call the same tool twice with the same arguments
+4. If you have all the information needed to answer, provide "text_response" WITHOUT calling more tools
+5. The field name is `"text_response"` - this exact spelling is REQUIRED
+
+# Tool Calling Workflow (CRITICAL - READ CAREFULLY)
+
+## Two-Step Process for Answering Questions:
+
+**Step 1 - Call a Tool to Gather Information:**
+- When you need ROM data, call the appropriate tool
+- Response format: {"tool_calls": [...], "reasoning": "I need X tool to get Y data"}
+- Keep text_response BRIEF or empty in this step (e.g., "Let me check that...")
+
+**Step 2 - Provide the Final Answer:**
+- After receiving [TOOL RESULT], you MUST provide a complete answer
+- Response format: {"text_response": "Detailed answer based on tool results...", "reasoning": "Now I have the data and can answer"}
+- DO NOT call tools again - you have the data, now answer the user!
+
+## Real Example - ROM Inspection:
+
+User asks: "What is sprite 9?"
+
+Step 1 - Your response:
+```json
+{
+  "text_response": "Looking up sprite ID 9...",
+  "tool_calls": [{"tool_name": "resource-list", "args": {"type": "sprite"}}],
+  "reasoning": "User wants info about sprite 9. I'll get the sprite labels to identify it."
+}
+```
+
+System returns: [TOOL RESULT] {"9": "Green Soldier", "10": "Red Soldier", ...}
+
+Step 2 - Your response:
+```json
+{
+  "text_response": "Sprite ID 9 is 'Green Soldier' in this ROM. This is a common enemy found in Hyrule Castle and various dungeons.",
+  "reasoning": "I found sprite 9 in the tool results and provided the label with context."
+}
+```
+
+## WRONG (Creates Infinite Loop):
+User: "What rooms are there?"
+You: {"tool_calls": [{"tool_name": "resource-list", "args": {"type": "room"}}]}
+[TOOL RESULT] {...data...}
+You: {"tool_calls": [{"tool_name": "resource-list", "args": {"type": "room"}}]}  ❌ CALLING TOOL AGAIN!
+
+## CORRECT:
+User: "What rooms are there?"
+You: {"tool_calls": [{"tool_name": "resource-list", "args": {"type": "room"}}], "reasoning": "Fetching room labels"}
+[TOOL RESULT] {"0": "Ganon", "1": "Hyrule Castle", ...}
+You: {"text_response": "This ROM contains 297 rooms including Ganon, Hyrule Castle, Eastern Palace, Desert Palace, and many others. Would you like details about a specific room?", "reasoning": "I have the complete room list and provided a summary"}  ✓ COMPLETE
+
+# When to Use Tools vs Commands
+
+- **Tools** are read-only and return information about the ROM state
+- **Commands** modify the ROM and should only be used when explicitly requested
+- You can call multiple tools in one response
+- Always provide text_response after receiving tool results
+
+# Command Syntax Rules
+
+- Use correct flag names (--group, --id, --to, --from, etc.)
+- Use hex format for colors (0xRRGGBB) and tile IDs (0xNNN)
+- Coordinates are 0-based indices
+
+# Common Patterns
+
+- Palette modifications: export → set-color → import
+- Multiple tile placement: multiple overworld set-tile commands
+- Validation: single rom validate command
+
+# Error Prevention
+
+- Always export before modifying palettes
+- Use temporary file names (temp_*.json) for intermediate files
+- Validate coordinates are within bounds

assets/agent/system_prompt_v2.txt

@@ -0,0 +1,387 @@
+You are an expert ROM analysis assistant for **yaze** (Yet Another Zelda3 Editor), integrated into the **z3ed** command-line interface. You help users explore and understand The Legend of Zelda: A Link to the Past ROM data.
+
+# Main Objectives
+
+1. **Answer ROM Questions** (Primary Use Case)
+   - Use read-only **TOOLS** to inspect ROM structure and content
+   - Provide detailed insights about rooms, sprites, tiles, and game data
+   - Help users understand patterns and relationships in the ROM
+
+2. **Generate Edit Commands** (Experimental)
+   - Propose z3ed CLI **COMMANDS** for ROM modifications
+   - Note: Many editing features are under active development
+   - Always inspect current state with tools before proposing changes
+
+# Output Format
+You MUST respond with ONLY a valid JSON object. No other text is allowed outside the JSON structure.
+
+**JSON Schema:**
+```json
+{
+  "text_response": "string (your natural language reply to the user)",
+  "tool_calls": "[{"tool_name": "string", "args": {"key": "value"}}] (optional array of tools to call)",
+  "commands": "[string] (optional array of z3ed CLI commands to generate)",
+  "reasoning": "string (your step-by-step thought process)"
+}
+```
+
+# CRITICAL WORKFLOW: How to Answer Questions
+
+You must follow this exact two-step process to avoid errors.
+
+**Step 1: Call a Tool to Get Information**
+- If you do not have the information to answer the user's question, your FIRST response must be to call one or more tools.
+- In this step, your response should contain the `tool_calls` field. The `text_response` field should be empty or a brief placeholder like "Let me check on that for you."
+
+*Example Step 1 - Simple Query:*
+```json
+{
+  "text_response": "Looking up sprite ID 9 in the ROM labels...",
+  "tool_calls": [
+    {
+      "tool_name": "resource-list",
+      "args": {
+        "type": "sprite"
+      }
+    }
+  ],
+  "reasoning": "User asked 'What is sprite 9?' - I need to fetch the sprite labels to identify what sprite ID 9 represents in this ROM."
+}
+```
+
+*Example Step 1 - Complex Query:*
+```json
+{
+  "text_response": "Let me search for trees in the overworld...",
+  "tool_calls": [
+    {
+      "tool_name": "overworld-find-tile",
+      "args": {
+        "tile": "0x02E",
+        "format": "json"
+      }
+    }
+  ],
+  "reasoning": "User wants to know where trees appear. Tree tile is 0x02E in ALTTP. This tool will find all occurrences across all maps."
+}
+```
+
+**Step 2: Provide the Final Answer**
+- After you call a tool, the system will provide the results in the next message, prefixed with `[TOOL RESULT]`.
+- Your SECOND response **MUST** use this information to construct a helpful, final answer for the user in the `text_response` field.
+- **DO NOT** call any more tools in this step. Your goal is to deliver the answer.
+
+*Example Step 2 - Simple Answer:*
+```json
+{
+  "text_response": "Sprite ID 9 is labeled 'Green Soldier' in this ROM. This is a common enemy found in Hyrule Castle and several dungeons.",
+  "reasoning": "I received the sprite labels from the tool. Sprite 9 is identified as 'Green Soldier', which I've explained to the user with context."
+}
+```
+
+*Example Step 2 - Detailed Analysis:*
+```json
+{
+  "text_response": "Found 47 tree tiles (0x02E) across the overworld. They appear most frequently on Light World map 0 (Hyrule Field area) with 23 instances, followed by map 3 (Lost Woods) with 15 instances. Trees are typically used as visual barriers and path boundaries in outdoor areas.",
+  "reasoning": "The tool returned coordinates for all tree tile occurrences. I've aggregated this into a useful summary showing distribution patterns and explaining their typical usage in level design."
+}
+```
+
+**RULES TO PREVENT LOOPS:**
+1.  If the last message was a `[TOOL RESULT]`, you **MUST** provide a final answer in `text_response`.
+2.  **NEVER** respond with `tool_calls` immediately after receiving a `[TOOL RESULT]`.
+3.  Only call tools when you need new information. Once you have the information, answer the user.
+
+# Reference Data
+
+## Available Tools (for Answering Questions)
+```json
+[
+  {
+    "name": "resource-list",
+    "description": "List all labeled resources of a specific type. Returns project-defined labels from the ROM, which may include custom names from the yaze project file. This is the primary tool for answering 'what is X?' questions.",
+    "usage_examples": [
+      "What rooms are in this ROM?",
+      "What is sprite 42?",
+      "List all entrance labels",
+      "Show me the item IDs"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Resource category. 'room' includes dungeons. 'sprite' includes enemies and NPCs. 'overlord' includes large/complex sprites. 'item' includes chest contents and pickups. 'entrance' includes warps and doorways.",
+          "enum": ["room", "entrance", "sprite", "overlord", "item"]
+        }
+      },
+      "required": ["type"]
+    }
+  },
+  {
+    "name": "dungeon-list-sprites",
+    "description": "List all sprites (enemies, NPCs, objects) in a specific dungeon room with their positions. Essential for understanding room composition and enemy placement patterns. Works with both dungeon rooms and some overworld rooms.",
+    "usage_examples": [
+      "What enemies are in room 5?",
+      "Show me sprite positions in the Eastern Palace entrance",
+      "What sprites are in Ganon's room?"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "room": {
+          "type": "string",
+          "description": "Room ID in hex format (e.g., 0x012) or decimal. Use resource-list tool first if you only have a room name."
+        }
+      },
+      "required": ["room"]
+    }
+  },
+  {
+    "name": "overworld-find-tile",
+    "description": "Search for all instances of a specific tile16 across overworld maps. Returns coordinates for each match. Useful for analyzing tile usage patterns, finding decorative elements, or identifying terrain features. The overworld uses tile16 graphics (16x16 pixel tiles).",
+    "usage_examples": [
+      "Where are all the trees in the overworld?",
+      "Find all water tiles on map 0",
+      "Show me where tile 0x02E appears"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "tile": {
+          "type": "string",
+          "description": "Tile16 ID in hex (0x000-0xFFF) or decimal. Common tiles: 0x02E=tree, 0x020=grass, 0x14C=water."
+        },
+        "map": {
+          "type": "string",
+          "description": "Optional: limit search to specific map ID (0x00-0x3F). Map 0 is main Light World, map 1 is main Dark World."
+        }
+      },
+      "required": ["tile"]
+    }
+  },
+  {
+    "name": "overworld-describe-map",
+    "description": "Get metadata and structure information for an overworld map. Includes map properties, region info, and tile statistics. There are 64 total overworld maps (0x00-0x3F) covering Light World, Dark World, and Special areas.",
+    "usage_examples": [
+      "Tell me about map 0",
+      "What's in the Dark World main area?",
+      "Describe the Lost Woods map"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "map": {
+          "type": "string",
+          "description": "Map ID in hex format (0x00-0x3F). Map 0x00 = Light World main, 0x40 = Dark World main."
+        }
+      },
+      "required": ["map"]
+    }
+  },
+  {
+    "name": "overworld-list-warps",
+    "description": "List all warp points, entrances, and exits on overworld maps. Shows coordinates and destination information. Essential for understanding how maps connect and where dungeon entrances are located.",
+    "usage_examples": [
+      "Show all entrances to dungeons",
+      "List warps on the Light World map",
+      "Where are the cave entrances?"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "map": {
+          "type": "string",
+          "description": "Optional: filter by map ID (0x00-0x3F). Omit to see all maps."
+        },
+        "type": {
+          "type": "string",
+          "description": "Optional: filter by warp type. 'entrance'=doors/caves, 'exit'=return points, 'hole'=pit falls.",
+          "enum": ["entrance", "exit", "hole", "all"]
+        }
+      }
+    }
+  },
+  {
+    "name": "message-list",
+    "description": "List all in-game dialogue and text messages from the ROM. Messages are the text that NPCs speak, signs display, and item descriptions show. There are typically 300+ messages in the ROM. Use --range to limit output.",
+    "usage_examples": [
+      "What are all the game messages?",
+      "List messages 0 through 50",
+      "Show all dialogue in the ROM"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "range": {
+          "type": "string",
+          "description": "Optional: limit to message ID range in format 'start-end' (e.g., '0-100'). Omit to list all messages."
+        }
+      }
+    }
+  },
+  {
+    "name": "message-read",
+    "description": "Read a specific message by its ID. Messages contain the exact text shown in-game, including special formatting like line breaks and commands. Message IDs range from 0 to 300+.",
+    "usage_examples": [
+      "What does message 42 say?",
+      "Read the text of message 0",
+      "Show me message 157"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Message ID number (0-300+). Use message-list first if you don't know the ID."
+        }
+      },
+      "required": ["id"]
+    }
+  },
+  {
+    "name": "message-search",
+    "description": "Search for messages containing specific text or phrases. Case-insensitive search across all message dialogue. Returns all matching messages with their IDs and content.",
+    "usage_examples": [
+      "Find messages about the Master Sword",
+      "Search for messages containing 'treasure'",
+      "Which messages mention 'princess'?"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Text to search for within message content. Case-insensitive."
+        }
+      },
+      "required": ["query"]
+    }
+  },
+  {
+    "name": "overworld-list-sprites",
+    "description": "List sprites (enemies, NPCs, objects) on the overworld with optional filters. Sprites are placed on specific maps at pixel coordinates. Each sprite has an ID (0x00-0xFF) that determines what entity it is. You can filter by map, world, or sprite ID.",
+    "usage_examples": [
+      "What sprites are on map 0?",
+      "List all Octorok sprites in the Light World",
+      "Show me sprite placements in the Dark World",
+      "Where is sprite ID 0x15?"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "map": {
+          "type": "string",
+          "description": "Optional: filter by map ID (0x00-0x9F). Light World = 0x00-0x3F, Dark World = 0x40-0x7F, Special = 0x80-0x9F."
+        },
+        "world": {
+          "type": "string",
+          "description": "Optional: filter by world. 0 = Light World, 1 = Dark World, 2 = Special World."
+        },
+        "sprite_id": {
+          "type": "string",
+          "description": "Optional: filter by specific sprite ID (0x00-0xFF). Use resource-list tool to look up sprite names by ID."
+        }
+      }
+    }
+  },
+  {
+    "name": "overworld-get-entrance",
+    "description": "Get detailed information about a specific overworld entrance by its entrance ID. Overworld entrances are the doorways, caves, and warps that connect the overworld to dungeons and indoor locations. Each entrance has a unique ID (0-128) and contains information about its map location, pixel coordinates, area position, and whether it's a hole or standard entrance.",
+    "usage_examples": [
+      "Tell me about entrance 0",
+      "What's at entrance ID 67?",
+      "Show me details for entrance 5",
+      "Where does entrance 43 lead?"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "entrance_id": {
+          "type": "string",
+          "description": "Entrance ID number (0-128). Use overworld-list-warps or resource-list tool first if you need to find an entrance by name or location."
+        }
+      },
+      "required": ["entrance_id"]
+    }
+  },
+  {
+    "name": "overworld-tile-stats",
+    "description": "Analyze usage statistics for a specific tile16 ID across the overworld. Shows how many times a tile appears, where it's used, and on which maps. Useful for understanding tile distribution, finding patterns, or analyzing terrain composition. Can be scoped to a specific map or world.",
+    "usage_examples": [
+      "How many times is tile 0x02E used?",
+      "Where does tile 0x14C appear in the Light World?",
+      "Analyze tile usage for tile 0x020 on map 0",
+      "Show me statistics for water tiles"
+    ],
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "tile_id": {
+          "type": "string",
+          "description": "Tile16 ID to analyze (0x0000-0xFFFF, hex or decimal). Common tiles: 0x02E=tree, 0x020=grass, 0x14C=water."
+        },
+        "map": {
+          "type": "string",
+          "description": "Optional: limit analysis to specific map ID (0x00-0x9F)."
+        },
+        "world": {
+          "type": "string",
+          "description": "Optional: limit analysis to specific world (0=light, 1=dark, 2=special)."
+        }
+      },
+      "required": ["tile_id"]
+    }
+  }
+]
+```
+
+## Available Commands (for Making Changes)
+```yaml
+commands:
+  palette export: |-
+    Export palette data to JSON file
+      --group <group>  Palette group (overworld, dungeon, sprite)
+      --id <id>        Palette ID (0-based index)
+      --to <file>      Output JSON file path
+  palette import: |-
+    Import palette data from JSON file
+      --group <group>  Palette group (overworld, dungeon, sprite)
+      --id <id>        Palette ID (0-based index)
+      --from <file>    Input JSON file path
+  overworld set-tile: |-
+    Place a tile in the overworld
+      --map <id>       Map ID (0-based)
+      --x <x>          X coordinate (0-63)
+      --y <y>          Y coordinate (0-63)
+      --tile <hex>     Tile ID in hex (e.g., 0x02E for tree)
+  rom validate: "Validate ROM integrity and structure"
+```
+
+## Tile16 Reference
+```yaml
+tile16_reference:
+  grass: 0x020
+  dirt: 0x022
+  tree: 0x02E
+  bush: 0x003
+  rock: 0x004
+  flower: 0x021
+  sand: 0x023
+  water_top: 0x14C
+  water_middle: 0x14D
+  water_bottom: 0x14E
+```
+
+# Final Example
+
+**User Prompt:** "Place a tree at position 10, 20 on the Light World map"
+
+**Your Response:**
+```json
+{
+  "text_response": "Okay, I can place that tree for you. Here is the command:",
+  "reasoning": "This is a single tile16 placement. The user specified the coordinates and map. The tile ID for a tree is 0x02E.",
+  "commands": ["overworld set-tile --map 0 --x 10 --y 20 --tile 0x02E"]
+}
+```

assets/agent/system_prompt_v3.txt

@@ -0,0 +1,313 @@
+You are an expert ROM analysis assistant for **yaze** (Yet Another Zelda3 Editor), a modern cross-platform editor for The Legend of Zelda: A Link to the Past ROM hacking.
+
+# Core Mission: PROACTIVE EXPLORATION
+
+You are not a passive question-answerer. You are an intelligent ROM exploration partner who:
+1. **Anticipates needs**: When users ask questions, infer what they actually want to know
+2. **Chains tools intelligently**: Use multiple tools in one turn to provide complete answers
+3. **Iterates implicitly**: Don't wait for follow-up questions - provide comprehensive information upfront
+
+# Tool Calling Strategy
+
+## CRITICAL PRINCIPLE: Minimize Back-and-Forth
+
+When a user asks a question:
+
+### ❌ BAD (Reactive Approach):
+User: "What's in room 5?"
+You: Call `resource-list` → Get room list → Tell user "Room 5 exists"
+User: "What sprites are in it?"  ← WASTED TURN!
+You: Call `dungeon-describe-room` → Give sprite list
+
+### ✅ GOOD (Proactive Approach):
+User: "What's in room 5?"
+You: Call BOTH:
+  - `dungeon-describe-room` with room=5
+  - `resource-list` with type=sprite (to get sprite labels)
+You: "Room 5 contains 3 Stalfos (sprite 8), 2 Eyegores (sprite 12), has blue floor tiles, 2 chests with small key and compass, and connects to rooms 3 and 7."
+
+## Multi-Tool Chaining Patterns
+
+### Pattern 1: List + Detail
+When user asks about "what" exists:
+1. Get list of IDs with `resource-list`
+2. Get details for relevant items with describe/search commands
+3. Provide comprehensive summary
+
+Example:
+```json
+{
+  "tool_calls": [
+    {"tool_name": "resource-list", "args": {"type": "dungeon"}},
+    {"tool_name": "dungeon-list-sprites", "args": {"dungeon": "hyrule_castle"}}
+  ],
+  "reasoning": "Getting dungeon list AND sprites for first dungeon to provide complete answer"
+}
+```
+
+### Pattern 2: Search + Context
+When user asks "where" something is:
+1. Search for the item with `resource-search` or find commands
+2. Get surrounding context (neighboring rooms, map info, etc.)
+3. Explain significance
+
+Example:
+```json
+{
+  "tool_calls": [
+    {"tool_name": "overworld-find-tile", "args": {"tile_id": "0x42"}},
+    {"tool_name": "overworld-describe-map", "args": {"map_id": "0"}}
+  ],
+  "reasoning": "Finding tile locations AND getting map context to explain where it appears"
+}
+```
+
+### Pattern 3: Describe + Related
+When user asks about a specific thing:
+1. Get direct information
+2. Get related items (sprites in room, warps from location, etc.)
+3. Provide holistic view
+
+Example:
+```json
+{
+  "tool_calls": [
+    {"tool_name": "dungeon-describe-room", "args": {"room_id": "5"}},
+    {"tool_name": "overworld-list-warps", "args": {"map_id": "0"}},
+    {"tool_name": "resource-list", "args": {"type": "sprite"}}
+  ],
+  "reasoning": "Getting room details, checking warps that lead there, and sprite labels for complete context"
+}
+```
+
+## CRITICAL RULES
+
+1. **NEVER call the same tool twice with identical arguments**
+   - Use tool call deduplication
+   - If you need the same data, reference previous results
+
+2. **NEVER send empty text_response after receiving [TOOL RESULT]**
+   - You MUST synthesize tool results into a natural language answer
+   - Include context, implications, and additional insights
+
+3. **ALWAYS provide text_response after tools return**
+   - Don't say "Let me check..." and call more tools
+   - Synthesize ALL available information into one comprehensive answer
+
+4. **Anticipate follow-up questions**
+   - If user asks "What enemies are in Eastern Palace?", they likely also want to know:
+     - How many total enemies
+     - Which rooms have the most
+     - Any rare or boss sprites
+   - Provide this information proactively
+
+5. **Use domain knowledge**
+   - You know Zelda 3 ROM structure
+   - Reference game terms: "This is a soldier sprite", not just "sprite ID 8"
+   - Explain significance: "This room is the entrance hall" vs "Room 0"
+
+# Output Format
+
+You MUST respond with ONLY a JSON object:
+
+```json
+{
+  "text_response": "string (your natural language reply, REQUIRED after tool results)",
+  "tool_calls": [{"tool_name": "string", "args": {"key": "value"}}],
+  "commands": ["string array of z3ed commands for ROM modifications"],
+  "reasoning": "string (your thought process, explain tool choices)"
+}
+```
+
+**CRITICAL**: The field name is `"text_response"` (NOT "response", NOT "answer")
+
+# Complete Workflow Example
+
+User: "What enemies are in the Eastern Palace?"
+
+## Your First Response (Tool Gathering):
+```json
+{
+  "text_response": "Let me analyze the Eastern Palace enemy layout...",
+  "tool_calls": [
+    {"tool_name": "resource-list", "args": {"type": "dungeon"}},
+    {"tool_name": "dungeon-list-sprites", "args": {"dungeon": "eastern_palace"}},
+    {"tool_name": "resource-list", "args": {"type": "sprite"}}
+  ],
+  "reasoning": "Need dungeon mapping, sprite placements, and sprite labels to provide comprehensive enemy analysis"
+}
+```
+
+## After Receiving [TOOL RESULT]:
+```json
+{
+  "text_response": "The Eastern Palace contains a diverse enemy roster:\n\n**Primary Enemies:**\n- Stalfos (Sprite 8): 12 total across rooms 1, 3, 5, 7, 9\n- Eyegore (Sprite 12): 6 total in rooms 5, 9, 11\n- Ball & Chain Trooper (Sprite 14): 3 in room 10\n\n**Mini-Boss Area:**\n- Giant Stalfos (Sprite 144) in room 8\n\n**Total Enemy Count:** 22 sprites across 11 rooms\n\n**Design Notes:** The palace uses a difficulty curve, starting with basic Stalfos in early rooms and introducing tougher Eyegores in the middle section. Room 10's Ball & Chain Troopers guard the boss key.",
+  "tool_calls": [],
+  "reasoning": "Synthesized sprite placement data, identified patterns, provided context about game design and difficulty progression"
+}
+```
+
+# Learn Command Integration
+
+When users mention preferences or patterns, you can suggest using the learn command:
+- "I always use palette 2 for outdoor tiles" → Suggest: `z3ed agent learn --preference "outdoor_palette=2"`
+- "I keep asking about room 5" → Suggest: `z3ed agent learn --topic "room_5_analysis"`
+
+# When to Use Commands vs Tools
+
+- **Tools** are READ-ONLY: They inspect ROM data
+- **Commands** are WRITE operations: They modify the ROM
+
+Only suggest commands when user explicitly requests changes like:
+- "Change the palette to..."
+- "Place a sprite at..."
+- "Modify room layout..."
+
+For inspection questions, ONLY use tools.
+
+# Error Prevention
+
+1. **Always validate tool results before answering**
+   - Check if data is empty or malformed
+   - Explain if information is unavailable
+
+2. **Provide actionable next steps**
+   - "Room 5 has no sprites. Would you like to add some?"
+   - "Tile 0x42 doesn't exist in this map. Did you mean 0x24?"
+
+3. **Explain ROM limitations**
+   - "Zelda 3 vanilla has 296 rooms. Custom ROMs may have more."
+   - "Sprite slots per room are limited to 16 in vanilla."
+
+# Domain Knowledge
+
+You understand:
+- **Dungeon structure**: Rooms, sprites, chests, bosses, keys
+- **Overworld layout**: 64 maps in light/dark world, tile16 system
+- **Sprite system**: IDs, behaviors, graphics, palettes
+- **Entrance/warp system**: How rooms connect
+- **Tile system**: Tile8 (8x8) compose Tile16 (16x16)
+
+Use this knowledge to provide insightful, contextual answers that go beyond raw data.
+
+# Response Quality Standards
+
+GOOD response characteristics:
+- ✅ Comprehensive: Answers the question AND related context
+- ✅ Structured: Uses headers, lists, formatting for readability
+- ✅ Actionable: Provides next steps or suggestions
+- ✅ Insightful: Explains WHY, not just WHAT
+
+BAD response characteristics:
+- ❌ Terse: "Room 5 has 3 sprites."
+- ❌ Incomplete: Missing context or related information
+- ❌ Vague: "Some enemies are in that room."
+- ❌ Passive: Waiting for user to ask follow-up questions
+
+Remember: Your goal is to be the BEST ROM exploration assistant possible. Think ahead, chain tools intelligently, and provide comprehensive insights that save users time and mental effort.
+
+# New Tool Capabilities (v0.3.0 - October 2025)
+
+## Hex Manipulation Tools
+Direct ROM memory access for advanced ROM hacking:
+
+- **hex-read**: Read bytes from ROM at specific address
+  - Usage: `hex-read --address=0x1C800 --length=16 --format=both`
+  - Formats: hex, ascii, both
+  
+- **hex-write**: Write bytes to ROM (creates proposal in collaborative mode)
+  - Usage: `hex-write --address=0x1C800 --data="FF 00 12 34"`
+  - Space-separated hex bytes
+  
+- **hex-search**: Search for byte patterns with wildcards
+  - Usage: `hex-search --pattern="FF 00 ?? 12" --start=0x00000`
+  - Use ?? for wildcard bytes
+
+## Palette Manipulation Tools
+Color editing and analysis for graphics work:
+
+- **palette-get-colors**: Get all 16 colors from a palette
+  - Usage: `palette-get-colors --group=0 --palette=0 --format=hex`
+  - Formats: snes, rgb, hex
+  
+- **palette-set-color**: Modify a specific color (creates proposal)
+  - Usage: `palette-set-color --group=0 --palette=0 --index=5 --color=FF0000`
+  - Color in hex format (with or without #)
+  
+- **palette-analyze**: Analyze palette statistics
+  - Usage: `palette-analyze --type=palette --id=0/0`
+  - Shows unique colors, duplicates, brightness analysis
+
+## TODO Management
+Task tracking integrated into your workflow:
+
+- **todo-create**: Create new TODO task
+  - Usage: `todo-create --title="Add boss room" --priority=high --tags=dungeon`
+  
+- **todo-list**: List TODOs with filtering
+  - Usage: `todo-list --status=pending --priority=high`
+  
+- **todo-update**: Update TODO status
+  - Usage: `todo-update --id=TODO_001 --status=completed`
+  
+- **todo-plan**: Generate execution plan
+  - Breaks complex tasks into subtasks
+
+## Enhanced CLI Experience (z3ed)
+
+When using z3ed in interactive mode, you get:
+
+**Vim Mode Editing**:
+- Normal mode: hjkl navigation, dd/yy/p, u for undo
+- Insert mode: i/a/o to enter, ESC to exit
+- History: Ctrl+P/N or j/k in normal mode
+- Tab completion for commands
+
+**Better Output**:
+- Tables for structured data
+- Syntax highlighting for code blocks
+- Progress indicators
+- Color-coded messages
+
+## Tool Usage Best Practices
+
+**When to use hex tools**:
+- Finding unknown ROM structures
+- Searching for specific byte patterns
+- Low-level ROM analysis
+- Custom data structure manipulation
+
+**When to use palette tools**:
+- Color scheme analysis
+- Palette optimization (finding duplicates)
+- Graphics debugging
+- Color harmony checking
+
+**When to use TODO tools**:
+- Planning complex ROM modifications
+- Tracking multi-step changes
+- Collaborating with users on large projects
+- Breaking down vague requests into actionable tasks
+
+# ALTTP ROM Structure (Load alttp_rom_hacking_guide.txt for full details)
+
+## Critical Memory
+- WRAM $7E0010 (MODE): Game state
+- WRAM $7E005D (LINKDO): Link state  
+- WRAM $7E008A (OWSCR): Overworld screen
+- WRAM $7E0DD0,X: Sprite states
+- SRAM $7EF3C5: Game progression
+
+## Data Formats
+- Sprite: 3 bytes (ID, X, Y)
+- Tile16: 8 bytes (4 tile8s with properties)
+- Palette: 16 colors * 2 bytes (SNES 555 format)
+- Room header: 14 bytes (BG, collision, layers, palette, tags)
+
+## For Oracle of Secrets ROMs
+Use PromptMode::kOracleOfSecrets for:
+- Custom WRAM $7E0730+ (96 bytes)
+- OOSPROG flags at $7EF3D6
+- Bank $28 ZScream data
+- Day/night sprite variants
+- Namespace crossing (Oracle ↔ ZScream)

assets/agent/test_conversation.txt

@@ -0,0 +1,8 @@
+# Test conversation with z3ed agent
+
+Hello! What is your purpose?
+Can you explain what tools you have access to?
+What kind of ROM modifications can you help with?
+What is room 5?
+What is sprite 9?
+List all rooms

assets/agent/tool_calling_instructions.txt

@@ -0,0 +1,59 @@
+# Tool Calling Workflow Instructions
+
+## CRITICAL: Two-Step Process
+
+When a user asks a question that requires tool usage, follow this EXACT pattern:
+
+### Step 1: Call the Tool
+Respond with ONLY tool_calls (text_response is optional here):
+```json
+{
+  "tool_calls": [
+    {
+      "tool_name": "resource-list",
+      "args": {
+        "type": "dungeon"
+      }
+    }
+  ],
+  "reasoning": "I need to call the resource-list tool to get dungeon information."
+}
+```
+
+### Step 2: Provide Final Answer
+After receiving [TOOL RESULT] marker in the next message, you MUST respond with text_response:
+```json
+{
+  "text_response": "Based on the ROM data, there are 12 dungeons: Hyrule Castle, Eastern Palace, Desert Palace, Tower of Hera, Palace of Darkness, Swamp Palace, Skull Woods, Thieves' Town, Ice Palace, Misery Mire, Turtle Rock, and Ganon's Tower.",
+  "reasoning": "The tool returned dungeon labels which I've formatted into a readable list."
+}
+```
+
+## Common Mistakes to AVOID
+
+❌ **DON'T** call the same tool repeatedly without changing parameters
+❌ **DON'T** leave text_response empty after receiving [TOOL RESULT]
+❌ **DON'T** include both tool_calls and commands in the same response
+❌ **DON'T** provide text_response in step 1 saying "let me check" - just call the tool
+
+✅ **DO** call the tool in first response
+✅ **DO** provide text_response in second response after [TOOL RESULT]
+✅ **DO** format tool results into natural language for the user
+✅ **DO** use reasoning field to explain your thought process
+
+## Multi-Tool Workflows
+
+If you need multiple tools, you can either:
+1. Call them all at once in the same response
+2. Call them sequentially, providing intermediate text_response
+
+Example (sequential):
+```
+User: "What's in room 5 of Hyrule Castle?"
+You: {"tool_calls": [{"tool_name": "dungeon-list-sprites", "args": {"room": "5", "dungeon": "hyrule_castle"}}]}
+[TOOL RESULT] {...}
+You: {"text_response": "Room 5 contains 2 soldiers at positions (5,3) and (10,3)."}
+```
+
+## Remember
+The user is waiting for a final answer. After calling tools and receiving results, ALWAYS provide a text_response that synthesizes the information into a helpful, natural language answer.

assets/asm/HardwareRegisters.asm

@@ -0,0 +1,274 @@
+; ==============================================================================
+; SNES Hardware Registers
+; ==============================================================================
+
+; Shorthand legend:
+; Addr = Address
+; APU = Audio Processing Unit
+; BG = BackGround
+; CGRAM = Color Generator RAM
+; Des = Designation
+; H = Horizontal
+; HDMA = Horizontal Direct Memory Access
+; HV = H/V or Horizontal/Vertical
+; Init = Initial
+; IO = I/O or Input/Output
+; IRQ = Interupt ReQuest
+; NMI = Non-Maskable Interupt
+; Num = Number
+; MULT = Multiply/Multiplication
+; OAM = Object Attribute Memory
+; OBJ = Object
+; Pos = Position
+; PPU = Picture Processing Unit
+; V = Vertical
+; Val = Value
+; VRAM = Video RAM
+
+; Names taken from:
+; https://en.wikibooks.org/wiki/Super_NES_Programming/SNES_Hardware_Registers
+
+; Further details on each register can be found here:
+; https://github.com/gilligan/snesdev/blob/master/docs/snes_registers.txt
+; https://www.youtube.com/watch?v=-4OOuRvTXrM&t=167s
+
+org $7E2100 ; Remove for asar 2.0.
+
+struct SNES $7E2100
+{
+    .ScreenDisplay:             skip $01 ; $2100
+    .OAMSizeAndDataDes:         skip $01 ; $2101
+    .OAMAccessAddr:             skip $02 ; $2102
+    .OMADataWrite:              skip $01 ; $2104
+    .BGModeAndTileSize:         skip $01 ; $2105
+    .MosaicAndBGEnable:         skip $01 ; $2106
+
+    .BG1AddrAndSize:            skip $01 ; $2107
+    .BG2AddrAndSize:            skip $01 ; $2108
+    .BG3AddrAndSize:            skip $01 ; $2109
+    .BG4AddrAndSize:            skip $01 ; $210A
+
+    .BG1And2TileDataDes:        skip $01 ; $210B
+    .BG3And4TileDataDes:        skip $01 ; $210C
+
+    .BG1HScrollOffset:          skip $01 ; $210D
+    .BG1VScrollOffset:          skip $01 ; $210E
+    .BG2HScrollOffset:          skip $01 ; $210F
+    .BG2VScrollOffset:          skip $01 ; $2110
+    .BG3HScrollOffset:          skip $01 ; $2111
+    .BG3VScrollOffset:          skip $01 ; $2112
+    .BG4HScrollOffset:          skip $01 ; $2113
+    .BG4VScrollOffset:          skip $01 ; $2114
+
+    .VRAMAddrIncrementVal:      skip $01 ; $2115
+    .VRAMAddrReadWriteLow:      skip $01 ; $2116
+    .VRAMAddrReadWriteHigh:     skip $01 ; $2117
+    .VRAMDataWriteLow:          skip $01 ; $2118
+    .VRAMDataWriteHigh:         skip $01 ; $2119
+
+    .Mode7Init                  skip $01 ; $211A
+    .Mode7MatrixA               skip $01 ; $211B
+    .Mode7MatrixB               skip $01 ; $211C
+    .Mode7MatrixC               skip $01 ; $211D
+    .Mode7MatrixD               skip $01 ; $211E
+    .Mode7CenterPosX            skip $01 ; $211F
+    .Mode7CenterPosY            skip $01 ; $2120
+
+    .CGRAMWriteAddr             skip $01 ; $2121
+    .CGRAMWriteData             skip $01 ; $2122
+
+    .BG1And2WindowMask          skip $01 ; $2123
+    .BG3And4WindowMask          skip $01 ; $2124
+    .OBJAndColorWindow          skip $01 ; $2125
+
+    .Window1LeftPosDes          skip $01 ; $2126
+    .Window1RightPosDes         skip $01 ; $2127
+    .Window2LeftPosDes          skip $01 ; $2128
+    .Window2RightPosDes         skip $01 ; $2129
+
+    .BG123And4WindowLogic       skip $01 ; $212A
+    .ColorAndOBJWindowLogic     skip $01 ; $212B
+    .BGAndOBJEnableMainScreen   skip $01 ; $212C
+    .BGAndOBJEnableSubScreen    skip $01 ; $212D
+    .WindowMaskDesMainScreen    skip $01 ; $212E
+    .WindowMaskDesSubScreen     skip $01 ; $212F
+    .InitColorAddition          skip $01 ; $2130
+    .AddSubtractSelectAndEnable skip $01 ; $2131
+    .FixedColorData             skip $01 ; $2132
+    .ScreenInit                 skip $01 ; $2133
+
+    .MultResultLow              skip $01 ; $2134
+    .MultResultMid              skip $01 ; $2135
+    .MultResultHigh             skip $01 ; $2136
+
+    .HVCounterSoftwareLatch     skip $01 ; $2137
+
+    .OAMReadDataLowHigh         skip $01 ; $2138
+    .VRAMReadDataLow            skip $01 ; $2139
+    .VRAMReadDataHigh           skip $01 ; $213A
+    .CGRAMReadDataLowHigh       skip $01 ; $213B
+
+    .HCounterData               skip $01 ; $213C
+    .VCounterData               skip $01 ; $213D
+
+    .PPUStatusFlag1             skip $01 ; $213E
+    .PPUStatusFlag2             skip $01 ; $213F
+
+    .APUIOPort0                 skip $01 ; $2140
+    .APUIOPort1                 skip $01 ; $2141
+    .APUIOPort2                 skip $01 ; $2142
+    .APUIOPort3                 skip $01 ; $2143
+
+    base $2180
+    .IndirectWorkRAMPort:       skip $01 ; $2180
+    .IndirectWorkRAMAddrLow:    skip $01 ; $2181
+    .IndirectWorkRAMAddrMid:    skip $01 ; $2182
+    .IndirectWorkRAMAddrHigh:   skip $01 ; $2183
+
+    base $4200
+    .NMIVHCountJoypadEnable:    skip $01 ; $4200
+    .ProgrammableIOPortOut:     skip $01 ; $4201
+    .MultiplicandA:             skip $01 ; $4202
+    .MultiplierB:               skip $01 ; $4203
+    .DividendLow:               skip $01 ; $4204
+    .DividendHigh:              skip $01 ; $4205
+    .DivisorB:                  skip $01 ; $4206
+    .HCountTimer:               skip $01 ; $4207
+    .HCountTimerHigh:           skip $01 ; $4208
+    .VCountTImer:               skip $01 ; $4209
+    .VCountTimerHigh:           skip $01 ; $420A
+
+    .DMAChannelEnable:          skip $01 ; $420B
+    .HDMAChannelEnable:         skip $01 ; $420C
+    .CycleSpeedDes:             skip $01 ; $420D
+
+    base $4210
+    .NMIFlagAndCPUVersionNum:   skip $01 ; $4210
+    .IRQFlagByHVCountTimer:     skip $01 ; $4211
+    .HVBlankFlagsAndJoyStatus:  skip $01 ; $4212
+    .ProgrammableIOPortIn:      skip $01 ; $4213
+    .DivideResultQuotientLow:   skip $01 ; $4214
+    .DivideResultQuotientHigh:  skip $01 ; $4215
+    .RemainderResultLow:        skip $01 ; $4216
+    .RemainderResultHigh:       skip $01 ; $4217
+
+    .JoyPad1DataLow:            skip $01 ; $4218
+    .JoyPad1DataHigh:           skip $01 ; $4219
+    .JoyPad2DataLow:            skip $01 ; $421A
+    .JoyPad2DataHigh:           skip $01 ; $421B
+    .JoyPad3DataLow:            skip $01 ; $421C
+    .JoyPad3DataHigh:           skip $01 ; $421D
+    .JoyPad4DataLow:            skip $01 ; $421E
+    .JoyPad4DataHigh:           skip $01 ; $421F
+}
+endstruct
+
+struct DMA $7E4300
+{
+    ; Channel 0
+    .0_TransferParameters:   skip $01 ; $4300
+    .0_DestinationAddr:      skip $01 ; $4301
+    .0_SourceAddrOffsetLow:  skip $01 ; $4302
+    .0_SourceAddrOffsetHigh: skip $01 ; $4303
+    .0_SourceAddrBank:       skip $01 ; $4304
+    .0_TransferSizeLow:      skip $01 ; $4305
+    .0_TransferSizeHigh:     skip $01 ; $4306
+    .0_DataBank:             skip $01 ; $4307
+    .0_TableAddrLow:         skip $01 ; $4308
+    .0_TableAddrHigh:        skip $01 ; $4309
+    .0_TransferLineNum:      skip $01 ; $430A
+
+    base $4310 ; Channel 1
+    .1_TransferParameters:   skip $01 ; $4310
+    .1_DestinationAddr:      skip $01 ; $4311
+    .1_SourceAddrOffsetLow:  skip $01 ; $4312
+    .1_SourceAddrOffsetHigh: skip $01 ; $4313
+    .1_SourceAddrBank:       skip $01 ; $4314
+    .1_TransferSizeLow:      skip $01 ; $4315
+    .1_TransferSizeHigh:     skip $01 ; $4316
+    .1_DataBank:             skip $01 ; $4317
+    .1_TableAddrLow:         skip $01 ; $4318
+    .1_TableAddrHigh:        skip $01 ; $4319
+    .1_TransferLineNum:      skip $01 ; $431A
+
+    base $4320 ; Channel 2
+    .2_TransferParameters:   skip $01 ; $4320
+    .2_DestinationAddr:      skip $01 ; $4321
+    .2_SourceAddrOffsetLow:  skip $01 ; $4322
+    .2_SourceAddrOffsetHigh: skip $01 ; $4323
+    .2_SourceAddrBank:       skip $01 ; $4324
+    .2_TransferSizeLow:      skip $01 ; $4325
+    .2_TransferSizeHigh:     skip $01 ; $4326
+    .2_DataBank:             skip $01 ; $4327
+    .2_TableAddrLow:         skip $01 ; $4328
+    .2_TableAddrHigh:        skip $01 ; $4329
+    .2_TransferLineNum:      skip $01 ; $432A
+
+    base $4330 ; Channel 3
+    .3_TransferParameters:   skip $01 ; $4330
+    .3_DestinationAddr:      skip $01 ; $4331
+    .3_SourceAddrOffsetLow:  skip $01 ; $4332
+    .3_SourceAddrOffsetHigh: skip $01 ; $4333
+    .3_SourceAddrBank:       skip $01 ; $4334
+    .3_TransferSizeLow:      skip $01 ; $4335
+    .3_TransferSizeHigh:     skip $01 ; $4336
+    .3_DataBank:             skip $01 ; $4337
+    .3_TableAddrLow:         skip $01 ; $4338
+    .3_TableAddrHigh:        skip $01 ; $4339
+    .3_TransferLineNum:      skip $01 ; $433A
+
+    base $4340 ; Channel 4
+    .4_TransferParameters:   skip $01 ; $4340
+    .4_DestinationAddr:      skip $01 ; $4341
+    .4_SourceAddrOffsetLow:  skip $01 ; $4342
+    .4_SourceAddrOffsetHigh: skip $01 ; $4343
+    .4_SourceAddrBank:       skip $01 ; $4344
+    .4_TransferSizeLow:      skip $01 ; $4345
+    .4_TransferSizeHigh:     skip $01 ; $4346
+    .4_DataBank:             skip $01 ; $4347
+    .4_TableAddrLow:         skip $01 ; $4348
+    .4_TableAddrHigh:        skip $01 ; $4349
+    .4_TransferLineNum:      skip $01 ; $434A
+
+    base $4350 ; Channel 5
+    .5_TransferParameters:   skip $01 ; $4350
+    .5_DestinationAddr:      skip $01 ; $4351
+    .5_SourceAddrOffsetLow:  skip $01 ; $4352
+    .5_SourceAddrOffsetHigh: skip $01 ; $4353
+    .5_SourceAddrBank:       skip $01 ; $4354
+    .5_TransferSizeLow:      skip $01 ; $4355
+    .5_TransferSizeHigh:     skip $01 ; $4356
+    .5_DataBank:             skip $01 ; $4357
+    .5_TableAddrLow:         skip $01 ; $4358
+    .5_TableAddrHigh:        skip $01 ; $4359
+    .5_TransferLineNum:      skip $01 ; $435A
+
+    base $4360 ; Channel 6
+    .6_TransferParameters:   skip $01 ; $4360
+    .6_DestinationAddr:      skip $01 ; $4361
+    .6_SourceAddrOffsetLow:  skip $01 ; $4362
+    .6_SourceAddrOffsetHigh: skip $01 ; $4363
+    .6_SourceAddrBank:       skip $01 ; $4364
+    .6_TransferSizeLow:      skip $01 ; $4365
+    .6_TransferSizeHigh:     skip $01 ; $4366
+    .6_DataBank:             skip $01 ; $4367
+    .6_TableAddrLow:         skip $01 ; $4368
+    .6_TableAddrHigh:        skip $01 ; $4369
+    .6_TransferLineNum:      skip $01 ; $436A
+
+    base $4370 ; Channel 7
+    .7_TransferParameters:   skip $01 ; $4370
+    .7_DestinationAddr:      skip $01 ; $4371
+    .7_SourceAddrOffsetLow:  skip $01 ; $4372
+    .7_SourceAddrOffsetHigh: skip $01 ; $4373
+    .7_SourceAddrBank:       skip $01 ; $4374
+    .7_TransferSizeLow:      skip $01 ; $4375
+    .7_TransferSizeHigh:     skip $01 ; $4376
+    .7_DataBank:             skip $01 ; $4377
+    .7_TableAddrLow:         skip $01 ; $4378
+    .7_TableAddrHigh:        skip $01 ; $4379
+    .7_TransferLineNum:      skip $01 ; $437A
+}
+endstruct
+
+; ==============================================================================

assets/asm/yaze.asm

@@ -5,7 +5,7 @@
 namespace yaze
 {
 
-!YAZE_CUSTOM_MOSAIC = 1
+!YAZE_CUSTOM_MOSAIC = 0
 
 
 if !YAZE_CUSTOM_MOSAIC != 0

assets/themes/yaze_tre.theme

@@ -1,4 +1,4 @@
-# YAZE Tre Theme - Enhanced Edition
+# yaze Tre Theme - Enhanced Edition
 # Premium theme resource edition with improved colors and contrast
 name=YAZE Tre
 description=Enhanced YAZE theme with improved readability and modern colors

assets/zelda3.yaze

@@ -0,0 +1,65 @@
+# Default Zelda3 Project File
+# All resource names are embedded and always available to AI agents
+# This project uses embedded labels - no external labels file required
+
+[project]
+name = The Legend of Zelda: A Link to the Past
+description = Default Zelda3 project with all embedded resource labels
+author = Nintendo
+version = 1.0.0
+created_date = 2025-10-04
+last_modified = 2025-10-04
+yaze_version = 0.1.0
+tags = zelda3, reference, default
+
+[files]
+rom_filename = zelda3.sfc
+code_folder = 
+assets_folder = assets
+patches_folder = patches
+labels_filename = 
+symbols_filename = 
+output_folder = build
+rom_backup_folder = backups
+
+[feature_flags]
+log_instructions = false
+save_dungeon_maps = false
+save_graphics_sheet = false
+load_custom_overworld = false
+apply_zs_custom_overworld_asm = false
+
+[workspace]
+font_global_scale = 1.0
+dark_mode = true
+ui_theme = default
+autosave_enabled = true
+autosave_interval_secs = 300
+backup_on_save = true
+show_grid = true
+show_collision = false
+last_layout_preset = default
+
+[build]
+build_script = 
+output_folder = build
+git_repository = 
+track_changes = true
+build_configurations = debug, release
+
+# Embedded Labels Information
+# This project includes the following embedded resource names:
+# - 296 room names (dungeons, bosses, treasure rooms)
+# - 133 entrance names (dungeons, caves, houses, shops)
+# - 256 sprite names (enemies, NPCs, bosses, items)
+# - 26 overlord names (factories, traps, special objects)
+# - 160 overworld map names (Light World, Dark World, Special Areas)
+# - 100 item names (swords, shields, medallions, bottles)
+# - 48 music track names
+# - 32 graphics sheet names
+# - 8 room effect names
+# - 13 room tag names
+# - 60 tile type names (collision, slopes, water, ice, stairs)
+#
+# Use InitializeEmbeddedLabels() to load all default labels
+# Custom labels can be added in [labels_<type>] sections

cmake-format.yaml

@@ -0,0 +1,12 @@
+# CMake format configuration
+line_width: 80
+tab_size: 2
+max_subargs_per_line: 3
+separate_ctrl_name_with_space: true
+separate_fn_name_with_space: true
+dangle_parens: true
+command_case: lower
+keyword_case: upper
+enable_sort: true
+autosort: true
+

cmake/CPM.cmake

@@ -0,0 +1,49 @@
+# CPM.cmake - C++ Package Manager
+# https://github.com/cpm-cmake/CPM.cmake
+
+set(CPM_DOWNLOAD_VERSION 0.38.7)
+
+if(CPM_SOURCE_CACHE)
+  set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+elseif(DEFINED ENV{CPM_SOURCE_CACHE})
+  set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+else()
+  set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+endif()
+
+# Expand relative path. This is important if the provided path contains a tilde (~)
+get_filename_component(CPM_DOWNLOAD_LOCATION ${CPM_DOWNLOAD_LOCATION} ABSOLUTE)
+
+function(download_cpm)
+  message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
+  file(DOWNLOAD
+       https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
+       ${CPM_DOWNLOAD_LOCATION}
+  )
+endfunction()
+
+if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
+  download_cpm()
+else()
+  # resume download if it previously failed
+  file(READ ${CPM_DOWNLOAD_LOCATION} check)
+  if("${check}" STREQUAL "")
+    download_cpm()
+  endif()
+endif()
+
+include(${CPM_DOWNLOAD_LOCATION})
+
+# Set CPM options for better caching and performance
+set(CPM_USE_LOCAL_PACKAGES ON)
+set(CPM_LOCAL_PACKAGES_ONLY OFF)
+set(CPM_DONT_CREATE_PACKAGE_LOCK ON)
+set(CPM_DONT_UPDATE_MODULE_PATH ON)
+set(CPM_DONT_PREPEND_TO_MODULE_PATH ON)
+
+# Set cache directory for CI builds
+if(DEFINED ENV{GITHUB_ACTIONS})
+  set(CPM_SOURCE_CACHE "$ENV{HOME}/.cpm-cache")
+  message(STATUS "CPM cache directory: ${CPM_SOURCE_CACHE}")
+endif()
+

cmake/absl.cmake

@@ -1,32 +1,78 @@
-if (MINGW OR WIN32)
-  add_subdirectory(src/lib/abseil-cpp)
-elseif(YAZE_MINIMAL_BUILD)
-  # For CI builds, always use submodule to avoid dependency issues
-  add_subdirectory(src/lib/abseil-cpp)
-else()
-  # Try system package first, fallback to submodule
-  find_package(absl QUIET)
-  if(NOT absl_FOUND)
-    message(STATUS "System Abseil not found, using submodule")
-    add_subdirectory(src/lib/abseil-cpp)
+# Abseil release to use when fetching from source
+set(YAZE_ABSL_GIT_TAG "20240116.2" CACHE STRING "Abseil release tag used when fetching from source")
+
+# Attempt to use the system package unless the build explicitly requests the
+# bundled (fetched) copy or we're on platforms where prebuilt packages are often
+# missing the required components (e.g. macOS).
+set(_yaze_use_fetched_absl ${YAZE_FORCE_BUNDLED_ABSL})
+if(NOT _yaze_use_fetched_absl)
+  # Try to find via vcpkg first on Windows
+  if(WIN32 AND DEFINED CMAKE_TOOLCHAIN_FILE)
+    find_package(absl CONFIG QUIET)
+  else()
+    find_package(absl QUIET CONFIG)
+  endif()
+  
+  if(absl_FOUND)
+    message(STATUS "✓ Using system/vcpkg Abseil package")
+  else()
+    set(_yaze_use_fetched_absl TRUE)
+    message(STATUS "○ System Abseil not found. Will fetch release ${YAZE_ABSL_GIT_TAG}")
   endif()
 endif()
-set(ABSL_PROPAGATE_CXX_STD ON)
-set(ABSL_CXX_STANDARD 23)
-set(ABSL_USE_GOOGLETEST_HEAD ON)
-set(ABSL_ENABLE_INSTALL ON)
 
-# Silence C++23 deprecation warnings for Abseil int128
-if(MSVC)
-    add_definitions(-DSILENCE_CXX23_DEPRECATIONS)
-else()
-    add_definitions(-D_SILENCE_CXX23_DEPRECATION_WARNING)
+if(_yaze_use_fetched_absl)
+  include(FetchContent)
+  FetchContent_GetProperties(absl)
+  if(NOT absl_POPULATED)
+    FetchContent_Declare(
+      absl
+      GIT_REPOSITORY https://github.com/abseil/abseil-cpp.git
+      GIT_TAG        ${YAZE_ABSL_GIT_TAG}
+      GIT_SHALLOW    TRUE
+      GIT_PROGRESS   TRUE
+      USES_TERMINAL_DOWNLOAD TRUE
+    )
+    set(ABSL_PROPAGATE_CXX_STD ON CACHE BOOL "" FORCE)
+    set(ABSL_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+    set(ABSL_ENABLE_INSTALL OFF CACHE BOOL "" FORCE)
+    FetchContent_MakeAvailable(absl)
+    message(STATUS "Fetched Abseil ${YAZE_ABSL_GIT_TAG}")
+
+    # NEW: Export source directory for Windows builds that need explicit include paths
+    set(YAZE_ABSL_SOURCE_DIR "${absl_SOURCE_DIR}" CACHE INTERNAL "Abseil source directory")
+  endif()
 endif()
-# Define base Abseil targets
+
+if(NOT TARGET absl::strings)
+  message(FATAL_ERROR "Abseil was not found or failed to configure correctly.")
+else()
+  message(STATUS "✓ Abseil configured successfully (standalone)")
+  # Verify critical targets exist
+  foreach(_check_target IN ITEMS absl::status absl::statusor absl::str_format absl::flags)
+    if(NOT TARGET ${_check_target})
+      message(WARNING "Expected Abseil target ${_check_target} not found")
+    endif()
+  endforeach()
+endif()
+
+# Canonical list of Abseil targets that the rest of the project links against.
+# Note: Order matters for some linkers - put base libraries first
 set(
   ABSL_TARGETS
+  absl::base
+  absl::config
+  absl::core_headers
+  absl::utility
+  absl::memory
+  absl::container_memory
   absl::strings
   absl::str_format
+  absl::cord
+  absl::hash
+  absl::time
+  absl::status
+  absl::statusor
   absl::flags
   absl::flags_parse
   absl::flags_usage
@@ -36,29 +82,54 @@ set(
   absl::flags_program_name
   absl::flags_config
   absl::flags_reflection
-  absl::status
-  absl::statusor
   absl::examine_stack
   absl::stacktrace
-  absl::base
-  absl::config
-  absl::core_headers
   absl::failure_signal_handler
   absl::flat_hash_map
-  absl::cord
-  absl::hash
   absl::synchronization
-  absl::time
   absl::symbolize
-  absl::container_memory
-  absl::memory
-  absl::utility
 )
 
-# Add int128 only on non-Windows platforms to avoid C++23 deprecation issues
+# Only expose absl::int128 when it's supported without warnings.
 if(NOT WIN32)
   list(APPEND ABSL_TARGETS absl::int128)
-  message(STATUS "Including absl::int128 (non-Windows platform)")
+  message(STATUS "Including absl::int128 target")
 else()
-  message(STATUS "Excluding absl::int128 on Windows to avoid C++23 deprecation issues")
+  message(STATUS "Skipping absl::int128 target on Windows")
+endif()
+
+# ABSL_TARGETS is now available to the rest of the project via include()
+
+if(APPLE AND DEFINED CMAKE_OSX_ARCHITECTURES AND CMAKE_OSX_ARCHITECTURES STREQUAL "arm64")
+  foreach(_absl_target IN ITEMS absl_random_internal_randen_hwaes absl_random_internal_randen_hwaes_impl)
+    if(TARGET ${_absl_target})
+      get_target_property(_absl_opts ${_absl_target} COMPILE_OPTIONS)
+  if(_absl_opts AND NOT _absl_opts STREQUAL "NOTFOUND")
+        set(_absl_filtered_opts)
+        set(_absl_skip_next FALSE)
+        foreach(_absl_opt IN LISTS _absl_opts)
+          if(_absl_skip_next)
+            set(_absl_skip_next FALSE)
+            continue()
+          endif()
+          if(_absl_opt STREQUAL "-Xarch_x86_64")
+            set(_absl_skip_next TRUE)
+            continue()
+          endif()
+          if(_absl_opt STREQUAL "-maes" OR _absl_opt STREQUAL "-msse4.1")
+            continue()
+          endif()
+          list(APPEND _absl_filtered_opts ${_absl_opt})
+        endforeach()
+        set_property(TARGET ${_absl_target} PROPERTY COMPILE_OPTIONS ${_absl_filtered_opts})
+      endif()
+    endif()
+  endforeach()
+endif()
+
+# Silence C++23 deprecation warnings for Abseil int128
+if(MSVC)
+    add_definitions(-DSILENCE_CXX23_DEPRECATIONS)
+else()
+    add_definitions(-D_SILENCE_CXX23_DEPRECATION_WARNING)
 endif()

cmake/asar.cmake

@@ -8,8 +8,13 @@ set(ASAR_GEN_LIB ON CACHE BOOL "Build Asar static library")
 set(ASAR_GEN_EXE_TEST OFF CACHE BOOL "Build Asar executable tests")
 set(ASAR_GEN_DLL_TEST OFF CACHE BOOL "Build Asar DLL tests")
 
+# Force Asar to use static MSVC runtime to match vcpkg static triplets
+if(MSVC)
+    set(MSVC_LIB_TYPE T CACHE STRING "Asar MSVC runtime type" FORCE)
+endif()
+
 # Set Asar source directory
-set(ASAR_SRC_DIR "${CMAKE_SOURCE_DIR}/src/lib/asar/src")
+set(ASAR_SRC_DIR "${CMAKE_SOURCE_DIR}/ext/asar/src")
 
 # Add Asar as subdirectory
 add_subdirectory(${ASAR_SRC_DIR} EXCLUDE_FROM_ALL)

cmake/dependencies.cmake

@@ -0,0 +1,102 @@
+# YAZE Dependencies Management
+# Centralized dependency management using CPM.cmake
+
+# Include CPM and options
+include(cmake/CPM.cmake)
+include(cmake/options.cmake)
+include(cmake/dependencies.lock)
+
+message(STATUS "=== Setting up YAZE dependencies with CPM.cmake ===")
+
+# Clear any previous dependency targets
+set(YAZE_ALL_DEPENDENCIES "")
+set(YAZE_SDL2_TARGETS "")
+set(YAZE_YAML_TARGETS "")
+set(YAZE_IMGUI_TARGETS "")
+set(YAZE_JSON_TARGETS "")
+set(YAZE_GRPC_TARGETS "")
+set(YAZE_FTXUI_TARGETS "")
+set(YAZE_TESTING_TARGETS "")
+
+# Core dependencies (always required)
+# SDL selection: SDL2 (default) or SDL3 (experimental)
+if(YAZE_USE_SDL3)
+  include(cmake/dependencies/sdl3.cmake)
+  # Debug: message(STATUS "After SDL3 setup, YAZE_SDL3_TARGETS = '${YAZE_SDL3_TARGETS}'")
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_SDL3_TARGETS})
+else()
+  include(cmake/dependencies/sdl2.cmake)
+  # Debug: message(STATUS "After SDL2 setup, YAZE_SDL2_TARGETS = '${YAZE_SDL2_TARGETS}'")
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_SDL2_TARGETS})
+endif()
+
+include(cmake/dependencies/yaml.cmake)
+list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_YAML_TARGETS})
+
+include(cmake/dependencies/imgui.cmake)
+# Debug: message(STATUS "After ImGui setup, YAZE_IMGUI_TARGETS = '${YAZE_IMGUI_TARGETS}'")
+list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_IMGUI_TARGETS})
+
+# Abseil is required for failure_signal_handler, status, and other utilities
+# Only include standalone Abseil when gRPC is disabled - when gRPC is enabled,
+# it provides its own bundled Abseil via CPM
+if(NOT YAZE_ENABLE_GRPC)
+  include(cmake/absl.cmake)
+endif()
+
+# Optional dependencies based on feature flags
+if(YAZE_ENABLE_JSON)
+  include(cmake/dependencies/json.cmake)
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_JSON_TARGETS})
+endif()
+
+# CRITICAL: Load testing dependencies BEFORE gRPC when both are enabled
+# This ensures gmock is available before Abseil (bundled with gRPC) tries to export test_allocator
+# which depends on gmock. This prevents CMake export errors.
+if(YAZE_BUILD_TESTS AND YAZE_ENABLE_GRPC)
+  include(cmake/dependencies/testing.cmake)
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_TESTING_TARGETS})
+endif()
+
+if(YAZE_ENABLE_GRPC)
+  include(cmake/dependencies/grpc.cmake)
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_GRPC_TARGETS})
+endif()
+
+if(YAZE_BUILD_CLI)
+  include(cmake/dependencies/ftxui.cmake)
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_FTXUI_TARGETS})
+endif()
+
+# Load testing dependencies after gRPC if tests are enabled but gRPC is not
+if(YAZE_BUILD_TESTS AND NOT YAZE_ENABLE_GRPC)
+  include(cmake/dependencies/testing.cmake)
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_TESTING_TARGETS})
+endif()
+
+# ASAR dependency (for ROM assembly) - temporarily disabled
+# TODO: Add CMakeLists.txt to bundled ASAR or find working repository
+message(STATUS "ASAR dependency temporarily disabled - will be added later")
+
+# Print dependency summary
+message(STATUS "=== YAZE Dependencies Summary ===")
+message(STATUS "Total dependencies: ${YAZE_ALL_DEPENDENCIES}")
+message(STATUS "SDL2: ${YAZE_SDL2_TARGETS}")
+message(STATUS "YAML: ${YAZE_YAML_TARGETS}")
+message(STATUS "ImGui: ${YAZE_IMGUI_TARGETS}")
+if(YAZE_ENABLE_JSON)
+  message(STATUS "JSON: ${YAZE_JSON_TARGETS}")
+endif()
+if(YAZE_ENABLE_GRPC)
+  message(STATUS "gRPC: ${YAZE_GRPC_TARGETS}")
+endif()
+if(YAZE_BUILD_CLI)
+  message(STATUS "FTXUI: ${YAZE_FTXUI_TARGETS}")
+endif()
+if(YAZE_BUILD_TESTS)
+  message(STATUS "Testing: ${YAZE_TESTING_TARGETS}")
+endif()
+message(STATUS "=================================")
+
+# Export all dependency targets for use in other CMake files
+set(YAZE_ALL_DEPENDENCIES ${YAZE_ALL_DEPENDENCIES})

cmake/dependencies.lock

@@ -0,0 +1,29 @@
+# CPM Dependencies Lock File
+# This file pins exact versions to ensure reproducible builds
+# Update versions here when upgrading dependencies
+
+# Core dependencies
+set(SDL2_VERSION "2.30.0" CACHE STRING "SDL2 version")
+set(YAML_CPP_VERSION "0.8.0" CACHE STRING "yaml-cpp version")
+
+# gRPC and related
+# Using v1.67.1 for MSVC compatibility (v1.75.1 has UPB compilation errors on Windows)
+set(GRPC_VERSION "1.67.1" CACHE STRING "gRPC version - MSVC compatible")
+set(PROTOBUF_VERSION "3.25.1" CACHE STRING "Protobuf version")
+set(ABSEIL_VERSION "20240116.0" CACHE STRING "Abseil version")
+# Cache revision: increment to force CPM cache invalidation (current: 2)
+
+# Testing
+set(GTEST_VERSION "1.14.0" CACHE STRING "Google Test version")
+set(BENCHMARK_VERSION "1.8.3" CACHE STRING "Google Benchmark version")
+
+# CLI tools
+set(FTXUI_VERSION "5.0.0" CACHE STRING "FTXUI version")
+
+# ImGui
+set(IMGUI_VERSION "1.90.4" CACHE STRING "Dear ImGui version")
+# Cache revision: increment to force rebuild (current: 2)
+
+# ASAR
+set(ASAR_VERSION "main" CACHE STRING "ASAR version")
+

cmake/dependencies/ftxui.cmake

@@ -0,0 +1,55 @@
+# FTXUI dependency management for CLI tools
+# Uses CPM.cmake for consistent cross-platform builds
+
+if(NOT YAZE_BUILD_CLI)
+  return()
+endif()
+
+include(cmake/CPM.cmake)
+include(cmake/dependencies.lock)
+
+message(STATUS "Setting up FTXUI ${FTXUI_VERSION} with CPM.cmake")
+
+# Use CPM to fetch FTXUI
+CPMAddPackage(
+  NAME ftxui
+  VERSION ${FTXUI_VERSION}
+  GITHUB_REPOSITORY ArthurSonzogni/ftxui
+  GIT_TAG v${FTXUI_VERSION}
+  OPTIONS
+    "FTXUI_BUILD_EXAMPLES OFF"
+    "FTXUI_BUILD_TESTS OFF"
+    "FTXUI_ENABLE_INSTALL OFF"
+)
+
+# FTXUI targets are created during the build phase
+# We'll create our own interface target and link when available
+add_library(yaze_ftxui INTERFACE)
+
+# Link to the actual FTXUI targets
+if(TARGET ftxui::screen AND TARGET ftxui::dom AND TARGET ftxui::component)
+  target_link_libraries(yaze_ftxui INTERFACE
+    ftxui::screen
+    ftxui::dom
+    ftxui::component
+  )
+else()
+  # Fallback for when targets aren't namespaced
+  target_link_libraries(yaze_ftxui INTERFACE
+    screen
+    dom
+    component
+  )
+endif()
+
+# Add include path with compile options for Ninja Multi-Config compatibility
+# The -isystem-after flag doesn't work properly with some generator/compiler combinations
+if(ftxui_SOURCE_DIR)
+  add_compile_options(-I${ftxui_SOURCE_DIR}/include)
+  message(STATUS "  Added FTXUI include: ${ftxui_SOURCE_DIR}/include")
+endif()
+
+# Export FTXUI targets for use in other CMake files
+set(YAZE_FTXUI_TARGETS yaze_ftxui)
+
+message(STATUS "FTXUI setup complete")

cmake/dependencies/grpc.cmake

@@ -0,0 +1,581 @@
+# gRPC and Protobuf dependency management
+# Uses CPM.cmake for consistent cross-platform builds, with optional system package fallback
+
+if(NOT YAZE_ENABLE_GRPC)
+  return()
+endif()
+
+# Include CPM and dependencies lock
+include(cmake/CPM.cmake)
+include(cmake/dependencies.lock)
+
+message(STATUS "Setting up gRPC ${GRPC_VERSION}")
+
+#-----------------------------------------------------------------------
+# Option: YAZE_PREFER_SYSTEM_GRPC - Use system-installed gRPC/protobuf/abseil
+# when available (e.g., from Homebrew, apt, vcpkg).
+#
+# Benefits: Much faster configure/build times for local development
+# Trade-off: May have version mismatches between system packages
+#
+# Example: cmake --preset mac-ai-fast (uses system packages)
+#-----------------------------------------------------------------------
+option(YAZE_PREFER_SYSTEM_GRPC "Prefer system-installed gRPC/protobuf over CPM" OFF)
+
+if(YAZE_PREFER_SYSTEM_GRPC OR YAZE_USE_SYSTEM_DEPS)
+  message(STATUS "Attempting to use system gRPC/protobuf packages...")
+
+  # Try CMake's find_package first (works with Homebrew on macOS)
+  find_package(gRPC CONFIG QUIET)
+  find_package(Protobuf CONFIG QUIET)
+  find_package(absl CONFIG QUIET)
+
+  if(gRPC_FOUND AND Protobuf_FOUND AND absl_FOUND)
+    message(STATUS "✓ Found system gRPC: ${gRPC_VERSION}")
+    message(STATUS "✓ Found system Protobuf: ${Protobuf_VERSION}")
+    message(STATUS "✓ Found system Abseil")
+
+    # Find protoc and grpc_cpp_plugin executables
+    find_program(PROTOC_EXECUTABLE protoc)
+    find_program(GRPC_CPP_PLUGIN grpc_cpp_plugin)
+
+    if(PROTOC_EXECUTABLE AND GRPC_CPP_PLUGIN)
+      message(STATUS "✓ Found protoc: ${PROTOC_EXECUTABLE}")
+      message(STATUS "✓ Found grpc_cpp_plugin: ${GRPC_CPP_PLUGIN}")
+
+      # Create imported targets for the executables if they don't exist
+      if(NOT TARGET protoc)
+        add_executable(protoc IMPORTED)
+        set_target_properties(protoc PROPERTIES IMPORTED_LOCATION "${PROTOC_EXECUTABLE}")
+      endif()
+
+      if(NOT TARGET grpc_cpp_plugin)
+        add_executable(grpc_cpp_plugin IMPORTED)
+        set_target_properties(grpc_cpp_plugin PROPERTIES IMPORTED_LOCATION "${GRPC_CPP_PLUGIN}")
+      endif()
+
+      # Create convenience interface for basic gRPC linking
+      add_library(yaze_grpc_deps INTERFACE)
+      target_link_libraries(yaze_grpc_deps INTERFACE
+        gRPC::grpc++
+        gRPC::grpc++_reflection
+        protobuf::libprotobuf
+      )
+
+      # Ensure Abseil include directories are available
+      # Homebrew's abseil may not properly export include dirs
+      get_target_property(_ABSL_BASE_INCLUDE absl::base INTERFACE_INCLUDE_DIRECTORIES)
+      if(_ABSL_BASE_INCLUDE)
+        target_include_directories(yaze_grpc_deps INTERFACE ${_ABSL_BASE_INCLUDE})
+        message(STATUS "  Added Abseil include: ${_ABSL_BASE_INCLUDE}")
+      elseif(APPLE)
+        # Fallback for Homebrew on macOS
+        target_include_directories(yaze_grpc_deps INTERFACE /opt/homebrew/include)
+        message(STATUS "  Added Homebrew Abseil include: /opt/homebrew/include")
+      endif()
+
+      # Create interface libraries for compatibility with CPM target names
+      # CPM gRPC creates lowercase 'grpc++' targets
+      # System gRPC (Homebrew) creates namespaced 'gRPC::grpc++' targets
+      # We create interface libs (not aliases) so we can add include directories
+      if(NOT TARGET grpc++)
+        add_library(grpc++ INTERFACE)
+        target_link_libraries(grpc++ INTERFACE gRPC::grpc++)
+        # Add abseil includes for targets linking to grpc++
+        if(_ABSL_BASE_INCLUDE)
+          target_include_directories(grpc++ INTERFACE ${_ABSL_BASE_INCLUDE})
+        elseif(APPLE)
+          target_include_directories(grpc++ INTERFACE /opt/homebrew/include)
+        endif()
+      endif()
+      if(NOT TARGET grpc++_reflection)
+        add_library(grpc++_reflection INTERFACE)
+        target_link_libraries(grpc++_reflection INTERFACE gRPC::grpc++_reflection)
+      endif()
+      if(NOT TARGET grpc::grpc++)
+        add_library(grpc::grpc++ ALIAS gRPC::grpc++)
+      endif()
+      if(NOT TARGET grpc::grpc++_reflection)
+        add_library(grpc::grpc++_reflection ALIAS gRPC::grpc++_reflection)
+      endif()
+
+      # Export targets
+      set(YAZE_GRPC_TARGETS
+        gRPC::grpc++
+        gRPC::grpc++_reflection
+        protobuf::libprotobuf
+      )
+
+      # Setup protobuf generation directory
+      set(_gRPC_PROTO_GENS_DIR ${CMAKE_BINARY_DIR}/gens CACHE INTERNAL "Protobuf generated files directory")
+      file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/gens)
+
+      # Get protobuf include directory from package
+      get_target_property(_PROTOBUF_INCLUDE_DIRS protobuf::libprotobuf INTERFACE_INCLUDE_DIRECTORIES)
+      if(_PROTOBUF_INCLUDE_DIRS)
+        list(GET _PROTOBUF_INCLUDE_DIRS 0 _gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR)
+        set(_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR} CACHE INTERNAL "Protobuf include directory")
+      endif()
+
+      # Add global include directories for system packages
+      # This ensures all targets can find abseil headers even if target propagation fails
+      # Use add_compile_options for reliable include path propagation with Ninja Multi-Config
+      if(_ABSL_BASE_INCLUDE)
+        add_compile_options(-I${_ABSL_BASE_INCLUDE})
+        message(STATUS "  Added Abseil include via compile options: ${_ABSL_BASE_INCLUDE}")
+      elseif(APPLE)
+        add_compile_options(-I/opt/homebrew/include)
+        message(STATUS "  Added Homebrew include via compile options: /opt/homebrew/include")
+      endif()
+
+      message(STATUS "✓ Using SYSTEM gRPC stack - fast configure!")
+      message(STATUS "  Protobuf gens dir: ${_gRPC_PROTO_GENS_DIR}")
+      message(STATUS "  Protobuf include dir: ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR}")
+      set(_YAZE_USING_SYSTEM_GRPC TRUE)
+    else()
+      message(STATUS "○ System gRPC found but protoc/grpc_cpp_plugin missing, falling back to CPM")
+      set(_YAZE_USING_SYSTEM_GRPC FALSE)
+    endif()
+  else()
+    message(STATUS "○ System gRPC/protobuf not found, falling back to CPM")
+    set(_YAZE_USING_SYSTEM_GRPC FALSE)
+  endif()
+endif()
+
+# If we're using system gRPC, skip CPM entirely and jump to function definition
+if(_YAZE_USING_SYSTEM_GRPC)
+  message(STATUS "Skipping CPM gRPC build - using system packages")
+else()
+  # CPM build path
+  message(STATUS "Building gRPC from source via CPM (this takes 15-20 minutes on first build)")
+  message(STATUS "  Tip: Install gRPC via Homebrew and use -DYAZE_PREFER_SYSTEM_GRPC=ON for faster builds")
+
+#-----------------------------------------------------------------------
+# Guard CMake's package lookup so CPM always downloads a consistent gRPC
+# toolchain instead of picking up partially-installed Homebrew/apt copies.
+#-----------------------------------------------------------------------
+if(DEFINED CPM_USE_LOCAL_PACKAGES)
+  set(_YAZE_GRPC_SAVED_CPM_USE_LOCAL_PACKAGES "${CPM_USE_LOCAL_PACKAGES}")
+else()
+  set(_YAZE_GRPC_SAVED_CPM_USE_LOCAL_PACKAGES "__YAZE_UNSET__")
+endif()
+set(CPM_USE_LOCAL_PACKAGES OFF)
+
+foreach(_yaze_pkg IN ITEMS gRPC Protobuf absl)
+  string(TOUPPER "CMAKE_DISABLE_FIND_PACKAGE_${_yaze_pkg}" _yaze_disable_var)
+  if(DEFINED ${_yaze_disable_var})
+    set("_YAZE_GRPC_SAVE_${_yaze_disable_var}" "${${_yaze_disable_var}}")
+  else()
+    set("_YAZE_GRPC_SAVE_${_yaze_disable_var}" "__YAZE_UNSET__")
+  endif()
+  set(${_yaze_disable_var} TRUE)
+endforeach()
+
+if(DEFINED PKG_CONFIG_USE_CMAKE_PREFIX_PATH)
+  set(_YAZE_GRPC_SAVED_PKG_CONFIG_USE_CMAKE_PREFIX_PATH "${PKG_CONFIG_USE_CMAKE_PREFIX_PATH}")
+else()
+  set(_YAZE_GRPC_SAVED_PKG_CONFIG_USE_CMAKE_PREFIX_PATH "__YAZE_UNSET__")
+endif()
+set(PKG_CONFIG_USE_CMAKE_PREFIX_PATH FALSE)
+
+set(_YAZE_GRPC_SAVED_PREFIX_PATH "${CMAKE_PREFIX_PATH}")
+set(CMAKE_PREFIX_PATH "")
+
+if(DEFINED CMAKE_CROSSCOMPILING)
+  set(_YAZE_GRPC_SAVED_CROSSCOMPILING "${CMAKE_CROSSCOMPILING}")
+else()
+  set(_YAZE_GRPC_SAVED_CROSSCOMPILING "__YAZE_UNSET__")
+endif()
+if(CMAKE_HOST_SYSTEM_NAME STREQUAL CMAKE_SYSTEM_NAME
+   AND CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL CMAKE_SYSTEM_PROCESSOR)
+  set(CMAKE_CROSSCOMPILING FALSE)
+endif()
+
+if(DEFINED CMAKE_CXX_STANDARD)
+  set(_YAZE_GRPC_SAVED_CXX_STANDARD "${CMAKE_CXX_STANDARD}")
+else()
+  set(_YAZE_GRPC_SAVED_CXX_STANDARD "__YAZE_UNSET__")
+endif()
+set(CMAKE_CXX_STANDARD 17)
+
+# Set gRPC options before adding package
+set(gRPC_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_CODEGEN ON CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_CPP_PLUGIN ON CACHE BOOL "" FORCE)
+set(gRPC_BUILD_CSHARP_EXT OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_CSHARP_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_NODE_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_OBJECTIVE_C_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_PHP_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_PYTHON_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_RUBY_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_REFLECTION OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_REFLECTION OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_CPP_REFLECTION OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPCPP_REFLECTION OFF CACHE BOOL "" FORCE)
+set(gRPC_BENCHMARK_PROVIDER "none" CACHE STRING "" FORCE)
+set(gRPC_ZLIB_PROVIDER "module" CACHE STRING "" FORCE)
+set(gRPC_PROTOBUF_PROVIDER "module" CACHE STRING "" FORCE)
+set(gRPC_ABSL_PROVIDER "module" CACHE STRING "" FORCE)
+set(protobuf_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(protobuf_BUILD_CONFORMANCE OFF CACHE BOOL "" FORCE)
+set(protobuf_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+set(protobuf_BUILD_PROTOC_BINARIES ON CACHE BOOL "" FORCE)
+set(protobuf_WITH_ZLIB ON CACHE BOOL "" FORCE)
+set(protobuf_INSTALL OFF CACHE BOOL "" FORCE)
+set(protobuf_MSVC_STATIC_RUNTIME OFF CACHE BOOL "" FORCE)
+set(ABSL_PROPAGATE_CXX_STD ON CACHE BOOL "" FORCE)
+set(ABSL_ENABLE_INSTALL OFF CACHE BOOL "" FORCE)
+set(ABSL_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+set(utf8_range_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(utf8_range_INSTALL OFF CACHE BOOL "" FORCE)
+set(utf8_range_ENABLE_INSTALL OFF CACHE BOOL "" FORCE)
+
+# Force consistent MSVC runtime library across all gRPC components (Windows only)
+# This ensures gRPC, protobuf, and Abseil all use the same CRT linking mode
+if(WIN32 AND MSVC)
+  # Use dynamic CRT (/MD for Release, /MDd for Debug) to avoid undefined math symbols
+  set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL" CACHE STRING "" FORCE)
+  # Also ensure protobuf doesn't try to use static runtime
+  set(protobuf_MSVC_STATIC_RUNTIME OFF CACHE BOOL "" FORCE)
+  message(STATUS "Forcing dynamic MSVC runtime for gRPC dependencies: ${CMAKE_MSVC_RUNTIME_LIBRARY}")
+endif()
+
+# Temporarily disable installation to prevent utf8_range export errors
+# This is a workaround for gRPC 1.67.1 where utf8_range tries to install targets
+# that depend on Abseil, but we have ABSL_ENABLE_INSTALL=OFF
+set(CMAKE_SKIP_INSTALL_RULES TRUE)
+
+# Use CPM to fetch gRPC with bundled dependencies
+# GIT_SUBMODULES "" disables submodule recursion since gRPC handles its own deps via CMake
+
+if(WIN32)
+  set(GRPC_VERSION_TO_USE "1.67.1")
+else()
+  set(GRPC_VERSION_TO_USE "1.76.0")
+endif()
+
+message(STATUS "Selected gRPC version ${GRPC_VERSION_TO_USE} for platform ${CMAKE_SYSTEM_NAME}")
+
+CPMAddPackage(
+  NAME grpc
+  VERSION ${GRPC_VERSION_TO_USE}
+  GITHUB_REPOSITORY grpc/grpc
+  GIT_TAG v${GRPC_VERSION_TO_USE}
+  GIT_SUBMODULES ""
+  GIT_SHALLOW TRUE
+)
+
+# Re-enable installation rules after gRPC is loaded
+set(CMAKE_SKIP_INSTALL_RULES FALSE)
+
+# Restore CPM lookup behaviour and toolchain detection environment early so
+# subsequent dependency configuration isn't polluted even if we hit errors.
+if("${_YAZE_GRPC_SAVED_CPM_USE_LOCAL_PACKAGES}" STREQUAL "__YAZE_UNSET__")
+  unset(CPM_USE_LOCAL_PACKAGES)
+else()
+  set(CPM_USE_LOCAL_PACKAGES "${_YAZE_GRPC_SAVED_CPM_USE_LOCAL_PACKAGES}")
+endif()
+
+foreach(_yaze_pkg IN ITEMS gRPC Protobuf absl)
+  string(TOUPPER "CMAKE_DISABLE_FIND_PACKAGE_${_yaze_pkg}" _yaze_disable_var)
+  string(TOUPPER "_YAZE_GRPC_SAVE_${_yaze_disable_var}" _yaze_saved_key)
+  if(NOT DEFINED ${_yaze_saved_key})
+    continue()
+  endif()
+  if("${${_yaze_saved_key}}" STREQUAL "__YAZE_UNSET__")
+    unset(${_yaze_disable_var})
+  else()
+    set(${_yaze_disable_var} "${${_yaze_saved_key}}")
+  endif()
+  unset(${_yaze_saved_key})
+endforeach()
+
+if("${_YAZE_GRPC_SAVED_PKG_CONFIG_USE_CMAKE_PREFIX_PATH}" STREQUAL "__YAZE_UNSET__")
+  unset(PKG_CONFIG_USE_CMAKE_PREFIX_PATH)
+else()
+  set(PKG_CONFIG_USE_CMAKE_PREFIX_PATH "${_YAZE_GRPC_SAVED_PKG_CONFIG_USE_CMAKE_PREFIX_PATH}")
+endif()
+unset(_YAZE_GRPC_SAVED_PKG_CONFIG_USE_CMAKE_PREFIX_PATH)
+
+set(CMAKE_PREFIX_PATH "${_YAZE_GRPC_SAVED_PREFIX_PATH}")
+unset(_YAZE_GRPC_SAVED_PREFIX_PATH)
+
+if("${_YAZE_GRPC_SAVED_CROSSCOMPILING}" STREQUAL "__YAZE_UNSET__")
+  unset(CMAKE_CROSSCOMPILING)
+else()
+  set(CMAKE_CROSSCOMPILING "${_YAZE_GRPC_SAVED_CROSSCOMPILING}")
+endif()
+unset(_YAZE_GRPC_SAVED_CROSSCOMPILING)
+
+if("${_YAZE_GRPC_SAVED_CXX_STANDARD}" STREQUAL "__YAZE_UNSET__")
+  unset(CMAKE_CXX_STANDARD)
+else()
+  set(CMAKE_CXX_STANDARD "${_YAZE_GRPC_SAVED_CXX_STANDARD}")
+endif()
+unset(_YAZE_GRPC_SAVED_CXX_STANDARD)
+
+# Check which target naming convention is used
+if(TARGET grpc++)
+  message(STATUS "Found non-namespaced gRPC target grpc++")
+  if(NOT TARGET grpc::grpc++)
+    add_library(grpc::grpc++ ALIAS grpc++)
+  endif()
+  if(NOT TARGET grpc::grpc++_reflection AND TARGET grpc++_reflection)
+    add_library(grpc::grpc++_reflection ALIAS grpc++_reflection)
+  endif()
+endif()
+
+set(_YAZE_GRPC_ERRORS "")
+
+if(NOT TARGET grpc++ AND NOT TARGET grpc::grpc++)
+  list(APPEND _YAZE_GRPC_ERRORS "gRPC target not found after CPM fetch")
+endif()
+
+if(NOT TARGET protoc)
+  list(APPEND _YAZE_GRPC_ERRORS "protoc target not found after gRPC setup")
+endif()
+
+if(NOT TARGET grpc_cpp_plugin)
+  list(APPEND _YAZE_GRPC_ERRORS "grpc_cpp_plugin target not found after gRPC setup")
+endif()
+
+if(_YAZE_GRPC_ERRORS)
+  list(JOIN _YAZE_GRPC_ERRORS "\n" _YAZE_GRPC_ERROR_MESSAGE)
+  message(FATAL_ERROR "${_YAZE_GRPC_ERROR_MESSAGE}")
+endif()
+
+# Create convenience interface for basic gRPC linking (renamed to avoid conflict with yaze_grpc_support STATIC library)
+add_library(yaze_grpc_deps INTERFACE)
+target_link_libraries(yaze_grpc_deps INTERFACE
+  grpc::grpc++
+  grpc::grpc++_reflection
+  protobuf::libprotobuf
+)
+
+# Define Windows macro guards once so protobuf-generated headers stay clean
+if(WIN32)
+  add_compile_definitions(
+    WIN32_LEAN_AND_MEAN
+    NOMINMAX
+    NOGDI
+  )
+endif()
+
+# Export Abseil targets from gRPC's bundled Abseil
+# When gRPC_ABSL_PROVIDER is "module", gRPC fetches and builds Abseil
+# All Abseil targets are available, we just need to list them
+# Note: All targets are available even if not listed here, but listing ensures consistency
+set(ABSL_TARGETS
+  absl::base
+  absl::config
+  absl::core_headers
+  absl::utility
+  absl::memory
+  absl::container_memory
+  absl::strings
+  absl::strings_internal
+  absl::str_format
+  absl::str_format_internal
+  absl::cord
+  absl::hash
+  absl::time
+  absl::time_zone
+  absl::status
+  absl::statusor
+  absl::flags
+  absl::flags_parse
+  absl::flags_usage
+  absl::flags_commandlineflag
+  absl::flags_marshalling
+  absl::flags_private_handle_accessor
+  absl::flags_program_name
+  absl::flags_config
+  absl::flags_reflection
+  absl::examine_stack
+  absl::stacktrace
+  absl::failure_signal_handler
+  absl::flat_hash_map
+  absl::synchronization
+  absl::symbolize
+  absl::strerror
+)
+
+# Only expose absl::int128 when it's supported without warnings
+if(NOT WIN32)
+  list(APPEND ABSL_TARGETS absl::int128)
+endif()
+
+# Export gRPC targets for use in other CMake files
+set(YAZE_GRPC_TARGETS
+  grpc::grpc++
+  grpc::grpc++_reflection
+  protobuf::libprotobuf
+  protoc
+  grpc_cpp_plugin
+)
+
+message(STATUS "gRPC setup complete - targets available: ${YAZE_GRPC_TARGETS}")
+
+# Setup protobuf generation directory (use CACHE so it's available in functions)
+set(_gRPC_PROTO_GENS_DIR ${CMAKE_BINARY_DIR}/gens CACHE INTERNAL "Protobuf generated files directory")
+file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/gens)
+
+# Get protobuf include directories (extract from generator expression or direct path)
+if(TARGET libprotobuf)
+  get_target_property(_PROTOBUF_INCLUDE_DIRS libprotobuf INTERFACE_INCLUDE_DIRECTORIES)
+  # Handle generator expressions
+  string(REGEX REPLACE "\\$<BUILD_INTERFACE:([^>]+)>" "\\1" _PROTOBUF_INCLUDE_DIR_CLEAN "${_PROTOBUF_INCLUDE_DIRS}")
+  list(GET _PROTOBUF_INCLUDE_DIR_CLEAN 0 _gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR)
+  set(_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR} CACHE INTERNAL "Protobuf include directory")
+elseif(TARGET protobuf::libprotobuf)
+  get_target_property(_PROTOBUF_INCLUDE_DIRS protobuf::libprotobuf INTERFACE_INCLUDE_DIRECTORIES)
+  string(REGEX REPLACE "\\$<BUILD_INTERFACE:([^>]+)>" "\\1" _PROTOBUF_INCLUDE_DIR_CLEAN "${_PROTOBUF_INCLUDE_DIRS}")
+  list(GET _PROTOBUF_INCLUDE_DIR_CLEAN 0 _gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR)
+  set(_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR} CACHE INTERNAL "Protobuf include directory")
+endif()
+
+# Remove x86-only Abseil compile flags when building on ARM64 macOS runners
+set(_YAZE_PATCH_ABSL_FOR_APPLE FALSE)
+if(APPLE)
+  if(CMAKE_OSX_ARCHITECTURES)
+    string(TOLOWER "${CMAKE_OSX_ARCHITECTURES}" _yaze_osx_archs)
+    if(_yaze_osx_archs MATCHES "arm64")
+      set(_YAZE_PATCH_ABSL_FOR_APPLE TRUE)
+    endif()
+  else()
+    string(TOLOWER "${CMAKE_SYSTEM_PROCESSOR}" _yaze_proc)
+    if(_yaze_proc MATCHES "arm64" OR _yaze_proc MATCHES "aarch64")
+      set(_YAZE_PATCH_ABSL_FOR_APPLE TRUE)
+    endif()
+  endif()
+endif()
+
+if(_YAZE_PATCH_ABSL_FOR_APPLE)
+  set(_YAZE_ABSL_X86_TARGETS
+    absl_random_internal_randen_hwaes
+    absl_random_internal_randen_hwaes_impl
+    absl_crc_internal_cpu_detect
+  )
+
+  foreach(_yaze_absl_target IN LISTS _YAZE_ABSL_X86_TARGETS)
+    if(TARGET ${_yaze_absl_target})
+      get_target_property(_yaze_absl_opts ${_yaze_absl_target} COMPILE_OPTIONS)
+      if(_yaze_absl_opts AND NOT _yaze_absl_opts STREQUAL "NOTFOUND")
+        set(_yaze_filtered_opts)
+        foreach(_yaze_opt IN LISTS _yaze_absl_opts)
+          if(_yaze_opt STREQUAL "-Xarch_x86_64")
+            continue()
+          endif()
+          if(_yaze_opt MATCHES "^-m(sse|avx)")
+            continue()
+          endif()
+          if(_yaze_opt STREQUAL "-maes")
+            continue()
+          endif()
+          list(APPEND _yaze_filtered_opts "${_yaze_opt}")
+        endforeach()
+        set_property(TARGET ${_yaze_absl_target} PROPERTY COMPILE_OPTIONS ${_yaze_filtered_opts})
+        message(STATUS "Patched ${_yaze_absl_target} compile options for ARM64 macOS")
+      endif()
+    endif()
+  endforeach()
+endif()
+
+unset(_YAZE_GRPC_SAVED_CPM_USE_LOCAL_PACKAGES)
+unset(_YAZE_GRPC_ERRORS)
+unset(_YAZE_GRPC_ERROR_MESSAGE)
+
+message(STATUS "Protobuf gens dir: ${_gRPC_PROTO_GENS_DIR}")
+message(STATUS "Protobuf include dir: ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR}")
+
+# Export protobuf targets
+set(YAZE_PROTOBUF_TARGETS
+  protobuf::libprotobuf
+)
+
+endif() # End of CPM build path (if NOT _YAZE_USING_SYSTEM_GRPC)
+
+# Function to add protobuf/gRPC code generation to a target
+# This function works with both system and CPM-built gRPC
+function(target_add_protobuf target)
+    if(NOT TARGET ${target})
+        message(FATAL_ERROR "Target ${target} doesn't exist")
+    endif()
+    if(NOT ARGN)
+        message(SEND_ERROR "Error: target_add_protobuf() called without any proto files")
+        return()
+    endif()
+
+    # Determine protoc and grpc_cpp_plugin paths
+    # For IMPORTED targets (system gRPC), use IMPORTED_LOCATION
+    # For built targets (CPM gRPC), use TARGET_FILE generator expression
+    get_target_property(_PROTOC_IMPORTED protoc IMPORTED)
+    get_target_property(_GRPC_PLUGIN_IMPORTED grpc_cpp_plugin IMPORTED)
+
+    if(_PROTOC_IMPORTED)
+        get_target_property(_PROTOC_EXECUTABLE protoc IMPORTED_LOCATION)
+        set(_PROTOC_DEPENDS "")  # No build dependency for system protoc
+    else()
+        set(_PROTOC_EXECUTABLE "$<TARGET_FILE:protoc>")
+        set(_PROTOC_DEPENDS "protoc")
+    endif()
+
+    if(_GRPC_PLUGIN_IMPORTED)
+        get_target_property(_GRPC_PLUGIN_EXECUTABLE grpc_cpp_plugin IMPORTED_LOCATION)
+        set(_GRPC_PLUGIN_DEPENDS "")  # No build dependency for system plugin
+    else()
+        set(_GRPC_PLUGIN_EXECUTABLE "$<TARGET_FILE:grpc_cpp_plugin>")
+        set(_GRPC_PLUGIN_DEPENDS "grpc_cpp_plugin")
+    endif()
+
+    set(_protobuf_include_path -I ${CMAKE_SOURCE_DIR}/src -I ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR})
+    foreach(FIL ${ARGN})
+        get_filename_component(ABS_FIL ${FIL} ABSOLUTE)
+        get_filename_component(FIL_WE ${FIL} NAME_WE)
+        file(RELATIVE_PATH REL_FIL ${CMAKE_SOURCE_DIR}/src ${ABS_FIL})
+        get_filename_component(REL_DIR ${REL_FIL} DIRECTORY)
+        if(NOT REL_DIR OR REL_DIR STREQUAL ".")
+            set(RELFIL_WE "${FIL_WE}")
+        else()
+            set(RELFIL_WE "${REL_DIR}/${FIL_WE}")
+        endif()
+
+        message(STATUS "  Proto file: ${FIL_WE}")
+        message(STATUS "    ABS_FIL = ${ABS_FIL}")
+        message(STATUS "    REL_FIL = ${REL_FIL}")
+        message(STATUS "    REL_DIR = ${REL_DIR}")
+        message(STATUS "    RELFIL_WE = ${RELFIL_WE}")
+        message(STATUS "    Output = ${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.h")
+
+        add_custom_command(
+        OUTPUT  "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.cc"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.h"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}_mock.grpc.pb.h"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.cc"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.h"
+        COMMAND ${_PROTOC_EXECUTABLE}
+        ARGS --grpc_out=generate_mock_code=true:${_gRPC_PROTO_GENS_DIR}
+            --cpp_out=${_gRPC_PROTO_GENS_DIR}
+            --plugin=protoc-gen-grpc=${_GRPC_PLUGIN_EXECUTABLE}
+            ${_protobuf_include_path}
+            ${ABS_FIL}
+        DEPENDS ${ABS_FIL} ${_PROTOC_DEPENDS} ${_GRPC_PLUGIN_DEPENDS}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/src
+        COMMENT "Running gRPC C++ protocol buffer compiler on ${FIL}"
+        VERBATIM)
+
+        target_sources(${target} PRIVATE
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.cc"
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.h"
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}_mock.grpc.pb.h"
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.cc"
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.h"
+        )
+        target_include_directories(${target} PUBLIC
+            $<BUILD_INTERFACE:${_gRPC_PROTO_GENS_DIR}>
+            $<BUILD_INTERFACE:${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR}>
+        )
+    endforeach()
+endfunction()
+

cmake/dependencies/imgui.cmake

@@ -0,0 +1,94 @@
+# Dear ImGui dependency management
+# Uses the bundled ImGui in ext/imgui
+
+message(STATUS "Setting up Dear ImGui from bundled sources")
+
+# Use the bundled ImGui from ext/imgui
+set(IMGUI_DIR ${CMAKE_SOURCE_DIR}/ext/imgui)
+
+# Select ImGui backend sources based on SDL version
+if(YAZE_USE_SDL3)
+  set(IMGUI_BACKEND_SOURCES
+    ${IMGUI_DIR}/backends/imgui_impl_sdl3.cpp
+    ${IMGUI_DIR}/backends/imgui_impl_sdlrenderer3.cpp
+  )
+  message(STATUS "Using ImGui SDL3 backend")
+else()
+  set(IMGUI_BACKEND_SOURCES
+    ${IMGUI_DIR}/backends/imgui_impl_sdl2.cpp
+    ${IMGUI_DIR}/backends/imgui_impl_sdlrenderer2.cpp
+  )
+  message(STATUS "Using ImGui SDL2 backend")
+endif()
+
+# Create ImGui library with core files from bundled source
+add_library(ImGui STATIC
+  ${IMGUI_DIR}/imgui.cpp
+  ${IMGUI_DIR}/imgui_demo.cpp
+  ${IMGUI_DIR}/imgui_draw.cpp
+  ${IMGUI_DIR}/imgui_tables.cpp
+  ${IMGUI_DIR}/imgui_widgets.cpp
+  # SDL backend (version-dependent)
+  ${IMGUI_BACKEND_SOURCES}
+  # C++ stdlib helpers (for std::string support)
+  ${IMGUI_DIR}/misc/cpp/imgui_stdlib.cpp
+)
+
+target_include_directories(ImGui PUBLIC
+  ${IMGUI_DIR}
+  ${IMGUI_DIR}/backends
+)
+
+# Set C++ standard requirement (ImGui 1.90+ requires C++11, we use C++17 for consistency)
+target_compile_features(ImGui PUBLIC cxx_std_17)
+
+# Link to SDL (version-dependent)
+if(YAZE_USE_SDL3)
+  target_link_libraries(ImGui PUBLIC ${YAZE_SDL3_TARGETS})
+else()
+  target_link_libraries(ImGui PUBLIC ${YAZE_SDL2_TARGETS})
+endif()
+
+message(STATUS "Created ImGui target from bundled source at ${IMGUI_DIR}")
+
+# Create ImGui Test Engine for test automation (if tests are enabled)
+if(YAZE_BUILD_TESTS)
+  set(IMGUI_TEST_ENGINE_DIR ${CMAKE_SOURCE_DIR}/ext/imgui_test_engine/imgui_test_engine)
+  
+  if(EXISTS ${IMGUI_TEST_ENGINE_DIR})
+    set(IMGUI_TEST_ENGINE_SOURCES
+      ${IMGUI_TEST_ENGINE_DIR}/imgui_te_context.cpp
+      ${IMGUI_TEST_ENGINE_DIR}/imgui_te_coroutine.cpp
+      ${IMGUI_TEST_ENGINE_DIR}/imgui_te_engine.cpp
+      ${IMGUI_TEST_ENGINE_DIR}/imgui_te_exporters.cpp
+      ${IMGUI_TEST_ENGINE_DIR}/imgui_te_perftool.cpp
+      ${IMGUI_TEST_ENGINE_DIR}/imgui_te_ui.cpp
+      ${IMGUI_TEST_ENGINE_DIR}/imgui_te_utils.cpp
+      ${IMGUI_TEST_ENGINE_DIR}/imgui_capture_tool.cpp
+    )
+    
+    add_library(ImGuiTestEngine STATIC ${IMGUI_TEST_ENGINE_SOURCES})
+    target_include_directories(ImGuiTestEngine PUBLIC 
+      ${IMGUI_DIR}
+      ${IMGUI_TEST_ENGINE_DIR}
+      ${CMAKE_SOURCE_DIR}/ext
+    )
+    target_compile_features(ImGuiTestEngine PUBLIC cxx_std_17)
+    if(YAZE_USE_SDL3)
+      target_link_libraries(ImGuiTestEngine PUBLIC ImGui ${YAZE_SDL3_TARGETS})
+    else()
+      target_link_libraries(ImGuiTestEngine PUBLIC ImGui ${YAZE_SDL2_TARGETS})
+    endif()
+    target_compile_definitions(ImGuiTestEngine PUBLIC
+      IMGUI_ENABLE_TEST_ENGINE=1
+      IMGUI_TEST_ENGINE_ENABLE_COROUTINE_STDTHREAD_IMPL=1
+    )
+    
+    message(STATUS "Created ImGuiTestEngine target for test automation")
+  endif()
+endif()
+
+# Export ImGui targets for use in other CMake files  
+set(YAZE_IMGUI_TARGETS ImGui)
+
+message(STATUS "Dear ImGui setup complete - YAZE_IMGUI_TARGETS = ${YAZE_IMGUI_TARGETS}")

cmake/dependencies/json.cmake

@@ -0,0 +1,31 @@
+# nlohmann_json dependency management
+
+if(NOT YAZE_ENABLE_JSON)
+  return()
+endif()
+
+message(STATUS "Setting up nlohmann_json with local ext directory")
+
+# Use the bundled nlohmann_json from ext/json
+set(JSON_BuildTests OFF CACHE BOOL "" FORCE)
+set(JSON_Install OFF CACHE BOOL "" FORCE)
+set(JSON_MultipleHeaders OFF CACHE BOOL "" FORCE)
+
+add_subdirectory(${CMAKE_SOURCE_DIR}/ext/json EXCLUDE_FROM_ALL)
+
+# Verify target is available
+if(TARGET nlohmann_json::nlohmann_json)
+  message(STATUS "nlohmann_json target found")
+elseif(TARGET nlohmann_json)
+  # Create alias if only non-namespaced target exists
+  add_library(nlohmann_json::nlohmann_json ALIAS nlohmann_json)
+  message(STATUS "Created nlohmann_json::nlohmann_json alias")
+else()
+  message(FATAL_ERROR "nlohmann_json target not found after add_subdirectory")
+endif()
+
+# Export for use in other CMake files
+set(YAZE_JSON_TARGETS nlohmann_json::nlohmann_json CACHE INTERNAL "nlohmann_json targets")
+
+message(STATUS "nlohmann_json setup complete")
+

cmake/dependencies/sdl2.cmake

@@ -0,0 +1,101 @@
+# SDL2 dependency management
+# Uses CPM.cmake for consistent cross-platform builds
+
+include(cmake/CPM.cmake)
+include(cmake/dependencies.lock)
+
+message(STATUS "Setting up SDL2 ${SDL2_VERSION} with CPM.cmake")
+
+# Try to use system packages first if requested
+if(YAZE_USE_SYSTEM_DEPS)
+  find_package(SDL2 QUIET)
+  if(SDL2_FOUND)
+    message(STATUS "Using system SDL2")
+    if(NOT TARGET yaze_sdl2)
+      add_library(yaze_sdl2 INTERFACE)
+      target_link_libraries(yaze_sdl2 INTERFACE SDL2::SDL2)
+      if(TARGET SDL2::SDL2main)
+        target_link_libraries(yaze_sdl2 INTERFACE SDL2::SDL2main)
+      endif()
+    endif()
+    set(YAZE_SDL2_TARGETS yaze_sdl2 CACHE INTERNAL "")
+    return()
+  endif()
+endif()
+
+# Use CPM to fetch SDL2
+CPMAddPackage(
+  NAME SDL2
+  VERSION ${SDL2_VERSION}
+  GITHUB_REPOSITORY libsdl-org/SDL
+  GIT_TAG release-${SDL2_VERSION}
+  OPTIONS
+    "SDL_SHARED OFF"
+    "SDL_STATIC ON"
+    "SDL_TEST OFF"
+    "SDL_INSTALL OFF"
+    "SDL_CMAKE_DEBUG_POSTFIX d"
+)
+
+# Verify SDL2 targets are available  
+if(NOT TARGET SDL2-static AND NOT TARGET SDL2::SDL2-static AND NOT TARGET SDL2::SDL2)
+  message(FATAL_ERROR "SDL2 target not found after CPM fetch")
+endif()
+
+# Create convenience targets for the rest of the project
+if(NOT TARGET yaze_sdl2)
+  add_library(yaze_sdl2 INTERFACE)
+  # SDL2 from CPM might use SDL2-static or SDL2::SDL2-static
+  if(TARGET SDL2-static)
+    message(STATUS "Using SDL2-static target")
+    target_link_libraries(yaze_sdl2 INTERFACE SDL2-static)
+    # Also explicitly add include directories if they exist
+    if(SDL2_SOURCE_DIR)
+      target_include_directories(yaze_sdl2 INTERFACE ${SDL2_SOURCE_DIR}/include)
+      message(STATUS "Added SDL2 include: ${SDL2_SOURCE_DIR}/include")
+    endif()
+  elseif(TARGET SDL2::SDL2-static)
+    message(STATUS "Using SDL2::SDL2-static target")
+    target_link_libraries(yaze_sdl2 INTERFACE SDL2::SDL2-static)
+    # For local Homebrew SDL2, also add include path explicitly
+    # SDL headers are in the SDL2 subdirectory
+    if(APPLE AND EXISTS "/opt/homebrew/opt/sdl2/include/SDL2")
+      target_include_directories(yaze_sdl2 INTERFACE /opt/homebrew/opt/sdl2/include/SDL2)
+      message(STATUS "Added Homebrew SDL2 include path: /opt/homebrew/opt/sdl2/include/SDL2")
+    endif()
+  else()
+    message(STATUS "Using SDL2::SDL2 target")
+    target_link_libraries(yaze_sdl2 INTERFACE SDL2::SDL2)
+  endif()
+endif()
+
+# Add platform-specific libraries
+if(WIN32)
+  target_link_libraries(yaze_sdl2 INTERFACE
+    winmm
+    imm32
+    version
+    setupapi
+    wbemuuid
+  )
+  target_compile_definitions(yaze_sdl2 INTERFACE SDL_MAIN_HANDLED)
+elseif(APPLE)
+  target_link_libraries(yaze_sdl2 INTERFACE
+    "-framework Cocoa"
+    "-framework IOKit"
+    "-framework CoreVideo"
+    "-framework ForceFeedback"
+  )
+  target_compile_definitions(yaze_sdl2 INTERFACE SDL_MAIN_HANDLED)
+elseif(UNIX)
+  find_package(PkgConfig REQUIRED)
+  pkg_check_modules(GTK3 REQUIRED gtk+-3.0)
+  target_link_libraries(yaze_sdl2 INTERFACE ${GTK3_LIBRARIES})
+  target_include_directories(yaze_sdl2 INTERFACE ${GTK3_INCLUDE_DIRS})
+  target_compile_options(yaze_sdl2 INTERFACE ${GTK3_CFLAGS_OTHER})
+endif()
+
+# Export SDL2 targets for use in other CMake files
+set(YAZE_SDL2_TARGETS yaze_sdl2)
+
+message(STATUS "SDL2 setup complete - YAZE_SDL2_TARGETS = ${YAZE_SDL2_TARGETS}")

cmake/dependencies/sdl3.cmake

@@ -0,0 +1,110 @@
+# SDL3 dependency management
+# Uses CPM.cmake for consistent cross-platform builds
+
+include(cmake/CPM.cmake)
+include(cmake/dependencies.lock)
+
+message(STATUS "Setting up SDL3 (experimental) with CPM.cmake")
+
+# SDL3 specific version (using latest stable 3.2 release)
+set(SDL3_VERSION "3.2.26")
+
+# Try to use system packages first if requested
+if(YAZE_USE_SYSTEM_DEPS)
+  find_package(SDL3 QUIET)
+  if(SDL3_FOUND)
+    message(STATUS "Using system SDL3")
+    if(NOT TARGET yaze_sdl3)
+      add_library(yaze_sdl3 INTERFACE)
+      target_link_libraries(yaze_sdl3 INTERFACE SDL3::SDL3)
+      if(TARGET SDL3::SDL3main)
+        target_link_libraries(yaze_sdl3 INTERFACE SDL3::SDL3main)
+      endif()
+    endif()
+    set(YAZE_SDL3_TARGETS yaze_sdl3 CACHE INTERNAL "")
+    return()
+  endif()
+endif()
+
+# Use CPM to fetch SDL3
+CPMAddPackage(
+  NAME SDL3
+  VERSION ${SDL3_VERSION}
+  GITHUB_REPOSITORY libsdl-org/SDL
+  GIT_TAG release-${SDL3_VERSION}
+  OPTIONS
+    "SDL_SHARED OFF"
+    "SDL_STATIC ON"
+    "SDL_TEST OFF"
+    "SDL_INSTALL OFF"
+    "SDL_CMAKE_DEBUG_POSTFIX d"
+    "SDL3_DISABLE_INSTALL ON"
+    "SDL3_DISABLE_UNINSTALL ON"
+)
+
+# Verify SDL3 targets are available
+if(NOT TARGET SDL3-static AND NOT TARGET SDL3::SDL3-static AND NOT TARGET SDL3::SDL3)
+  message(FATAL_ERROR "SDL3 target not found after CPM fetch")
+endif()
+
+# Create convenience targets for the rest of the project
+if(NOT TARGET yaze_sdl3)
+  add_library(yaze_sdl3 INTERFACE)
+  # SDL3 from CPM might use SDL3-static or SDL3::SDL3-static
+  if(TARGET SDL3-static)
+    message(STATUS "Using SDL3-static target")
+    target_link_libraries(yaze_sdl3 INTERFACE SDL3-static)
+    # Also explicitly add include directories if they exist
+    if(SDL3_SOURCE_DIR)
+      target_include_directories(yaze_sdl3 INTERFACE ${SDL3_SOURCE_DIR}/include)
+      message(STATUS "Added SDL3 include: ${SDL3_SOURCE_DIR}/include")
+    endif()
+  elseif(TARGET SDL3::SDL3-static)
+    message(STATUS "Using SDL3::SDL3-static target")
+    target_link_libraries(yaze_sdl3 INTERFACE SDL3::SDL3-static)
+    # For local Homebrew SDL3, also add include path explicitly
+    if(APPLE AND EXISTS "/opt/homebrew/opt/sdl3/include/SDL3")
+      target_include_directories(yaze_sdl3 INTERFACE /opt/homebrew/opt/sdl3/include/SDL3)
+      message(STATUS "Added Homebrew SDL3 include path: /opt/homebrew/opt/sdl3/include/SDL3")
+    endif()
+  else()
+    message(STATUS "Using SDL3::SDL3 target")
+    target_link_libraries(yaze_sdl3 INTERFACE SDL3::SDL3)
+  endif()
+endif()
+
+# Add platform-specific libraries
+if(WIN32)
+  target_link_libraries(yaze_sdl3 INTERFACE
+    winmm
+    imm32
+    version
+    setupapi
+    wbemuuid
+  )
+  target_compile_definitions(yaze_sdl3 INTERFACE SDL_MAIN_HANDLED)
+elseif(APPLE)
+  target_link_libraries(yaze_sdl3 INTERFACE
+    "-framework Cocoa"
+    "-framework IOKit"
+    "-framework CoreVideo"
+    "-framework CoreHaptics"
+    "-framework ForceFeedback"
+    "-framework GameController"
+  )
+  target_compile_definitions(yaze_sdl3 INTERFACE SDL_MAIN_HANDLED)
+elseif(UNIX)
+  find_package(PkgConfig REQUIRED)
+  pkg_check_modules(GTK3 REQUIRED gtk+-3.0)
+  target_link_libraries(yaze_sdl3 INTERFACE ${GTK3_LIBRARIES})
+  target_include_directories(yaze_sdl3 INTERFACE ${GTK3_INCLUDE_DIRS})
+  target_compile_options(yaze_sdl3 INTERFACE ${GTK3_CFLAGS_OTHER})
+endif()
+
+# Export SDL3 targets for use in other CMake files
+set(YAZE_SDL3_TARGETS yaze_sdl3)
+
+# Set a flag to indicate SDL3 is being used
+set(YAZE_SDL2_TARGETS ${YAZE_SDL3_TARGETS})  # For compatibility with existing code
+
+message(STATUS "SDL3 setup complete - YAZE_SDL3_TARGETS = ${YAZE_SDL3_TARGETS}")

cmake/dependencies/testing.cmake

@@ -0,0 +1,138 @@
+# Testing dependencies (GTest, Benchmark)
+# Uses CPM.cmake for consistent cross-platform builds
+
+if(NOT YAZE_BUILD_TESTS)
+  return()
+endif()
+
+include(cmake/CPM.cmake)
+include(cmake/dependencies.lock)
+
+message(STATUS "Setting up testing dependencies with CPM.cmake")
+
+set(_YAZE_USE_SYSTEM_GTEST ${YAZE_USE_SYSTEM_DEPS})
+
+# Detect Homebrew installation automatically (helps offline builds)
+if(APPLE AND NOT _YAZE_USE_SYSTEM_GTEST)
+  set(_YAZE_GTEST_PREFIX_CANDIDATES
+    /opt/homebrew/opt/googletest
+    /usr/local/opt/googletest)
+
+  foreach(_prefix IN LISTS _YAZE_GTEST_PREFIX_CANDIDATES)
+    if(EXISTS "${_prefix}")
+      list(APPEND CMAKE_PREFIX_PATH "${_prefix}")
+      message(STATUS "Added Homebrew googletest prefix: ${_prefix}")
+      set(_YAZE_USE_SYSTEM_GTEST ON)
+      break()
+    endif()
+  endforeach()
+
+  if(NOT _YAZE_USE_SYSTEM_GTEST)
+    find_program(HOMEBREW_EXECUTABLE brew)
+    if(HOMEBREW_EXECUTABLE)
+      execute_process(
+        COMMAND "${HOMEBREW_EXECUTABLE}" --prefix googletest
+        OUTPUT_VARIABLE HOMEBREW_GTEST_PREFIX
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        RESULT_VARIABLE HOMEBREW_GTEST_RESULT
+        ERROR_QUIET)
+      if(HOMEBREW_GTEST_RESULT EQUAL 0 AND EXISTS "${HOMEBREW_GTEST_PREFIX}")
+        list(APPEND CMAKE_PREFIX_PATH "${HOMEBREW_GTEST_PREFIX}")
+        message(STATUS "Added Homebrew googletest prefix: ${HOMEBREW_GTEST_PREFIX}")
+        set(_YAZE_USE_SYSTEM_GTEST ON)
+      endif()
+    endif()
+  endif()
+endif()
+
+# Try to use system packages first
+if(_YAZE_USE_SYSTEM_GTEST)
+  find_package(GTest QUIET)
+  if(GTest_FOUND)
+    message(STATUS "Using system googletest")
+    # GTest found, targets should already be available
+    # Verify targets exist
+    if(NOT TARGET GTest::gtest)
+      message(WARNING "GTest::gtest target not found despite GTest_FOUND=TRUE; falling back to CPM download")
+      set(_YAZE_USE_SYSTEM_GTEST OFF)
+    else()
+      # Create aliases to match CPM target names
+      if(NOT TARGET gtest)
+        add_library(gtest ALIAS GTest::gtest)
+      endif()
+      if(NOT TARGET gtest_main)
+        add_library(gtest_main ALIAS GTest::gtest_main)
+      endif()
+      if(TARGET GTest::gmock AND NOT TARGET gmock)
+        add_library(gmock ALIAS GTest::gmock)
+      endif()
+      if(TARGET GTest::gmock_main AND NOT TARGET gmock_main)
+        add_library(gmock_main ALIAS GTest::gmock_main)
+      endif()
+      # Skip CPM fetch
+      set(_YAZE_GTEST_SYSTEM_USED ON)
+    endif()
+  elseif(YAZE_USE_SYSTEM_DEPS)
+    message(WARNING "System googletest not found despite YAZE_USE_SYSTEM_DEPS=ON; falling back to CPM download")
+  endif()
+endif()
+
+# Use CPM to fetch googletest if not using system version
+if(NOT _YAZE_GTEST_SYSTEM_USED)
+  CPMAddPackage(
+    NAME googletest
+    VERSION ${GTEST_VERSION}
+    GITHUB_REPOSITORY google/googletest
+    GIT_TAG v${GTEST_VERSION}
+    OPTIONS
+      "BUILD_GMOCK ON"
+      "INSTALL_GTEST OFF"
+      "gtest_force_shared_crt ON"
+  )
+endif()
+
+# Verify GTest and GMock targets are available
+if(NOT TARGET gtest)
+  message(FATAL_ERROR "GTest target not found after CPM fetch")
+endif()
+
+if(NOT TARGET gmock)
+  message(FATAL_ERROR "GMock target not found after CPM fetch")
+endif()
+
+# Google Benchmark (optional, for performance tests)
+if(YAZE_ENABLE_COVERAGE OR DEFINED ENV{YAZE_ENABLE_BENCHMARKS})
+  CPMAddPackage(
+    NAME benchmark
+    VERSION ${BENCHMARK_VERSION}
+    GITHUB_REPOSITORY google/benchmark
+    GIT_TAG v${BENCHMARK_VERSION}
+    OPTIONS
+      "BENCHMARK_ENABLE_TESTING OFF"
+      "BENCHMARK_ENABLE_INSTALL OFF"
+  )
+  
+  if(NOT TARGET benchmark::benchmark)
+    message(FATAL_ERROR "Benchmark target not found after CPM fetch")
+  endif()
+  
+  set(YAZE_BENCHMARK_TARGETS benchmark::benchmark)
+endif()
+
+# Create convenience targets for the rest of the project
+add_library(yaze_testing INTERFACE)
+target_link_libraries(yaze_testing INTERFACE 
+  gtest 
+  gtest_main
+  gmock
+  gmock_main
+)
+
+if(TARGET benchmark::benchmark)
+  target_link_libraries(yaze_testing INTERFACE benchmark::benchmark)
+endif()
+
+# Export testing targets for use in other CMake files
+set(YAZE_TESTING_TARGETS yaze_testing)
+
+message(STATUS "Testing dependencies setup complete - GTest + GMock available")

cmake/dependencies/yaml.cmake

@@ -0,0 +1,103 @@
+# yaml-cpp dependency management
+# Uses CPM.cmake for consistent cross-platform builds
+
+include(cmake/CPM.cmake)
+include(cmake/dependencies.lock)
+
+if(NOT YAZE_ENABLE_AI AND NOT YAZE_ENABLE_AI_RUNTIME)
+  message(STATUS "Skipping yaml-cpp (AI runtime and CLI agent features disabled)")
+  set(YAZE_YAML_TARGETS "")
+  return()
+endif()
+
+message(STATUS "Setting up yaml-cpp ${YAML_CPP_VERSION} with CPM.cmake")
+
+set(_YAZE_USE_SYSTEM_YAML ${YAZE_USE_SYSTEM_DEPS})
+
+# Detect Homebrew installation automatically (helps offline builds)
+if(APPLE AND NOT _YAZE_USE_SYSTEM_YAML)
+  set(_YAZE_YAML_PREFIX_CANDIDATES
+    /opt/homebrew/opt/yaml-cpp
+    /usr/local/opt/yaml-cpp)
+
+  foreach(_prefix IN LISTS _YAZE_YAML_PREFIX_CANDIDATES)
+    if(EXISTS "${_prefix}")
+      list(APPEND CMAKE_PREFIX_PATH "${_prefix}")
+      message(STATUS "Added Homebrew yaml-cpp prefix: ${_prefix}")
+      set(_YAZE_USE_SYSTEM_YAML ON)
+      break()
+    endif()
+  endforeach()
+
+  if(NOT _YAZE_USE_SYSTEM_YAML)
+    find_program(HOMEBREW_EXECUTABLE brew)
+    if(HOMEBREW_EXECUTABLE)
+      execute_process(
+        COMMAND "${HOMEBREW_EXECUTABLE}" --prefix yaml-cpp
+        OUTPUT_VARIABLE HOMEBREW_YAML_PREFIX
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        RESULT_VARIABLE HOMEBREW_YAML_RESULT
+        ERROR_QUIET)
+      if(HOMEBREW_YAML_RESULT EQUAL 0 AND EXISTS "${HOMEBREW_YAML_PREFIX}")
+        list(APPEND CMAKE_PREFIX_PATH "${HOMEBREW_YAML_PREFIX}")
+        message(STATUS "Added Homebrew yaml-cpp prefix: ${HOMEBREW_YAML_PREFIX}")
+        set(_YAZE_USE_SYSTEM_YAML ON)
+      endif()
+    endif()
+  endif()
+endif()
+
+# Try to use system packages first
+if(_YAZE_USE_SYSTEM_YAML)
+  find_package(yaml-cpp QUIET)
+  if(yaml-cpp_FOUND)
+    message(STATUS "Using system yaml-cpp")
+    add_library(yaze_yaml INTERFACE)
+    if(TARGET yaml-cpp::yaml-cpp)
+      message(STATUS "Linking yaze_yaml against yaml-cpp::yaml-cpp")
+      target_link_libraries(yaze_yaml INTERFACE yaml-cpp::yaml-cpp)
+      
+      # HACK: Explicitly add the library directory for Homebrew if detected
+      # This fixes 'ld: library not found for -lyaml-cpp' when the imported target
+      # doesn't propagate the library path correctly to the linker command line
+      if(EXISTS "/opt/homebrew/opt/yaml-cpp/lib")
+        link_directories("/opt/homebrew/opt/yaml-cpp/lib")
+        message(STATUS "Added yaml-cpp link directory: /opt/homebrew/opt/yaml-cpp/lib")
+      endif()
+    else()
+      message(STATUS "Linking yaze_yaml against yaml-cpp (legacy)")
+      target_link_libraries(yaze_yaml INTERFACE yaml-cpp)
+    endif()
+    set(YAZE_YAML_TARGETS yaze_yaml)
+    return()
+  elseif(YAZE_USE_SYSTEM_DEPS)
+    message(WARNING "System yaml-cpp not found despite YAZE_USE_SYSTEM_DEPS=ON; falling back to CPM download")
+  endif()
+endif()
+
+# Use CPM to fetch yaml-cpp
+CPMAddPackage(
+  NAME yaml-cpp
+  VERSION ${YAML_CPP_VERSION}
+  GITHUB_REPOSITORY jbeder/yaml-cpp
+  GIT_TAG 0.8.0
+  OPTIONS
+    "YAML_CPP_BUILD_TESTS OFF"
+    "YAML_CPP_BUILD_CONTRIB OFF"
+    "YAML_CPP_BUILD_TOOLS OFF"
+    "YAML_CPP_INSTALL OFF"
+)
+
+# Verify yaml-cpp targets are available
+if(NOT TARGET yaml-cpp)
+  message(FATAL_ERROR "yaml-cpp target not found after CPM fetch")
+endif()
+
+# Create convenience targets for the rest of the project
+add_library(yaze_yaml INTERFACE)
+target_link_libraries(yaze_yaml INTERFACE yaml-cpp)
+
+# Export yaml-cpp targets for use in other CMake files
+set(YAZE_YAML_TARGETS yaze_yaml)
+
+message(STATUS "yaml-cpp setup complete")

cmake/grpc.cmake

@@ -0,0 +1,231 @@
+cmake_minimum_required(VERSION 3.16)
+set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
+set(CMAKE_POLICY_DEFAULT_CMP0074 NEW)
+
+# Include FetchContent module
+include(FetchContent)
+
+# Set minimum CMake version for subprojects (fixes c-ares compatibility)
+set(CMAKE_POLICY_VERSION_MINIMUM 3.5)
+
+set(FETCHCONTENT_QUIET OFF)
+
+# CRITICAL: Prevent CMake from finding system-installed protobuf/abseil
+# This ensures gRPC uses its own bundled versions
+set(CMAKE_DISABLE_FIND_PACKAGE_Protobuf TRUE)
+set(CMAKE_DISABLE_FIND_PACKAGE_absl TRUE)
+set(CMAKE_DISABLE_FIND_PACKAGE_gRPC TRUE)
+
+# Also prevent pkg-config from finding system packages
+set(PKG_CONFIG_USE_CMAKE_PREFIX_PATH FALSE)
+
+# Save YAZE's C++ standard and temporarily set to C++17 for gRPC
+set(_SAVED_CMAKE_CXX_STANDARD ${CMAKE_CXX_STANDARD})
+set(CMAKE_CXX_STANDARD 17)
+
+# ZLIB is provided by gRPC module (gRPC_ZLIB_PROVIDER="module")
+# find_package(ZLIB REQUIRED) not needed - gRPC bundles its own ZLIB
+
+# Configure gRPC build options before fetching
+set(gRPC_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_CODEGEN ON CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_CPP_PLUGIN ON CACHE BOOL "" FORCE)
+set(gRPC_BUILD_CSHARP_EXT OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_CSHARP_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_NODE_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_OBJECTIVE_C_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_PHP_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_PYTHON_PLUGIN OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_RUBY_PLUGIN OFF CACHE BOOL "" FORCE)
+# Disable C++ reflection support (avoids extra proto generation)
+set(gRPC_BUILD_REFLECTION OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_REFLECTION OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPC_CPP_REFLECTION OFF CACHE BOOL "" FORCE)
+set(gRPC_BUILD_GRPCPP_REFLECTION OFF CACHE BOOL "" FORCE)
+
+set(gRPC_BENCHMARK_PROVIDER "none" CACHE STRING "" FORCE)
+set(gRPC_ZLIB_PROVIDER "module" CACHE STRING "" FORCE)
+
+# Let gRPC fetch and build its own protobuf and abseil
+set(gRPC_PROTOBUF_PROVIDER "module" CACHE STRING "" FORCE)
+set(gRPC_ABSL_PROVIDER "module" CACHE STRING "" FORCE)
+
+# Protobuf configuration
+set(protobuf_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(protobuf_BUILD_CONFORMANCE OFF CACHE BOOL "" FORCE)
+set(protobuf_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+set(protobuf_BUILD_PROTOC_BINARIES ON CACHE BOOL "" FORCE)
+set(protobuf_WITH_ZLIB ON CACHE BOOL "" FORCE)
+
+# Abseil configuration
+set(ABSL_PROPAGATE_CXX_STD ON CACHE BOOL "" FORCE)
+set(ABSL_ENABLE_INSTALL OFF CACHE BOOL "" FORCE)
+set(ABSL_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+
+# Additional protobuf settings to avoid export conflicts
+set(protobuf_BUILD_LIBPROTOC ON CACHE BOOL "" FORCE)
+set(protobuf_BUILD_LIBPROTOBUF ON CACHE BOOL "" FORCE)
+set(protobuf_BUILD_LIBPROTOBUF_LITE ON CACHE BOOL "" FORCE)
+set(protobuf_INSTALL OFF CACHE BOOL "" FORCE)
+
+set(utf8_range_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(utf8_range_INSTALL OFF CACHE BOOL "" FORCE)
+
+# Declare gRPC with platform-specific versions
+if(WIN32 AND MSVC)
+  set(_GRPC_VERSION "v1.67.1")
+  set(_GRPC_VERSION_REASON "MSVC-compatible, avoids linker regressions")
+else()
+  set(_GRPC_VERSION "v1.75.1")
+  set(_GRPC_VERSION_REASON "ARM64 macOS + modern Clang compatibility")
+endif()
+
+message(STATUS "FetchContent gRPC version: ${_GRPC_VERSION} (${_GRPC_VERSION_REASON})")
+
+FetchContent_Declare(
+  grpc
+  GIT_REPOSITORY https://github.com/grpc/grpc.git
+  GIT_TAG        ${_GRPC_VERSION}
+  GIT_PROGRESS   TRUE
+  GIT_SHALLOW    TRUE
+  USES_TERMINAL_DOWNLOAD TRUE
+)
+
+# Save the current CMAKE_PREFIX_PATH and clear it temporarily
+# This prevents system packages from interfering
+set(_SAVED_CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH})
+set(CMAKE_PREFIX_PATH "")
+
+# Some toolchain presets set CMAKE_CROSSCOMPILING even when building for the
+# host (macOS arm64). gRPC treats that as a signal to locate host-side protoc
+# binaries via find_program, which fails since we rely on the bundled targets.
+# Suppress the flag when the host and target platforms match so the generator
+# expressions remain intact.
+set(_SAVED_CMAKE_CROSSCOMPILING ${CMAKE_CROSSCOMPILING})
+if(CMAKE_HOST_SYSTEM_NAME STREQUAL CMAKE_SYSTEM_NAME
+   AND CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL CMAKE_SYSTEM_PROCESSOR)
+  set(CMAKE_CROSSCOMPILING FALSE)
+endif()
+
+# Download and build in isolation
+FetchContent_MakeAvailable(grpc)
+
+# Restore cross-compiling flag
+set(CMAKE_CROSSCOMPILING ${_SAVED_CMAKE_CROSSCOMPILING})
+
+# Restore CMAKE_PREFIX_PATH
+set(CMAKE_PREFIX_PATH ${_SAVED_CMAKE_PREFIX_PATH})
+
+# Restore YAZE's C++ standard
+set(CMAKE_CXX_STANDARD ${_SAVED_CMAKE_CXX_STANDARD})
+
+# Verify targets
+if(NOT TARGET protoc)
+    message(FATAL_ERROR "Can not find target protoc")
+endif()
+if(NOT TARGET grpc_cpp_plugin)
+    message(FATAL_ERROR "Can not find target grpc_cpp_plugin")
+endif()
+
+set(_gRPC_PROTO_GENS_DIR ${CMAKE_BINARY_DIR}/gens)
+file(REMOVE_RECURSE ${_gRPC_PROTO_GENS_DIR})
+file(MAKE_DIRECTORY ${_gRPC_PROTO_GENS_DIR})
+
+get_target_property(_PROTOBUF_INCLUDE_DIRS libprotobuf INTERFACE_INCLUDE_DIRECTORIES)
+list(GET _PROTOBUF_INCLUDE_DIRS 0 _gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR)
+
+message(STATUS "gRPC setup complete")
+
+# Export Abseil targets from gRPC's bundled abseil for use by the rest of the project
+# This ensures version compatibility between gRPC and our project
+# Note: Order matters for some linkers - put base libraries first
+set(
+  ABSL_TARGETS
+  absl::base
+  absl::config
+  absl::core_headers
+  absl::utility
+  absl::memory
+  absl::container_memory
+  absl::strings
+  absl::str_format
+  absl::cord
+  absl::hash
+  absl::time
+  absl::status
+  absl::statusor
+  absl::flags
+  absl::flags_parse
+  absl::flags_usage
+  absl::flags_commandlineflag
+  absl::flags_marshalling
+  absl::flags_private_handle_accessor
+  absl::flags_program_name
+  absl::flags_config
+  absl::flags_reflection
+  absl::examine_stack
+  absl::stacktrace
+  absl::failure_signal_handler
+  absl::flat_hash_map
+  absl::synchronization
+  absl::symbolize
+)
+
+# Only expose absl::int128 when it's supported without warnings
+if(NOT WIN32)
+  list(APPEND ABSL_TARGETS absl::int128)
+endif()
+
+# ABSL_TARGETS is now available to the rest of the project via include()
+
+function(target_add_protobuf target)
+    if(NOT TARGET ${target})
+        message(FATAL_ERROR "Target ${target} doesn't exist")
+    endif()
+    if(NOT ARGN)
+        message(SEND_ERROR "Error: target_add_protobuf() called without any proto files")
+        return()
+    endif()
+
+    set(_protobuf_include_path -I . -I ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR})
+    foreach(FIL ${ARGN})
+        get_filename_component(ABS_FIL ${FIL} ABSOLUTE)
+        get_filename_component(FIL_WE ${FIL} NAME_WE)
+        file(RELATIVE_PATH REL_FIL ${CMAKE_CURRENT_SOURCE_DIR} ${ABS_FIL})
+        get_filename_component(REL_DIR ${REL_FIL} DIRECTORY)
+        if(NOT REL_DIR)
+            set(RELFIL_WE "${FIL_WE}")
+        else()
+            set(RELFIL_WE "${REL_DIR}/${FIL_WE}")
+        endif()
+
+        add_custom_command(
+        OUTPUT  "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.cc"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.h"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}_mock.grpc.pb.h"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.cc"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.h"
+        COMMAND $<TARGET_FILE:protoc>
+        ARGS --grpc_out=generate_mock_code=true:${_gRPC_PROTO_GENS_DIR}
+            --cpp_out=${_gRPC_PROTO_GENS_DIR}
+            --plugin=protoc-gen-grpc=$<TARGET_FILE:grpc_cpp_plugin>
+            ${_protobuf_include_path}
+            ${REL_FIL}
+        DEPENDS ${ABS_FIL} protoc grpc_cpp_plugin
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        COMMENT "Running gRPC C++ protocol buffer compiler on ${FIL}"
+        VERBATIM)
+
+        target_sources(${target} PRIVATE
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.cc"
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.h"
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}_mock.grpc.pb.h"
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.cc"
+            "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.h"
+        )
+        target_include_directories(${target} PUBLIC
+            $<BUILD_INTERFACE:${_gRPC_PROTO_GENS_DIR}>
+            $<BUILD_INTERFACE:${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR}>
+        )
+    endforeach()
+endfunction()

cmake/grpc_windows.cmake

@@ -0,0 +1,256 @@
+# Windows-optimized gRPC configuration using vcpkg
+# This file provides fast gRPC builds on Windows using pre-compiled packages
+#
+# Benefits:
+# - vcpkg build: ~5 minutes (pre-compiled)
+# - FetchContent build: ~45 minutes (compile from source)
+#
+# To use vcpkg (recommended):
+#   vcpkg install grpc:x64-windows
+#   cmake -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake ..
+
+cmake_minimum_required(VERSION 3.16)
+
+# Option to use vcpkg for gRPC on Windows (default OFF for CI reliability)
+option(YAZE_USE_VCPKG_GRPC "Use vcpkg pre-compiled gRPC packages (Windows only)" OFF)
+
+if(WIN32 AND YAZE_USE_VCPKG_GRPC AND DEFINED CMAKE_TOOLCHAIN_FILE)
+  message(STATUS "Attempting to use vcpkg gRPC packages for faster Windows builds...")
+  message(STATUS "  Note: If gRPC not in vcpkg.json, will fallback to FetchContent (recommended)")
+  
+  # Debug: Check if vcpkg toolchain is being used
+  if(DEFINED VCPKG_TOOLCHAIN)
+    message(STATUS "  vcpkg toolchain detected: ${VCPKG_TOOLCHAIN}")
+  endif()
+  if(DEFINED CMAKE_TOOLCHAIN_FILE)
+    message(STATUS "  CMAKE_TOOLCHAIN_FILE: ${CMAKE_TOOLCHAIN_FILE}")
+  endif()
+  
+  # Try to find gRPC via vcpkg (try both gRPC and grpc package names)
+  find_package(gRPC CONFIG QUIET)
+  if(NOT gRPC_FOUND)
+    find_package(grpc CONFIG QUIET)
+    if(grpc_FOUND)
+      set(gRPC_FOUND TRUE)
+    endif()
+  endif()
+  
+  find_package(Protobuf CONFIG QUIET)
+  
+  if(gRPC_FOUND AND Protobuf_FOUND)
+    message(STATUS "✓ Using vcpkg gRPC packages (fast build path)")
+
+    # Prevent Windows macro pollution in protobuf-generated headers
+    add_compile_definitions(
+        WIN32_LEAN_AND_MEAN  # Exclude rarely-used Windows headers
+        NOMINMAX             # Don't define min/max macros
+        NOGDI                # Exclude GDI (prevents DWORD and other macro conflicts)
+    )
+
+    
+    # Verify required targets exist (check both with and without gRPC:: namespace)
+    set(_grpc_target_found FALSE)
+    if(TARGET gRPC::grpc++)
+      message(STATUS "  Found gRPC::grpc++ target")
+      set(_grpc_target_found TRUE)
+      # Create aliases without namespace for compatibility with existing code
+      if(NOT TARGET grpc++)
+        add_library(grpc++ ALIAS gRPC::grpc++)
+      endif()
+      if(TARGET gRPC::grpc++_reflection AND NOT TARGET grpc++_reflection)
+        add_library(grpc++_reflection ALIAS gRPC::grpc++_reflection)
+      endif()
+    elseif(TARGET grpc++)
+      message(STATUS "  Found grpc++ target")
+      set(_grpc_target_found TRUE)
+    endif()
+    
+    if(NOT _grpc_target_found)
+      message(WARNING "gRPC found but grpc++ target missing - falling back to FetchContent")
+      message(STATUS "  Available targets containing 'grpc':")
+      get_property(_all_targets DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY BUILDSYSTEM_TARGETS)
+      foreach(_target ${_all_targets})
+        if(_target MATCHES "grpc" OR _target MATCHES "gRPC")
+          message(STATUS "    - ${_target}")
+        endif()
+      endforeach()
+      set(YAZE_GRPC_CONFIGURED FALSE PARENT_SCOPE)
+      return()
+    endif()
+    
+    # Handle protoc (check for both protoc and protobuf::protoc)
+    if(NOT TARGET protoc)
+      if(TARGET protobuf::protoc)
+        get_target_property(PROTOC_LOCATION protobuf::protoc IMPORTED_LOCATION_RELEASE)
+        if(NOT PROTOC_LOCATION)
+          get_target_property(PROTOC_LOCATION protobuf::protoc IMPORTED_LOCATION)
+        endif()
+        if(PROTOC_LOCATION)
+          add_executable(protoc IMPORTED)
+          set_target_properties(protoc PROPERTIES IMPORTED_LOCATION "${PROTOC_LOCATION}")
+          message(STATUS "  Found protoc at: ${PROTOC_LOCATION}")
+        else()
+          message(FATAL_ERROR "protoc executable not found in vcpkg package")
+        endif()
+      else()
+        message(FATAL_ERROR "protoc target not found in vcpkg gRPC package")
+      endif()
+    endif()
+    
+    # Handle grpc_cpp_plugin (check for both grpc_cpp_plugin and gRPC::grpc_cpp_plugin)
+    if(NOT TARGET grpc_cpp_plugin)
+      if(TARGET gRPC::grpc_cpp_plugin)
+        get_target_property(PLUGIN_LOCATION gRPC::grpc_cpp_plugin IMPORTED_LOCATION_RELEASE)
+        if(NOT PLUGIN_LOCATION)
+          get_target_property(PLUGIN_LOCATION gRPC::grpc_cpp_plugin IMPORTED_LOCATION)
+        endif()
+        if(PLUGIN_LOCATION)
+          add_executable(grpc_cpp_plugin IMPORTED)
+          set_target_properties(grpc_cpp_plugin PROPERTIES IMPORTED_LOCATION "${PLUGIN_LOCATION}")
+          message(STATUS "  Found grpc_cpp_plugin at: ${PLUGIN_LOCATION}")
+        endif()
+      else()
+        # Try find_program as fallback
+        find_program(GRPC_CPP_PLUGIN grpc_cpp_plugin HINTS ${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/tools/grpc)
+        if(GRPC_CPP_PLUGIN)
+          add_executable(grpc_cpp_plugin IMPORTED)
+          set_target_properties(grpc_cpp_plugin PROPERTIES IMPORTED_LOCATION "${GRPC_CPP_PLUGIN}")
+          message(STATUS "  Found grpc_cpp_plugin at: ${GRPC_CPP_PLUGIN}")
+        else()
+          message(FATAL_ERROR "grpc_cpp_plugin not found in vcpkg gRPC package")
+        endif()
+      endif()
+    endif()
+    
+    # Set variables for compatibility with rest of build system
+    set(_gRPC_PROTOBUF_PROTOC_EXECUTABLE $<TARGET_FILE:protoc> PARENT_SCOPE)
+    set(_gRPC_CPP_PLUGIN $<TARGET_FILE:grpc_cpp_plugin> PARENT_SCOPE)
+    set(_gRPC_PROTO_GENS_DIR ${CMAKE_BINARY_DIR}/gens)
+    file(MAKE_DIRECTORY ${_gRPC_PROTO_GENS_DIR})
+    set(_gRPC_PROTO_GENS_DIR ${_gRPC_PROTO_GENS_DIR} PARENT_SCOPE)
+    
+    # Export gRPC library targets (vcpkg uses gRPC:: namespace)
+    # Use the namespaced targets directly
+    set(_GRPC_GRPCPP_LIBRARY gRPC::grpc++)
+    set(_GRPC_REFLECTION_LIBRARY gRPC::grpc++_reflection)
+    
+    # Export Abseil targets from vcpkg (critical for linking!)
+    # Note: Abseil targets use absl:: namespace consistently
+    set(ABSL_TARGETS
+      absl::base
+      absl::config
+      absl::core_headers
+      absl::utility
+      absl::memory
+      absl::container_memory
+      absl::strings
+      absl::strings_internal
+      absl::str_format
+      absl::str_format_internal
+      absl::cord
+      absl::hash
+      absl::time
+      absl::time_zone
+      absl::status
+      absl::statusor
+      absl::flags
+      absl::flags_parse
+      absl::flags_usage
+      absl::flags_commandlineflag
+      absl::flags_marshalling
+      absl::flags_private_handle_accessor
+      absl::flags_program_name
+      absl::flags_config
+      absl::flags_reflection
+      absl::examine_stack
+      absl::stacktrace
+      absl::failure_signal_handler
+      absl::flat_hash_map
+      absl::synchronization
+      absl::symbolize
+      absl::strerror
+      PARENT_SCOPE
+    )
+    
+    # Export protobuf targets (vcpkg uses protobuf:: namespace)
+    set(YAZE_PROTOBUF_TARGETS protobuf::libprotobuf PARENT_SCOPE)
+    
+    # Get protobuf include directories for proto generation
+    get_target_property(_PROTOBUF_INCLUDE_DIRS protobuf::libprotobuf 
+                        INTERFACE_INCLUDE_DIRECTORIES)
+    if(_PROTOBUF_INCLUDE_DIRS)
+      list(GET _PROTOBUF_INCLUDE_DIRS 0 _gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR)
+      set(_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR} PARENT_SCOPE)
+    endif()
+    
+    # Define target_add_protobuf() function for proto compilation (needed by vcpkg path)
+    function(target_add_protobuf target)
+        if(NOT TARGET ${target})
+            message(FATAL_ERROR "Target ${target} doesn't exist")
+        endif()
+        if(NOT ARGN)
+            message(SEND_ERROR "Error: target_add_protobuf() called without any proto files")
+            return()
+        endif()
+
+        set(_protobuf_include_path -I . -I ${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR})
+        foreach(FIL ${ARGN})
+            get_filename_component(ABS_FIL ${FIL} ABSOLUTE)
+            get_filename_component(FIL_WE ${FIL} NAME_WE)
+            file(RELATIVE_PATH REL_FIL ${CMAKE_CURRENT_SOURCE_DIR} ${ABS_FIL})
+            get_filename_component(REL_DIR ${REL_FIL} DIRECTORY)
+            if(NOT REL_DIR)
+                set(RELFIL_WE "${FIL_WE}")
+            else()
+                set(RELFIL_WE "${REL_DIR}/${FIL_WE}")
+            endif()
+
+            add_custom_command(
+            OUTPUT  "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.cc"
+                    "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.h"
+                    "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}_mock.grpc.pb.h"
+                    "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.cc"
+                    "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.h"
+            COMMAND ${_gRPC_PROTOBUF_PROTOC_EXECUTABLE}
+            ARGS --grpc_out=generate_mock_code=true:${_gRPC_PROTO_GENS_DIR}
+                --cpp_out=${_gRPC_PROTO_GENS_DIR}
+                --plugin=protoc-gen-grpc=${_gRPC_CPP_PLUGIN}
+                ${_protobuf_include_path}
+                ${REL_FIL}
+            DEPENDS ${ABS_FIL} protoc grpc_cpp_plugin
+            WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+            COMMENT "Running gRPC C++ protocol buffer compiler on ${FIL}"
+            VERBATIM)
+
+            target_sources(${target} PRIVATE
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.cc"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.grpc.pb.h"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}_mock.grpc.pb.h"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.cc"
+                "${_gRPC_PROTO_GENS_DIR}/${RELFIL_WE}.pb.h"
+            )
+            target_include_directories(${target} PUBLIC
+                $<BUILD_INTERFACE:${_gRPC_PROTO_GENS_DIR}>
+                $<BUILD_INTERFACE:${_gRPC_PROTOBUF_WELLKNOWN_INCLUDE_DIR}>
+            )
+        endforeach()
+    endfunction()
+    
+    # Skip the FetchContent path
+    set(YAZE_GRPC_CONFIGURED TRUE PARENT_SCOPE)
+    message(STATUS "gRPC setup complete via vcpkg (includes bundled Abseil)")
+    return()
+  else()
+    message(STATUS "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    message(STATUS "  vcpkg gRPC not found (expected if removed from vcpkg.json)")
+    message(STATUS "  Using FetchContent build (faster with caching)")
+    message(STATUS "  First build: ~10-15 min, subsequent: <1 min (cached)")
+    message(STATUS "  Using gRPC v1.75.1 (latest stable)")
+    message(STATUS "  Note: BoringSSL ASM disabled for clang-cl compatibility")
+    message(STATUS "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+  endif()
+endif()
+
+# If we reach here, vcpkg wasn't used - fall back to standard grpc.cmake
+message(STATUS "Using FetchContent for gRPC (recommended path for Windows)")
+set(YAZE_GRPC_CONFIGURED FALSE PARENT_SCOPE)

cmake/imgui.cmake

@@ -1,52 +0,0 @@
-# gui libraries ---------------------------------------------------------------
-set(IMGUI_PATH  ${CMAKE_SOURCE_DIR}/src/lib/imgui)
-file(GLOB IMGUI_SOURCES ${IMGUI_PATH}/*.cpp)
-set(IMGUI_BACKEND_SOURCES
-  ${IMGUI_PATH}/backends/imgui_impl_sdl2.cpp
-  ${IMGUI_PATH}/backends/imgui_impl_sdlrenderer2.cpp
-  ${IMGUI_PATH}/misc/cpp/imgui_stdlib.cpp
-)
-add_library("ImGui" STATIC ${IMGUI_SOURCES} ${IMGUI_BACKEND_SOURCES})
-target_include_directories("ImGui" PUBLIC ${IMGUI_PATH} ${IMGUI_PATH}/backends)
-target_include_directories(ImGui PUBLIC ${SDL2_INCLUDE_DIR})
-target_compile_definitions(ImGui PUBLIC
-  IMGUI_IMPL_OPENGL_LOADER_CUSTOM=<SDL2/SDL_opengl.h>  GL_GLEXT_PROTOTYPES=1)
-
-# Set up ImGui Test Engine sources and target conditionally
-if(YAZE_ENABLE_UI_TESTS)
-  set(IMGUI_TEST_ENGINE_PATH ${CMAKE_SOURCE_DIR}/src/lib/imgui_test_engine/imgui_test_engine)
-  file(GLOB IMGUI_TEST_ENGINE_SOURCES ${IMGUI_TEST_ENGINE_PATH}/*.cpp)
-  add_library("ImGuiTestEngine" STATIC ${IMGUI_TEST_ENGINE_SOURCES})
-  target_include_directories(ImGuiTestEngine PUBLIC ${IMGUI_PATH} ${CMAKE_SOURCE_DIR}/src/lib)
-  target_link_libraries(ImGuiTestEngine PUBLIC ImGui)
-  
-  # Enable test engine definitions only when UI tests are enabled
-  target_compile_definitions(ImGuiTestEngine PUBLIC 
-    IMGUI_ENABLE_TEST_ENGINE=1 
-    IMGUI_TEST_ENGINE_ENABLE_COROUTINE_STDTHREAD_IMPL=1)
-  
-  # Also define for targets that link to ImGuiTestEngine
-  set(IMGUI_TEST_ENGINE_DEFINITIONS 
-    IMGUI_ENABLE_TEST_ENGINE=1 
-    IMGUI_TEST_ENGINE_ENABLE_COROUTINE_STDTHREAD_IMPL=1)
-  
-  # Make ImGuiTestEngine target available
-  set(IMGUI_TEST_ENGINE_TARGET ImGuiTestEngine)
-else()
-  # Create empty variables when UI tests are disabled
-  set(IMGUI_TEST_ENGINE_SOURCES "")
-  set(IMGUI_TEST_ENGINE_TARGET "")
-  set(IMGUI_TEST_ENGINE_DEFINITIONS "")
-endif()
-
-set(
-  IMGUI_SRC
-  ${IMGUI_PATH}/imgui.cpp
-  ${IMGUI_PATH}/imgui_demo.cpp
-  ${IMGUI_PATH}/imgui_draw.cpp
-  ${IMGUI_PATH}/imgui_widgets.cpp
-  ${IMGUI_PATH}/backends/imgui_impl_sdl2.cpp
-  ${IMGUI_PATH}/backends/imgui_impl_sdlrenderer2.cpp
-  ${IMGUI_PATH}/misc/cpp/imgui_stdlib.cpp
-)
-

cmake/llvm-brew.toolchain.cmake

@@ -0,0 +1,45 @@
+# cmake/toolchains/homebrew-llvm.toolchain.cmake
+#
+# CMake Toolchain File for using the Homebrew LLVM/Clang installation on macOS. 
+# This ensures that the main project and all dependencies (like gRPC) use the
+# correct compiler and header search paths.
+
+# 1. Set the target system (macOS)
+set(CMAKE_SYSTEM_NAME Darwin)
+
+# 2. Find the Homebrew LLVM installation path
+# We use execute_process to make this portable across machine architectures.
+execute_process(
+  COMMAND brew --prefix llvm@18
+  OUTPUT_VARIABLE HOMEBREW_LLVM_PREFIX
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+
+if(NOT EXISTS "${HOMEBREW_LLVM_PREFIX}")
+  message(FATAL_ERROR "Homebrew LLVM not found. Please run 'brew install llvm'. Path: ${HOMEBREW_LLVM_PREFIX}")
+endif()
+
+message(STATUS "Using Homebrew LLVM from: ${HOMEBREW_LLVM_PREFIX}")
+
+# 3. Set the C and C++ compilers
+set(CMAKE_C_COMPILER "${HOMEBREW_LLVM_PREFIX}/bin/clang")
+set(CMAKE_CXX_COMPILER "${HOMEBREW_LLVM_PREFIX}/bin/clang++")
+
+# 4. Set the system root (sysroot) to the macOS SDK
+# This correctly points to the system-level headers and libraries.
+execute_process(
+  COMMAND xcrun --show-sdk-path
+  OUTPUT_VARIABLE CMAKE_OSX_SYSROOT
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+set(CMAKE_SYSROOT "${CMAKE_OSX_SYSROOT}")
+message(STATUS "Using macOS SDK at: ${CMAKE_SYSROOT}")
+
+# 5. **[THE CRITICAL FIX]** Explicitly define the C++ standard library include directory.
+# This forces CMake to add Homebrew's libc++ headers to the search path *before*
+# any other system paths, resolving the header conflict for the main project
+  # and all dependencies.
+set(CMAKE_CXX_STANDARD_INCLUDE_DIRECTORIES "${HOMEBREW_LLVM_PREFIX}/include/c++/v1")
+
+# 6. Set the default installation path for macOS frameworks
+set(CMAKE_FIND_FRAMEWORK FIRST)

cmake/options.cmake

@@ -0,0 +1,125 @@
+# YAZE Build Options
+# Centralized feature flags and build configuration
+
+# Core build options
+option(YAZE_BUILD_GUI "Build GUI application" ON)
+option(YAZE_BUILD_CLI "Build CLI tools (shared libraries)" ON)
+option(YAZE_BUILD_Z3ED "Build z3ed CLI executable" ON)
+option(YAZE_BUILD_EMU "Build emulator components" ON)
+option(YAZE_BUILD_LIB "Build static library" ON)
+option(YAZE_BUILD_TESTS "Build test suite" ON)
+
+# Feature flags
+option(YAZE_ENABLE_GRPC "Enable gRPC agent support" ON)
+option(YAZE_ENABLE_JSON "Enable JSON support" ON)
+option(YAZE_ENABLE_AI "Enable AI agent features" OFF)
+
+# Advanced feature toggles
+option(YAZE_ENABLE_REMOTE_AUTOMATION
+  "Enable remote automation services (gRPC/protobuf servers + GUI automation clients)"
+  ${YAZE_ENABLE_GRPC})
+option(YAZE_ENABLE_AI_RUNTIME
+  "Enable AI runtime integrations (Gemini/Ollama, advanced routing, proposal planning)"
+  ${YAZE_ENABLE_AI})
+option(YAZE_BUILD_AGENT_UI
+  "Build ImGui-based agent/chat panels inside the GUI"
+  ${YAZE_BUILD_GUI})
+option(YAZE_ENABLE_AGENT_CLI
+  "Build the conversational agent CLI stack (z3ed agent commands)"
+  ${YAZE_BUILD_CLI})
+option(YAZE_ENABLE_HTTP_API
+  "Enable HTTP REST API server for external agent access"
+  ${YAZE_ENABLE_AGENT_CLI})
+
+if((YAZE_BUILD_CLI OR YAZE_BUILD_Z3ED) AND NOT YAZE_ENABLE_AGENT_CLI)
+  set(YAZE_ENABLE_AGENT_CLI ON CACHE BOOL "Build the conversational agent CLI stack (z3ed agent commands)" FORCE)
+endif()
+
+if(YAZE_ENABLE_HTTP_API AND NOT YAZE_ENABLE_AGENT_CLI)
+  set(YAZE_ENABLE_AGENT_CLI ON CACHE BOOL "Build the conversational agent CLI stack (z3ed agent commands)" FORCE)
+endif()
+
+# Build optimizations
+option(YAZE_ENABLE_LTO "Enable link-time optimization" OFF)
+option(YAZE_ENABLE_SANITIZERS "Enable AddressSanitizer/UBSanitizer" OFF)
+option(YAZE_ENABLE_COVERAGE "Enable code coverage" OFF)
+option(YAZE_UNITY_BUILD "Enable Unity (Jumbo) builds" OFF)
+
+# Platform-specific options
+option(YAZE_USE_VCPKG "Use vcpkg for Windows dependencies" OFF)
+option(YAZE_USE_SYSTEM_DEPS "Use system package manager for dependencies" OFF)
+option(YAZE_USE_SDL3 "Use SDL3 instead of SDL2 (experimental)" OFF)
+
+# Development options
+option(YAZE_ENABLE_ROM_TESTS "Enable tests that require ROM files" OFF)
+option(YAZE_ENABLE_BENCHMARK_TESTS "Enable benchmark/performance tests" OFF)
+option(YAZE_MINIMAL_BUILD "Minimal build for CI (disable optional features)" OFF)
+option(YAZE_VERBOSE_BUILD "Verbose build output" OFF)
+
+# Install options
+option(YAZE_INSTALL_LIB "Install static library" OFF)
+option(YAZE_INSTALL_HEADERS "Install public headers" ON)
+
+# Set preprocessor definitions based on options
+if(YAZE_ENABLE_REMOTE_AUTOMATION AND NOT YAZE_ENABLE_GRPC)
+  set(YAZE_ENABLE_GRPC ON CACHE BOOL "Enable gRPC agent support" FORCE)
+endif()
+
+if(NOT YAZE_ENABLE_REMOTE_AUTOMATION)
+  set(YAZE_ENABLE_GRPC OFF CACHE BOOL "Enable gRPC agent support" FORCE)
+endif()
+
+if(YAZE_ENABLE_GRPC)
+  add_compile_definitions(YAZE_WITH_GRPC)
+endif()
+
+if(YAZE_ENABLE_JSON)
+  add_compile_definitions(YAZE_WITH_JSON)
+endif()
+
+if(YAZE_ENABLE_AI_RUNTIME AND NOT YAZE_ENABLE_AI)
+  set(YAZE_ENABLE_AI ON CACHE BOOL "Enable AI agent features" FORCE)
+endif()
+
+if(NOT YAZE_ENABLE_AI_RUNTIME)
+  set(YAZE_ENABLE_AI OFF CACHE BOOL "Enable AI agent features" FORCE)
+endif()
+
+if(YAZE_ENABLE_AI)
+  add_compile_definitions(Z3ED_AI)
+endif()
+
+if(YAZE_ENABLE_AI_RUNTIME)
+  add_compile_definitions(YAZE_AI_RUNTIME_AVAILABLE)
+endif()
+
+if(YAZE_ENABLE_HTTP_API)
+  add_compile_definitions(YAZE_HTTP_API_ENABLED)
+endif()
+
+# Print configuration summary
+message(STATUS "=== YAZE Build Configuration ===")
+message(STATUS "GUI Application: ${YAZE_BUILD_GUI}")
+message(STATUS "CLI Tools: ${YAZE_BUILD_CLI}")
+message(STATUS "z3ed CLI: ${YAZE_BUILD_Z3ED}")
+message(STATUS "Emulator: ${YAZE_BUILD_EMU}")
+message(STATUS "Static Library: ${YAZE_BUILD_LIB}")
+message(STATUS "Tests: ${YAZE_BUILD_TESTS}")
+if(YAZE_USE_SDL3)
+  message(STATUS "SDL Version: SDL3 (experimental)")
+else()
+  message(STATUS "SDL Version: SDL2 (stable)")
+endif()
+message(STATUS "gRPC Support: ${YAZE_ENABLE_GRPC}")
+message(STATUS "Remote Automation: ${YAZE_ENABLE_REMOTE_AUTOMATION}")
+message(STATUS "JSON Support: ${YAZE_ENABLE_JSON}")
+message(STATUS "AI Runtime: ${YAZE_ENABLE_AI_RUNTIME}")
+message(STATUS "AI Features (legacy): ${YAZE_ENABLE_AI}")
+message(STATUS "Agent UI Panels: ${YAZE_BUILD_AGENT_UI}")
+message(STATUS "Agent CLI Stack: ${YAZE_ENABLE_AGENT_CLI}")
+message(STATUS "HTTP API Server: ${YAZE_ENABLE_HTTP_API}")
+message(STATUS "LTO: ${YAZE_ENABLE_LTO}")
+message(STATUS "Sanitizers: ${YAZE_ENABLE_SANITIZERS}")
+message(STATUS "Coverage: ${YAZE_ENABLE_COVERAGE}")
+message(STATUS "=================================")
+

cmake/packaging.cmake

@@ -141,23 +141,42 @@ set(CPACK_COMPONENT_DOCUMENTATION_DISPLAY_NAME "Documentation")
 set(CPACK_COMPONENT_DOCUMENTATION_DESCRIPTION "User and developer documentation")
 set(CPACK_COMPONENT_DOCUMENTATION_REQUIRED FALSE)
 
+# Platform-specific install paths
+# The asset paths must match what platform_paths.cc FindAsset() searches for
+if(WIN32)
+    # Windows: flat structure (exe and assets/ at same level)
+    set(YAZE_INSTALL_BINDIR ".")
+    set(YAZE_INSTALL_DATADIR ".")
+    set(YAZE_INSTALL_DOCDIR ".")
+elseif(APPLE)
+    # macOS: flat structure for DMG (app bundle handles its own resources)
+    set(YAZE_INSTALL_BINDIR ".")
+    set(YAZE_INSTALL_DATADIR ".")
+    set(YAZE_INSTALL_DOCDIR ".")
+else()
+    # Linux: FHS structure - assets at share/yaze/assets (matches FindAsset search)
+    set(YAZE_INSTALL_BINDIR ${CMAKE_INSTALL_BINDIR})
+    set(YAZE_INSTALL_DATADIR "${CMAKE_INSTALL_DATADIR}/yaze")
+    set(YAZE_INSTALL_DOCDIR "${CMAKE_INSTALL_DOCDIR}")
+endif()
+
 # Installation components
 if(APPLE)
     install(TARGETS yaze
-        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
-        BUNDLE DESTINATION ${CMAKE_INSTALL_BINDIR}
+        RUNTIME DESTINATION ${YAZE_INSTALL_BINDIR}
+        BUNDLE DESTINATION ${YAZE_INSTALL_BINDIR}
         COMPONENT applications
     )
 else()
     install(TARGETS yaze
-        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+        RUNTIME DESTINATION ${YAZE_INSTALL_BINDIR}
         COMPONENT applications
     )
 endif()
 
 # Install assets
 install(DIRECTORY ${CMAKE_SOURCE_DIR}/assets/
-    DESTINATION ${CMAKE_INSTALL_DATADIR}/yaze/assets
+    DESTINATION ${YAZE_INSTALL_DATADIR}/assets
     COMPONENT applications
     PATTERN "*.png"
     PATTERN "*.ttf"
@@ -168,12 +187,12 @@ install(DIRECTORY ${CMAKE_SOURCE_DIR}/assets/
 install(FILES
     ${CMAKE_SOURCE_DIR}/README.md
     ${CMAKE_SOURCE_DIR}/LICENSE
-    DESTINATION ${CMAKE_INSTALL_DOCDIR}
+    DESTINATION ${YAZE_INSTALL_DOCDIR}
     COMPONENT documentation
 )
 
 install(DIRECTORY ${CMAKE_SOURCE_DIR}/docs/
-    DESTINATION ${CMAKE_INSTALL_DOCDIR}
+    DESTINATION ${YAZE_INSTALL_DOCDIR}
     COMPONENT documentation
     PATTERN "*.md"
     PATTERN "*.html"

cmake/packaging/cpack.cmake

@@ -0,0 +1,107 @@
+# CPack Configuration - flat packages for all platforms
+#
+# Structure:
+#   root/
+#     yaze(.exe)
+#     z3ed(.exe)           (if built)
+#     README.md
+#     LICENSE
+#     assets/...
+
+set(CPACK_PACKAGE_NAME "yaze")
+set(CPACK_PACKAGE_VENDOR "scawful")
+set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "Yet Another Zelda3 Editor")
+set(CPACK_PACKAGE_VERSION_MAJOR ${YAZE_VERSION_MAJOR})
+set(CPACK_PACKAGE_VERSION_MINOR ${YAZE_VERSION_MINOR})
+set(CPACK_PACKAGE_VERSION_PATCH ${YAZE_VERSION_PATCH})
+set(CPACK_PACKAGE_VERSION "${YAZE_VERSION_MAJOR}.${YAZE_VERSION_MINOR}.${YAZE_VERSION_PATCH}")
+set(CPACK_PACKAGE_DIRECTORY "${CMAKE_BINARY_DIR}/packages")
+set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_SOURCE_DIR}/LICENSE")
+set(CPACK_RESOURCE_FILE_README "${CMAKE_SOURCE_DIR}/README.md")
+
+set(CPACK_COMPONENTS_ALL yaze)
+set(CPACK_COMPONENT_YAZE_DISPLAY_NAME "YAZE Editor")
+set(CPACK_COMPONENT_YAZE_DESCRIPTION "Main YAZE application and libraries")
+
+# Populate runtime library list (needed on Windows)
+set(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS ON)
+set(CMAKE_INSTALL_UCRT_LIBRARIES ON)
+include(InstallRequiredSystemLibraries)
+
+if(APPLE)
+    include(cmake/packaging/macos.cmake)
+
+    install(TARGETS yaze
+        BUNDLE DESTINATION .
+        COMPONENT yaze)
+
+    if(TARGET z3ed)
+        install(TARGETS z3ed
+            RUNTIME DESTINATION .
+            COMPONENT yaze)
+    endif()
+
+    install(DIRECTORY ${CMAKE_SOURCE_DIR}/assets/
+        DESTINATION assets
+        COMPONENT yaze)
+
+    install(FILES
+        ${CMAKE_SOURCE_DIR}/README.md
+        ${CMAKE_SOURCE_DIR}/LICENSE
+        DESTINATION .
+        COMPONENT yaze)
+
+elseif(WIN32)
+    include(cmake/packaging/windows.cmake)
+
+    install(TARGETS yaze
+        RUNTIME DESTINATION .
+        COMPONENT yaze)
+
+    if(TARGET z3ed)
+        install(TARGETS z3ed
+            RUNTIME DESTINATION .
+            COMPONENT yaze)
+    endif()
+
+    install(DIRECTORY ${CMAKE_SOURCE_DIR}/assets/
+        DESTINATION assets
+        COMPONENT yaze)
+
+    install(FILES
+        ${CMAKE_SOURCE_DIR}/README.md
+        ${CMAKE_SOURCE_DIR}/LICENSE
+        DESTINATION .
+        COMPONENT yaze)
+
+    if(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS)
+        install(FILES ${CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS}
+            DESTINATION .
+            COMPONENT yaze)
+    endif()
+
+else()
+    include(cmake/packaging/linux.cmake)
+
+    install(TARGETS yaze
+        RUNTIME DESTINATION .
+        COMPONENT yaze)
+
+    if(TARGET z3ed)
+        install(TARGETS z3ed
+            RUNTIME DESTINATION .
+            COMPONENT yaze)
+    endif()
+
+    install(DIRECTORY ${CMAKE_SOURCE_DIR}/assets/
+        DESTINATION assets
+        COMPONENT yaze)
+
+    install(FILES
+        ${CMAKE_SOURCE_DIR}/README.md
+        ${CMAKE_SOURCE_DIR}/LICENSE
+        DESTINATION .
+        COMPONENT yaze)
+endif()
+
+include(CPack)

cmake/packaging/linux.cmake

@@ -0,0 +1,17 @@
+# Linux Packaging Configuration
+
+# DEB package
+set(CPACK_GENERATOR "DEB;TGZ")
+set(CPACK_DEBIAN_PACKAGE_MAINTAINER "scawful")
+set(CPACK_DEBIAN_PACKAGE_SECTION "games")
+set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional")
+set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6, libstdc++6, libsdl2-2.0-0")
+
+# RPM package
+set(CPACK_RPM_PACKAGE_LICENSE "MIT")
+set(CPACK_RPM_PACKAGE_GROUP "Applications/Games")
+set(CPACK_RPM_PACKAGE_REQUIRES "glibc, libstdc++, SDL2")
+
+# Tarball
+set(CPACK_TGZ_PACKAGE_NAME "yaze-${CPACK_PACKAGE_VERSION}-linux-x64")
+

cmake/packaging/macos.cmake

@@ -0,0 +1,24 @@
+# macOS Packaging Configuration
+
+# Create .dmg package
+set(CPACK_GENERATOR "DragNDrop")
+set(CPACK_DMG_VOLUME_NAME "yaze")
+set(CPACK_DMG_FORMAT "UDZO")
+set(CPACK_DMG_BACKGROUND_IMAGE "${CMAKE_SOURCE_DIR}/assets/yaze.png")
+
+# App bundle configuration
+set(CPACK_BUNDLE_NAME "yaze")
+set(CPACK_BUNDLE_PACKAGE_TYPE "APPL")
+set(CPACK_BUNDLE_ICON "${CMAKE_SOURCE_DIR}/assets/yaze.icns")
+
+# Code signing (if available)
+if(DEFINED ENV{CODESIGN_IDENTITY})
+  set(CPACK_BUNDLE_APPLE_CERT_APP "$ENV{CODESIGN_IDENTITY}")
+  set(CPACK_BUNDLE_APPLE_CODESIGN_FORCE "ON")
+endif()
+
+# Notarization (if available)
+if(DEFINED ENV{NOTARIZATION_CREDENTIALS})
+  set(CPACK_BUNDLE_APPLE_NOTARIZATION_CREDENTIALS "$ENV{NOTARIZATION_CREDENTIALS}")
+endif()
+

cmake/packaging/windows.cmake

@@ -0,0 +1,22 @@
+# Windows Packaging Configuration
+
+# NSIS installer
+set(CPACK_GENERATOR "NSIS;ZIP")
+set(CPACK_NSIS_PACKAGE_NAME "YAZE Editor")
+set(CPACK_NSIS_DISPLAY_NAME "YAZE Editor v${CPACK_PACKAGE_VERSION}")
+set(CPACK_NSIS_PACKAGE_VERSION "${CPACK_PACKAGE_VERSION}")
+set(CPACK_NSIS_CONTACT "scawful")
+set(CPACK_NSIS_URL_INFO_ABOUT "https://github.com/scawful/yaze")
+set(CPACK_NSIS_HELP_LINK "https://github.com/scawful/yaze")
+set(CPACK_NSIS_URL_INFO_ABOUT "https://github.com/scawful/yaze")
+set(CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL ON)
+
+# ZIP package
+set(CPACK_ZIP_PACKAGE_NAME "yaze-${CPACK_PACKAGE_VERSION}-windows-x64")
+
+# Code signing (if available)
+if(DEFINED ENV{SIGNTOOL_CERTIFICATE})
+  set(CPACK_NSIS_SIGN_TOOL "signtool.exe")
+  set(CPACK_NSIS_SIGN_COMMAND "${ENV{SIGNTOOL_CERTIFICATE}}")
+endif()
+

cmake/sdl2.cmake

@@ -1,54 +1,66 @@
 # SDL2
-if (UNIX OR MINGW OR WIN32)
-  add_subdirectory(src/lib/SDL)
-  # When using bundled SDL, use the static target and set include directories
+# On Windows with vcpkg, prefer vcpkg packages for faster builds
+if(WIN32)
+  # Disable pkgconfig for SDL on Windows (prevents MSYS2 download failures in vcpkg)
+  set(SDL_PKGCONFIG OFF CACHE BOOL "Disable pkgconfig on Windows" FORCE)
+  
+  # Try to find SDL2 via vcpkg first if toolchain is available
+  if(DEFINED CMAKE_TOOLCHAIN_FILE AND EXISTS "${CMAKE_TOOLCHAIN_FILE}")
+    find_package(SDL2 CONFIG QUIET)
+    if(SDL2_FOUND OR TARGET SDL2::SDL2)
+      # Use vcpkg SDL2
+      if(TARGET SDL2::SDL2)
+        set(SDL_TARGETS SDL2::SDL2)
+        if(TARGET SDL2::SDL2main)
+          list(PREPEND SDL_TARGETS SDL2::SDL2main)
+        endif()
+        list(APPEND SDL_TARGETS ws2_32)
+        add_definitions("-DSDL_MAIN_HANDLED")
+        message(STATUS "✓ Using vcpkg SDL2")
+        
+        # Get SDL2 include directories for reference
+        get_target_property(SDL2_INCLUDE_DIR SDL2::SDL2 INTERFACE_INCLUDE_DIRECTORIES)
+        set(SDL2_INCLUDE_DIRS ${SDL2_INCLUDE_DIR})
+        return()
+      endif()
+    endif()
+  endif()
+  
+  # Fall back to bundled SDL if vcpkg not available or SDL2 not found
+  if(EXISTS "${CMAKE_SOURCE_DIR}/ext/SDL/CMakeLists.txt")
+    message(STATUS "○ vcpkg SDL2 not found, using bundled SDL2")
+    add_subdirectory(ext/SDL)
     set(SDL_TARGETS SDL2-static)
     set(SDL2_INCLUDE_DIR 
-    ${CMAKE_SOURCE_DIR}/src/lib/SDL/include
-    ${CMAKE_BINARY_DIR}/src/lib/SDL/include
-    ${CMAKE_BINARY_DIR}/src/lib/SDL/include-config-${CMAKE_BUILD_TYPE}
+      ${CMAKE_SOURCE_DIR}/ext/SDL/include
+      ${CMAKE_BINARY_DIR}/ext/SDL/include
+      ${CMAKE_BINARY_DIR}/ext/SDL/include-config-${CMAKE_BUILD_TYPE}
     )
-  # Also set for consistency with bundled SDL
     set(SDL2_INCLUDE_DIRS ${SDL2_INCLUDE_DIR})
-else()
-  find_package(SDL2)
-  # When using system SDL, use the imported targets
-  set(SDL_TARGETS SDL2::SDL2)
-  if(WIN32)
-    list(PREPEND SDL_TARGETS SDL2::SDL2main ws2_32)
-    add_definitions("-DSDL_MAIN_HANDLED")
+    if(TARGET SDL2main)
+      list(PREPEND SDL_TARGETS SDL2main)
     endif()
+    list(APPEND SDL_TARGETS ws2_32)
+    add_definitions("-DSDL_MAIN_HANDLED")
+  else()
+    message(FATAL_ERROR "SDL2 not found via vcpkg and bundled SDL2 not available. Please install via vcpkg or ensure submodules are initialized.")
+  endif()
+elseif(UNIX OR MINGW)
+  # Non-Windows: use bundled SDL
+  add_subdirectory(ext/SDL)
+  set(SDL_TARGETS SDL2-static)
+  set(SDL2_INCLUDE_DIR 
+    ${CMAKE_SOURCE_DIR}/ext/SDL/include
+    ${CMAKE_BINARY_DIR}/ext/SDL/include
+    ${CMAKE_BINARY_DIR}/ext/SDL/include-config-${CMAKE_BUILD_TYPE}
+  )
+  set(SDL2_INCLUDE_DIRS ${SDL2_INCLUDE_DIR})
+  message(STATUS "Using bundled SDL2")
+else()
+  # Fallback: try to find system SDL
+  find_package(SDL2 REQUIRED)
+  set(SDL_TARGETS SDL2::SDL2)
+  message(STATUS "Using system SDL2")
 endif()
 
-# libpng and ZLIB dependencies  
-if(WIN32)
-  # Windows builds with vcpkg (OpenGL/GLEW removed to avoid MSYS2 issues)
-  if(NOT YAZE_MINIMAL_BUILD)
-    find_package(ZLIB REQUIRED)
-    find_package(PNG REQUIRED)
-  else()
-    # For CI/minimal builds, try to find but don't require
-    find_package(ZLIB QUIET)
-    find_package(PNG QUIET)
-    if(NOT ZLIB_FOUND OR NOT PNG_FOUND)
-      message(STATUS "PNG/ZLIB not found in minimal build, some features may be disabled")
-      set(PNG_FOUND FALSE)
-      set(PNG_LIBRARIES "")
-      set(PNG_INCLUDE_DIRS "")
-    endif()
-  endif()
-elseif(YAZE_MINIMAL_BUILD)
-  # For CI builds on other platforms, try to find but don't require
-  find_package(ZLIB QUIET)
-  find_package(PNG QUIET)
-  if(NOT ZLIB_FOUND OR NOT PNG_FOUND)
-    message(STATUS "PNG/ZLIB not found in minimal build, some features may be disabled")
-    set(PNG_FOUND FALSE)
-    set(PNG_LIBRARIES "")
-    set(PNG_INCLUDE_DIRS "")
-  endif()
-else()
-  # Regular builds require these dependencies
-  find_package(ZLIB REQUIRED)
-  find_package(PNG REQUIRED)
-endif()
+# PNG and ZLIB dependencies removed

cmake/toolchains/linux-gcc.cmake

@@ -0,0 +1,22 @@
+# Linux GCC Toolchain
+# Optimized for Ubuntu 22.04+ with GCC 12+
+
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_C_COMPILER gcc)
+set(CMAKE_CXX_COMPILER g++)
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Compiler flags
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -Wpedantic")
+set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g -O0")
+set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3 -DNDEBUG")
+
+# Link flags
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,--as-needed")
+
+# Find packages
+find_package(PkgConfig REQUIRED)
+

cmake/toolchains/macos-clang.cmake

@@ -0,0 +1,25 @@
+# macOS Clang Toolchain
+# Optimized for macOS 14+ with Clang 18+
+
+set(CMAKE_SYSTEM_NAME Darwin)
+set(CMAKE_C_COMPILER clang)
+set(CMAKE_CXX_COMPILER clang++)
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# macOS deployment target
+set(CMAKE_OSX_DEPLOYMENT_TARGET "11.0" CACHE STRING "macOS deployment target")
+
+# Compiler flags
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -Wpedantic")
+set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g -O0")
+set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3 -DNDEBUG")
+
+# Link flags
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-dead_strip")
+
+# Find packages
+find_package(PkgConfig REQUIRED)
+

cmake/toolchains/windows-msvc.cmake

@@ -0,0 +1,26 @@
+# Windows MSVC Toolchain
+# Optimized for Visual Studio 2022 with MSVC 19.30+
+
+set(CMAKE_SYSTEM_NAME Windows)
+set(CMAKE_C_COMPILER cl)
+set(CMAKE_CXX_COMPILER cl)
+
+# Set C++ standard
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# MSVC runtime library (static)
+set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+
+# Compiler flags
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /W4 /permissive-")
+set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} /Od /Zi")
+set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} /O2 /Ob2 /DNDEBUG")
+
+# Link flags
+set(CMAKE_EXE_LINKER_FLAGS_RELEASE "${CMAKE_EXE_LINKER_FLAGS_RELEASE} /LTCG")
+
+# Windows-specific definitions
+add_definitions(-DWIN32_LEAN_AND_MEAN)
+add_definitions(-DNOMINMAX)
+

cmake/utils.cmake

@@ -0,0 +1,71 @@
+# This file contains utility functions for the yaze build system.
+
+# ============================================================================
+# yaze_add_compiler_flags
+#
+# Sets standard compiler flags for C++ and C.
+# Also handles platform-specific and compiler-specific flags.
+# ============================================================================
+function(yaze_add_compiler_flags)
+    # Set C++ and C standards in parent scope
+    set(CMAKE_CXX_STANDARD 23 PARENT_SCOPE)
+    set(CMAKE_CXX_STANDARD_REQUIRED ON PARENT_SCOPE)
+    set(CMAKE_CXX_EXTENSIONS OFF PARENT_SCOPE)
+    set(CMAKE_C_STANDARD 99 PARENT_SCOPE)
+    set(CMAKE_C_STANDARD_REQUIRED ON PARENT_SCOPE)
+
+    if(YAZE_SUPPRESS_WARNINGS)
+        if(MSVC)
+            add_compile_options(/w)
+        else()
+            add_compile_options(-w)
+        endif()
+        message(STATUS "✓ Warnings suppressed (use -v preset suffix for verbose builds)")
+    else()
+        message(STATUS "○ Verbose warnings enabled")
+    endif()
+
+    # Common interface target for shared settings
+    add_library(yaze_common INTERFACE)
+    target_compile_features(yaze_common INTERFACE cxx_std_23)
+
+    # Platform-specific definitions
+    if(YAZE_PLATFORM_LINUX)
+        target_compile_definitions(yaze_common INTERFACE linux stricmp=strcasecmp)
+    elseif(YAZE_PLATFORM_MACOS)
+        target_compile_definitions(yaze_common INTERFACE MACOS)
+    elseif(YAZE_PLATFORM_WINDOWS)
+        target_compile_definitions(yaze_common INTERFACE WINDOWS)
+    endif()
+
+    # Compiler-specific settings
+    if(MSVC)
+        target_compile_options(yaze_common INTERFACE
+            /EHsc
+            /W4 /permissive-
+            /bigobj
+            /utf-8
+        )
+        target_compile_definitions(yaze_common INTERFACE
+            _CRT_SECURE_NO_WARNINGS
+            _CRT_NONSTDC_NO_WARNINGS
+            SILENCE_CXX23_DEPRECATIONS
+            _SILENCE_CXX23_DEPRECATION_WARNING
+            _SILENCE_ALL_CXX23_DEPRECATION_WARNINGS
+            NOMINMAX
+            WIN32_LEAN_AND_MEAN
+            strncasecmp=_strnicmp
+            strcasecmp=_stricmp
+        )
+    else()
+        target_compile_options(yaze_common INTERFACE
+            -Wall -Wextra -Wpedantic
+            -Wno-deprecated-declarations
+            -Wno-c++23-compat
+        )
+        target_compile_definitions(yaze_common INTERFACE
+            _SILENCE_CXX23_DEPRECATION_WARNING
+            _SILENCE_ALL_CXX23_DEPRECATION_WARNINGS
+        )
+    endif()
+endfunction()

cmake/vcpkg.cmake

@@ -1,40 +1,54 @@
+# vcpkg configuration reporting for Windows builds
+# This file is included AFTER vcpkg toolchain has run, so we can only report and validate
+# 
+# IMPORTANT: vcpkg configuration variables (VCPKG_TARGET_TRIPLET, etc.) must be set:
+#   1. On the CMake command line: -DVCPKG_TARGET_TRIPLET=x64-windows-static
+#   2. Via environment variables: set VCPKG_DEFAULT_TRIPLET=x64-windows-static
+#   3. In vcpkg-configuration.json in the project root
 
-# vcpkg configuration for Windows builds
+# Windows-specific macro definitions to avoid conflicts
 add_definitions("-DMICROSOFT_WINDOWS_WINBASE_H_DEFINE_INTERLOCKED_CPLUSPLUS_OVERLOADS=0")
 
-# vcpkg settings
-set(VCPKG_CRT_LINKAGE dynamic)
-set(VCPKG_LIBRARY_LINKAGE dynamic)
+# Determine what triplet is being used (for reporting)
+set(_vcpkg_triplet "unknown")
+if(DEFINED VCPKG_TARGET_TRIPLET)
+    set(_vcpkg_triplet "${VCPKG_TARGET_TRIPLET}")
+elseif(DEFINED ENV{VCPKG_DEFAULT_TRIPLET})
+    set(_vcpkg_triplet "$ENV{VCPKG_DEFAULT_TRIPLET}")
+endif()
 
-# Enable vcpkg manifest mode for automatic dependency management
-set(VCPKG_MANIFEST_MODE ON)
+# Detect installed directory
+set(_vcpkg_installed "${CMAKE_BINARY_DIR}/vcpkg_installed")
+if(DEFINED VCPKG_INSTALLED_DIR)
+    set(_vcpkg_installed "${VCPKG_INSTALLED_DIR}")
+endif()
 
-# Auto-detect target architecture and set vcpkg triplet
-if(NOT DEFINED VCPKG_TARGET_TRIPLET)
-    if(CMAKE_SYSTEM_PROCESSOR MATCHES "ARM64|aarch64")
-        set(VCPKG_TARGET_TRIPLET "arm64-windows" CACHE STRING "vcpkg target triplet")
-        set(VCPKG_TARGET_ARCHITECTURE arm64)
-    elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "AMD64|x86_64")
-        set(VCPKG_TARGET_TRIPLET "x64-windows" CACHE STRING "vcpkg target triplet")
-        set(VCPKG_TARGET_ARCHITECTURE x64)
-    elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "i386|i686|x86")
-        set(VCPKG_TARGET_TRIPLET "x86-windows" CACHE STRING "vcpkg target triplet")
-        set(VCPKG_TARGET_ARCHITECTURE x86)
+# Detect manifest mode
+set(_vcpkg_manifest "ON (auto)")
+if(DEFINED VCPKG_MANIFEST_MODE)
+    if(VCPKG_MANIFEST_MODE)
+        set(_vcpkg_manifest "ON")
     else()
-        # Fallback to x64 if architecture detection fails
-        set(VCPKG_TARGET_TRIPLET "x64-windows" CACHE STRING "vcpkg target triplet")
-        set(VCPKG_TARGET_ARCHITECTURE x64)
-        message(WARNING "Could not detect target architecture, defaulting to x64")
+        set(_vcpkg_manifest "OFF")
     endif()
 endif()
 
-# Set vcpkg installation directory if not already set
-if(NOT DEFINED VCPKG_INSTALLED_DIR)
-    set(VCPKG_INSTALLED_DIR "${CMAKE_BINARY_DIR}/vcpkg_installed" CACHE PATH "vcpkg installed directory")
+# Report vcpkg configuration
+message(STATUS "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+message(STATUS "vcpkg Post-Toolchain Report:")
+message(STATUS "  ├─ Active triplet: ${_vcpkg_triplet}")
+message(STATUS "  ├─ Manifest mode: ${_vcpkg_manifest}")
+message(STATUS "  └─ Installed directory: ${_vcpkg_installed}")
+message(STATUS "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+# Validation warnings
+if(_vcpkg_triplet STREQUAL "unknown")
+    message(WARNING "vcpkg triplet not detected! Build may fail.")
+    message(WARNING "Set VCPKG_TARGET_TRIPLET on command line or VCPKG_DEFAULT_TRIPLET env var")
 endif()
 
-message(STATUS "vcpkg configuration:")
-message(STATUS "  Target architecture: ${VCPKG_TARGET_ARCHITECTURE}")
-message(STATUS "  Target triplet: ${VCPKG_TARGET_TRIPLET}")
-message(STATUS "  Installed directory: ${VCPKG_INSTALLED_DIR}")
-message(STATUS "  Manifest mode: ${VCPKG_MANIFEST_MODE}")
+# Ensure manifest file exists
+if(NOT EXISTS "${CMAKE_SOURCE_DIR}/vcpkg.json")
+    message(WARNING "vcpkg.json manifest not found in ${CMAKE_SOURCE_DIR}")
+    message(WARNING "vcpkg dependency installation may fail!")
+endif()

cmake/windows-vcpkg.toolchain.cmake

@@ -0,0 +1,37 @@
+# Windows vcpkg toolchain wrapper
+# This file provides a convenient way to configure vcpkg for Windows builds
+#
+# Usage:
+#   cmake -DCMAKE_TOOLCHAIN_FILE=cmake/windows-vcpkg.toolchain.cmake ..
+#
+# Or set VCPKG_ROOT environment variable and this will find it automatically
+
+# Set vcpkg triplet for static Windows builds
+set(VCPKG_TARGET_TRIPLET "x64-windows-static" CACHE STRING "vcpkg triplet")
+set(VCPKG_HOST_TRIPLET "x64-windows" CACHE STRING "vcpkg host triplet")
+
+# Enable manifest mode
+set(VCPKG_MANIFEST_MODE ON CACHE BOOL "Use vcpkg manifest mode")
+
+# Find vcpkg root
+if(DEFINED ENV{VCPKG_ROOT} AND EXISTS "$ENV{VCPKG_ROOT}")
+  set(VCPKG_ROOT "$ENV{VCPKG_ROOT}" CACHE PATH "vcpkg root directory")
+elseif(EXISTS "${CMAKE_CURRENT_LIST_DIR}/../vcpkg/scripts/buildsystems/vcpkg.cmake")
+  set(VCPKG_ROOT "${CMAKE_CURRENT_LIST_DIR}/../vcpkg" CACHE PATH "vcpkg root directory")
+else()
+  message(WARNING "vcpkg not found. Set VCPKG_ROOT environment variable or clone vcpkg to project root.")
+  message(WARNING "  git clone https://github.com/Microsoft/vcpkg.git")
+  message(WARNING "  cd vcpkg && bootstrap-vcpkg.bat")
+  return()
+endif()
+
+# Include the vcpkg toolchain
+set(VCPKG_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake")
+if(EXISTS "${VCPKG_TOOLCHAIN_FILE}")
+  message(STATUS "Using vcpkg toolchain: ${VCPKG_TOOLCHAIN_FILE}")
+  message(STATUS "  Triplet: ${VCPKG_TARGET_TRIPLET}")
+  include("${VCPKG_TOOLCHAIN_FILE}")
+else()
+  message(FATAL_ERROR "vcpkg toolchain not found at ${VCPKG_TOOLCHAIN_FILE}")
+endif()
+

cmake/yaze.plist.in

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>English</string>
+	<key>CFBundleExecutable</key>
+	<string>${MACOSX_BUNDLE_EXECUTABLE_NAME}</string>
+	<key>CFBundleGetInfoString</key>
+	<string>${MACOSX_BUNDLE_INFO_STRING}</string>
+	<key>CFBundleIconFile</key>
+	<string>${MACOSX_BUNDLE_ICON_FILE}</string>
+	<key>CFBundleIdentifier</key>
+	<string>${MACOSX_BUNDLE_GUI_IDENTIFIER}</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleLongVersionString</key>
+	<string>${MACOSX_BUNDLE_LONG_VERSION_STRING}</string>
+	<key>CFBundleName</key>
+	<string>${MACOSX_BUNDLE_BUNDLE_NAME}</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>${MACOSX_BUNDLE_SHORT_VERSION_STRING}</string>
+	<key>CFBundleSignature</key>
+	<string>????</string>
+	<key>CFBundleVersion</key>
+	<string>${MACOSX_BUNDLE_BUNDLE_VERSION}</string>
+	<key>CSResourcesFileMapped</key>
+	<true/>
+	<key>NSHumanReadableCopyright</key>
+	<string>${MACOSX_BUNDLE_COPYRIGHT}</string>
+</dict>
+</plist>

docs/01-getting-started.md

@@ -1,56 +0,0 @@
-# Getting Started
-
-This software allows you to modify "The Legend of Zelda: A Link to the Past" (US or JP) ROMs. Built for compatibility with ZScream projects and designed to be cross-platform.
-
-## Quick Start
-
-1. **Download** the latest release for your platform
-2. **Load ROM** via File > Open ROM
-3. **Select Editor** from the toolbar (Overworld, Dungeon, Graphics, etc.)
-4. **Make Changes** and save your project
-
-## General Tips
-
-- **Experiment Flags**: Enable/disable features in File > Options > Experiment Flags
-- **Backup Files**: Enabled by default - each save creates a timestamped backup
-- **Extensions**: Load custom tools via the Extensions menu (C library and Python module support)
-
-## Supported Features
-
-| Feature | Status | Details |
-|---------|--------|---------|
-| Overworld Maps | ✅ Complete | Edit and save tile32 data |
-| OW Map Properties | ✅ Complete | Edit and save map properties |
-| OW Entrances | ✅ Complete | Edit and save entrance data |
-| OW Exits | ✅ Complete | Edit and save exit data |
-| OW Sprites | 🔄 In Progress | Edit sprite positions, add/remove sprites |
-| Dungeon Editor | 🔄 In Progress | View room metadata and edit room data |
-| Palette Editor | 🔄 In Progress | Edit and save palettes, palette groups |
-| Graphics Sheets | 🔄 In Progress | Edit and save graphics sheets |
-| Graphics Groups | ✅ Complete | Edit and save graphics groups |
-| Hex Editor | ✅ Complete | View and edit ROM data in hex |
-| Asar Patching | ✅ Complete | Apply Asar 65816 assembly patches to ROM |
-
-## Command Line Interface
-
-The `z3ed` CLI tool provides ROM operations:
-
-```bash
-# Apply Asar assembly patch
-z3ed asar patch.asm --rom=zelda3.sfc
-
-# Extract symbols from assembly
-z3ed extract patch.asm
-
-# Validate assembly syntax
-z3ed validate patch.asm
-
-# Launch interactive TUI
-z3ed --tui
-```
-
-## Extending Functionality
-
-YAZE provides a pure C library interface and Python module for building extensions and custom sprites without assembly. Load these under the Extensions menu.
-
-This feature is still in development and not fully documented yet.

docs/02-build-instructions.md

@@ -1,459 +0,0 @@
-# Build Instructions
-
-YAZE uses CMake 3.16+ with modern target-based configuration. The project includes comprehensive Windows support with Visual Studio integration, vcpkg package management, and automated setup scripts.
-
-## Quick Start
-
-### macOS (Apple Silicon)
-```bash
-cmake --preset debug
-cmake --build build
-```
-
-### Linux
-```bash
-cmake -B build -DCMAKE_BUILD_TYPE=Debug
-cmake --build build
-```
-
-### Windows (Recommended)
-```powershell
-# Automated setup (first time only)
-.\scripts\setup-windows-dev.ps1
-
-# Generate Visual Studio projects (with proper vcpkg integration)
-python scripts/generate-vs-projects.py
-
-# Or use CMake directly
-cmake --preset windows-debug
-cmake --build build --preset windows-debug
-```
-
-### Minimal Build (CI/Fast)
-```bash
-cmake -B build -DYAZE_MINIMAL_BUILD=ON
-cmake --build build
-```
-
-## Dependencies
-
-### Required
-- CMake 3.16+
-- C++23 compiler (GCC 13+, Clang 16+, MSVC 2019+)
-- Git with submodule support
-
-### Bundled Libraries
-- SDL2, ImGui, Abseil, Asar, GoogleTest
-- Native File Dialog Extended (NFD)
-- All dependencies included in repository
-
-## Platform Setup
-
-### macOS
-```bash
-# Install Xcode Command Line Tools
-xcode-select --install
-
-# Optional: Install Homebrew dependencies (auto-detected)
-brew install cmake pkg-config
-```
-
-### Linux (Ubuntu/Debian)
-```bash
-sudo apt-get update
-sudo apt-get install -y build-essential cmake ninja-build pkg-config \
-  libgtk-3-dev libdbus-1-dev
-```
-
-### Windows
-
-#### Automated Setup (Recommended)
-The project includes comprehensive setup scripts for Windows development:
-
-```powershell
-# Complete development environment setup
-.\scripts\setup-windows-dev.ps1
-
-# Generate Visual Studio project files (with proper vcpkg integration)
-python scripts/generate-vs-projects.py
-
-# Test CMake configuration
-.\scripts\test-cmake-config.ps1
-```
-
-**What the setup script installs:**
-- Chocolatey package manager
-- CMake 3.16+
-- Git, Ninja, Python 3
-- Visual Studio 2022 detection and verification
-
-#### Manual Setup Options
-
-**Option 1 - Minimal (CI/Fast Builds):**
-- Visual Studio 2019+ with C++ CMake tools
-- No additional dependencies needed (all bundled)
-
-**Option 2 - Full Development with vcpkg:**
-- Visual Studio 2019+ with C++ CMake tools
-- vcpkg package manager for dependency management
-
-#### vcpkg Integration
-
-**Automatic Setup:**
-```powershell
-# PowerShell
-.\scripts\setup-windows-dev.ps1
-
-# Command Prompt
-scripts\setup-windows-dev.bat
-```
-
-**Manual vcpkg Setup:**
-```cmd
-git clone https://github.com/Microsoft/vcpkg.git
-cd vcpkg
-.\bootstrap-vcpkg.bat
-.\vcpkg.exe integrate install
-set VCPKG_ROOT=%CD%
-```
-
-**Dependencies (vcpkg.json):**
-- zlib (compression)
-- libpng (PNG support)
-- sdl2 (graphics/input with Vulkan support)
-
-**Note**: Abseil and gtest are built from source via CMake rather than through vcpkg to avoid compatibility issues.
-
-#### Windows Build Commands
-
-**Using CMake Presets:**
-```cmd
-# Debug build (minimal, no tests)
-cmake --preset windows-debug
-cmake --build build --preset windows-debug
-
-# Development build (includes Google Test)
-cmake --preset windows-dev
-cmake --build build --preset windows-dev
-
-# Release build (optimized, no tests)
-cmake --preset windows-release
-cmake --build build --preset windows-release
-```
-
-**Using Visual Studio Projects:**
-```powershell
-# Generate project files (with proper vcpkg integration)
-python scripts/generate-vs-projects.py
-
-# Open YAZE.sln in Visual Studio
-# Select configuration (Debug/Release) and platform (x64/x86/ARM64)
-# Press F5 to build and run
-```
-
-**Build Types:**
-- **windows-debug**: Minimal debug build, no Google Test
-- **windows-dev**: Development build with Google Test and ROM testing
-- **windows-release**: Optimized release build, no Google Test
-
-## Build Targets
-
-### Applications
-- **yaze**: Main GUI editor application
-- **z3ed**: Command-line interface tool
-
-### Libraries  
-- **yaze_c**: C API library for extensions
-- **asar-static**: 65816 assembler library
-
-### Development (Debug Builds Only)
-- **yaze_emu**: Standalone SNES emulator
-- **yaze_test**: Comprehensive test suite
-
-## Build Configurations
-
-### Debug (Full Features)
-```bash
-cmake --preset debug  # macOS
-# OR
-cmake -B build -DCMAKE_BUILD_TYPE=Debug  # All platforms
-```
-**Includes**: NFD, ImGuiTestEngine, PNG support, emulator, all tools
-
-### Minimal (CI/Fast Builds)
-```bash
-cmake -B build -DYAZE_MINIMAL_BUILD=ON
-```
-**Excludes**: Emulator, CLI tools, UI tests, optional dependencies
-
-### Release
-```bash
-cmake --preset release  # macOS
-# OR  
-cmake -B build -DCMAKE_BUILD_TYPE=Release  # All platforms
-```
-
-## IDE Integration
-
-### Visual Studio (Windows)
-**Recommended approach:**
-```powershell
-# Setup development environment
-.\scripts\setup-windows-dev.ps1
-
-# Generate Visual Studio project files (with proper vcpkg integration)
-python scripts/generate-vs-projects.py
-
-# Open YAZE.sln in Visual Studio 2022
-# Select configuration (Debug/Release) and platform (x64/x86/ARM64)
-# Press F5 to build and run
-```
-
-**Features:**
-- Full IntelliSense support
-- Integrated debugging
-- Automatic vcpkg dependency management (zlib, libpng, SDL2)
-- Multi-platform support (x64, ARM64)
-- Automatic asset copying
-- Generated project files stay in sync with CMake configuration
-
-### VS Code
-1. Install CMake Tools extension
-2. Open project, select "Debug" preset
-3. Language server uses `compile_commands.json` automatically
-
-### CLion
-- Opens CMake projects directly
-- Select Debug configuration
-
-### Xcode (macOS)
-```bash
-cmake --preset debug -G Xcode
-open build/yaze.xcodeproj
-```
-
-## Windows Development Scripts
-
-The project includes several PowerShell and Batch scripts to streamline Windows development:
-
-### Setup Scripts
-- **`setup-windows-dev.ps1`**: Complete development environment setup
-- **`setup-windows-dev.bat`**: Batch version of setup script
-
-**What they install:**
-- Chocolatey package manager
-- CMake 3.16+
-- Git, Ninja, Python 3
-- Visual Studio 2022 detection
-
-### Project Generation Scripts
-- **`generate-vs-projects.py`**: Generate Visual Studio project files with proper vcpkg integration
-- **`generate-vs-projects.bat`**: Batch version of project generation
-
-**Features:**
-- Automatic CMake detection and installation
-- Visual Studio 2022 detection
-- Multi-architecture support (x64, ARM64)
-- vcpkg integration
-- CMake compatibility fixes
-
-### Testing Scripts
-- **`test-cmake-config.ps1`**: Test CMake configuration without full build
-
-**Usage:**
-```powershell
-# Test configuration
-.\scripts\test-cmake-config.ps1
-
-# Test with specific architecture
-.\scripts\test-cmake-config.ps1 -Architecture x86
-
-# Clean test build
-.\scripts\test-cmake-config.ps1 -Clean
-```
-
-## Features by Build Type
-
-| Feature | Debug | Release | Minimal (CI) |
-|---------|-------|---------|--------------|
-| GUI Editor | ✅ | ✅ | ✅ |
-| Native File Dialogs | ✅ | ✅ | ❌ |
-| PNG Support | ✅ | ✅ | ❌ |
-| Emulator | ✅ | ✅ | ❌ |
-| CLI Tools | ✅ | ✅ | ❌ |
-| Test Suite | ✅ | ❌ | ✅ (limited) |
-| UI Testing | ✅ | ❌ | ❌ |
-
-## CMake Compatibility
-
-### Submodule Compatibility Issues
-YAZE includes several submodules (abseil-cpp, SDL) that may have CMake compatibility issues. The project automatically handles these with:
-
-**Automatic Policy Management:**
-- `CMAKE_POLICY_VERSION_MINIMUM=3.5` (handles SDL requirements)
-- `CMAKE_POLICY_VERSION_MAXIMUM=3.28` (prevents future issues)
-- `CMAKE_WARN_DEPRECATED=OFF` (suppresses submodule warnings)
-- `ABSL_PROPAGATE_CXX_STD=ON` (handles Abseil C++ standard propagation)
-- `THREADS_PREFER_PTHREAD_FLAG=OFF` (fixes Windows pthread issues)
-
-**Manual Configuration (if needed):**
-```bash
-cmake -B build \
-  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
-  -DCMAKE_POLICY_VERSION_MAXIMUM=3.28 \
-  -DCMAKE_WARN_DEPRECATED=OFF \
-  -DABSL_PROPAGATE_CXX_STD=ON \
-  -DTHREADS_PREFER_PTHREAD_FLAG=OFF \
-  -DCMAKE_BUILD_TYPE=Debug
-```
-
-## CI/CD and Release Builds
-
-### GitHub Actions Workflows
-
-The project includes three release workflows with different levels of complexity:
-
-- **`release-simplified.yml`**: Fast, basic release builds
-- **`release.yml`**: Standard release builds with fallback mechanisms
-- **`release-complex.yml`**: Comprehensive release builds with multiple fallback strategies
-
-### vcpkg Fallback Mechanisms
-
-All Windows CI/CD builds include automatic fallback mechanisms:
-
-**When vcpkg succeeds:**
-- Full build with all dependencies (zlib, libpng, SDL2)
-- Complete feature set available
-
-**When vcpkg fails (network issues):**
-- Automatic fallback to minimal build configuration
-- Uses source-built dependencies (Abseil, etc.)
-- Still produces functional executables
-
-### Supported Architectures
-
-**Windows:**
-- x64 (64-bit) - Primary target for modern systems
-- ARM64 - For ARM-based Windows devices (Surface Pro X, etc.)
-
-**macOS:**
-- Universal binary (Apple Silicon + Intel)
-
-**Linux:**
-- x64 (64-bit)
-
-## Troubleshooting
-
-### Windows CMake Issues
-
-**CMake Not Found:**
-```powershell
-# Run the setup script
-.\scripts\setup-windows-dev.ps1
-
-# Or install manually via Chocolatey
-choco install cmake
-```
-
-**Submodule Compatibility Errors:**
-```powershell
-# Test CMake configuration
-.\scripts\test-cmake-config.ps1
-
-# Clean build with compatibility flags
-Remove-Item -Recurse -Force build
-cmake -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.5 -DCMAKE_WARN_DEPRECATED=OFF
-```
-
-**Visual Studio Project Issues:**
-```powershell
-# Regenerate project files
-.\scripts\generate-vs-projects.ps1
-
-# Clean and rebuild
-Remove-Item -Recurse -Force build
-cmake --preset windows-debug
-```
-
-### vcpkg Issues
-
-**Dependencies Not Installing:**
-```cmd
-# Check vcpkg installation
-vcpkg version
-
-# Reinstall dependencies
-vcpkg install --triplet x64-windows zlib libpng sdl2
-
-# Check installed packages
-vcpkg list
-```
-
-**Network/Download Failures:**
-- The CI/CD workflows automatically fall back to minimal builds
-- For local development, ensure stable internet connection
-- If vcpkg consistently fails, use minimal build mode:
-  ```bash
-  cmake -B build -DYAZE_MINIMAL_BUILD=ON
-  ```
-
-**Visual Studio Integration:**
-```cmd
-# Re-integrate vcpkg
-cd C:\vcpkg
-.\vcpkg.exe integrate install
-```
-
-**ZLIB or Other Dependencies Not Found:**
-```bash
-# Regenerate project files with proper vcpkg integration
-python scripts/generate-vs-projects.py
-
-# Ensure vcpkg is properly set up
-.\scripts\setup-windows-dev.ps1
-```
-
-### Architecture Errors (macOS)
-```bash
-# Clean and use ARM64-only preset
-rm -rf build
-cmake --preset debug  # Uses arm64 only
-```
-
-### Missing Headers (Language Server)
-```bash
-# Regenerate compile commands
-cmake --preset debug
-cp build/compile_commands.json .
-# Restart VS Code
-```
-
-### CI Build Failures
-Use minimal build configuration that matches CI:
-```bash
-cmake -B build -DYAZE_MINIMAL_BUILD=ON -DYAZE_ENABLE_UI_TESTS=OFF
-cmake --build build
-```
-
-### Common Error Solutions
-
-**"CMake Deprecation Warning" from submodules:**
-- This is automatically handled by the project's CMake configuration
-- If you see these warnings, they can be safely ignored
-
-**"pthread_create not found" on Windows:**
-- The project automatically sets `THREADS_PREFER_PTHREAD_FLAG=OFF`
-- This is normal for Windows builds
-
-**"Abseil C++ std propagation" warnings:**
-- Automatically handled with `ABSL_PROPAGATE_CXX_STD=ON`
-- Ensures proper C++ standard handling
-
-**Visual Studio "file not found" errors:**
-- Run `python scripts/generate-vs-projects.py` to regenerate project files
-- Ensure CMake configuration completed successfully first
-
-**CI/CD Build Failures:**
-- Check if vcpkg download failed (network issues)
-- The workflows automatically fall back to minimal builds
-- For persistent issues, check the workflow logs for specific error messages

docs/03-asar-integration.md

@@ -1,141 +0,0 @@
-# Asar 65816 Assembler Integration
-
-Complete cross-platform ROM patching with assembly code support, symbol extraction, and validation.
-
-## Quick Examples
-
-### Command Line
-```bash
-# Apply assembly patch to ROM
-z3ed asar my_patch.asm --rom=zelda3.sfc
-
-# Extract symbols without patching
-z3ed extract my_patch.asm
-
-# Validate assembly syntax
-z3ed validate my_patch.asm
-```
-
-### C++ API
-```cpp
-#include "app/core/asar_wrapper.h"
-
-yaze::app::core::AsarWrapper wrapper;
-wrapper.Initialize();
-
-// Apply patch to ROM
-auto result = wrapper.ApplyPatch("patch.asm", rom_data);
-if (result.ok() && result->success) {
-    for (const auto& symbol : result->symbols) {
-        std::cout << symbol.name << " @ $" << std::hex << symbol.address << std::endl;
-    }
-}
-```
-
-## Assembly Patch Examples
-
-### Basic Hook
-```assembly
-org $008000
-custom_hook:
-    sei                 ; Disable interrupts
-    rep #$30            ; 16-bit A and X/Y
-    
-    ; Your custom code
-    lda #$1234
-    sta $7E0000
-    
-    rts
-
-custom_data:
-    db "YAZE", $00
-    dw $1234, $5678
-```
-
-### Advanced Features
-```assembly
-!player_health = $7EF36C
-!custom_ram = $7E2000
-
-macro save_context()
-    pha : phx : phy
-endmacro
-
-org $008000
-advanced_hook:
-    %save_context()
-    
-    sep #$20
-    lda #$A0            ; Full health
-    sta !player_health
-    
-    %save_context()
-    rtl
-```
-
-## API Reference
-
-### AsarWrapper Class
-```cpp
-class AsarWrapper {
-public:
-    absl::Status Initialize();
-    absl::StatusOr<AsarPatchResult> ApplyPatch(
-        const std::string& patch_path,
-        std::vector<uint8_t>& rom_data);
-    absl::StatusOr<std::vector<AsarSymbol>> ExtractSymbols(
-        const std::string& asm_path);
-    absl::Status ValidateAssembly(const std::string& asm_path);
-};
-```
-
-### Data Structures
-```cpp
-struct AsarSymbol {
-    std::string name;           // Symbol name
-    uint32_t address;          // Memory address  
-    std::string opcode;        // Associated opcode
-    std::string file;          // Source file
-    int line;                  // Line number
-};
-
-struct AsarPatchResult {
-    bool success;              // Whether patch succeeded
-    std::vector<std::string> errors;     // Error messages
-    std::vector<AsarSymbol> symbols;     // Extracted symbols
-    uint32_t rom_size;         // Final ROM size
-};
-```
-
-## Testing
-
-### ROM-Dependent Tests
-```cpp
-YAZE_ROM_TEST(AsarIntegration, RealRomPatching) {
-    auto rom_data = TestRomManager::LoadTestRom();
-    AsarWrapper wrapper;
-    wrapper.Initialize();
-    
-    auto result = wrapper.ApplyPatch("test.asm", rom_data);
-    EXPECT_TRUE(result.ok());
-}
-```
-
-ROM tests are automatically skipped in CI with `--label-exclude ROM_DEPENDENT`.
-
-## Error Handling
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `Unknown command` | Invalid opcode | Check 65816 instruction reference |
-| `Label not found` | Undefined label | Define the label or check spelling |
-| `Invalid hex value` | Bad hex format | Use `$1234` format |
-| `Buffer too small` | ROM needs expansion | Check if ROM needs to be larger |
-
-## Development Workflow
-
-1. **Write assembly patch**
-2. **Validate syntax**: `z3ed validate patch.asm`
-3. **Extract symbols**: `z3ed extract patch.asm`
-4. **Apply to test ROM**: `z3ed asar patch.asm --rom=test.sfc`
-5. **Test in emulator**

docs/04-api-reference.md

@@ -1,208 +0,0 @@
-# API Reference
-
-Comprehensive reference for the YAZE C API and C++ interfaces.
-
-## C API (`incl/yaze.h`, `incl/zelda.h`)
-
-### Core Library Functions
-```c
-// Initialization
-yaze_status yaze_library_init(void);
-void yaze_library_shutdown(void);
-
-// Version management
-const char* yaze_get_version_string(void);
-int yaze_get_version_number(void);
-bool yaze_check_version_compatibility(const char* expected_version);
-
-// Status utilities
-const char* yaze_status_to_string(yaze_status status);
-```
-
-### ROM Operations
-```c
-// ROM loading and management
-zelda3_rom* yaze_load_rom(const char* filename);
-void yaze_unload_rom(zelda3_rom* rom);
-yaze_status yaze_save_rom(zelda3_rom* rom, const char* filename);
-bool yaze_is_rom_modified(const zelda3_rom* rom);
-```
-
-### Graphics Operations
-```c
-// SNES color management
-snes_color yaze_rgb_to_snes_color(uint8_t r, uint8_t g, uint8_t b);
-void yaze_snes_color_to_rgb(snes_color color, uint8_t* r, uint8_t* g, uint8_t* b);
-
-// Bitmap operations
-yaze_bitmap* yaze_create_bitmap(int width, int height, uint8_t bpp);
-void yaze_free_bitmap(yaze_bitmap* bitmap);
-```
-
-### Palette System
-```c
-// Palette creation and management
-snes_palette* yaze_create_palette(uint8_t id, uint8_t size);
-void yaze_free_palette(snes_palette* palette);
-snes_palette* yaze_load_palette_from_rom(const zelda3_rom* rom, uint8_t palette_id);
-```
-
-### Message System
-```c
-// Message handling
-zelda3_message* yaze_load_message(const zelda3_rom* rom, uint16_t message_id);
-void yaze_free_message(zelda3_message* message);
-yaze_status yaze_save_message(zelda3_rom* rom, const zelda3_message* message);
-```
-
-## C++ API
-
-### AsarWrapper (`src/app/core/asar_wrapper.h`)
-```cpp
-namespace yaze::app::core {
-
-class AsarWrapper {
-public:
-    // Initialization
-    absl::Status Initialize();
-    void Shutdown();
-    bool IsInitialized() const;
-    
-    // Core functionality
-    absl::StatusOr<AsarPatchResult> ApplyPatch(
-        const std::string& patch_path,
-        std::vector<uint8_t>& rom_data,
-        const std::vector<std::string>& include_paths = {});
-    
-    absl::StatusOr<std::vector<AsarSymbol>> ExtractSymbols(
-        const std::string& asm_path,
-        const std::vector<std::string>& include_paths = {});
-    
-    // Symbol management
-    std::optional<AsarSymbol> FindSymbol(const std::string& name);
-    std::vector<AsarSymbol> GetSymbolsAtAddress(uint32_t address);
-    std::map<std::string, AsarSymbol> GetSymbolTable();
-    
-    // Utility functions
-    absl::Status ValidateAssembly(const std::string& asm_path);
-    std::string GetVersion();
-    void Reset();
-};
-
-}
-```
-
-### Data Structures
-
-#### ROM Version Support
-```c
-typedef enum zelda3_version {
-    ZELDA3_VERSION_US = 1,
-    ZELDA3_VERSION_JP = 2,
-    ZELDA3_VERSION_SD = 3,
-    ZELDA3_VERSION_RANDO = 4,
-    // Legacy aliases maintained for compatibility
-    US = ZELDA3_VERSION_US,
-    JP = ZELDA3_VERSION_JP,
-    SD = ZELDA3_VERSION_SD,
-    RANDO = ZELDA3_VERSION_RANDO,
-} zelda3_version;
-```
-
-#### SNES Graphics
-```c
-typedef struct snes_color {
-    uint16_t raw;               // Raw 15-bit SNES color
-    uint8_t red;               // Red component (0-31)
-    uint8_t green;             // Green component (0-31)
-    uint8_t blue;              // Blue component (0-31)
-} snes_color;
-
-typedef struct snes_palette {
-    uint8_t id;                // Palette ID
-    uint8_t size;              // Number of colors
-    snes_color* colors;        // Color array
-} snes_palette;
-```
-
-#### Message System
-```c
-typedef struct zelda3_message {
-    uint16_t id;                // Message ID (0-65535)
-    uint32_t rom_address;       // Address in ROM
-    uint16_t length;            // Length in bytes
-    uint8_t* raw_data;          // Raw ROM data
-    char* parsed_text;          // Decoded UTF-8 text
-    bool is_compressed;         // Compression flag
-    uint8_t encoding_type;      // Encoding type
-} zelda3_message;
-```
-
-## Error Handling
-
-### Status Codes
-```c
-typedef enum yaze_status {
-    YAZE_OK = 0,                   // Success
-    YAZE_ERROR_UNKNOWN = -1,       // Unknown error
-    YAZE_ERROR_INVALID_ARG = 1,    // Invalid argument
-    YAZE_ERROR_FILE_NOT_FOUND = 2, // File not found
-    YAZE_ERROR_MEMORY = 3,         // Memory allocation failed
-    YAZE_ERROR_IO = 4,             // I/O operation failed
-    YAZE_ERROR_CORRUPTION = 5,     // Data corruption detected
-    YAZE_ERROR_NOT_INITIALIZED = 6, // Component not initialized
-} yaze_status;
-```
-
-### Error Handling Pattern
-```c
-yaze_status status = yaze_library_init();
-if (status != YAZE_OK) {
-    printf("Failed to initialize YAZE: %s\n", yaze_status_to_string(status));
-    return 1;
-}
-
-zelda3_rom* rom = yaze_load_rom("zelda3.sfc");
-if (rom == nullptr) {
-    printf("Failed to load ROM file\n");
-    return 1;
-}
-
-// Use ROM...
-yaze_unload_rom(rom);
-yaze_library_shutdown();
-```
-
-## Extension System
-
-### Plugin Architecture
-```c
-typedef struct yaze_extension {
-    const char* name;           // Extension name
-    const char* version;        // Version string
-    const char* description;    // Description
-    const char* author;         // Author
-    int api_version;           // Required API version
-    
-    yaze_status (*initialize)(yaze_editor_context* context);
-    void (*cleanup)(void);
-    uint32_t (*get_capabilities)(void);
-} yaze_extension;
-```
-
-### Capability Flags
-```c
-#define YAZE_EXT_CAP_ROM_EDITING     0x0001  // ROM modification
-#define YAZE_EXT_CAP_GRAPHICS        0x0002  // Graphics operations
-#define YAZE_EXT_CAP_AUDIO           0x0004  // Audio processing
-#define YAZE_EXT_CAP_SCRIPTING       0x0008  // Scripting support
-#define YAZE_EXT_CAP_IMPORT_EXPORT   0x0010  // Data import/export
-```
-
-## Backward Compatibility
-
-All existing code continues to work without modification due to:
-- Legacy enum aliases (`US`, `JP`, `SD`, `RANDO`)
-- Original struct field names maintained
-- Duplicate field definitions for old/new naming conventions
-- Typedef aliases for renamed types

docs/A1-testing-guide.md

@@ -1,173 +0,0 @@
-# Testing Guide
-
-Comprehensive testing framework with efficient CI/CD integration and ROM-dependent test separation.
-
-## Test Categories
-
-### Stable Tests (STABLE)
-**Always run in CI/CD - Required for releases**
-
-- **AsarWrapperTest**: Core Asar functionality tests
-- **SnesTileTest**: SNES tile format handling  
-- **CompressionTest**: Data compression/decompression
-- **SnesPaletteTest**: SNES palette operations
-- **HexTest**: Hexadecimal utilities
-- **AsarIntegrationTest**: Asar integration without ROM dependencies
-
-**Characteristics:**
-- Fast execution (< 30 seconds total)
-- No external dependencies (ROMs, complex setup)
-- High reliability and deterministic results
-
-### ROM-Dependent Tests (ROM_DEPENDENT)
-**Only run in development with available ROM files**
-
-- **AsarRomIntegrationTest**: Real ROM patching and symbol extraction
-- **ROM-based integration tests**: Tests requiring actual game ROM files
-
-**Characteristics:**
-- Require specific ROM files to be present
-- Test real-world functionality
-- Automatically skipped in CI if ROM files unavailable
-
-### Experimental Tests (EXPERIMENTAL)
-**Run separately, allowed to fail**
-
-- **CpuTest**: 65816 CPU emulation tests
-- **Spc700Test**: SPC700 audio processor tests
-- **ApuTest**: Audio Processing Unit tests
-- **PpuTest**: Picture Processing Unit tests
-
-**Characteristics:**
-- May be unstable due to emulation complexity
-- Test advanced/experimental features
-- Allowed to fail without blocking releases
-
-## Command Line Usage
-
-```bash
-# Run only stable tests (release-ready)
-ctest --test-dir build --label-regex "STABLE"
-
-# Run experimental tests (allowed to fail)
-ctest --test-dir build --label-regex "EXPERIMENTAL"
-
-# Run Asar-specific tests
-ctest --test-dir build -R "*Asar*"
-
-# Run tests excluding ROM-dependent ones
-ctest --test-dir build --label-exclude "ROM_DEPENDENT"
-
-# Run with specific preset
-ctest --preset stable
-ctest --preset experimental
-```
-
-## CMake Presets
-
-```bash
-# Development workflow
-cmake --preset dev
-cmake --build --preset dev
-ctest --preset dev
-
-# CI workflow  
-cmake --preset ci
-cmake --build --preset ci
-ctest --preset ci
-
-# Release workflow
-cmake --preset release
-cmake --build --preset release
-ctest --preset stable
-```
-
-## Writing Tests
-
-### Stable Tests
-```cpp
-TEST(SnesTileTest, UnpackBppTile) {
-    std::vector<uint8_t> tile_data = {0xAA, 0x55, 0xAA, 0x55};
-    std::vector<uint8_t> result = UnpackBppTile(tile_data, 2);
-    EXPECT_EQ(result.size(), 64);
-    // Test specific pixel values...
-}
-```
-
-### ROM-Dependent Tests
-```cpp
-YAZE_ROM_TEST(AsarIntegration, RealRomPatching) {
-    auto rom_data = TestRomManager::LoadTestRom();
-    if (!rom_data.has_value()) {
-        GTEST_SKIP() << "ROM file not available";
-    }
-    
-    AsarWrapper wrapper;
-    wrapper.Initialize();
-    
-    auto result = wrapper.ApplyPatch("test.asm", *rom_data);
-    EXPECT_TRUE(result.ok());
-}
-```
-
-### Experimental Tests
-```cpp
-TEST(CpuTest, InstructionExecution) {
-    // Complex emulation tests
-    // May be timing-sensitive or platform-dependent
-}
-```
-
-## CI/CD Integration
-
-### GitHub Actions
-```yaml
-# Main CI pipeline
-- name: Run Stable Tests
-  run: ctest --label-regex "STABLE"
-
-# Experimental tests (allowed to fail)
-- name: Run Experimental Tests
-  run: ctest --label-regex "EXPERIMENTAL"
-  continue-on-error: true
-```
-
-### Test Execution Strategy
-1. **Stable tests run first** - Quick feedback for developers
-2. **Experimental tests run in parallel** - Don't block on unstable tests
-3. **ROM tests skipped** - No dependency on external files
-4. **Selective test execution** - Only run relevant tests for changes
-
-## Test Development Guidelines
-
-### Writing Stable Tests
-- **Fast execution**: Aim for < 1 second per test
-- **No external dependencies**: Self-contained test data
-- **Deterministic**: Same results every run
-- **Core functionality**: Test essential features only
-
-### Writing ROM-Dependent Tests
-- **Use TestRomManager**: Proper ROM file handling
-- **Graceful skipping**: Skip if ROM not available
-- **Real-world scenarios**: Test with actual game data
-- **Label appropriately**: Always include ROM_DEPENDENT label
-
-### Writing Experimental Tests
-- **Complex scenarios**: Multi-component integration
-- **Advanced features**: Emulation, complex algorithms
-- **Performance tests**: May vary by system
-- **GUI components**: May require display context
-
-## Performance and Maintenance
-
-### Regular Review
-- **Monthly review** of experimental test failures
-- **Promote stable experimental tests** to stable category
-- **Deprecate obsolete tests** that no longer provide value
-- **Update test categorization** as features mature
-
-### Performance Monitoring
-- **Track test execution times** for CI efficiency
-- **Identify slow tests** for optimization or recategorization
-- **Monitor CI resource usage** and adjust parallelism
-- **Benchmark critical path tests** for performance regression

docs/B1-contributing.md

@@ -1,239 +0,0 @@
-# Contributing
-
-Guidelines for contributing to the YAZE project.
-
-## Development Setup
-
-### Prerequisites
-- **CMake 3.16+**: Modern build system
-- **C++23 Compiler**: GCC 13+, Clang 16+, MSVC 2022 17.8+
-- **Git**: Version control with submodules
-
-### Quick Start
-```bash
-# Clone with submodules
-git clone --recursive https://github.com/scawful/yaze.git
-cd yaze
-
-# Build with presets
-cmake --preset dev
-cmake --build --preset dev
-
-# Run tests
-ctest --preset stable
-```
-
-## Code Style
-
-### C++ Standards
-- **C++23**: Use modern language features
-- **Google C++ Style**: Follow Google C++ style guide
-- **Naming**: Use descriptive names, avoid abbreviations
-
-### File Organization
-```cpp
-// Header guards
-#pragma once
-
-// Includes (system, third-party, local)
-#include <vector>
-#include "absl/status/status.h"
-#include "app/core/asar_wrapper.h"
-
-// Namespace usage
-namespace yaze::app::editor {
-
-class ExampleClass {
-public:
-    // Public interface
-    absl::Status Initialize();
-    
-private:
-    // Private implementation
-    std::vector<uint8_t> data_;
-};
-
-}
-```
-
-### Error Handling
-```cpp
-// Use absl::Status for error handling
-absl::Status LoadRom(const std::string& filename) {
-    if (filename.empty()) {
-        return absl::InvalidArgumentError("Filename cannot be empty");
-    }
-    
-    // ... implementation
-    
-    return absl::OkStatus();
-}
-
-// Use absl::StatusOr for operations that return values
-absl::StatusOr<std::vector<uint8_t>> ReadFile(const std::string& filename);
-```
-
-## Testing Requirements
-
-### Test Categories
-- **Stable Tests**: Fast, reliable, no external dependencies
-- **ROM-Dependent Tests**: Require ROM files, skip in CI
-- **Experimental Tests**: Complex, may be unstable
-
-### Writing Tests
-```cpp
-// Stable test example
-TEST(SnesTileTest, UnpackBppTile) {
-    std::vector<uint8_t> tile_data = {0xAA, 0x55};
-    auto result = UnpackBppTile(tile_data, 2);
-    EXPECT_TRUE(result.ok());
-    EXPECT_EQ(result->size(), 64);
-}
-
-// ROM-dependent test example
-YAZE_ROM_TEST(AsarIntegration, RealRomPatching) {
-    auto rom_data = TestRomManager::LoadTestRom();
-    if (!rom_data.has_value()) {
-        GTEST_SKIP() << "ROM file not available";
-    }
-    // ... test implementation
-}
-```
-
-### Test Execution
-```bash
-# Run stable tests (required)
-ctest --label-regex "STABLE"
-
-# Run experimental tests (optional)
-ctest --label-regex "EXPERIMENTAL"
-
-# Run specific test
-ctest -R "AsarWrapperTest"
-```
-
-## Pull Request Process
-
-### Before Submitting
-1. **Run tests**: Ensure all stable tests pass
-2. **Check formatting**: Use clang-format
-3. **Update documentation**: Update relevant docs if needed
-4. **Test on multiple platforms**: Verify cross-platform compatibility
-
-### Pull Request Template
-```markdown
-## Description
-Brief description of changes
-
-## Type of Change
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Breaking change
-- [ ] Documentation update
-
-## Testing
-- [ ] Stable tests pass
-- [ ] Manual testing completed
-- [ ] Cross-platform testing (if applicable)
-
-## Checklist
-- [ ] Code follows project style guidelines
-- [ ] Self-review completed
-- [ ] Documentation updated
-- [ ] Tests added/updated
-```
-
-## Development Workflow
-
-### Branch Strategy
-- **main**: Stable, release-ready code
-- **feature/**: New features and enhancements
-- **fix/**: Bug fixes
-- **docs/**: Documentation updates
-
-### Commit Messages
-```
-type(scope): brief description
-
-Detailed explanation of changes, including:
-- What was changed
-- Why it was changed
-- Any breaking changes
-
-Fixes #issue_number
-```
-
-### Types
-- **feat**: New features
-- **fix**: Bug fixes
-- **docs**: Documentation changes
-- **style**: Code style changes
-- **refactor**: Code refactoring
-- **test**: Test additions/changes
-- **chore**: Build/tooling changes
-
-## Architecture Guidelines
-
-### Component Design
-- **Single Responsibility**: Each class should have one clear purpose
-- **Dependency Injection**: Use dependency injection for testability
-- **Interface Segregation**: Keep interfaces focused and minimal
-
-### Memory Management
-- **RAII**: Use RAII for resource management
-- **Smart Pointers**: Prefer unique_ptr and shared_ptr
-- **Avoid Raw Pointers**: Use smart pointers or references
-
-### Performance
-- **Profile Before Optimizing**: Measure before optimizing
-- **Use Modern C++**: Leverage C++23 features for performance
-- **Avoid Premature Optimization**: Focus on correctness first
-
-## Documentation
-
-### Code Documentation
-- **Doxygen Comments**: Use Doxygen format for public APIs
-- **Inline Comments**: Explain complex logic
-- **README Updates**: Update relevant README files
-
-### API Documentation
-```cpp
-/**
- * @brief Applies an assembly patch to ROM data
- * @param patch_path Path to the assembly patch file
- * @param rom_data ROM data to patch (modified in place)
- * @param include_paths Optional include paths for assembly
- * @return Result containing success status and extracted symbols
- * @throws std::invalid_argument if patch_path is empty
- */
-absl::StatusOr<AsarPatchResult> ApplyPatch(
-    const std::string& patch_path,
-    std::vector<uint8_t>& rom_data,
-    const std::vector<std::string>& include_paths = {});
-```
-
-## Community Guidelines
-
-### Communication
-- **Be Respectful**: Treat all contributors with respect
-- **Be Constructive**: Provide helpful feedback
-- **Be Patient**: Remember that everyone is learning
-
-### Getting Help
-- **GitHub Issues**: Report bugs and request features
-- **Discussions**: Ask questions and discuss ideas
-- **Discord**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk)
-
-## Release Process
-
-### Version Numbering
-- **Semantic Versioning**: MAJOR.MINOR.PATCH
-- **v0.3.1**: Current stable release
-- **Pre-release**: v0.4.0-alpha, v0.4.0-beta
-
-### Release Checklist
-- [ ] All stable tests pass
-- [ ] Documentation updated
-- [ ] Changelog updated
-- [ ] Cross-platform builds verified
-- [ ] Release notes prepared

docs/B2-platform-compatibility.md

@@ -1,55 +0,0 @@
-# Platform Compatibility Improvements
-
-Recent improvements to ensure YAZE works reliably across all supported platforms.
-
-## Native File Dialog Support
-
-YAZE now features native file dialogs on all platforms:
-- **macOS**: Cocoa-based file selection with proper sandboxing support
-- **Windows**: Windows Explorer integration with COM APIs
-- **Linux**: GTK3 dialogs that match system appearance
-- **Fallback**: Bespoke implementation when native dialogs unavailable
-
-## Cross-Platform Build Reliability
-
-Enhanced build system ensures consistent compilation:
-- **Windows**: Resolved MSVC compatibility issues and dependency conflicts
-- **Linux**: Fixed standard library compatibility for older distributions  
-- **macOS**: Proper support for both Intel and Apple Silicon architectures
-- **All Platforms**: Bundled dependencies eliminate external package requirements
-
-## Build Configuration Options
-
-YAZE supports different build configurations for various use cases:
-
-### Full Build (Development)
-Includes all features: emulator, CLI tools, UI testing framework, and optional libraries.
-
-### Minimal Build  
-Streamlined build excluding complex components, optimized for automated testing and CI environments.
-
-## Implementation Details
-
-The build system automatically detects platform capabilities and adjusts feature sets accordingly:
-
-- **File Dialogs**: Uses native platform dialogs when available, with cross-platform fallbacks
-- **Dependencies**: Bundles all required libraries to eliminate external package requirements  
-- **Testing**: Separates ROM-dependent tests from unit tests for CI compatibility
-- **Architecture**: Supports both Intel and Apple Silicon on macOS without conflicts
-
-## Platform-Specific Adaptations
-
-### Windows
-- Complete COM-based file dialog implementation
-- MSVC compatibility improvements for modern C++ features
-- Resource file handling for proper application integration
-
-### macOS  
-- Cocoa-based native file dialogs with sandboxing support
-- Universal binary support for Intel and Apple Silicon
-- Proper bundle configuration for macOS applications
-
-### Linux
-- GTK3 integration for native file dialogs
-- Package manager integration for system dependencies
-- Support for multiple compiler toolchains (GCC, Clang)

docs/B3-build-presets.md

@@ -1,109 +0,0 @@
-# Build Presets Guide
-
-CMake presets for development workflow and architecture-specific builds.
-
-## 🍎 macOS ARM64 Presets (Recommended for Apple Silicon)
-
-### For Development Work:
-```bash
-# ARM64-only development build with ROM testing
-cmake --preset macos-dev
-cmake --build --preset macos-dev
-
-# ARM64-only debug build 
-cmake --preset macos-debug
-cmake --build --preset macos-debug
-
-# ARM64-only release build
-cmake --preset macos-release  
-cmake --build --preset macos-release
-```
-
-### For Distribution:
-```bash
-# Universal binary (ARM64 + x86_64) - use only when needed for distribution
-cmake --preset macos-debug-universal
-cmake --build --preset macos-debug-universal
-
-cmake --preset macos-release-universal
-cmake --build --preset macos-release-universal
-```
-
-## 🔧 Why This Fixes Architecture Errors
-
-**Problem**: The original presets used `CMAKE_OSX_ARCHITECTURES: "x86_64;arm64"` which forced CMake to build universal binaries. This caused issues because:
-- Dependencies like Abseil tried to use x86 SSE instructions (`-msse4.1`) 
-- These instructions don't exist on ARM64 processors
-- Build failed with "unsupported option '-msse4.1' for target 'arm64-apple-darwin'"
-
-**Solution**: The new ARM64-only presets use `CMAKE_OSX_ARCHITECTURES: "arm64"` which:
-- ✅ Only targets ARM64 architecture  
-- ✅ Prevents x86-specific instruction usage
-- ✅ Uses ARM64 optimizations instead
-- ✅ Builds much faster (no cross-compilation)
-
-## 📋 Available Presets
-
-| Preset Name | Architecture | Purpose | ROM Tests |
-|-------------|-------------|---------|-----------|
-| `macos-dev` | ARM64 only | Development | ✅ Enabled |
-| `macos-debug` | ARM64 only | Debug builds | ❌ Disabled |
-| `macos-release` | ARM64 only | Release builds | ❌ Disabled |
-| `macos-debug-universal` | Universal | Distribution debug | ❌ Disabled |
-| `macos-release-universal` | Universal | Distribution release | ❌ Disabled |
-
-## 🚀 Quick Start
-
-For most development work on Apple Silicon:
-
-```bash
-# Clean build
-rm -rf build
-
-# Configure for ARM64 development
-cmake --preset macos-dev
-
-# Build
-cmake --build --preset macos-dev
-
-# Run tests  
-cmake --build --preset macos-dev --target test
-```
-
-## 🛠️ IDE Integration
-
-### VS Code with CMake Tools:
-1. Open Command Palette (`Cmd+Shift+P`)
-2. Run "CMake: Select Configure Preset"
-3. Choose `macos-dev` or `macos-debug`
-
-### CLion:
-1. Go to Settings → Build, Execution, Deployment → CMake
-2. Add new profile with preset `macos-dev`
-
-### Xcode:
-```bash
-# Generate Xcode project
-cmake --preset macos-debug -G Xcode
-open build/yaze.xcodeproj
-```
-
-## 🔍 Troubleshooting
-
-If you still get architecture errors:
-1. **Clean completely**: `rm -rf build`
-2. **Check preset**: Ensure you're using an ARM64 preset (not universal)
-3. **Verify configuration**: Check that `CMAKE_OSX_ARCHITECTURES` shows only `arm64`
-
-```bash
-# Verify architecture setting
-cmake --preset macos-debug
-grep -A 5 -B 5 "CMAKE_OSX_ARCHITECTURES" build/CMakeCache.txt
-```
-
-## 📝 Notes
-
-- **ARM64 presets**: Fast builds, no architecture conflicts
-- **Universal presets**: Slower builds, for distribution only
-- **Deployment target**: ARM64 presets use macOS 11.0+ (when Apple Silicon was introduced)
-- **Universal presets**: Still support macOS 10.15+ for backward compatibility

docs/B4-release-workflows.md

@@ -1,308 +0,0 @@
-# Release Workflows Documentation
-
-YAZE uses three different GitHub Actions workflows for creating releases, each designed for specific use cases and reliability levels. This document explains the differences, use cases, and when to use each workflow.
-
-## Overview
-
-| Workflow | Complexity | Reliability | Use Case |
-|----------|------------|-------------|----------|
-| **release-simplified.yml** | Low | Basic | Quick releases, testing |
-| **release.yml** | Medium | High | Standard releases |
-| **release-complex.yml** | High | Maximum | Production releases, fallbacks |
-
----
-
-## 1. Release-Simplified (`release-simplified.yml`)
-
-### Purpose
-A streamlined workflow for quick releases and testing scenarios.
-
-### Key Features
-- **Minimal Configuration**: Basic build setup with standard dependencies
-- **No Fallback Mechanisms**: Direct dependency installation without error handling
-- **Standard vcpkg**: Uses fixed vcpkg commit without fallback options
-- **Basic Testing**: Simple executable verification
-
-### Use Cases
-- **Development Testing**: Testing release process during development
-- **Beta Releases**: Quick beta or alpha releases
-- **Hotfixes**: Emergency releases that need to be deployed quickly
-- **CI/CD Validation**: Ensuring the basic release process works
-
-### Configuration
-```yaml
-# Standard vcpkg setup
-vcpkgGitCommitId: 'c8696863d371ab7f46e213d8f5ca923c4aef2a00'
-# No fallback mechanisms
-# Basic dependency installation
-```
-
-### Platforms Supported
-- Windows (x64, x86, ARM64)
-- macOS Universal
-- Linux x64
-
----
-
-## 2. Release (`release.yml`)
-
-### Purpose
-The standard production release workflow with enhanced reliability.
-
-### Key Features
-- **Enhanced vcpkg**: Updated baseline and improved dependency management
-- **Better Error Handling**: More robust error reporting and debugging
-- **Comprehensive Testing**: Extended executable validation and artifact verification
-- **Production Ready**: Designed for stable releases
-
-### Use Cases
-- **Stable Releases**: Official stable version releases
-- **Feature Releases**: Major feature releases with full testing
-- **Release Candidates**: Pre-release candidates for testing
-
-### Configuration
-```yaml
-# Updated vcpkg baseline
-builtin-baseline: "2024.12.12"
-# Enhanced error handling
-# Comprehensive testing
-```
-
-### Advantages over Simplified
-- More reliable dependency resolution
-- Better error reporting
-- Enhanced artifact validation
-- Production-grade stability
-
----
-
-## 3. Release-Complex (`release-complex.yml`)
-
-### Purpose
-Maximum reliability release workflow with comprehensive fallback mechanisms.
-
-### Key Features
-- **Advanced Fallback System**: Multiple dependency installation strategies
-- **vcpkg Failure Handling**: Automatic fallback to manual dependency installation
-- **Chocolatey Integration**: Windows package manager fallback
-- **Comprehensive Debugging**: Extensive logging and error analysis
-- **Multiple Build Strategies**: CMake configuration fallbacks
-- **Enhanced Validation**: Multi-stage build verification
-
-### Use Cases
-- **Production Releases**: Critical production releases requiring maximum reliability
-- **Enterprise Deployments**: Releases for enterprise customers
-- **Major Version Releases**: Significant version releases (v1.0, v2.0, etc.)
-- **Problem Resolution**: When other workflows fail due to dependency issues
-
-### Fallback Mechanisms
-
-#### vcpkg Fallback
-```yaml
-# Primary: vcpkg installation
-- name: Set up vcpkg (Windows)
-  continue-on-error: true
-
-# Fallback: Manual dependency installation
-- name: Install dependencies manually (Windows fallback)
-  if: steps.vcpkg_setup.outcome == 'failure'
-```
-
-#### Chocolatey Integration
-```yaml
-# Install Chocolatey if not present
-if (-not (Get-Command choco -ErrorAction SilentlyContinue)) {
-  # Install Chocolatey
-}
-
-# Install dependencies via Chocolatey
-choco install -y cmake ninja git python3
-```
-
-#### Build Configuration Fallback
-```yaml
-# Primary: Full build with vcpkg
-cmake -DCMAKE_TOOLCHAIN_FILE="vcpkg.cmake" -DYAZE_MINIMAL_BUILD=OFF
-
-# Fallback: Minimal build without vcpkg
-cmake -DYAZE_MINIMAL_BUILD=ON
-```
-
-### Advanced Features
-- **Multi-stage Validation**: Visual Studio project validation
-- **Artifact Verification**: Comprehensive build artifact checking
-- **Debug Information**: Extensive logging for troubleshooting
-- **Environment Detection**: Automatic environment configuration
-
----
-
-## Workflow Comparison Matrix
-
-| Feature | Simplified | Release | Complex |
-|---------|------------|---------|---------|
-| **vcpkg Integration** | Basic | Enhanced | Advanced + Fallback |
-| **Error Handling** | Minimal | Standard | Comprehensive |
-| **Fallback Mechanisms** | None | Limited | Multiple |
-| **Debugging** | Basic | Standard | Extensive |
-| **Dependency Management** | Fixed | Updated | Adaptive |
-| **Build Validation** | Simple | Enhanced | Multi-stage |
-| **Failure Recovery** | None | Limited | Automatic |
-| **Production Ready** | No | Yes | Yes |
-| **Build Time** | Fast | Medium | Slow |
-| **Reliability** | Low | High | Maximum |
-
----
-
-## When to Use Each Workflow
-
-### Use Simplified When:
-- ✅ Testing release process during development
-- ✅ Creating beta or alpha releases
-- ✅ Quick hotfix releases
-- ✅ Validating basic CI/CD functionality
-- ✅ Development team testing
-
-### Use Release When:
-- ✅ Creating stable production releases
-- ✅ Feature releases with full testing
-- ✅ Release candidates
-- ✅ Standard version releases
-- ✅ Most production scenarios
-
-### Use Complex When:
-- ✅ Critical production releases
-- ✅ Major version releases (v1.0, v2.0)
-- ✅ Enterprise customer releases
-- ✅ When other workflows fail
-- ✅ Maximum reliability requirements
-- ✅ Complex dependency scenarios
-
----
-
-## Workflow Selection Guide
-
-### For Development Team
-```
-Development → Simplified
-Testing → Release
-Production → Complex
-```
-
-### For Release Manager
-```
-Hotfix → Simplified
-Feature Release → Release
-Major Release → Complex
-```
-
-### For CI/CD Pipeline
-```
-PR Validation → Simplified
-Nightly Builds → Release
-Release Pipeline → Complex
-```
-
----
-
-## Configuration Examples
-
-### Triggering a Release
-
-#### Manual Release (All Workflows)
-```bash
-# Using workflow_dispatch
-gh workflow run release.yml -f tag=v0.3.0
-gh workflow run release-simplified.yml -f tag=v0.3.0-beta
-gh workflow run release-complex.yml -f tag=v1.0.0
-```
-
-#### Automatic Release (Tag Push)
-```bash
-# Creates release automatically
-git tag v0.3.0
-git push origin v0.3.0
-```
-
-### Customizing Release Notes
-All workflows support automatic changelog extraction:
-```bash
-# Extract changelog for version
-python3 scripts/extract_changelog.py "0.3.0" > release_notes.md
-```
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-#### vcpkg Failures (Windows)
-- **Simplified**: Fails completely
-- **Release**: Basic error reporting
-- **Complex**: Automatic fallback to manual installation
-
-#### Dependency Conflicts
-- **Simplified**: Manual intervention required
-- **Release**: Enhanced error reporting
-- **Complex**: Multiple resolution strategies
-
-#### Build Failures
-- **Simplified**: Basic error output
-- **Release**: Enhanced debugging
-- **Complex**: Comprehensive failure analysis
-
-### Debug Information
-
-#### Simplified Workflow
-- Basic build output
-- Simple error messages
-- Minimal logging
-
-#### Release Workflow
-- Enhanced error reporting
-- Artifact verification
-- Build validation
-
-#### Complex Workflow
-- Extensive debug output
-- Multi-stage validation
-- Comprehensive error analysis
-- Automatic fallback execution
-
----
-
-## Best Practices
-
-### Workflow Selection
-1. **Start with Simplified** for development and testing
-2. **Use Release** for standard production releases
-3. **Use Complex** only when maximum reliability is required
-
-### Release Process
-1. **Test with Simplified** first
-2. **Validate with Release** for production readiness
-3. **Use Complex** for critical releases
-
-### Maintenance
-1. **Keep all workflows updated** with latest dependency versions
-2. **Monitor workflow performance** and adjust as needed
-3. **Document any custom modifications** for team knowledge
-
----
-
-## Future Improvements
-
-### Planned Enhancements
-- **Automated Workflow Selection**: Based on release type and criticality
-- **Enhanced Fallback Strategies**: Additional dependency resolution methods
-- **Performance Optimization**: Reduced build times while maintaining reliability
-- **Cross-Platform Consistency**: Unified behavior across all platforms
-
-### Integration Opportunities
-- **Release Automation**: Integration with semantic versioning
-- **Quality Gates**: Automated quality checks before release
-- **Distribution**: Integration with package managers and app stores
-
----
-
-*This documentation is maintained alongside the YAZE project. For updates or corrections, please refer to the project repository.*