backend-infra-engineer: Release v0.3.8 snapshot

.clang-format

@@ -0,0 +1,83 @@
+# Google C/C++ Code Style settings
+# https://clang.llvm.org/docs/ClangFormatStyleOptions.html
+# Author: Kehan Xue, kehan.xue (at) gmail.com
+
+Language: Cpp
+BasedOnStyle: Google
+AccessModifierOffset: -1
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: None
+AlignOperands: Align
+AllowAllArgumentsOnNextLine: true
+AllowAllConstructorInitializersOnNextLine: true
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: Empty
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: Never  # To avoid conflict, set this "Never" and each "if statement" should include brace when coding
+AllowShortLambdasOnASingleLine: Inline
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterReturnType: None
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: true
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterCaseLabel: false
+  AfterClass: false
+  AfterStruct: false
+  AfterControlStatement: Never
+  AfterEnum: false
+  AfterFunction: false
+  AfterNamespace: false
+  AfterUnion: false
+  AfterExternBlock: false
+  BeforeCatch: false
+  BeforeElse: false
+  BeforeLambdaBody: false
+  IndentBraces: false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: None
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: BeforeColon
+BreakInheritanceList: BeforeColon
+ColumnLimit: 80
+CompactNamespaces: false
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false  # Make sure the * or & align on the left
+EmptyLineBeforeAccessModifier: LogicalBlock
+FixNamespaceComments: true
+IncludeBlocks: Preserve
+IndentCaseLabels: true
+IndentPPDirectives: None
+IndentWidth: 2
+KeepEmptyLinesAtTheStartOfBlocks: true
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PointerAlignment: Left
+ReflowComments: false
+# SeparateDefinitionBlocks: Always   # Only support since clang-format 14
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceBeforeSquareBrackets: false
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles: false
+SpacesInCStyleCastParentheses: false
+SpacesInContainerLiterals: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: c++11
+TabWidth: 4
+UseTab: Never

.clang-tidy

@@ -0,0 +1,130 @@
+# 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,  # 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,  # 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,  # 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-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  
+    value: lower_case
+  - key: readability-identifier-naming.ClassCase
+    value: CamelCase
+  - key: readability-identifier-naming.StructCase
+    value: CamelCase
+  - key: readability-identifier-naming.NamespaceCase
+    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: 200
+  - key: readability-function-size.StatementThreshold
+    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;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|incl)\/.*\.(h|hpp|hxx)$'
+FormatStyle: google
+
+# Additional ROM hacking specific configurations
+UseColor: true
+SystemHeaders: false
+User: ''

.clangd

@@ -0,0 +1,87 @@
+# 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
+    # Platform detection
+    - -DMACOS
+  Remove:
+    - -mllvm
+    - -xclang
+    - -w  # Remove warning suppression for better diagnostics
+
+Index:
+  Background: Build
+  StandardLibrary: Yes
+
+InlayHints:
+  Enabled: Yes
+  ParameterNames: Yes
+  DeducedTypes: Yes
+
+Hover:
+  ShowAKA: Yes
+
+Diagnostics:
+  MissingIncludes: Strict
+  UnusedIncludes: Strict
+  ClangTidy:
+    Add: 
+      # Core checks for ROM hacking software
+      - performance-*
+      - bugprone-*
+      - readability-*
+      - modernize-*
+      - 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  # ROM hacking uses many magic numbers
+      - readability-implicit-bool-conversion
+      - 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,58 @@
+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 \
+          --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 \
+          --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 \
+          --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/ci.yml

@@ -0,0 +1,297 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ "master", "develop" ]
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - 'cmake/**'
+      - 'CMakeLists.txt'
+      - '.github/workflows/**'
+  pull_request:
+    branches: [ "master", "develop" ]
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - '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:
+  BUILD_TYPE: ${{ github.event.inputs.build_type || 'RelWithDebInfo' }}
+
+jobs:
+  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
+            platform: linux
+            preset: ci-linux
+          - name: "macOS 14 (Clang)"
+            os: macos-14
+            platform: macos
+            preset: ci-macos
+          - name: "Windows 2022 (Core)"
+            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
+        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: |
+            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
+
+  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
+
+    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
+        uses: ./.github/actions/build-project
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: ${{ env.BUILD_TYPE }}
+
+      - name: Run stable tests
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: stable
+          preset: ${{ matrix.preset }}
+
+      - name: Run unit tests
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: unit
+          preset: ${{ matrix.preset }}
+
+      - name: Run HTTP API tests
+        if: github.event.inputs.enable_http_api_tests == 'true'
+        run: scripts/agents/test-http-api.sh
+
+  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:
+          submodules: recursive
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: windows
+          preset: ci-windows-ai
+          cache-key: ${{ hashFiles('cmake/dependencies.lock') }}
+
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: windows
+          preset: ci-windows-ai
+          build-type: ${{ env.BUILD_TYPE }}
+
+      - name: Run stable tests (agent stack)
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: stable
+          preset: ci-windows-ai
+
+      - name: Run unit tests (agent stack)
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: unit
+          preset: ci-windows-ai
+
+  code-quality:
+    name: "Code Quality"
+    runs-on: ubuntu-22.04
+    continue-on-error: ${{ github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/') }}
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Install Tools
+      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)$'
+
+  memory-sanitizer:
+    name: "Memory Sanitizer"
+    runs-on: ubuntu-22.04
+    if: |
+      github.event_name == 'pull_request' || 
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.run_sanitizers == 'true')
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+    
+    - 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
+    
+    - name: Configure with AddressSanitizer
+      run: |
+        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" \
+          -DYAZE_BUILD_TESTS=ON
+    
+    - name: Build
+      run: cmake --build build --parallel
+    
+    - name: Test
+      working-directory: build
+      env:
+        ASAN_OPTIONS: detect_leaks=1:abort_on_error=1
+      run: ctest --output-on-failure
+
+  z3ed-agent-test:
+    name: "z3ed Agent"
+    runs-on: macos-14
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+    
+    - name: Install Dependencies
+      run: brew install ollama ninja
+    
+    - name: Build z3ed
+      run: |
+        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: Start Ollama
+      env:
+        OLLAMA_MODEL: qwen2.5-coder:0.5b
+      run: |
+        ollama serve & 
+        sleep 10
+        ollama pull "$OLLAMA_MODEL"
+    
+    - name: Run Test Suite
+      env:
+        OLLAMA_MODEL: qwen2.5-coder:0.5b
+      run: |
+        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/cmake.yml

@@ -1,50 +0,0 @@
-name: CMake
-
-on:
-  push:
-    paths:
-      - 'src/**'
-      - 'test/**'
-    branches: [ "master" ]
-  pull_request:
-    paths:
-      - 'src/**'
-      - 'test/**'
-    branches: [ "master" ]
-
-env:
-  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
-  BUILD_TYPE: Debug
-
-jobs:
-  build:
-    # The CMake configure and build commands are platform agnostic and should work equally well on Windows or Mac.
-    # You can convert this to a matrix build if you need cross-platform coverage.
-    # See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        submodules: recursive
-    
-    - name: Install Video Libs
-      run: sudo apt install libglew-dev 
-      
-    - name: Install Audio Libs
-      run: sudo apt install libwavpack-dev
-
-    - name: Configure CMake
-      # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
-      # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
-      run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
-
-    - name: Build
-      # Build your program with the given configuration
-      run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
-
-    - name: Test
-      working-directory: ${{github.workspace}}/build
-      # Execute tests defined by the CMake configuration.  
-      # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
-      run: ${{github.workspace}}/build/bin/yaze_test

.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

@@ -0,0 +1,81 @@
+name: Doxygen Documentation
+
+# Only run when documentation-related files are modified
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'src/**/*.h'
+      - 'src/**/*.cc'
+      - 'src/**/*.cpp'
+      - 'docs/**'
+      - 'Doxyfile'
+      - '.github/workflows/doxy.yml'
+  pull_request:
+    branches: [ master ]
+    paths:
+      - 'src/**/*.h'
+      - 'src/**/*.cc'
+      - 'src/**/*.cpp'
+      - 'docs/**'
+      - 'Doxyfile'
+      - '.github/workflows/doxy.yml'
+
+
+  
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  generate-docs:
+    name: Generate Documentation
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y doxygen graphviz
+
+    - name: Check if documentation build is needed
+      id: changes
+      run: |
+        # Check if this is the first commit or if docs-related files changed
+        if git show --name-only HEAD | grep -E '\.(h|cc|cpp|md)$|Doxyfile'; then
+          echo "docs_changed=true" >> $GITHUB_OUTPUT
+          echo "📝 Documentation-related files have changed"
+        else
+          echo "docs_changed=false" >> $GITHUB_OUTPUT
+          echo "ℹ️ No documentation changes detected"
+        fi
+
+    - name: Clean previous build
+      if: steps.changes.outputs.docs_changed == 'true'
+      run: rm -rf build/docs
+
+    - name: Generate Doxygen documentation
+      if: steps.changes.outputs.docs_changed == 'true'
+      uses: mattnotmitt/doxygen-action@v1.9.8
+      with:
+        doxyfile-path: "./Doxyfile"
+        working-directory: "."
+
+    - name: Deploy to GitHub Pages
+      if: steps.changes.outputs.docs_changed == 'true'
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./build/docs/html
+        commit_message: 'docs: update API documentation'
+        
+    - name: Summary
+      run: |
+        if [[ "${{ steps.changes.outputs.docs_changed }}" == "true" ]]; then
+          echo "✅ Documentation generated and deployed successfully"
+          echo "📖 View at: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
+        else
+          echo "⏭️ Documentation build skipped - no relevant changes detected"
+        fi

.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/release.yml

@@ -0,0 +1,296 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., v1.0.0)'
+        required: true
+        type: string
+
+env:
+  VERSION: ${{ github.event.inputs.version || github.ref_name }}
+
+jobs:
+  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: Free up disk space (Linux)
+        if: matrix.platform == 'linux'
+        run: |
+          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:
+          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
+        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 -f build/*.deb build/*.tar.gz build/*.dmg build/*.zip build/*.exe 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: Patch cmake_install.cmake (Windows)
+        if: matrix.platform == 'windows'
+        shell: pwsh
+        run: |
+          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"
+
+      - 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: "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: 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
+        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: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: ./artifacts
+
+      - name: Display downloaded artifacts
+        run: |
+          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

.gitignore

@@ -1,19 +1,95 @@
-build/
-.cache/
-.vscode/
-src/lib/SDL2
-src/lib/cmake
-src/lib/GL
-src/lib/abseil-cpp
-src/lib/libGLEW.2.2.0.dylib
-src/lib/libGLEW.2.2.dylib
-src/lib/libGLEW.a
-src/lib/libGLEW.dylib
-src/lib/libSDL2_test.a
-src/lib/libSDL2-2.0.0.dylib
-src/lib/libSDL2.a
-src/lib/libSDL2.dylib
-src/lib/libSDL2main.a
-checks.json
-assets/lib/libasar.dll
-cmake/yaze.plist.in
+# 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/
+.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
+.favorites.json
+checks.json
+assets/etc/
+imgui.ini
+.gitignore
+recent_files.txt
+.vs/*
+.gitignore
+.genkit
+.claude
+scripts/__pycache__/

.gitmodules

@@ -1,30 +1,27 @@
-[submodule "src/lib/imgui"]
-	path = src/lib/imgui
+[submodule "ext/imgui"]
+	path = ext/imgui
 	url = https://github.com/ocornut/imgui.git
-[submodule "src/lib/ImGuiFileDialog"]
-	path = src/lib/ImGuiFileDialog
-	url = https://github.com/aiekick/ImGuiFileDialog.git
-[submodule "src/lib/ImGuiColorTextEdit"]
-	path = src/lib/ImGuiColorTextEdit
-	url = https://github.com/BalazsJako/ImGuiColorTextEdit.git
-[submodule "src/lib/sneshacking"]
-	path = src/lib/sneshacking
-	url = https://github.com/Skarsnik/sneshacking.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/snes_spc"]
-	path = src/lib/snes_spc
-	url = https://github.com/blarggs-audio-libraries/snes_spc.git
-[submodule "src/lib/SDL_mixer"]
-	path = src/lib/SDL_mixer
-	url = https://github.com/libsdl-org/SDL_mixer.git
+[submodule "ext/imgui_test_engine"]
+	path = ext/imgui_test_engine
+	url = https://github.com/ocornut/imgui_test_engine.git
+[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,45 @@
+## Inter-Agent Collaboration Protocol
+
+Multiple assistants may work in this repository at the same time. To avoid conflicts, every agent
+must follow the shared protocol defined in
+[`docs/internal/agents/coordination-board.md`](docs/internal/agents/coordination-board.md).
+
+### Required Steps
+1. **Read the board** before starting a task to understand active work, blockers, or pending
+   requests.
+2. **Append a new entry** (format described in the coordination board) outlining your intent,
+   affected files, and any dependencies.
+3. **Respond to requests** addressed to your agent ID before taking on new work whenever possible.
+4. **Record completion or handoffs** so the next agent has a clear state snapshot.
+5. For multi-day initiatives, fill out the template in
+   [`docs/internal/agents/initiative-template.md`](docs/internal/agents/initiative-template.md) and
+   link it from your board entry instead of duplicating long notes.
+
+### Agent IDs
+Use the following canonical identifiers in board entries and handoffs (see
+[`docs/internal/agents/personas.md`](docs/internal/agents/personas.md) for details):
+
+| Agent ID        | Description                                      |
+|-----------------|--------------------------------------------------|
+| `CLAUDE_CORE`   | Claude agent handling general editor/engine work |
+| `CLAUDE_AIINF`  | Claude agent focused on AI/agent infrastructure   |
+| `CLAUDE_DOCS`   | Claude agent dedicated to docs/product guidance   |
+| `GEMINI_FLASH_AUTOM` | Gemini agent focused on automation/CLI/test work |
+| `CODEX`         | This Codex CLI assistant                          |
+| `OTHER`         | Any future agent (define in entry)                |
+
+If you introduce a new agent persona, add it to the table along with a short description.
+
+### Helper Scripts
+Common automation helpers live under [`scripts/agents/`](scripts/agents). Use them whenever possible:
+- `run-gh-workflow.sh` – trigger GitHub workflows (`ci.yml`, etc.) with parameters such as `enable_http_api_tests`.
+- `smoke-build.sh` – configure/build a preset in place and report how long it took.
+- `run-tests.sh` – configure/build a preset and run `ctest` (`scripts/agents/run-tests.sh mac-dbg --output-on-failure`).
+- `test-http-api.sh` – poll the `/api/v1/health` endpoint once the HTTP server is running.
+
+Log command results and workflow URLs on the coordination board so other agents know what ran and where to find artifacts.
+
+### Escalation
+If two agents need the same subsystem concurrently, negotiate via the board using the
+`REQUEST`/`BLOCKER` keywords. When in doubt, prefer smaller, well-defined handoffs instead of broad
+claims over directories.

CLAUDE.md

@@ -0,0 +1,295 @@
+# 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
+
+```bash
+# Build tests
+cmake --build build --target yaze_test
+
+# Run all tests
+./build/bin/yaze_test
+
+# Run specific categories
+./build/bin/yaze_test --unit              # Unit tests only
+./build/bin/yaze_test --integration       # Integration tests
+./build/bin/yaze_test --e2e --show-gui    # End-to-end GUI tests
+
+# Run with ROM-dependent tests
+./build/bin/yaze_test --rom-dependent --rom-path zelda3.sfc
+
+# Run specific test by name
+./build/bin/yaze_test "*Asar*"
+```
+
+## 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
+
+### 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
+- **Unit Tests**: Fast, self-contained, no external dependencies (primary CI validation)
+- **Integration Tests**: Test component interactions, may require ROM files
+- **E2E Tests**: Full user workflows driven by ImGui Test Engine (requires GUI)
+- **ROM-Dependent Tests**: Any test requiring an actual Zelda3 ROM file
+
+### Writing New Tests
+- New class `MyClass`? → Add `test/unit/my_class_test.cc`
+- Testing with ROM? → Add `test/integration/my_class_rom_test.cc`
+- Testing UI workflow? → Add `test/e2e/my_class_workflow_test.cc`
+
+### 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

@@ -1,57 +1,138 @@
-# CMake Specifications 
-cmake_minimum_required(VERSION 3.10)
-
 # Yet Another Zelda3 Editor
 # by scawful
-project(yaze VERSION 0.01)
+cmake_minimum_required(VERSION 3.16)
 
-# C++ Standard Specifications 
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-set(CMAKE_CXX_EXTENSIONS ON)
-set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
-set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
-set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
-set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
-set(CMAKE_POSITION_INDEPENDENT_CODE ON)
-set(CMAKE_MODULE_LINKER_FLAGS \"-Wl,--no-undefined -Wl,--no-undefined\")
+# 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(CMAKE_SYSTEM_NAME MATCHES "Darwin")
+    project(yaze VERSION 0.3.8
+                 DESCRIPTION "Yet Another Zelda3 Editor"
+                 LANGUAGES CXX C OBJC OBJCXX)
+else()
+    project(yaze VERSION 0.3.8
+                 DESCRIPTION "Yet Another Zelda3 Editor"
+                 LANGUAGES CXX C)
+endif()
+
+# 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")
+
+# Add cmake directory to module path
 set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
-set(BUILD_SHARED_LIBS ON)
 
-# Abseil Standard Specifications
-include(cmake/absl.cmake)
-add_subdirectory(src/lib/abseil-cpp)
+# Include utility functions
+include(cmake/utils.cmake)
 
-include(cmake/openssl.cmake)
+# Set up dependencies using CPM.cmake
+include(cmake/dependencies.cmake)
 
-# Video Libraries 
-find_package(PNG REQUIRED)
-find_package(OpenGL REQUIRED)
-include(cmake/sdl2.cmake)
+# 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")
 
-# Asar 
-# add_subdirectory(src/lib/asar/src)
-# include(cmake/asar.cmake)
+# Export compile commands for clangd/LSP
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
-# snes-spc
-ADD_DEFINITIONS(-DSNES_SPC_EXPORTS)
-set(SNES_SPC_SOURCES
-  "../src/lib/snes_spc/snes_spc/spc.cpp"
-  "../src/lib/snes_spc/snes_spc/SNES_SPC.cpp"
-  "../src/lib/snes_spc/snes_spc/SNES_SPC_misc.cpp"
-  "../src/lib/snes_spc/snes_spc/SNES_SPC_state.cpp"
-  "../src/lib/snes_spc/snes_spc/SPC_DSP.cpp"
-  "../src/lib/snes_spc/snes_spc/dsp.cpp"
-  "../src/lib/snes_spc/snes_spc/SPC_Filter.cpp"
-  "../src/lib/snes_spc/demo/wave_writer.c"
-  "../src/lib/snes_spc/demo/demo_util.c"
+# Platform detection
+if(CMAKE_SYSTEM_NAME MATCHES "Darwin")
+    set(YAZE_PLATFORM_MACOS ON)
+elseif(CMAKE_SYSTEM_NAME MATCHES "Linux")
+    set(YAZE_PLATFORM_LINUX ON)
+elseif(CMAKE_SYSTEM_NAME MATCHES "Windows")
+    set(YAZE_PLATFORM_WINDOWS ON)
+endif()
+
+# Setup compiler flags and common interface target
+yaze_add_compiler_flags()
+
+# Configure yaze_config.h
+configure_file(
+  ${CMAKE_CURRENT_SOURCE_DIR}/src/yaze_config.h.in
+  ${CMAKE_CURRENT_BINARY_DIR}/yaze_config.h
+  @ONLY
 )
-include_directories(src/lib/snes_spc/snes_spc)
-ADD_LIBRARY(snes_spc STATIC ${SNES_SPC_SOURCES} src/app/zelda3/music/spc700.def)
 
-# ImGui
-include(cmake/imgui.cmake)
+# 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)
+
+# Handle dependencies
 
 # Project Files
 add_subdirectory(src)
-add_subdirectory(test)
+
+# 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)
+endif()
+
+# Code quality targets
+find_program(CLANG_FORMAT NAMES clang-format clang-format-14 clang-format-15 clang-format-16 clang-format-17 clang-format-18)
+if(CLANG_FORMAT)
+  file(GLOB_RECURSE ALL_SOURCE_FILES
+       "${CMAKE_SOURCE_DIR}/src/*.cc"
+       "${CMAKE_SOURCE_DIR}/src/*.h"
+       "${CMAKE_SOURCE_DIR}/test/*.cc"
+       "${CMAKE_SOURCE_DIR}/test/*.h")
+
+  # 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(yaze-format-check
+    COMMAND ${CLANG_FORMAT} --dry-run --Werror --style=Google ${ALL_SOURCE_FILES}
+    COMMENT "Checking code format"
+  )
+endif()
+
+# Packaging configuration
+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"
+)

CMakePresets.json

@@ -0,0 +1,938 @@
+{
+  "version": 6,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 16,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "base",
+      "hidden": true,
+      "description": "Base preset with common settings",
+      "binaryDir": "${sourceDir}/build",
+      "generator": "Ninja Multi-Config",
+      "cacheVariables": {
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+        "YAZE_BUILD_APP": "ON",
+        "YAZE_BUILD_LIB": "ON",
+        "YAZE_BUILD_EMU": "ON",
+        "YAZE_BUILD_CLI": "ON"
+      }
+    },
+    {
+      "name": "windows-base",
+      "hidden": true,
+      "description": "Base Windows preset with MSVC/clang-cl support",
+      "binaryDir": "${sourceDir}/build",
+      "generator": "Ninja Multi-Config",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Windows"
+      },
+      "cacheVariables": {
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+        "CMAKE_MSVC_RUNTIME_LIBRARY": "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL",
+        "YAZE_BUILD_APP": "ON",
+        "YAZE_BUILD_LIB": "ON",
+        "YAZE_BUILD_EMU": "ON",
+        "YAZE_BUILD_CLI": "ON",
+        "YAZE_SUPPRESS_WARNINGS": "ON"
+      },
+      "architecture": {
+        "value": "x64",
+        "strategy": "external"
+      }
+    },
+    {
+      "name": "windows-vs-base",
+      "hidden": true,
+      "description": "Base Windows preset for Visual Studio Generator",
+      "binaryDir": "${sourceDir}/build",
+      "generator": "Visual Studio 17 2022",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Windows"
+      },
+      "cacheVariables": {
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+        "CMAKE_MSVC_RUNTIME_LIBRARY": "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL",
+        "YAZE_BUILD_APP": "ON",
+        "YAZE_BUILD_LIB": "ON",
+        "YAZE_BUILD_EMU": "ON",
+        "YAZE_BUILD_CLI": "ON",
+        "YAZE_SUPPRESS_WARNINGS": "ON"
+      },
+      "architecture": {
+        "value": "x64",
+        "strategy": "set"
+      }
+    },
+    {
+      "name": "dev",
+      "inherits": "base",
+      "displayName": "Developer Build",
+      "description": "Full development build with all features",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_ENABLE_ROM_TESTS": "ON"
+      }
+    },
+    {
+      "name": "ci",
+      "inherits": "base",
+      "displayName": "CI Build",
+      "description": "Continuous integration build",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_ENABLE_ROM_TESTS": "OFF",
+        "YAZE_MINIMAL_BUILD": "OFF"
+      }
+    },
+    {
+      "name": "release",
+      "inherits": "base",
+      "displayName": "Release Build",
+      "description": "Optimized release build",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "YAZE_BUILD_TESTS": "OFF",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_ENABLE_LTO": "ON"
+      }
+    },
+    {
+      "name": "minimal",
+      "inherits": "base",
+      "displayName": "Minimal Build",
+      "description": "Minimal build for CI (no gRPC/AI)",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_MINIMAL_BUILD": "ON"
+      }
+    },
+    {
+      "name": "ci-linux",
+      "inherits": "base",
+      "displayName": "CI Build - Linux",
+      "description": "CI build with gRPC enabled (uses caching for speed)",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_ROM_TESTS": "OFF",
+        "YAZE_MINIMAL_BUILD": "OFF",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "ci-macos",
+      "inherits": "base",
+      "displayName": "CI Build - macOS",
+      "description": "CI build with gRPC enabled (uses caching for speed)",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_ROM_TESTS": "OFF",
+        "YAZE_MINIMAL_BUILD": "OFF",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "ci-windows",
+      "inherits": "windows-base",
+      "displayName": "CI Build - Windows",
+      "description": "CI build with gRPC enabled (uses MSVC-compatible version 1.67.1)",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_ROM_TESTS": "OFF",
+        "YAZE_MINIMAL_BUILD": "OFF",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "ci-windows-ai",
+      "inherits": "windows-base",
+      "displayName": "CI Build - Windows (Agent)",
+      "description": "Full agent build with gRPC + AI runtime (runs outside PRs)",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_ENABLE_ROM_TESTS": "OFF",
+        "YAZE_MINIMAL_BUILD": "OFF",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "ON"
+      }
+    },
+    {
+      "name": "coverage",
+      "inherits": "dev",
+      "displayName": "Coverage Build",
+      "description": "Debug build with code coverage",
+      "cacheVariables": {
+        "YAZE_ENABLE_COVERAGE": "ON",
+        "CMAKE_CXX_FLAGS": "--coverage -g -O0",
+        "CMAKE_C_FLAGS": "--coverage -g -O0",
+        "CMAKE_EXE_LINKER_FLAGS": "--coverage"
+      }
+    },
+    {
+      "name": "sanitizer",
+      "inherits": "dev",
+      "displayName": "Sanitizer Build",
+      "description": "Debug build with AddressSanitizer",
+      "cacheVariables": {
+        "YAZE_ENABLE_SANITIZERS": "ON",
+        "CMAKE_CXX_FLAGS": "-fsanitize=address -fno-omit-frame-pointer -g",
+        "CMAKE_C_FLAGS": "-fsanitize=address -fno-omit-frame-pointer -g",
+        "CMAKE_EXE_LINKER_FLAGS": "-fsanitize=address"
+      }
+    },
+    {
+      "name": "verbose",
+      "inherits": "dev",
+      "displayName": "Verbose Build",
+      "description": "Development build with all warnings",
+      "cacheVariables": {
+        "YAZE_SUPPRESS_WARNINGS": "OFF"
+      }
+    },
+    {
+      "name": "win-dbg",
+      "inherits": "windows-base",
+      "displayName": "Windows Debug (Ninja)",
+      "description": "Debug build for Windows with Ninja generator",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "win-dbg-v",
+      "inherits": "win-dbg",
+      "displayName": "Windows Debug Verbose",
+      "description": "Debug build with verbose warnings",
+      "cacheVariables": {
+        "YAZE_SUPPRESS_WARNINGS": "OFF"
+      }
+    },
+    {
+      "name": "win-rel",
+      "inherits": "windows-base",
+      "displayName": "Windows Release (Ninja)",
+      "description": "Release build for Windows with Ninja generator",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "YAZE_BUILD_TESTS": "OFF",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_LTO": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "win-dev",
+      "inherits": "windows-base",
+      "displayName": "Windows Development",
+      "description": "Development build with ROM tests",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_ROM_TESTS": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "win-ai",
+      "inherits": "windows-base",
+      "displayName": "Windows AI Development",
+      "description": "Full development build with AI features and gRPC",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_ENABLE_ROM_TESTS": "ON",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "ON"
+      }
+    },
+    {
+      "name": "win-z3ed",
+      "inherits": "windows-base",
+      "displayName": "Windows z3ed CLI",
+      "description": "z3ed CLI with AI agent support",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "YAZE_BUILD_TESTS": "OFF",
+        "YAZE_BUILD_CLI": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "ON"
+      }
+    },
+    {
+      "name": "win-arm",
+      "inherits": "windows-base",
+      "displayName": "Windows ARM64 Debug",
+      "description": "Debug build for Windows ARM64",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      },
+      "architecture": {
+        "value": "ARM64",
+        "strategy": "external"
+      }
+    },
+    {
+      "name": "win-arm-rel",
+      "inherits": "win-arm",
+      "displayName": "Windows ARM64 Release",
+      "description": "Release build for Windows ARM64",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "YAZE_BUILD_TESTS": "OFF",
+        "YAZE_ENABLE_LTO": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "win-vs-dbg",
+      "inherits": "windows-vs-base",
+      "displayName": "Windows Debug (Visual Studio)",
+      "description": "Debug build for Visual Studio IDE",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "win-vs-rel",
+      "inherits": "windows-vs-base",
+      "displayName": "Windows Release (Visual Studio)",
+      "description": "Release build for Visual Studio IDE",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "YAZE_BUILD_TESTS": "OFF",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_LTO": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "win-vs-ai",
+      "inherits": "windows-vs-base",
+      "displayName": "Windows AI Development (Visual Studio)",
+      "description": "Full development build with AI features for Visual Studio",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_ENABLE_ROM_TESTS": "ON",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "ON"
+      }
+    },
+    {
+      "name": "mac-dbg",
+      "inherits": "base",
+      "displayName": "macOS Debug",
+      "description": "Debug build for macOS",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Darwin"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "mac-dbg-v",
+      "inherits": "mac-dbg",
+      "displayName": "macOS Debug Verbose",
+      "description": "Debug build with verbose warnings",
+      "cacheVariables": {
+        "YAZE_SUPPRESS_WARNINGS": "OFF"
+      }
+    },
+    {
+      "name": "mac-rel",
+      "inherits": "base",
+      "displayName": "macOS Release",
+      "description": "Release build for macOS",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Darwin"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "YAZE_BUILD_TESTS": "OFF",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_LTO": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "mac-dev",
+      "inherits": "base",
+      "displayName": "macOS Development",
+      "description": "Development build with ROM tests",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Darwin"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_ROM_TESTS": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "mac-ai",
+      "inherits": "base",
+      "displayName": "macOS AI Development",
+      "description": "Full development build with AI features and gRPC",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Darwin"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_ENABLE_ROM_TESTS": "ON",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "ON"
+      }
+    },
+    {
+      "name": "mac-uni",
+      "inherits": "base",
+      "displayName": "macOS Universal Binary",
+      "description": "Universal binary for macOS (ARM64 + x86_64)",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Darwin"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "CMAKE_OSX_ARCHITECTURES": "arm64;x86_64",
+        "YAZE_BUILD_TESTS": "OFF",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_LTO": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "lin-dbg",
+      "inherits": "base",
+      "displayName": "Linux Debug",
+      "description": "Debug build for Linux",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Linux"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "lin-dbg-v",
+      "inherits": "lin-dbg",
+      "displayName": "Linux Debug Verbose",
+      "description": "Debug build with verbose warnings",
+      "cacheVariables": {
+        "YAZE_SUPPRESS_WARNINGS": "OFF"
+      }
+    },
+    {
+      "name": "lin-rel",
+      "inherits": "base",
+      "displayName": "Linux Release",
+      "description": "Release build for Linux",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Linux"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "YAZE_BUILD_TESTS": "OFF",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_LTO": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "lin-dev",
+      "inherits": "base",
+      "displayName": "Linux Development",
+      "description": "Development build with ROM tests",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Linux"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "OFF",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "OFF",
+        "YAZE_ENABLE_ROM_TESTS": "ON",
+        "YAZE_BUILD_AGENT_UI": "OFF",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "OFF",
+        "YAZE_ENABLE_AI_RUNTIME": "OFF"
+      }
+    },
+    {
+      "name": "lin-ai",
+      "inherits": "base",
+      "displayName": "Linux AI Development",
+      "description": "Full development build with AI features and gRPC",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Linux"
+      },
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "YAZE_BUILD_TESTS": "ON",
+        "YAZE_ENABLE_GRPC": "ON",
+        "YAZE_ENABLE_JSON": "ON",
+        "YAZE_ENABLE_AI": "ON",
+        "YAZE_ENABLE_ROM_TESTS": "ON",
+        "YAZE_BUILD_AGENT_UI": "ON",
+        "YAZE_ENABLE_REMOTE_AUTOMATION": "ON",
+        "YAZE_ENABLE_AI_RUNTIME": "ON"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "dev",
+      "configurePreset": "dev",
+      "displayName": "Developer Build",
+      "jobs": 12
+    },
+    {
+      "name": "ci",
+      "configurePreset": "ci",
+      "displayName": "CI Build",
+      "jobs": 12
+    },
+    {
+      "name": "release",
+      "configurePreset": "release",
+      "displayName": "Release Build",
+      "jobs": 12
+    },
+    {
+      "name": "minimal",
+      "configurePreset": "minimal",
+      "displayName": "Minimal Build",
+      "jobs": 12
+    },
+    {
+      "name": "ci-linux",
+      "configurePreset": "ci-linux",
+      "displayName": "CI Build - Linux",
+      "jobs": 12
+    },
+    {
+      "name": "ci-macos",
+      "configurePreset": "ci-macos",
+      "displayName": "CI Build - macOS",
+      "jobs": 12
+    },
+    {
+      "name": "ci-windows",
+      "configurePreset": "ci-windows",
+      "displayName": "CI Build - Windows",
+      "configuration": "RelWithDebInfo",
+      "jobs": 12
+    },
+    {
+      "name": "ci-windows-ai",
+      "configurePreset": "ci-windows-ai",
+      "displayName": "CI Build - Windows (AI)",
+      "configuration": "RelWithDebInfo",
+      "jobs": 12
+    },
+    {
+      "name": "coverage",
+      "configurePreset": "coverage",
+      "displayName": "Coverage Build",
+      "jobs": 12
+    },
+    {
+      "name": "sanitizer",
+      "configurePreset": "sanitizer",
+      "displayName": "Sanitizer Build",
+      "jobs": 12
+    },
+    {
+      "name": "verbose",
+      "configurePreset": "verbose",
+      "displayName": "Verbose Build",
+      "jobs": 12
+    },
+    {
+      "name": "win-dbg",
+      "configurePreset": "win-dbg",
+      "displayName": "Windows Debug Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "win-dbg-v",
+      "configurePreset": "win-dbg-v",
+      "displayName": "Windows Debug Verbose Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "win-rel",
+      "configurePreset": "win-rel",
+      "displayName": "Windows Release Build",
+      "configuration": "Release",
+      "jobs": 12
+    },
+    {
+      "name": "win-dev",
+      "configurePreset": "win-dev",
+      "displayName": "Windows Development Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "win-ai",
+      "configurePreset": "win-ai",
+      "displayName": "Windows AI Development Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "win-z3ed",
+      "configurePreset": "win-z3ed",
+      "displayName": "Windows z3ed CLI Build",
+      "configuration": "Release",
+      "jobs": 12
+    },
+    {
+      "name": "win-arm",
+      "configurePreset": "win-arm",
+      "displayName": "Windows ARM64 Debug Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "win-arm-rel",
+      "configurePreset": "win-arm-rel",
+      "displayName": "Windows ARM64 Release Build",
+      "configuration": "Release",
+      "jobs": 12
+    },
+    {
+      "name": "win-vs-dbg",
+      "configurePreset": "win-vs-dbg",
+      "displayName": "Windows Debug Build (Visual Studio)",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "win-vs-rel",
+      "configurePreset": "win-vs-rel",
+      "displayName": "Windows Release Build (Visual Studio)",
+      "configuration": "Release",
+      "jobs": 12
+    },
+    {
+      "name": "win-vs-ai",
+      "configurePreset": "win-vs-ai",
+      "displayName": "Windows AI Development Build (Visual Studio)",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "mac-dbg",
+      "configurePreset": "mac-dbg",
+      "displayName": "macOS Debug Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "mac-dbg-v",
+      "configurePreset": "mac-dbg-v",
+      "displayName": "macOS Debug Verbose Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "mac-rel",
+      "configurePreset": "mac-rel",
+      "displayName": "macOS Release Build",
+      "configuration": "Release",
+      "jobs": 12
+    },
+    {
+      "name": "mac-dev",
+      "configurePreset": "mac-dev",
+      "displayName": "macOS Development Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "mac-ai",
+      "configurePreset": "mac-ai",
+      "displayName": "macOS AI Development Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "mac-uni",
+      "configurePreset": "mac-uni",
+      "displayName": "macOS Universal Binary Build",
+      "configuration": "Release",
+      "jobs": 12
+    },
+    {
+      "name": "lin-dbg",
+      "configurePreset": "lin-dbg",
+      "displayName": "Linux Debug Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "lin-dbg-v",
+      "configurePreset": "lin-dbg-v",
+      "displayName": "Linux Debug Verbose Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "lin-rel",
+      "configurePreset": "lin-rel",
+      "displayName": "Linux Release Build",
+      "configuration": "Release",
+      "jobs": 12
+    },
+    {
+      "name": "lin-dev",
+      "configurePreset": "lin-dev",
+      "displayName": "Linux Development Build",
+      "configuration": "Debug",
+      "jobs": 12
+    },
+    {
+      "name": "lin-ai",
+      "configurePreset": "lin-ai",
+      "displayName": "Linux AI Development Build",
+      "configuration": "Debug",
+      "jobs": 12
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "all",
+      "configurePreset": "dev",
+      "displayName": "All Tests",
+      "description": "Run all tests including ROM-dependent tests"
+    },
+    {
+      "name": "stable",
+      "configurePreset": "minimal",
+      "displayName": "Stable Tests",
+      "description": "Run stable tests only (no ROM dependency)",
+      "filter": {
+        "include": {
+          "label": "stable"
+        }
+      }
+    },
+    {
+      "name": "unit",
+      "configurePreset": "minimal",
+      "displayName": "Unit Tests",
+      "description": "Run unit tests only",
+      "filter": {
+        "include": {
+          "label": "unit"
+        }
+      }
+    },
+    {
+      "name": "integration",
+      "configurePreset": "minimal",
+      "displayName": "Integration Tests",
+      "description": "Run integration tests only",
+      "filter": {
+        "include": {
+          "label": "integration"
+        }
+      }
+    },
+    {
+      "name": "stable-ai",
+      "configurePreset": "ci-windows-ai",
+      "displayName": "Stable Tests (Agent Stack)",
+      "description": "Run stable tests against the ci-windows-ai preset",
+      "filter": {
+        "include": {
+          "label": "stable"
+        }
+      }
+    },
+    {
+      "name": "unit-ai",
+      "configurePreset": "ci-windows-ai",
+      "displayName": "Unit Tests (Agent Stack)",
+      "description": "Run unit tests against the ci-windows-ai preset",
+      "filter": {
+        "include": {
+          "label": "unit"
+        }
+      }
+    },
+    {
+      "name": "integration-ai",
+      "configurePreset": "ci-windows-ai",
+      "displayName": "Integration Tests (Agent Stack)",
+      "description": "Run integration tests against the ci-windows-ai preset",
+      "filter": {
+        "include": {
+          "label": "integration"
+        }
+      }
+    }
+  ],
+  "packagePresets": [
+    {
+      "name": "release",
+      "configurePreset": "release",
+      "displayName": "Release Package"
+    },
+    {
+      "name": "minimal",
+      "configurePreset": "minimal",
+      "displayName": "Minimal Package"
+    }
+  ]
+}

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.

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.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2022 Justin Scofield
+Copyright (C) 2024 Justin Scofield
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -13,3 +13,7 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
+Dependencies:
+- SDL2 <https://www.libsdl.org/license.php>
+- ImGui <https://github.com/ocornut/imgui/blob/master/LICENSE.txt>
+- Abseil <https://github.com/abseil/abseil-cpp/blob/master/LICENSE>

README.md

@@ -1,52 +1,98 @@
-# Yet Another Zelda3 Editor
+# YAZE - Yet Another Zelda3 Editor
 
-- Platform: Windows, macOS, GNU/Linux
-- Dependencies: SDL2, ImGui
+[![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)
 
-## Description
+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.
 
-General purpose editor for The Legend of Zelda: A Link to the Past for the Super Nintendo.
+## 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.
 
-Takes heavy inspiration from ALTTP community efforts such as [Hyrule Magic](https://www.romhacking.net/utilities/200/) and [ZScream](https://github.com/Zarby89/ZScreamDungeon)
+## 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.
 
-Building and installation
--------------------------
-[CMake](http://www.cmake.org "CMake") is required to build yaze 
+## Quick Start
 
-1. Clone the repository
-
-```
-  git clone --recurse-submodules https://github.com/scawful/yaze.git 
+### Clone & Bootstrap
+```bash
+git clone --recursive https://github.com/scawful/yaze.git
+cd yaze
 ```
 
-2. Create the build directory and configuration
+Run the environment verifier once per machine:
+```bash
+# macOS / Linux
+./scripts/verify-build-environment.sh --fix
 
-```
-  cmake -S . -B build
+# Windows (PowerShell)
+.\scripts\verify-build-environment.ps1 -FixIssues
 ```
 
-3. Build and run.
+### 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.
 
+### 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
 ```
-  cmake --build build
-```
+
+## 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).
 
-- For users, please refer to [getting_started.md](docs/getting-started.md) for instructions on how to use yaze.
-- For developers, please refer to [infrastructure.md](docs/infrastructure.md) for information on the project's infrastructure.
+## 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 distributed under the [GNU GPLv3](https://www.gnu.org/licenses/gpl-3.0.txt) license.
-
-SDL2, ImGui and Abseil are subject to respective licenses.
-
-Screenshots
---------
-![image](https://user-images.githubusercontent.com/47263509/194669806-2b0da68d-9d38-4f52-bcce-c60ee861092c.png)
-
-![image](https://github.com/scawful/yaze/assets/47263509/8913f7ff-6345-4295-ae05-782fd3949eb5)
-
-![image](https://github.com/scawful/yaze/assets/47263509/e1cf3edb-a59e-4f0a-b4e0-d68925803e58)
+## License
+YAZE is licensed under the GNU GPL v3. See [`LICENSE`](LICENSE) for details and third-party notices.
 
+## 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)

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

@@ -0,0 +1,22 @@
+; =========================================================
+; yaze custom assembly code 
+; =========================================================
+
+namespace yaze
+{
+
+!YAZE_CUSTOM_MOSAIC = 0
+
+
+if !YAZE_CUSTOM_MOSAIC != 0
+  incsrc "mosaic_change.asm"
+endif
+
+!ZS_CUSTOM_OVERWORLD = 1
+
+if !ZS_CUSTOM_OVERWORLD != 0
+  incsrc "ZSCustomOverworld_v3.asm"
+endif
+
+}
+namespace off

assets/themes/cyberpunk.theme

@@ -0,0 +1,62 @@
+# Cyberpunk Theme
+# Neon-inspired futuristic theme
+name=Cyberpunk
+description=Neon-inspired futuristic theme
+author=YAZE Team
+version=1.0
+
+[colors]
+# Primary colors (neon cyberpunk)
+primary=255,20,147,255
+secondary=0,255,255,255
+accent=255,0,128,255
+background=10,10,20,255
+surface=20,20,40,255
+
+# Status colors
+error=255,50,100,255
+warning=255,255,0,255
+success=0,255,100,255
+info=100,200,255,255
+
+# Text colors
+text_primary=255,255,255,255
+text_secondary=200,200,255,255
+text_disabled=100,100,150,255
+
+# Window colors
+window_bg=15,15,30,240
+child_bg=10,10,25,200
+popup_bg=20,20,40,250
+
+# Interactive elements
+button=40,20,60,255
+button_hovered=120,20,120,255
+button_active=160,40,160,255
+frame_bg=30,30,50,255
+frame_bg_hovered=40,40,70,255
+frame_bg_active=60,20,80,255
+
+# Navigation
+header=30,10,50,255
+header_hovered=80,20,100,255
+header_active=120,40,140,255
+tab=25,15,45,255
+tab_hovered=60,30,80,255
+tab_active=100,20,120,255
+menu_bar_bg=20,10,40,255
+title_bg=25,15,45,255
+title_bg_active=30,10,50,255
+title_bg_collapsed=25,15,45,255
+
+[style]
+window_rounding=10.0
+frame_rounding=8.0
+scrollbar_rounding=10.0
+grab_rounding=6.0
+tab_rounding=6.0
+window_border_size=1.0
+frame_border_size=1.0
+enable_animations=true
+enable_glow_effects=true
+animation_speed=1.5

assets/themes/forest.theme

@@ -0,0 +1,73 @@
+# Forest Theme
+# Enhanced forest theme with better readability
+name=Forest
+description=Deep forest theme with enhanced readability
+author=YAZE Team
+version=1.0
+
+[colors]
+# Primary colors (enhanced forest with better contrast)
+primary=100,180,120,255         # Brighter forest green
+secondary=70,130,85,255         # Mid forest green
+accent=130,220,150,255          # Light accent green
+background=15,25,15,255         # Darker background for contrast
+surface=25,35,25,255
+
+# Status colors
+error=255,120,120,255
+warning=255,220,120,255
+success=100,180,120,255
+info=120,200,180,255
+
+# Text colors (enhanced for readability)
+text_primary=250,255,250,255    # Very light for contrast
+text_secondary=220,240,220,255  # Light green tint
+text_disabled=150,170,150,255   # Brighter disabled text
+
+# Window colors (better contrast)
+window_bg=20,30,20,240
+child_bg=15,25,15,200
+popup_bg=25,35,25,250
+
+# Interactive elements (better visibility)
+button=70,110,80,255
+button_hovered=100,150,115,255
+button_active=130,180,145,255
+frame_bg=40,60,45,200
+frame_bg_hovered=55,80,60,220
+frame_bg_active=70,110,80,240
+
+# Navigation (better contrast)
+header=55,85,60,255
+header_hovered=100,150,115,255
+header_active=130,180,145,255
+tab=45,75,50,255
+tab_hovered=70,110,80,255
+tab_active=100,150,115,255
+menu_bar_bg=40,70,45,255
+title_bg=50,80,55,255
+title_bg_active=55,85,60,255
+title_bg_collapsed=45,75,50,255
+
+# Separators (better visibility)
+separator=120,160,130,180
+separator_hovered=150,200,160,220
+separator_active=180,240,190,255
+
+# Scrollbars (better visibility)
+scrollbar_bg=40,60,45,180
+scrollbar_grab=80,120,90,200
+scrollbar_grab_hovered=100,150,115,230
+scrollbar_grab_active=130,180,145,255
+
+[style]
+window_rounding=6.0
+frame_rounding=4.0
+scrollbar_rounding=6.0
+grab_rounding=3.0
+tab_rounding=3.0
+window_border_size=0.0
+frame_border_size=0.0
+enable_animations=true
+enable_glow_effects=false
+animation_speed=1.0

assets/themes/midnight.theme

@@ -0,0 +1,73 @@
+# Midnight Theme
+# Enhanced midnight theme with better readability
+name=Midnight
+description=Deep blue midnight theme with enhanced readability
+author=YAZE Team
+version=1.0
+
+[colors]
+# Primary colors (enhanced midnight with better contrast)
+primary=100,160,230,255         # Brighter blue
+secondary=70,120,180,255        # Mid blue
+accent=140,200,255,255          # Light blue accent
+background=10,15,25,255         # Darker background for contrast
+surface=20,25,35,255
+
+# Status colors
+error=255,120,120,255
+warning=255,220,120,255
+success=120,255,180,255
+info=140,200,255,255
+
+# Text colors (enhanced for readability)
+text_primary=245,250,255,255    # Very light blue-white
+text_secondary=200,220,240,255  # Light blue tint
+text_disabled=140,160,180,255   # Brighter disabled text
+
+# Window colors (better contrast)
+window_bg=15,20,30,240
+child_bg=10,15,25,200
+popup_bg=20,25,35,250
+
+# Interactive elements (better visibility)
+button=50,80,120,255
+button_hovered=80,120,160,255
+button_active=110,150,190,255
+frame_bg=30,45,65,200
+frame_bg_hovered=40,60,85,220
+frame_bg_active=60,90,130,240
+
+# Navigation (better contrast)
+header=40,65,100,255
+header_hovered=70,110,150,255
+header_active=100,140,180,255
+tab=30,55,90,255
+tab_hovered=50,80,120,255
+tab_active=70,110,150,255
+menu_bar_bg=25,50,85,255
+title_bg=35,60,95,255
+title_bg_active=40,65,100,255
+title_bg_collapsed=30,55,90,255
+
+# Separators (better visibility)
+separator=100,140,180,180
+separator_hovered=130,170,210,220
+separator_active=160,200,240,255
+
+# Scrollbars (better visibility)
+scrollbar_bg=30,45,65,180
+scrollbar_grab=70,110,150,200
+scrollbar_grab_hovered=100,140,180,230
+scrollbar_grab_active=130,170,210,255
+
+[style]
+window_rounding=8.0
+frame_rounding=6.0
+scrollbar_rounding=8.0
+grab_rounding=4.0
+tab_rounding=6.0
+window_border_size=0.0
+frame_border_size=0.0
+enable_animations=true
+enable_glow_effects=true
+animation_speed=1.2

assets/themes/sunset.theme

@@ -0,0 +1,62 @@
+# Sunset Theme
+# Warm orange and purple sunset theme
+name=Sunset
+description=Warm orange and purple sunset theme
+author=YAZE Team
+version=1.0
+
+[colors]
+# Primary colors (sunset)
+primary=255,140,60,255
+secondary=200,100,150,255
+accent=255,180,100,255
+background=30,20,35,255
+surface=40,30,45,255
+
+# Status colors
+error=255,100,120,255
+warning=255,200,100,255
+success=150,255,150,255
+info=150,200,255,255
+
+# Text colors
+text_primary=255,245,235,255
+text_secondary=220,200,180,255
+text_disabled=150,130,120,255
+
+# Window colors
+window_bg=35,25,40,240
+child_bg=30,20,35,200
+popup_bg=40,30,45,250
+
+# Interactive elements
+button=60,40,70,255
+button_hovered=120,80,100,255
+button_active=150,100,120,255
+frame_bg=45,35,50,255
+frame_bg_hovered=55,45,60,255
+frame_bg_active=80,60,90,255
+
+# Navigation
+header=50,35,60,255
+header_hovered=100,70,90,255
+header_active=130,90,110,255
+tab=40,30,50,255
+tab_hovered=70,50,70,255
+tab_active=100,70,90,255
+menu_bar_bg=35,25,45,255
+title_bg=40,30,50,255
+title_bg_active=50,35,60,255
+title_bg_collapsed=40,30,50,255
+
+[style]
+window_rounding=12.0
+frame_rounding=8.0
+scrollbar_rounding=12.0
+grab_rounding=6.0
+tab_rounding=8.0
+window_border_size=0.0
+frame_border_size=0.0
+enable_animations=true
+enable_glow_effects=false
+animation_speed=1.0

assets/themes/yaze_tre.theme

@@ -0,0 +1,115 @@
+# 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
+author=YAZE Team
+version=2.0
+
+[colors]
+# Primary colors (enhanced ALTTP colors with better contrast)
+primary=105,135,105,255         # Brighter green for better visibility
+secondary=85,110,85,255         # Mid-tone green with more saturation
+accent=110,145,110,255          # Vibrant accent green for highlights
+background=12,12,15,255         # Slightly blue-tinted dark background
+surface=18,18,22,255            # Warmer surface color
+
+# Status colors (enhanced for better visibility)
+error=235,75,75,255             # Brighter red for better visibility
+warning=255,200,50,255          # Warmer yellow-orange
+success=105,135,105,255         # Match primary green
+info=70,170,255,255             # Brighter blue
+
+# Text colors (enhanced contrast)
+text_primary=245,245,245,255    # Brighter white for better readability
+text_secondary=200,200,200,255  # Higher contrast secondary text
+text_disabled=140,140,140,255   # Slightly brighter disabled text
+
+# Window colors (enhanced backgrounds)
+window_bg=12,12,15,230          # Slightly blue-tinted with transparency
+child_bg=0,0,0,0                # Transparent child backgrounds
+popup_bg=20,20,25,240           # Warmer popup background
+
+# Interactive elements (enhanced for better UX)
+button=85,110,85,255            # Enhanced mid-green for better visibility
+button_hovered=135,160,135,255  # Brighter hover state
+button_active=105,135,105,255   # Active state matches primary
+frame_bg=25,25,30,150           # Darker frames with transparency
+frame_bg_hovered=85,110,85,120  # Green tint on hover
+frame_bg_active=105,135,105,180 # Primary green when active
+
+# Navigation (enhanced contrast)
+header=55,75,55,255             # Slightly brighter header
+header_hovered=105,135,105,255  # Primary green on hover
+header_active=85,110,85,255     # Secondary green when active
+tab=45,60,45,255                # Darker tab background
+tab_hovered=85,110,85,255       # Secondary green on hover
+tab_active=110,145,110,255      # Accent green for active tab
+menu_bar_bg=55,75,55,255        # Match header background
+title_bg=85,110,85,255          # Secondary green
+title_bg_active=55,75,55,255    # Darker when active
+title_bg_collapsed=85,110,85,255 # Secondary green when collapsed
+
+# Borders and separators (exact from original)
+border=92,115,92,255            # allttpLightGreen
+border_shadow=0,0,0,0           # No shadow in original
+separator=127,127,127,153       # 0.50f, 0.50f, 0.50f, 0.60f
+separator_hovered=153,153,178,255 # 0.60f, 0.60f, 0.70f
+separator_active=178,178,230,255  # 0.70f, 0.70f, 0.90f
+
+# Scrollbars (exact from original)
+scrollbar_bg=92,115,92,153      # 0.36f, 0.45f, 0.36f, 0.60f
+scrollbar_grab=92,115,92,76     # 0.36f, 0.45f, 0.36f, 0.30f (exact)
+scrollbar_grab_hovered=92,115,92,102 # 0.36f, 0.45f, 0.36f, 0.40f
+scrollbar_grab_active=92,115,92,153  # 0.36f, 0.45f, 0.36f, 0.60f
+
+# Resize grips (exact from original - these are light blue, not white!)
+resize_grip=255,255,255,26      # 1.00f, 1.00f, 1.00f, 0.10f
+resize_grip_hovered=199,209,255,153 # 0.78f, 0.82f, 1.00f, 0.60f (light blue!)
+resize_grip_active=199,209,255,230  # 0.78f, 0.82f, 1.00f, 0.90f (light blue!)
+
+# Additional controls (enhanced)
+check_mark=245,245,245,200      # Brighter check marks for visibility
+slider_grab=180,180,180,120     # More visible slider grab
+slider_grab_active=110,145,110,200 # Accent color when active
+
+# Table colors (enhanced)
+table_header_bg=55,75,55,255    # Slightly brighter header
+table_border_strong=85,110,85,255 # Secondary green borders
+table_border_light=70,70,75,255 # Better contrast light borders
+table_row_bg=0,0,0,0            # Transparent
+table_row_bg_alt=255,255,255,25 # Slightly more visible alternating rows
+
+# Link colors (high contrast for better visibility)
+text_link=120,200,255,255       # Bright blue for links - high contrast against dark backgrounds
+
+# Navigation and special elements
+input_text_cursor=245,245,245,255
+nav_cursor=110,145,110,255
+nav_windowing_highlight=110,145,110,255
+nav_windowing_dim_bg=0,0,0,128
+modal_window_dim_bg=0,0,0,89
+text_selected_bg=89,119,89,89
+drag_drop_target=110,145,110,255
+docking_preview=92,115,92,180
+docking_empty_bg=46,66,46,255
+
+# Tree lines
+tree_lines=127,127,127,153
+
+# Tab variations for unfocused windows
+tab_dimmed=37,52,37,255
+tab_dimmed_selected=62,83,62,255
+tab_dimmed_selected_overline=110,145,110,255
+tab_selected_overline=110,145,110,255
+
+[style]
+window_rounding=0.0
+frame_rounding=5.0
+scrollbar_rounding=5.0
+grab_rounding=3.0
+tab_rounding=0.0
+window_border_size=0.0
+frame_border_size=0.0
+enable_animations=true
+enable_glow_effects=false
+animation_speed=1.0

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,19 +1,135 @@
-set(ABSL_PROPAGATE_CXX_STD ON)
-set(ABSL_CXX_STANDARD 17)
-set(ABSL_USE_GOOGLETEST_HEAD ON)
-set(ABSL_ENABLE_INSTALL ON)
+# 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()
+
+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()
+
+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::strings
-  absl::flags
-  absl::status
-  absl::statusor
-  absl::examine_stack
-  absl::stacktrace
+  ABSL_TARGETS
   absl::base
   absl::config
   absl::core_headers
-  absl::raw_logging_internal
+  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)
+  message(STATUS "Including absl::int128 target")
+else()
+  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

@@ -1,33 +1,99 @@
-get_target_property(ASAR_INCLUDE_DIR asar-static INCLUDE_DIRECTORIES)
-target_include_directories(asar-static PRIVATE ${ASAR_INCLUDE_DIR})
-set(ASAR_GEN_EXE OFF)
-set(ASAR_GEN_DLL ON)
-set(ASAR_GEN_LIB ON)
-set(ASAR_GEN_EXE_TEST OFF)
-set(ASAR_GEN_DLL_TEST OFF)
+# Modern Asar 65816 Assembler Integration
+# Improved cross-platform support for macOS, Linux, and Windows
 
-set(ASAR_STATIC_SRC
-  "../src/lib/asar/src/asar/interface-lib.cpp"
-  "../src/lib/asar/src/asar/addr2line.cpp"
-  "../src/lib/asar/src/asar/arch-65816.cpp"
-  "../src/lib/asar/src/asar/arch-spc700.cpp"
-  "../src/lib/asar/src/asar/arch-superfx.cpp"
-  "../src/lib/asar/src/asar/assembleblock.cpp"
-  "../src/lib/asar/src/asar/crc32.cpp"
-  "../src/lib/asar/src/asar/libcon.cpp"
-  "../src/lib/asar/src/asar/libsmw.cpp"
-  "../src/lib/asar/src/asar/libstr.cpp"
-  "../src/lib/asar/src/asar/macro.cpp"
-  "../src/lib/asar/src/asar/main.cpp"
-  "../src/lib/asar/src/asar/asar_math.cpp"
-  "../src/lib/asar/src/asar/virtualfile.cpp"
-  "../src/lib/asar/src/asar/warnings.cpp"
-  "../src/lib/asar/src/asar/errors.cpp"
-  "../src/lib/asar/src/asar/platform/file-helpers.cpp"
-)
+# Configure Asar build options
+set(ASAR_GEN_EXE OFF CACHE BOOL "Build Asar standalone executable")
+set(ASAR_GEN_DLL ON CACHE BOOL "Build Asar shared library")
+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")
 
-if(WIN32 OR MINGW)
-  list(APPEND ASAR_STATIC_SRC "../src/lib/asar/src/asar/platform/windows/file-helpers-win32.cpp")
+# 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}/ext/asar/src")
+
+# Add Asar as subdirectory
+add_subdirectory(${ASAR_SRC_DIR} EXCLUDE_FROM_ALL)
+
+# Create modern CMake target for Asar integration
+if(TARGET asar-static)
+    # Ensure asar-static is available and properly configured
+    set_target_properties(asar-static PROPERTIES
+        CXX_STANDARD 17
+        CXX_STANDARD_REQUIRED ON
+        POSITION_INDEPENDENT_CODE ON
+    )
+    
+    # Set platform-specific definitions for Asar
+    if(WIN32)
+        target_compile_definitions(asar-static PRIVATE
+            windows
+            strncasecmp=_strnicmp
+            strcasecmp=_stricmp
+            _CRT_SECURE_NO_WARNINGS
+            _CRT_NONSTDC_NO_WARNINGS
+        )
+    elseif(UNIX AND NOT APPLE)
+        target_compile_definitions(asar-static PRIVATE
+            linux
+            stricmp=strcasecmp
+        )
+    elseif(APPLE)
+        target_compile_definitions(asar-static PRIVATE
+            MACOS
+            stricmp=strcasecmp
+        )
+    endif()
+    
+    # Add include directories
+    target_include_directories(asar-static PUBLIC
+        $<BUILD_INTERFACE:${ASAR_SRC_DIR}>
+        $<BUILD_INTERFACE:${ASAR_SRC_DIR}/asar>
+        $<BUILD_INTERFACE:${ASAR_SRC_DIR}/asar-dll-bindings/c>
+    )
+    
+    # Create alias for easier linking
+    add_library(yaze::asar ALIAS asar-static)
+    
+    # Export Asar variables for use in other parts of the build
+    set(ASAR_FOUND TRUE CACHE BOOL "Asar library found")
+    set(ASAR_LIBRARIES asar-static CACHE STRING "Asar library target")
+    set(ASAR_INCLUDE_DIRS 
+        "${ASAR_SRC_DIR}"
+        "${ASAR_SRC_DIR}/asar"
+        "${ASAR_SRC_DIR}/asar-dll-bindings/c"
+        CACHE STRING "Asar include directories"
+    )
+    
+    message(STATUS "Asar 65816 assembler integration configured successfully")
 else()
-  list(APPEND ASAR_STATIC_SRC "../src/lib/asar/src/asar/platform/linux/file-helpers-linux.cpp")
-endif()
+    message(WARNING "Failed to configure Asar static library target")
+    set(ASAR_FOUND FALSE CACHE BOOL "Asar library found")
+endif()
+
+# Function to add Asar patching capabilities to a target
+function(yaze_add_asar_support target_name)
+    if(ASAR_FOUND)
+        target_link_libraries(${target_name} PRIVATE yaze::asar)
+        target_include_directories(${target_name} PRIVATE ${ASAR_INCLUDE_DIRS})
+        target_compile_definitions(${target_name} PRIVATE YAZE_ENABLE_ASAR=1)
+    else()
+        message(WARNING "Asar not available for target ${target_name}")
+    endif()
+endfunction()
+
+# Create function for ROM patching utilities
+function(yaze_create_asar_patch_tool tool_name patch_file rom_file)
+    if(ASAR_FOUND)
+        add_custom_target(${tool_name}
+            COMMAND ${CMAKE_COMMAND} -E echo "Patching ROM with Asar..."
+            COMMAND $<TARGET_FILE:asar-standalone> ${patch_file} ${rom_file}
+            DEPENDS asar-standalone
+            COMMENT "Applying Asar patch ${patch_file} to ${rom_file}"
+        )
+    endif()
+endfunction()

cmake/dependencies.cmake

@@ -0,0 +1,95 @@
+# 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)
+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})
+
+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,35 @@
+# 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)
+
+# Note: FTXUI targets will be available after the build phase
+# For now, we'll create a placeholder that can be linked later
+
+# 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,433 @@
+# gRPC and Protobuf dependency management
+# Uses CPM.cmake for consistent cross-platform builds
+
+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} with CPM.cmake")
+
+# Try to use system packages first if requested
+if(YAZE_USE_SYSTEM_DEPS)
+  find_package(PkgConfig QUIET)
+  if(PkgConfig_FOUND)
+    pkg_check_modules(GRPC_PC grpc++)
+    if(GRPC_PC_FOUND)
+      message(STATUS "Using system gRPC via pkg-config")
+      add_library(grpc::grpc++ INTERFACE IMPORTED)
+      target_include_directories(grpc::grpc++ INTERFACE ${GRPC_PC_INCLUDE_DIRS})
+      target_link_libraries(grpc::grpc++ INTERFACE ${GRPC_PC_LIBRARIES})
+      target_compile_options(grpc::grpc++ INTERFACE ${GRPC_PC_CFLAGS_OTHER})
+      return()
+    endif()
+  endif()
+endif()
+
+#-----------------------------------------------------------------------
+# 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
+)
+
+# Function to add protobuf/gRPC code generation to a target
+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 ${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 $<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}
+            ${ABS_FIL}
+        DEPENDS ${ABS_FIL} protoc grpc_cpp_plugin
+        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,72 @@
+# 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)
+
+# 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
+  # SDL2 backend
+  ${IMGUI_DIR}/backends/imgui_impl_sdl2.cpp
+  ${IMGUI_DIR}/backends/imgui_impl_sdlrenderer2.cpp
+  # 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 SDL2
+target_link_libraries(ImGui PUBLIC ${YAZE_SDL2_TARGETS})
+
+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)
+    target_link_libraries(ImGuiTestEngine PUBLIC ImGui ${YAZE_SDL2_TARGETS})
+    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/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,89 @@
+# 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 IMPORTED)
+    target_link_libraries(yaze_yaml INTERFACE yaml-cpp)
+    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/gtest.cmake

@@ -0,0 +1,11 @@
+# GoogleTest ------------------------------------------------------------------
+include(FetchContent)
+FetchContent_Declare(
+  googletest
+  URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
+)
+
+# For Windows: Prevent overriding the parent project's compiler/linker settings
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+enable_testing()

cmake/imgui.cmake

@@ -1,35 +0,0 @@
-# gui libraries ---------------------------------------------------------------
-set(IMGUI_PATH  ${CMAKE_SOURCE_DIR}/src/lib/imgui)
-file(GLOB IMGUI_SOURCES ${IMGUI_PATH}/*.cpp)
-add_library("ImGui" STATIC ${IMGUI_SOURCES})
-target_include_directories("ImGui" PUBLIC ${IMGUI_PATH})
-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(IMGUI_FILE_DLG_PATH ${CMAKE_SOURCE_DIR}/src/lib/ImGuiFileDialog)
-file(GLOB IMGUI_FILE_DLG_SOURCES ${IMGUI_FILE_DLG_PATH}/*.cpp)
-add_library("ImGuiFileDialog" STATIC ${IMGUI_FILE_DLG_SOURCES})
-target_include_directories(ImGuiFileDialog PUBLIC ${IMGUI_PATH})
-target_compile_definitions(ImGuiFileDialog PUBLIC 
-  IMGUI_IMPL_OPENGL_LOADER_CUSTOM=<SDL2/SDL_opengl.h>  GL_GLEXT_PROTOTYPES=1)
-
-set(IMGUI_COLOR_TEXT_EDIT_PATH ${CMAKE_SOURCE_DIR}/src/lib/ImGuiColorTextEdit)
-file(GLOB IMGUI_COLOR_TEXT_EDIT_SOURCES ${IMGUI_COLOR_TEXT_EDIT_PATH}/*.cpp)
-add_library("ImGuiColorTextEdit" STATIC ${IMGUI_COLOR_TEXT_EDIT_SOURCES})
-target_include_directories(ImGuiColorTextEdit PUBLIC ${IMGUI_PATH})
-target_compile_definitions(ImGuiColorTextEdit PUBLIC 
-  IMGUI_IMPL_OPENGL_LOADER_CUSTOM=<SDL2/SDL_opengl.h>  GL_GLEXT_PROTOTYPES=1)
-
-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
-  ${IMGUI_FILE_DLG_PATH}/ImGuiFileDialog.cpp
-  ${IMGUI_COLOR_TEXT_EDIT_PATH}/TextEditor.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/mingw64.cmake

@@ -0,0 +1,21 @@
+# cmake -DCMAKE_TOOLCHAIN_FILE=./cmake/mingw64.cmake -B build/build-windows && cmake --build ./build/build-windows
+
+set(CMAKE_SYSTEM_NAME Windows)
+set(CMAKE_SYSTEM_VERSION 1)
+set(CMAKE_SYSTEM_PROCESSOR x86_64)
+
+set(CMAKE_C_COMPILER x86_64-w64-mingw32-gcc)
+set(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
+set(CMAKE_RC_COMPILER x86_64-w64-mingw32-windres)
+
+set(CMAKE_FIND_ROOT_PATH /usr/local/opt/mingw-w64)
+
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
+
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O2 -pipe -g -feliminate-unused-debug-types")
+
+# Static link the C++ standard library
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -static -static-libgcc -static-libstdc++")

cmake/openssl.cmake

@@ -1,5 +0,0 @@
-if (UNIX)
-  set(OPENSSL_INCLUDE_DIR "/usr/local/Cellar/openssl@1.1/1.1.1q/include")
-  set(OPENSSL_CRYPTO_LIBRARY "/usr/local/Cellar/openssl@1.1/1.1.1q/lib/libcrypto.dylib")
-  set(OPENSSL_SSL_LIBRARY "/usr/local/Cellar/openssl@1.1/1.1.1q/lib/libssl.dylib")
-endif()

cmake/options.cmake

@@ -0,0 +1,118 @@
+# 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" ON)
+
+# 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)
+
+# Development options
+option(YAZE_ENABLE_ROM_TESTS "Enable tests that require ROM files" 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}")
+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

@@ -0,0 +1,240 @@
+# Modern packaging configuration for Yaze
+# Supports Windows (NSIS), macOS (DMG), and Linux (DEB/RPM)
+
+include(InstallRequiredSystemLibraries)
+
+# Basic package information
+set(CPACK_PACKAGE_NAME "yaze")
+set(CPACK_PACKAGE_VENDOR "scawful")
+set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "Yet Another Zelda3 Editor")
+set(CPACK_PACKAGE_DESCRIPTION "A comprehensive editor for The Legend of Zelda: A Link to the Past ROM hacking")
+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_INSTALL_DIRECTORY "Yaze")
+set(CPACK_PACKAGE_CONTACT "scawful@github.com")
+set(CPACK_PACKAGE_HOMEPAGE_URL "https://github.com/scawful/yaze")
+
+# Resource files
+set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_SOURCE_DIR}/LICENSE")
+set(CPACK_RESOURCE_FILE_README "${CMAKE_SOURCE_DIR}/README.md")
+
+# Package icon
+if(EXISTS "${CMAKE_SOURCE_DIR}/assets/yaze.png")
+    set(CPACK_PACKAGE_ICON "${CMAKE_SOURCE_DIR}/assets/yaze.png")
+endif()
+
+# Platform-specific configuration
+if(WIN32)
+    # Windows packaging configuration (conditional based on environment)
+    if(DEFINED ENV{GITHUB_ACTIONS})
+        # CI/CD build - use only ZIP (NSIS not available)
+        set(CPACK_GENERATOR "ZIP")
+    else()
+        # Local build - use both NSIS installer and ZIP
+        set(CPACK_GENERATOR "NSIS;ZIP")
+    endif()
+    
+    # NSIS-specific configuration (only for local builds with NSIS available)
+    if(NOT DEFINED ENV{GITHUB_ACTIONS})
+        set(CPACK_NSIS_DISPLAY_NAME "Yaze - Zelda3 Editor")
+        set(CPACK_NSIS_PACKAGE_NAME "Yaze")
+        set(CPACK_NSIS_CONTACT "scawful@github.com")
+        set(CPACK_NSIS_URL_INFO_ABOUT "https://github.com/scawful/yaze")
+        set(CPACK_NSIS_HELP_LINK "https://github.com/scawful/yaze/issues")
+        set(CPACK_NSIS_MENU_LINKS
+            "bin/yaze.exe" "Yaze Editor"
+            "https://github.com/scawful/yaze" "Yaze Homepage"
+        )
+        set(CPACK_NSIS_CREATE_ICONS_EXTRA
+            "CreateShortCut '$SMPROGRAMS\\\\$STARTMENU_FOLDER\\\\Yaze.lnk' '$INSTDIR\\\\bin\\\\yaze.exe'"
+            "CreateShortCut '$DESKTOP\\\\Yaze.lnk' '$INSTDIR\\\\bin\\\\yaze.exe'"
+        )
+        set(CPACK_NSIS_DELETE_ICONS_EXTRA
+            "Delete '$SMPROGRAMS\\\\$START_MENU\\\\Yaze.lnk'"
+            "Delete '$DESKTOP\\\\Yaze.lnk'"
+        )
+    endif()
+    
+    # Windows architecture detection
+    if(CMAKE_SIZEOF_VOID_P EQUAL 8)
+        if(DEFINED ENV{GITHUB_ACTIONS})
+            set(CPACK_PACKAGE_FILE_NAME "yaze-${CPACK_PACKAGE_VERSION}-windows-x64")
+        else()
+            set(CPACK_PACKAGE_FILE_NAME "yaze-${CPACK_PACKAGE_VERSION}-win64")
+        endif()
+        set(CPACK_NSIS_INSTALL_ROOT "$PROGRAMFILES64")
+    else()
+        if(DEFINED ENV{GITHUB_ACTIONS})
+            set(CPACK_PACKAGE_FILE_NAME "yaze-${CPACK_PACKAGE_VERSION}-windows-x86")
+        else()
+            set(CPACK_PACKAGE_FILE_NAME "yaze-${CPACK_PACKAGE_VERSION}-win32")
+        endif()
+        set(CPACK_NSIS_INSTALL_ROOT "$PROGRAMFILES")
+    endif()
+    
+elseif(APPLE)
+    # macOS DMG configuration
+    set(CPACK_GENERATOR "DragNDrop")
+    set(CPACK_DMG_VOLUME_NAME "Yaze ${CPACK_PACKAGE_VERSION}")
+    set(CPACK_DMG_FORMAT "UDZO")
+    set(CPACK_PACKAGE_FILE_NAME "yaze-${CPACK_PACKAGE_VERSION}-macos")
+    
+    # macOS app bundle configuration
+    if(EXISTS "${CMAKE_SOURCE_DIR}/assets/dmg_background.png")
+        set(CPACK_DMG_BACKGROUND_IMAGE "${CMAKE_SOURCE_DIR}/assets/dmg_background.png")
+    endif()
+    if(EXISTS "${CMAKE_SOURCE_DIR}/cmake/dmg_setup.scpt")
+        set(CPACK_DMG_DS_STORE_SETUP_SCRIPT "${CMAKE_SOURCE_DIR}/cmake/dmg_setup.scpt")
+    endif()
+    
+elseif(UNIX)
+    # Linux DEB/RPM configuration
+    set(CPACK_GENERATOR "DEB;RPM;TGZ")
+    
+    # DEB package configuration
+    set(CPACK_DEBIAN_PACKAGE_MAINTAINER "scawful <scawful@github.com>")
+    set(CPACK_DEBIAN_PACKAGE_SECTION "games")
+    set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional")
+    set(CPACK_DEBIAN_PACKAGE_DEPENDS 
+        "libsdl2-2.0-0, libpng16-16, libgl1-mesa-glx, libabsl20210324")
+    set(CPACK_DEBIAN_PACKAGE_RECOMMENDS "git")
+    set(CPACK_DEBIAN_PACKAGE_SUGGESTS "asar")
+    set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)
+    
+    # RPM package configuration
+    set(CPACK_RPM_PACKAGE_SUMMARY "Zelda3 ROM Editor")
+    set(CPACK_RPM_PACKAGE_LICENSE "MIT")
+    set(CPACK_RPM_PACKAGE_GROUP "Amusements/Games")
+    set(CPACK_RPM_PACKAGE_REQUIRES 
+        "SDL2 >= 2.0.0, libpng >= 1.6.0, mesa-libGL, abseil-cpp")
+    set(CPACK_RPM_PACKAGE_SUGGESTS "asar")
+    set(CPACK_RPM_FILE_NAME RPM-DEFAULT)
+    
+    # Architecture detection
+    execute_process(
+        COMMAND uname -m
+        OUTPUT_VARIABLE CPACK_SYSTEM_ARCH
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+    set(CPACK_PACKAGE_FILE_NAME "yaze-${CPACK_PACKAGE_VERSION}-linux-${CPACK_SYSTEM_ARCH}")
+endif()
+
+# Component configuration for advanced packaging
+set(CPACK_COMPONENTS_ALL applications libraries headers documentation)
+
+set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "Yaze Application")
+set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION "Main Yaze editor application")
+set(CPACK_COMPONENT_APPLICATIONS_REQUIRED TRUE)
+
+set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Development Libraries")
+set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION "Yaze development libraries")
+set(CPACK_COMPONENT_LIBRARIES_REQUIRED FALSE)
+
+set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "Development Headers")
+set(CPACK_COMPONENT_HEADERS_DESCRIPTION "Header files for Yaze development")
+set(CPACK_COMPONENT_HEADERS_REQUIRED FALSE)
+set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)
+
+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 ${YAZE_INSTALL_BINDIR}
+        BUNDLE DESTINATION ${YAZE_INSTALL_BINDIR}
+        COMPONENT applications
+    )
+else()
+    install(TARGETS yaze
+        RUNTIME DESTINATION ${YAZE_INSTALL_BINDIR}
+        COMPONENT applications
+    )
+endif()
+
+# Install assets
+install(DIRECTORY ${CMAKE_SOURCE_DIR}/assets/
+    DESTINATION ${YAZE_INSTALL_DATADIR}/assets
+    COMPONENT applications
+    PATTERN "*.png"
+    PATTERN "*.ttf"
+    PATTERN "*.asm"
+)
+
+# Install documentation
+install(FILES
+    ${CMAKE_SOURCE_DIR}/README.md
+    ${CMAKE_SOURCE_DIR}/LICENSE
+    DESTINATION ${YAZE_INSTALL_DOCDIR}
+    COMPONENT documentation
+)
+
+install(DIRECTORY ${CMAKE_SOURCE_DIR}/docs/
+    DESTINATION ${YAZE_INSTALL_DOCDIR}
+    COMPONENT documentation
+    PATTERN "*.md"
+    PATTERN "*.html"
+)
+
+# Install headers and libraries if building library components
+if(YAZE_INSTALL_LIB)
+    install(TARGETS yaze_c
+        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        COMPONENT libraries
+    )
+    
+    install(FILES ${CMAKE_SOURCE_DIR}/incl/yaze.h ${CMAKE_SOURCE_DIR}/incl/zelda.h
+        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/yaze
+        COMPONENT headers
+    )
+endif()
+
+# Desktop integration for Linux
+if(UNIX AND NOT APPLE)
+    # Desktop file
+    configure_file(
+        ${CMAKE_SOURCE_DIR}/cmake/yaze.desktop.in
+        ${CMAKE_BINARY_DIR}/yaze.desktop
+        @ONLY
+    )
+    
+    install(FILES ${CMAKE_BINARY_DIR}/yaze.desktop
+        DESTINATION ${CMAKE_INSTALL_DATADIR}/applications
+        COMPONENT applications
+    )
+    
+    # Icon
+    if(EXISTS "${CMAKE_SOURCE_DIR}/assets/yaze.png")
+        install(FILES ${CMAKE_SOURCE_DIR}/assets/yaze.png
+            DESTINATION ${CMAKE_INSTALL_DATADIR}/pixmaps
+            RENAME yaze.png
+            COMPONENT applications
+        )
+    endif()
+endif()
+
+# Include CPack
+include(CPack)

cmake/packaging/cpack.cmake

@@ -0,0 +1,92 @@
+# CPack Configuration
+# Cross-platform packaging using CPack
+# NOTE: include(CPack) MUST be called at the END of this file,
+# after all CPACK_ variables and install() rules are defined.
+
+# Set package information
+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 package directory
+set(CPACK_PACKAGE_DIRECTORY "${CMAKE_BINARY_DIR}/packages")
+
+# Platform-specific packaging
+if(APPLE)
+  include(cmake/packaging/macos.cmake)
+elseif(WIN32)
+  include(cmake/packaging/windows.cmake)
+elseif(UNIX)
+  include(cmake/packaging/linux.cmake)
+endif()
+
+# Common files to include
+set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_SOURCE_DIR}/LICENSE")
+set(CPACK_RESOURCE_FILE_README "${CMAKE_SOURCE_DIR}/README.md")
+
+# Set default component
+set(CPACK_COMPONENTS_ALL yaze)
+set(CPACK_COMPONENT_YAZE_DISPLAY_NAME "YAZE Editor")
+set(CPACK_COMPONENT_YAZE_DESCRIPTION "Main YAZE application and libraries")
+
+# Install rules - these define what CPack packages
+include(GNUInstallDirs)
+
+# 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()
+
+# Install main executable
+if(APPLE)
+    install(TARGETS yaze
+        RUNTIME DESTINATION ${YAZE_INSTALL_BINDIR}
+        BUNDLE DESTINATION .
+        COMPONENT yaze
+    )
+else()
+    install(TARGETS yaze
+        RUNTIME DESTINATION ${YAZE_INSTALL_BINDIR}
+        COMPONENT yaze
+    )
+endif()
+
+# Install assets
+install(DIRECTORY ${CMAKE_SOURCE_DIR}/assets/
+    DESTINATION ${YAZE_INSTALL_DATADIR}/assets
+    COMPONENT yaze
+    PATTERN "*.png"
+    PATTERN "*.ttf"
+    PATTERN "*.asm"
+)
+
+# Install documentation
+install(FILES
+    ${CMAKE_SOURCE_DIR}/README.md
+    ${CMAKE_SOURCE_DIR}/LICENSE
+    DESTINATION ${YAZE_INSTALL_DOCDIR}
+    COMPONENT yaze
+)
+
+# IMPORTANT: include(CPack) must be called LAST, after all CPACK_ variables
+# and install() rules are defined. This is a CPack requirement.
+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,19 +1,66 @@
-# SDL2, SDL2_image and SDL2_mixer
-if (UNIX)
-  add_subdirectory(src/lib/SDL)
-else()
-  find_package(SDL2)
-endif()
-set(SDL2MIXER_OPUS OFF)
-set(SDL2MIXER_FLAC OFF)
-set(SDL2MIXER_MOD OFF)
-set(SDL2MIXER_MIDI_FLUIDSYNTH OFF)
-find_library(SDL_MIXER_LIBRARY
-  NAMES SDL_mixer
-  HINTS
-    ENV SDLMIXERDIR
-    ENV SDLDIR
-  PATH_SUFFIXES lib ${VC_LIB_PATH_SUFFIX}
+# SDL2
+# 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}/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})
+    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}
   )
-add_subdirectory(src/lib/SDL_mixer)
-find_package(SDL2_image)
+  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()
+
+# 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

@@ -0,0 +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
+
+# Windows-specific macro definitions to avoid conflicts
+add_definitions("-DMICROSOFT_WINDOWS_WINBASE_H_DEFINE_INTERLOCKED_CPLUSPLUS_OVERLOADS=0")
+
+# 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()
+
+# Detect installed directory
+set(_vcpkg_installed "${CMAKE_BINARY_DIR}/vcpkg_installed")
+if(DEFINED VCPKG_INSTALLED_DIR)
+    set(_vcpkg_installed "${VCPKG_INSTALLED_DIR}")
+endif()
+
+# Detect manifest mode
+set(_vcpkg_manifest "ON (auto)")
+if(DEFINED VCPKG_MANIFEST_MODE)
+    if(VCPKG_MANIFEST_MODE)
+        set(_vcpkg_manifest "ON")
+    else()
+        set(_vcpkg_manifest "OFF")
+    endif()
+endif()
+
+# 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()
+
+# 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.desktop.in

@@ -0,0 +1,13 @@
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=Yaze
+Comment=Yet Another Zelda3 Editor
+Comment[en]=ROM editor for The Legend of Zelda: A Link to the Past
+Exec=@CMAKE_INSTALL_PREFIX@/@CMAKE_INSTALL_BINDIR@/yaze
+Icon=yaze
+Terminal=false
+Categories=Game;Development;
+Keywords=zelda;snes;rom;editor;hacking;
+StartupNotify=true
+MimeType=application/x-snes-rom;application/x-sfc;application/x-smc;