backend-infra-engineer: fix release build failures

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

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

@@ -0,0 +1,83 @@
+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: Setup MSVC Dev Cmd (Windows)
+      if: inputs.platform == 'windows'
+      uses: ilammy/msvc-dev-cmd@v1
+      with:
+        arch: x64
+
+    - 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,337 @@
+name: CI/CD Pipeline
+
+# Test Strategy:
+# - PR/Push: Run lean test set (stable tests + smoke tests) for fast feedback
+# - Nightly: Run comprehensive suite including ROM-dependent, experimental, benchmarks
+# - See .github/workflows/nightly.yml for extended test coverage
+#
+# Test Labels:
+# - stable: Core functionality tests that should always pass
+# - unit: Fast isolated component tests (subset of stable)
+# - integration: Multi-component tests (subset of stable)
+# - rom_dependent: Tests requiring Zelda3 ROM file (nightly only)
+# - experimental: AI and experimental feature tests (nightly only)
+# - gui: GUI/E2E tests with ImGuiTestEngine (nightly only)
+# - benchmark: Performance benchmarks (nightly only)
+
+on:
+  push:
+    branches: [ "master", "develop" ]
+    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: ${{ github.sha }}
+
+      - 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: ${{ github.sha }}
+
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: ${{ env.BUILD_TYPE }}
+
+      - name: Run stable tests only
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: stable
+          preset: ${{ matrix.preset }}
+
+      - name: Run smoke tests (GUI framework validation)
+        if: matrix.platform == 'linux'
+        run: |
+          cd build
+          # Run just the smoke tests to validate GUI framework is working
+          ./bin/yaze_test_gui -nogui --gtest_filter="*Smoke*" || true
+        continue-on-error: true
+
+      - 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: ${{ github.sha }}
+
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: windows
+          preset: ci-windows-ai
+          build-type: ${{ env.BUILD_TYPE }}
+
+      - name: Run stable tests only (agent stack)
+        uses: ./.github/actions/run-tests
+        with:
+          test-type: stable
+          preset: ci-windows-ai
+
+  wasm-smoke-test:
+    name: "WASM Build Smoke Test"
+    runs-on: ubuntu-22.04
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Emscripten
+        uses: mymindstorm/setup-emsdk@v14
+        with:
+          version: 3.1.51
+          actions-cache-folder: 'emsdk-cache'
+
+      - name: Setup Ninja
+        uses: seanmiddleditch/gha-setup-ninja@v4
+
+      - name: Quick WASM build test
+        run: |
+          emcmake cmake --preset wasm-debug
+          cmake --build build-wasm-debug --target yaze --parallel
+          # Verify output exists
+          test -f build-wasm-debug/bin/yaze.wasm
+          echo "WASM build successful!"
+
+  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
+    # Only run on master/develop push, not on PRs (moved to nightly for PRs)
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/develop')
+
+    steps:
+    - 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,59 +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: Install Abseil-cpp
-      run: sudo apt install libabsl-dev
-
-    - name: Install Boost and Boost Python
-      run: sudo apt install libboost-all-dev libboost-python-dev
-
-    - name: Install CPython headers
-      run: sudo apt install python3-dev libpython3-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/doxy.yml

@@ -1,45 +1,49 @@
-name: Doxygen Action
+name: Doxygen Documentation Check
 
-# Controls when the action will run. Triggers the workflow on push or pull request
+# Only run when documentation-related files are modified
-# events but only for the master branch
 on:
-  push:
+  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:
-  # This workflow contains a single job called "build"
+  check-docs:
-  build:
+    name: Check Documentation Build
-    # The type of runner that the job will run on
     runs-on: ubuntu-latest
-
-    # Steps represent a sequence of tasks that will be executed as part of the job
-    steps:
-    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-    - uses: actions/checkout@v2
-
-    # Delete the html directory if it exists
-    - name: Delete html directory
-      run: rm -rf html
-
-    # Installs graphviz for DOT graphs
-    - name: Install graphviz
-      run: sudo apt-get install graphviz
-        
-    - name: Doxygen Action
-      uses: mattnotmitt/doxygen-action@v1.1.0
-      with:
-        # Path to Doxyfile
-        doxyfile-path: "./Doxyfile" # default is ./Doxyfile
-        # Working directory
-        working-directory: "." # default is .
     
-    - name: Deploy
+    steps:
-      uses: peaceiris/actions-gh-pages@v3
+    - name: Checkout repository
+      uses: actions/checkout@v4
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
+        fetch-depth: 0
-        # Default Doxyfile build documentation to html directory. 
+
-        # Change the directory if changes in Doxyfile
+    - name: Install Graphviz
-        publish_dir: ./html
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y graphviz
+
+    - name: Install Doxygen 1.10.0
+      uses: ssciwr/doxygen-install@v1
+      with:
+        version: "1.10.0"
+
+    - name: Generate Doxygen documentation
+      run: |
+        mkdir -p build/docs
+        doxygen Doxyfile
+    
+    - name: Verify Generation
+      run: |
+        if [ -d "build/docs/html" ]; then
+          echo "✅ Documentation generated successfully"
+        else
+          echo "❌ Documentation generation failed"
+          exit 1
+        fi

.github/workflows/nightly.yml

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

.github/workflows/release.yml

@@ -0,0 +1,340 @@
+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: Compute dependency lock hash
+        id: deps-hash
+        shell: bash
+        run: |
+          python_cmd="$(command -v python3 || command -v python || true)"
+          if [ -z "$python_cmd" ]; then
+            echo "hash=none" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          hash=$("$python_cmd" - <<'PY'
+          import hashlib
+          import pathlib
+          path = pathlib.Path("cmake/dependencies.lock")
+          if path.is_file():
+              print(hashlib.sha256(path.read_bytes()).hexdigest())
+          else:
+              print("none")
+          PY
+          )
+          echo "hash=$hash" >> "$GITHUB_OUTPUT"
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
+
+      - name: Build project
+        uses: ./.github/actions/build-project
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          build-type: Release
+
+      - name: Patch cmake_install.cmake (Unix)
+        if: matrix.platform == 'linux' || matrix.platform == 'macos'
+        shell: bash
+        run: |
+          cd build
+          # Create a Python script to patch cmake_install.cmake
+          python3 << 'EOF'
+          import re
+          with open('cmake_install.cmake', 'r') as f:
+              content = f.read()
+          # Wrap include() statements with if(EXISTS)
+          pattern = r'(\s*)include\("(.*)/_deps/([^"]+)/cmake_install\.cmake"\)'
+          replacement = r'\1if(EXISTS "\2/_deps/\3/cmake_install.cmake")\n\1  include("\2/_deps/\3/cmake_install.cmake")\n\1endif()'
+          content = re.sub(pattern, replacement, content)
+          with open('cmake_install.cmake', 'w') as f:
+              f.write(content)
+          print("Patched cmake_install.cmake to handle missing dependency install scripts")
+          EOF
+
+      - name: Clean old packages before CPack
+        shell: bash
+        run: |
+          echo "Cleaning old package files to ensure fresh generation"
+          rm -rf build/packages build/_CPack_Packages
+          rm -f build/*.deb build/*.tar.gz build/*.dmg build/*.zip build/*.exe
+          mkdir -p build/packages
+
+      - name: Package artifacts (Linux)
+        if: matrix.platform == 'linux'
+        run: |
+          cd build
+          cpack -G DEB -G TGZ
+          echo "=== Contents of packages directory ==="
+          ls -la packages/ 2>/dev/null || echo "No packages directory"
+          echo "=== Package files created ==="
+          ls -la packages/*.deb packages/*.tar.gz 2>/dev/null || echo "No packages found"
+
+      - name: Package artifacts (macOS)
+        if: matrix.platform == 'macos'
+        run: |
+          cd build
+          cpack -G DragNDrop
+          echo "=== Contents of packages directory ==="
+          ls -la packages/ 2>/dev/null || echo "No packages directory"
+          echo "=== Package files created ==="
+          ls -la packages/*.dmg 2>/dev/null || echo "No packages found"
+
+      - name: Create notarized bundle (macOS)
+        if: matrix.platform == 'macos'
+        shell: bash
+        run: |
+          chmod +x ./scripts/create-macos-bundle.sh
+          ./scripts/create-macos-bundle.sh ${{ env.VERSION }} yaze-${{ env.VERSION }}-bundle || true
+          if [ -f "yaze-${{ env.VERSION }}-bundle.dmg" ]; then
+            mkdir -p build/packages
+            mv yaze-${{ env.VERSION }}-bundle.dmg build/packages/
+          fi
+
+      - name: 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: Compute dependency lock hash
+        id: deps-hash
+        shell: bash
+        run: |
+          python_cmd="$(command -v python3 || command -v python || true)"
+          if [ -z "$python_cmd" ]; then
+            echo "hash=none" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          hash=$("$python_cmd" - <<'PY'
+          import hashlib
+          import pathlib
+          path = pathlib.Path("cmake/dependencies.lock")
+          if path.is_file():
+              print(hashlib.sha256(path.read_bytes()).hexdigest())
+          else:
+              print("none")
+          PY
+          )
+          echo "hash=$hash" >> "$GITHUB_OUTPUT"
+
+      - name: Setup build environment
+        uses: ./.github/actions/setup-build
+        with:
+          platform: ${{ matrix.platform }}
+          preset: ${{ matrix.preset }}
+          cache-key: ${{ steps.deps-hash.outputs.hash }}
+
+      - name: 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/wasm-dev.yml

@@ -0,0 +1,175 @@
+name: WASM Development Build
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'CMakeLists.txt'
+      - 'CMakePresets.json'
+      - 'scripts/build-wasm.sh'
+      - '.github/workflows/wasm-dev.yml'
+  workflow_dispatch:
+    inputs:
+      debug_build:
+        description: 'Build debug version'
+        required: false
+        default: true
+        type: boolean
+      run_tests:
+        description: 'Run WASM tests (experimental)'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  wasm-build:
+    name: "WASM Build (Debug)"
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Emscripten
+        uses: mymindstorm/setup-emsdk@v14
+        with:
+          version: 3.1.51
+          actions-cache-folder: 'emsdk-cache'
+
+      - name: Setup Ninja
+        uses: seanmiddleditch/gha-setup-ninja@v4
+
+      - name: Setup CMake
+        uses: jwlawson/actions-setup-cmake@v1.14
+        with:
+          cmake-version: '3.27.x'
+
+      - name: Setup ccache
+        uses: hendrikmuhs/ccache-action@v1.2
+        with:
+          key: wasm-dev-ccache
+          max-size: 1G
+
+      - name: Cache CPM packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/CPM
+          key: cpm-wasm-debug-${{ hashFiles('**/CMakeLists.txt') }}
+          restore-keys: |
+            cpm-wasm-debug-
+            cpm-wasm-
+
+      - name: Verify Emscripten setup
+        run: |
+          echo "=== Emscripten Configuration ==="
+          emcc --version
+          emcmake --version
+          echo "=== Node.js Version ==="
+          node --version
+          echo "=== Environment ==="
+          env | grep -i em || true
+
+      - name: Build WASM (Debug)
+        if: github.event.inputs.debug_build != 'false'
+        run: |
+          export PATH="/usr/lib/ccache:$PATH"
+          echo "Building WASM debug version..."
+          chmod +x scripts/build-wasm.sh
+          ./scripts/build-wasm.sh debug
+
+      - name: Build WASM (Release)
+        if: github.event.inputs.debug_build == 'false'
+        run: |
+          export PATH="/usr/lib/ccache:$PATH"
+          echo "Building WASM release version..."
+          chmod +x scripts/build-wasm.sh
+          ./scripts/build-wasm.sh release
+
+      - name: Verify build output
+        run: |
+          BUILD_DIR="build-wasm-debug"
+          if [ "${{ github.event.inputs.debug_build }}" == "false" ]; then
+            BUILD_DIR="build-wasm"
+          fi
+
+          echo "=== Build Output Verification ==="
+          ls -lh "$BUILD_DIR/bin/" || true
+
+          # Check for critical files
+          if [ ! -f "$BUILD_DIR/bin/yaze.wasm" ]; then
+            echo "ERROR: yaze.wasm not found!"
+            exit 1
+          fi
+
+          if [ ! -f "$BUILD_DIR/bin/yaze.js" ]; then
+            echo "ERROR: yaze.js not found!"
+            exit 1
+          fi
+
+          if [ ! -f "$BUILD_DIR/bin/yaze.html" ]; then
+            echo "ERROR: yaze.html not found!"
+            exit 1
+          fi
+
+          # Report file sizes
+          echo ""
+          echo "=== File Sizes ==="
+          du -h "$BUILD_DIR/bin/yaze.wasm"
+          du -h "$BUILD_DIR/bin/yaze.js"
+          du -h "$BUILD_DIR/bin/yaze.data" 2>/dev/null || echo "No .data file (lazy loading enabled?)"
+
+          # Check for SharedArrayBuffer support
+          if grep -q "SharedArrayBuffer" "$BUILD_DIR/bin/yaze.js"; then
+            echo "✓ SharedArrayBuffer support detected"
+          else
+            echo "⚠ SharedArrayBuffer not detected - threading may not work"
+          fi
+
+      - name: Run WASM tests (experimental)
+        if: github.event.inputs.run_tests == 'true'
+        run: |
+          echo "WASM tests are experimental and not yet implemented"
+          # TODO: Add Node.js-based WASM tests here
+
+      - name: Upload WASM artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wasm-debug-${{ github.sha }}
+          path: |
+            build-wasm-debug/bin/*.wasm
+            build-wasm-debug/bin/*.js
+            build-wasm-debug/bin/*.html
+            build-wasm-debug/bin/*.data
+            build-wasm/bin/*.wasm
+            build-wasm/bin/*.js
+            build-wasm/bin/*.html
+            build-wasm/bin/*.data
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Build summary
+        if: always()
+        run: |
+          echo "## WASM Build Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          BUILD_DIR="build-wasm-debug"
+          BUILD_TYPE="Debug"
+          if [ "${{ github.event.inputs.debug_build }}" == "false" ]; then
+            BUILD_DIR="build-wasm"
+            BUILD_TYPE="Release"
+          fi
+
+          echo "**Build Type:** $BUILD_TYPE" >> $GITHUB_STEP_SUMMARY
+          echo "**Emscripten Version:** 3.1.51" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          if [ -f "$BUILD_DIR/bin/yaze.wasm" ]; then
+            WASM_SIZE=$(du -h "$BUILD_DIR/bin/yaze.wasm" | cut -f1)
+            echo "**WASM Size:** $WASM_SIZE" >> $GITHUB_STEP_SUMMARY
+            echo "✓ Build successful" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ Build failed - WASM file not generated" >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/web-build.yml

@@ -0,0 +1,209 @@
+name: Web Build & Deploy
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ master, main ]
+    paths:
+      - 'src/**'
+      - 'docs/**'
+      - 'CMakeLists.txt'
+      - 'CMakePresets.json'
+      - 'Doxyfile'
+      - 'scripts/build-wasm.sh'
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 2
+
+      # --- Detect what changed ---
+      - name: Check for web-only changes
+        id: changes
+        run: |
+          set -e
+          echo "Event: ${GITHUB_EVENT_NAME}"
+
+          NEEDS_BUILD=false
+          CHANGED=""
+
+          if git rev-parse HEAD~1 >/dev/null 2>&1; then
+            CHANGED=$(git diff --name-only HEAD~1 HEAD || echo "")
+          else
+            echo "No previous commit to diff against; forcing WASM build."
+            NEEDS_BUILD=true
+          fi
+
+          echo "Changed files:"
+          echo "${CHANGED}"
+
+          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+            echo "Manual dispatch - force WASM build."
+            NEEDS_BUILD=true
+          fi
+
+          if echo "${CHANGED}" | grep -qE '\.(cc|cpp|h|hpp|c)$|CMakeLists\.txt|CMakePresets\.json|build-wasm\.sh'; then
+            echo "C++ or build files changed - full WASM build required"
+            NEEDS_BUILD=true
+          fi
+
+          echo "needs_wasm_build=${NEEDS_BUILD}" >> "${GITHUB_OUTPUT}"
+
+      # --- Cache CPM dependencies ---
+      - name: Cache CPM packages
+        if: steps.changes.outputs.needs_wasm_build == 'true' || steps.wasm_cache.outputs.has_cached_wasm == 'false'
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/CPM
+          key: cpm-wasm-${{ hashFiles('**/CMakeLists.txt') }}
+          restore-keys: |
+            cpm-wasm-
+
+      # --- Cache WASM build artifacts ---
+      - name: Cache WASM build
+        uses: actions/cache@v4
+        with:
+          path: |
+            build_wasm_ai/bin
+            build_wasm_ai/CMakeCache.txt
+            build_wasm_ai/CMakeFiles
+          key: wasm-build-${{ hashFiles('src/**/*.cc', 'src/**/*.h', 'CMakeLists.txt', 'CMakePresets.json') }}
+          restore-keys: |
+            wasm-build-
+
+      - name: Check cached WASM artifacts
+        if: steps.changes.outputs.needs_wasm_build == 'false'
+        id: wasm_cache
+        run: |
+          if [ -f build_wasm_ai/bin/yaze.js ] && [ -f build_wasm_ai/bin/yaze.wasm ]; then
+            echo "Cached WASM found."
+            echo "has_cached_wasm=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "No cached WASM artifacts; will trigger a build."
+            echo "has_cached_wasm=false" >> "${GITHUB_OUTPUT}"
+          fi
+
+      # --- Setup Tools (only if WASM build needed or cache missing) ---
+      - name: Setup Emscripten
+        if: steps.changes.outputs.needs_wasm_build == 'true' || steps.wasm_cache.outputs.has_cached_wasm == 'false'
+        uses: mymindstorm/setup-emsdk@v14
+        with:
+          version: 3.1.51
+          actions-cache-folder: 'emsdk-cache'
+
+      - name: Setup Ninja
+        if: steps.changes.outputs.needs_wasm_build == 'true' || steps.wasm_cache.outputs.has_cached_wasm == 'false'
+        uses: seanmiddleditch/gha-setup-ninja@v4
+
+      - name: Setup CMake
+        if: steps.changes.outputs.needs_wasm_build == 'true' || steps.wasm_cache.outputs.has_cached_wasm == 'false'
+        uses: jwlawson/actions-setup-cmake@v1.14
+        with:
+          cmake-version: '3.27.x'
+
+      - name: Setup ccache
+        if: steps.changes.outputs.needs_wasm_build == 'true' || steps.wasm_cache.outputs.has_cached_wasm == 'false'
+        uses: hendrikmuhs/ccache-action@v1.2
+        with:
+          key: wasm-ccache
+          max-size: 1G
+
+      - name: Install Graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y graphviz
+
+      - name: Install Doxygen 1.10.0
+        uses: ssciwr/doxygen-install@v1
+        with:
+          version: "1.10.0"
+
+      # --- Build Web App (full build or use cache) ---
+      - name: Build WASM App
+        if: steps.changes.outputs.needs_wasm_build == 'true' || steps.wasm_cache.outputs.has_cached_wasm == 'false'
+        run: |
+          export PATH="/usr/lib/ccache:$PATH"
+          chmod +x scripts/build-wasm.sh
+          ./scripts/build-wasm.sh ai
+
+      - name: Use cached WASM + update web assets
+        if: steps.changes.outputs.needs_wasm_build == 'false' && steps.wasm_cache.outputs.has_cached_wasm == 'true'
+        run: |
+          echo "Using cached WASM build, updating web assets only..."
+          mkdir -p build_wasm_ai/dist
+
+          # Check if we have cached WASM files
+          if [ -f build_wasm_ai/bin/yaze.wasm ]; then
+            cp build_wasm_ai/bin/yaze.html build_wasm_ai/dist/index.html
+            cp build_wasm_ai/bin/yaze.js build_wasm_ai/dist/
+            cp build_wasm_ai/bin/yaze.wasm build_wasm_ai/dist/
+            cp build_wasm_ai/bin/yaze.data build_wasm_ai/dist/ 2>/dev/null || true
+            # CRITICAL: Copy pthread worker script for multi-threading
+            cp build_wasm_ai/bin/yaze.worker.js build_wasm_ai/dist/ 2>/dev/null || true
+          else
+            echo "ERROR: No cached WASM build found. Triggering full build..."
+            exit 1
+          fi
+
+          # Copy updated web assets (new directory structure)
+          # Root level files
+          cp src/web/app.js build_wasm_ai/dist/
+
+          # Copy subdirectories
+          cp -r src/web/styles build_wasm_ai/dist/ 2>/dev/null || true
+          cp -r src/web/components build_wasm_ai/dist/ 2>/dev/null || true
+          cp -r src/web/core build_wasm_ai/dist/ 2>/dev/null || true
+          cp -r src/web/pwa build_wasm_ai/dist/ 2>/dev/null || true
+          cp -r src/web/icons build_wasm_ai/dist/ 2>/dev/null || true
+          cp -r src/web/debug build_wasm_ai/dist/ 2>/dev/null || true
+
+          # CRITICAL: coi-serviceworker.js must be at root for proper service worker scope
+          if [ -f src/web/pwa/coi-serviceworker.js ]; then
+            cp src/web/pwa/coi-serviceworker.js build_wasm_ai/dist/
+            echo "coi-serviceworker.js copied to root (required for SharedArrayBuffer)"
+          else
+            echo "WARNING: coi-serviceworker.js not found!"
+          fi
+
+          # Copy yaze icon
+          if [ -f assets/yaze.png ]; then
+            mkdir -p build_wasm_ai/dist/assets
+            cp assets/yaze.png build_wasm_ai/dist/assets/
+          fi
+
+          echo "Web assets updated!"
+
+      # --- Build Documentation ---
+      - name: Build Documentation
+        run: |
+          mkdir -p build/docs
+          doxygen Doxyfile
+          # Move docs into dist/docs
+          mkdir -p build_wasm_ai/dist/docs
+          mv build/docs/html/* build_wasm_ai/dist/docs/
+
+      # --- Deploy ---
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build_wasm_ai/dist/
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,32 +1,129 @@
-.favorites.json
+# Build directories - organized by platform (root level only)
-build/
+/build/
-.cache/
+/build-*/
-.vscode/
+/build_*/
-disasm/
+/out/
-src/etc
+docs/html/
-src/lib/SDL2
+docs/latex/
-src/lib/cmake
+
-src/lib/GL
+# CMake
-src/lib/abseil-cpp
+CMakeCache.txt
-src/lib/libGLEW.2.2.0.dylib
+CMakeFiles/
-src/lib/libGLEW.2.2.dylib
+cmake_install.cmake
-src/lib/libGLEW.a
+compile_commands.json
-src/lib/libGLEW.dylib
+CPackConfig.cmake
-src/lib/libSDL2_test.a
+CPackSourceConfig.cmake
-src/lib/libSDL2-2.0.0.dylib
+CTestTestfile.cmake
-src/lib/libSDL2.a
+CMakeUserPresets.json
-src/lib/libSDL2.dylib
+
-src/lib/libSDL2main.a
+# Build artifacts
-checks.json
+*.o
-assets/lib/libasar.dll
+*.a
-cmake/yaze.plist.in
+*.so
-etc/
+*.dylib
-latex/
+*.dll
-html/
+*.exe
-docs/zarby_algos.md
+*.app
-docs/overworld-expansion.md
+*.out
-assets/asm/EditorCore.asm
+
-src/app/emu/cpu/internal/old_cpu.cc
+# IDE files
-build-windows
+.vscode/
-src/lib/libpng
+.idea/
-src/lib/zlib
+*.swp
+*.swo
+*~
+.DS_Store
+src/ios/yaze_ios.xcodeproj/
+src/ios/yaze.xcodeproj/xcuserdata/
+src/ios/yaze.xcodeproj/project.xcworkspace/xcuserdata/
+
+# Test outputs
+test_screenshots/
+test_temp_rom.sfc
+zelda3_v3_test.sfc
+
+# 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/
+assets/asm/usdasm/
+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__/
+build_gemini
+scripts/ai/results/*.json
+scripts/ai/results/*.md
+scripts/ai/results/*.txt
+logs/breakthrough_test.log
+logs/cmake_config 2.log
+logs/cmake_config 3.log
+logs/cmake_config.log
+logs/dungeon_debug.log
+logs/final_rendering.log
+logs/flag_fix_enhanced_test.log
+logs/flag_fix_test.log
+logs/layout_rendering.log
+logs/layout_tiles_test.log
+logs/scale_test.log
+logs/test_fixed.log
+logs/test_output.log
+logs/tile_data_test.log
+logs/timing_analysis.log
+logs/visual_test.log
+logs/windows_ci_linker_error.log
+logs/yaze_emu_trace.log
+logs/yaze_release.wasm
+logs/yaze_release.wat
+logs/build-logs-Windows 2022 (Clang)/build.log
+logs/build-logs-Windows 2022 (Clang)/cmake_config.log
+logs/build-logs-Windows 2022 (Clang-CL)/build.log
+logs/build-logs-Windows 2022 (Clang-CL)/cmake_config.log
+vanilla.sfc
+zelda3.sfc
+yaze_manual.log
+yaze_startup.log
+roms/

.gitmodules

@@ -1,24 +1,15 @@
-[submodule "src/lib/imgui"]
+[submodule "ext/imgui"]
-	path = src/lib/imgui
+	path = ext/imgui
 	url = https://github.com/ocornut/imgui.git
-[submodule "src/lib/ImGuiFileDialog"]
+[submodule "ext/SDL"]
-	path = src/lib/ImGuiFileDialog
+	path = ext/SDL
-	url = https://github.com/aiekick/ImGuiFileDialog.git
-[submodule "src/lib/ImGuiColorTextEdit"]
-	path = src/lib/ImGuiColorTextEdit
-	url = https://github.com/BalazsJako/ImGuiColorTextEdit.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
 	url = https://github.com/libsdl-org/SDL.git
-[submodule "src/lib/asar"]
+[submodule "ext/asar"]
-	path = src/lib/asar
+	path = ext/asar
 	url = https://github.com/RPGHacker/asar.git
-[submodule "src/lib/imgui_test_engine"]
+[submodule "ext/imgui_test_engine"]
-	path = src/lib/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

.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,60 @@
+# Agent Protocol
+
+_Extends: ~/AGENTS.md_
+
+Project-specific operating procedures for AI agents contributing to `yaze`.
+
+## 1. Persona Adoption
+**Rule:** You must adopt a specific persona for every session.
+*   **Source of Truth:** [docs/internal/agents/personas.md](docs/internal/agents/personas.md)
+*   **Requirement:** Use the exact `Agent ID` from that list in all logs, commits, and board updates.
+*   **Legacy IDs:** Do not use `CLAUDE_CORE`, `CLAUDE_AIINF`, etc. Use the role-based IDs (e.g., `ai-infra-architect`).
+*   **System Prompts:** Load the matching persona prompt from `.claude/agents/<agent-id>.md` (accessible to all agents) before starting work.
+
+## 2. Workflows & Coordination
+
+### Quick Tasks (< 30 min)
+*   **Board:** No update required.
+*   **Tools:** Use `z3ed agent todo` to track your own sub-steps if helpful.
+*   **Commit:** Commit directly with a clear message.
+
+### Substantial Work (> 30 min / Multi-file)
+1.  **Check Context:**
+    *   Read [docs/internal/agents/coordination-board.md](docs/internal/agents/coordination-board.md) for `REQUEST` or `BLOCKER` tags.
+    *   Run `git status` and `git diff` to understand the current state.
+2.  **Declare Intent:**
+    *   If your work overlaps with an active task on the board, post a note or Request for Comments (RFC) there first.
+    *   Otherwise, log a new entry on the **Coordination Board**.
+3.  **Execute:**
+    *   Use `z3ed agent todo` to break down the complex task.
+    *   Use `z3ed agent handoff` if you cannot finish in one session.
+
+### Multi-Day Initiatives
+*   Create a dedicated document using [docs/internal/agents/initiative-template.md](docs/internal/agents/initiative-template.md).
+*   Link to this document from the Coordination Board.
+
+### Specs & Docs
+*   Keep one canonical spec per initiative (link it from the board entry and back).
+*   Add a header with Status/Owner/Created/Last Reviewed/Next Review (≤14 days) and validation/exit criteria.
+*   Use existing templates (`initiative-template.md`, `release-checklist-template.md`) instead of creating ad-hoc files.
+*   Archive idle or completed specs to `docs/internal/agents/archive/` with the date; do not open duplicate status pages.
+
+## 3. The Coordination Board
+**Location:** `docs/internal/agents/coordination-board.md`
+
+*   **Hygiene:** Keep entries concise (≤ 5 lines).
+*   **Status:** Update your entry status to `COMPLETE` or `ARCHIVED` when done.
+*   **Maintenance:** Archive completed work weekly to `docs/internal/agents/archive/`.
+
+## 4. Helper Scripts
+Located in `scripts/agents/`:
+*   `run-gh-workflow.sh`: Trigger CI manually.
+*   `smoke-build.sh`: Fast verification build.
+*   `test-http-api.sh`: Validate the agent API.
+
+**Log results:** When running these scripts for significant validation, paste the run ID or result summary to the Board.
+
+## 5. Documentation Hygiene
+- Follow [docs/internal/agents/doc-hygiene.md](docs/internal/agents/doc-hygiene.md) to avoid doc sprawl.
+- Keep specs short, template-driven, and linked to the coordination board; prefer edits over new files.
+- Archive completed/idle docs (>=14 days) under `docs/internal/agents/archive/` with dates to keep the root clean.

CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+_Extends: ~/AGENTS.md, ~/CLAUDE.md_
+
+C++23 ROM editor for Zelda: A Link to the Past. GUI editor + SNES emulator + AI CLI (`z3ed`).
+
+## Build & Test
+
+```bash
+cmake --preset mac-dbg && cmake --build build -j8   # Build
+ctest --test-dir build -L stable -j4                 # Test
+./yaze --rom_file=zelda3.sfc --editor=Dungeon        # Run
+```
+
+Presets: `mac-dbg`/`lin-dbg`/`win-dbg`, `mac-ai`/`win-ai`, `*-rel`. See `docs/public/build/quick-reference.md`.
+
+## Architecture
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| Rom | `src/app/rom.h` | ROM data access, transactions |
+| Editors | `src/app/editor/` | Overworld, Dungeon, Graphics, Palette |
+| Graphics | `src/app/gfx/` | Bitmap, Arena (async loading), Tiles |
+| Zelda3 | `src/zelda3/` | Overworld (160 maps), Dungeon (296 rooms) |
+| Canvas | `src/app/gui/canvas.h` | ImGui canvas with pan/zoom |
+| CLI | `src/cli/z3ed.cc` | AI-powered ROM hacking tool |
+
+## Key Patterns
+
+**Graphics refresh**: Update model → `Load*()` → `Renderer::Get().RenderBitmap()`
+
+**Async loading**: `Arena::Get().QueueDeferredTexture(bitmap, priority)` + process in `Update()`
+
+**Bitmap sync**: Use `set_data()` for bulk updates (syncs `data_` and `surface_->pixels`)
+
+**Theming**: Always use `AgentUI::GetTheme()`, never hardcoded colors
+
+**Multi-area maps**: Always use `Overworld::ConfigureMultiAreaMap()`, never set `area_size` directly
+
+## Naming
+
+- **Load**: ROM → memory
+- **Render**: Data → bitmap (CPU)
+- **Draw**: Bitmap → screen (GPU)
+
+## Pitfalls
+
+1. Use `set_data()` not `mutable_data()` assignment for bitmap bulk updates
+2. Call `ProcessTextureQueue()` every frame
+3. Pass `0x800` to `DecompressV2`, never `0`
+4. SMC header: `size % 1MB == 512`, not `size % 32KB`
+5. Check `rom_->is_loaded()` before ROM operations
+
+## Code Style
+
+Google C++ Style. Use `absl::Status`/`StatusOr<T>` with `RETURN_IF_ERROR()`/`ASSIGN_OR_RETURN()`.
+
+Format: `cmake --build build --target format`
+
+## Docs
+
+- Architecture: `docs/internal/architecture/`
+- Build issues: `docs/BUILD-TROUBLESHOOTING.md`
+- Tests: `test/README.md`

CMakeLists.txt

@@ -1,49 +1,191 @@
 # Yet Another Zelda3 Editor
 # by scawful
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.16)
-project(yaze VERSION 0.2.0
-             DESCRIPTION "Yet Another Zelda3 Editor"
-             LANGUAGES CXX)
 
-# Build Flags
+# Set minimum policy version for subdirectories to allow older dependencies like yaml-cpp
-set(YAZE_BUILD_APP ON)
+# This allows cmake_minimum_required in subdirectories to use versions < 3.5
-set(YAZE_BUILD_LIB ON)
+set(CMAKE_POLICY_VERSION_MINIMUM 3.5 CACHE STRING "Minimum policy version for subdirectories")
-set(YAZE_BUILD_EMU ON)
-set(YAZE_BUILD_Z3ED ON)
-set(YAZE_BUILD_PYTHON OFF)
-set(YAZE_BUILD_TESTS ON)
-set(YAZE_INSTALL_LIB OFF)
 
-# libpng features in bitmap.cc
+# Set policies for compatibility
-add_definitions("-DYAZE_LIB_PNG=1")
+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)
 
-# C++ Standard and CMake Specifications
+# Enable Objective-C only on macOS where it's actually used
-set(CMAKE_CXX_STANDARD 20)
+if(DEFINED ENV{YAZE_VERSION_OVERRIDE})
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
+    set(YAZE_VERSION $ENV{YAZE_VERSION_OVERRIDE})
-set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
+elseif(DEFINED YAZE_VERSION_OVERRIDE)
-set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
+     set(YAZE_VERSION ${YAZE_VERSION_OVERRIDE})
-set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+else()
-set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+    set(YAZE_VERSION "0.5.0")
-set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
+    set(YAZE_VERSION_SUFFIX "")
-set(BUILD_SHARED_LIBS OFF)
-set(CMAKE_FIND_FRAMEWORK LAST)
-set(CMAKE_SHARED_MODULE_PREFIX "")
-set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Dlinux -Dstricmp=strcasecmp")
-if (MACOS)
-  set(CMAKE_INSTALL_PREFIX /usr/local)
 endif()
 
-# Abseil Standard Specifications
+if(APPLE)
-include(cmake/absl.cmake)
+    project(yaze VERSION ${YAZE_VERSION}
+                 DESCRIPTION "Yet Another Zelda3 Editor"
+                 LANGUAGES CXX C OBJC OBJCXX)
+else()
+    project(yaze VERSION ${YAZE_VERSION}
+                 DESCRIPTION "Yet Another Zelda3 Editor"
+                 LANGUAGES CXX C)
+endif()
 
-# SDL2 and PNG
+# Set language standards early so dependencies (e.g., Abseil) build with them.
-include(cmake/sdl2.cmake)
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_C_STANDARD 99)
+set(CMAKE_C_STANDARD_REQUIRED ON)
 
-# Asar
+# Include build options first
-include(cmake/asar.cmake)
+include(cmake/options.cmake)
 
-# ImGui
+# Enable sccache/ccache for faster rebuilds if available
-include(cmake/imgui.cmake)
+find_program(SCCACHE_FOUND sccache)
+if(SCCACHE_FOUND)
+    message(STATUS "✓ sccache found, enabling for faster builds")
+    set(CMAKE_CXX_COMPILER_LAUNCHER sccache)
+    set(CMAKE_C_COMPILER_LAUNCHER sccache)
+else()
+    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()
+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})
+
+# Platform detection
+if(APPLE)
+    if(CMAKE_SYSTEM_NAME STREQUAL "iOS")
+        set(YAZE_PLATFORM_IOS ON)
+    else()
+        set(YAZE_PLATFORM_MACOS ON)
+    endif()
+elseif(CMAKE_SYSTEM_NAME MATCHES "Linux")
+    set(YAZE_PLATFORM_LINUX ON)
+elseif(CMAKE_SYSTEM_NAME MATCHES "Windows")
+    set(YAZE_PLATFORM_WINDOWS ON)
+endif()
+
+# Include utility functions
+include(cmake/utils.cmake)
+
+# Set up dependencies using CPM.cmake
+include(cmake/dependencies.cmake)
+
+# Additional configuration options
+option(YAZE_SUPPRESS_WARNINGS "Suppress compiler warnings (use -v preset suffix for verbose)" ON)
+set(YAZE_TEST_ROM_VANILLA_PATH "" CACHE STRING "Path to vanilla test ROM file")
+set(YAZE_TEST_ROM_US_PATH "" CACHE STRING "Path to US test ROM file")
+set(YAZE_TEST_ROM_JP_PATH "" CACHE STRING "Path to JP test ROM file")
+set(YAZE_TEST_ROM_EU_PATH "" CACHE STRING "Path to EU test ROM file")
+set(YAZE_TEST_ROM_EXPANDED_PATH "" CACHE STRING "Path to expanded test ROM file")
+set(YAZE_TEST_ROM_PATH "" CACHE STRING "Legacy path to test ROM file (vanilla)")
+
+# Export compile commands for clangd/LSP
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+# 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
+)
+
+# 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)
+
+# Tools
+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
+if(YAZE_ENABLE_CLANG_TIDY)
+  if(NOT YAZE_CLANG_TIDY_EXE)
+    find_program(YAZE_CLANG_TIDY_EXE NAMES clang-tidy clang-tidy-18 clang-tidy-17 clang-tidy-16)
+  endif()
+
+  if(YAZE_CLANG_TIDY_EXE)
+    message(STATUS "✓ clang-tidy enabled: ${YAZE_CLANG_TIDY_EXE}")
+    set(CMAKE_CXX_CLANG_TIDY "${YAZE_CLANG_TIDY_EXE}")
+  else()
+    message(WARNING "clang-tidy requested but not found")
+  endif()
+endif()
+
+find_program(CLANG_FORMAT
+  NAMES clang-format-18 clang-format
+  HINTS "${HOMEBREW_LLVM_PREFIX}/bin" # Prefer clang-format from Homebrew LLVM
+  NO_DEFAULT_PATH
+)
+if(NOT CLANG_FORMAT) # Fallback to generic search if not found in Homebrew prefix
+  find_program(CLANG_FORMAT NAMES clang-format clang-format-17 clang-format-16 clang-format-15 clang-format-14)
+endif()
+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=file ${ALL_SOURCE_FILES}
+    COMMENT "Running clang-format on source files"
+  )
+
+  add_custom_target(yaze-format-check
+    COMMAND ${CLANG_FORMAT} --dry-run --Werror --style=file ${ALL_SOURCE_FILES}
+    COMMENT "Checking code format"
+  )
+endif()
+
+# Packaging configuration
+if(NOT YAZE_PLATFORM_IOS)
+  include(cmake/packaging/cpack.cmake)
+endif()
+
+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"
+)

CMakeUserPresets.json.example

@@ -0,0 +1,49 @@
+{
+  "version": 6,
+  "configurePresets": [
+    {
+      "name": "dev-local",
+      "inherits": "dev",
+      "binaryDir": "$env{YAZE_BUILD_ROOT}/build",
+      "environment": {
+        "CPM_SOURCE_CACHE": "$env{HOME}/.cpm-cache",
+        "VCPKG_DOWNLOADS": "$env{HOME}/.cache/vcpkg/downloads",
+        "VCPKG_BINARY_SOURCES": "clear;files,$env{HOME}/.cache/vcpkg/bincache,readwrite"
+      }
+    },
+    {
+      "name": "wasm-debug-local",
+      "inherits": "wasm-debug",
+      "binaryDir": "$env{YAZE_BUILD_ROOT}/build-wasm",
+      "environment": {
+        "CPM_SOURCE_CACHE": "$env{HOME}/.cpm-cache",
+        "VCPKG_DOWNLOADS": "$env{HOME}/.cache/vcpkg/downloads",
+        "VCPKG_BINARY_SOURCES": "clear;files,$env{HOME}/.cache/vcpkg/bincache,readwrite"
+      }
+    },
+    {
+      "name": "wasm-release-local",
+      "inherits": "wasm-release",
+      "binaryDir": "$env{YAZE_BUILD_ROOT}/build-wasm",
+      "environment": {
+        "CPM_SOURCE_CACHE": "$env{HOME}/.cpm-cache",
+        "VCPKG_DOWNLOADS": "$env{HOME}/.cache/vcpkg/downloads",
+        "VCPKG_BINARY_SOURCES": "clear;files,$env{HOME}/.cache/vcpkg/bincache,readwrite"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "dev-local",
+      "configurePreset": "dev-local"
+    },
+    {
+      "name": "wasm-debug-local",
+      "configurePreset": "wasm-debug-local"
+    },
+    {
+      "name": "wasm-release-local",
+      "configurePreset": "wasm-release-local"
+    }
+  ]
+}

Doxyfile

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

GEMINI.md

@@ -0,0 +1,354 @@
+# GEMINI.md - YAZE Build Instructions
+
+_Extends: ~/AGENTS.md, ~/GEMINI.md_
+
+Build and test instructions for YAZE project. Follow commands exactly.
+
+## Critical Rules
+
+1. **Use `build_ai/` directory** - Never use `build/` (reserved for user)
+2. **Use `*-ai` presets** - Never use `*-dbg` presets
+3. **Load persona** - Check `.claude/agents/<agent-id>.md` for system prompt
+4. **Use helper script:**
+   ```bash
+   ./scripts/agent_build.sh [target]
+   ```
+   *Example:* `./scripts/agent_build.sh yaze` or `./scripts/agent_build.sh yaze_test`
+
+---
+
+## Quick Reference: Build Times
+
+**First Build (Cold Start)**:
+- **Fast Mode (Recommended)**: 2-4 minutes (uses system gRPC/sccache)
+- Standard Mode: 10-20 minutes (compiles gRPC from source)
+
+**Incremental Builds (After Changes)**:
+- Typically 10-60 seconds depending on what changed
+- **sccache/ccache**: Automatically detected and used if installed (highly recommended)
+
+## Platform-Specific Build Commands
+
+### macOS
+
+```bash
+# Step 1: Configure (First time only, or when CMakeLists.txt changes)
+cmake --preset mac-ai
+
+# Step 2: Build the entire project
+cmake --build build_ai --preset mac-ai
+
+# Step 3: Build specific targets (faster for incremental work)
+cmake --build build_ai --target yaze                  # GUI application only
+cmake --build build_ai --target yaze_test            # Test suite only
+cmake --build build_ai --target ylib                 # Core library only
+```
+
+**Available macOS Presets**:
+- `mac-ai` - **Preferred for Agents**. Configured to use system gRPC/protobuf if available (brew installed) and defaults to `build_ai`.
+- `mac-dbg` - User's debug build (DO NOT USE).
+
+### Linux
+
+```bash
+# Step 1: Configure
+cmake --preset lin-ai
+
+# Step 2: Build
+cmake --build build_ai --preset lin-ai
+```
+
+**Available Linux Presets**:
+- `lin-ai` - **Preferred for Agents**. Uses `build_ai` and system libraries.
+
+### Windows
+
+```bash
+# Step 1: Configure (PowerShell or CMD)
+cmake --preset win-ai
+
+# Step 2: Build
+cmake --build build_ai --preset win-ai
+```
+
+**Available Windows Presets**:
+- `win-ai` - **Preferred for Agents**. Uses `build_ai`.
+
+## Testing
+
+### Running All Tests
+
+```bash
+# Build tests first
+cmake --build build_ai --target yaze_test
+
+# Run all tests
+./build_ai/bin/yaze_test
+```
+
+### Running Specific Test Categories
+
+```bash
+# Unit tests only (fast, ~5-10 seconds)
+./build/bin/yaze_test --unit
+
+# Integration tests (requires ROM file)
+./build/bin/yaze_test --integration --rom-path /path/to/zelda3.sfc
+
+# End-to-end GUI tests
+./build/bin/yaze_test --e2e --show-gui
+
+# Run specific test by name pattern
+./build/bin/yaze_test "*Asar*"          # All tests with "Asar" in name
+./build/bin/yaze_test "*Dungeon*"       # All dungeon-related tests
+```
+
+### Test Output Modes
+
+```bash
+# Minimal output (default)
+./build/bin/yaze_test
+
+# Verbose output (shows all test names)
+./build/bin/yaze_test -v
+
+# Very verbose (shows detailed test execution)
+./build/bin/yaze_test -vv
+
+# List all available tests without running
+./build/bin/yaze_test --list-tests
+```
+
+## Common Build Issues and Solutions
+
+### Issue 1: "No preset found"
+
+**Error**: `CMake Error: No such preset in CMakePresets.json`
+
+**Solution**: Check the exact preset name. Use tab-completion or check `CMakePresets.json`.
+
+```bash
+# List available presets
+cmake --list-presets
+
+# Common mistake: Using wrong platform prefix
+cmake --preset dbg          # ❌ WRONG
+cmake --preset mac-dbg      # ✅ CORRECT (macOS)
+cmake --preset lin-dbg      # ✅ CORRECT (Linux)
+cmake --preset win-dbg      # ✅ CORRECT (Windows)
+```
+
+### Issue 2: "Build directory exists but is outdated"
+
+**Error**: CMake complains about existing build directory
+
+**Solution**: Clean and reconfigure
+
+```bash
+# Remove old build directory
+rm -rf build
+
+# Reconfigure from scratch
+cmake --preset mac-dbg  # or lin-dbg / win-dbg
+```
+
+### Issue 3: "Tests fail with 'ROM not found'"
+
+**Error**: Integration tests fail with ROM-related errors
+
+**Solution**: Some tests require a Zelda3 ROM file
+
+```bash
+# Skip ROM-dependent tests
+./build/bin/yaze_test --unit
+
+# Or provide ROM path
+./build/bin/yaze_test --integration --rom-path zelda3.sfc
+```
+
+### Issue 4: Long build times on first run
+
+**Not an Error**: This is normal!
+
+**Explanation**:
+- CPM.cmake downloads all dependencies (~3-5 minutes)
+- gRPC compilation (Windows only, ~15-20 minutes)
+- ImGui compilation (~2-3 minutes)
+- SDL2, Abseil, PNG libraries (~3-5 minutes)
+
+**Solution**: Be patient on first build. Subsequent builds use ccache/sccache and are MUCH faster (10-60 seconds).
+
+```bash
+# Monitor build progress with verbose output
+cmake --build build --preset mac-dbg -v | tee build.log
+
+# Check build log for specific step taking long
+grep "Linking" build.log
+```
+
+### Issue 5: Incremental builds seem slow
+
+**Solution**: Only rebuild what changed
+
+```bash
+# Instead of rebuilding everything:
+cmake --build build --preset mac-dbg              # ❌ Rebuilds all targets
+
+# Build only what you need:
+cmake --build build --target yaze                 # ✅ Just the GUI app
+cmake --build build --target ylib                 # ✅ Just the core library
+cmake --build build --target object_editor_card   # ✅ Just one component
+```
+
+## Development Workflow
+
+### Typical Development Session
+
+```bash
+# 1. Configure once (first time only)
+cmake --preset mac-dbg
+
+# 2. Make code changes to src/app/editor/dungeon/object_editor_card.cc
+
+# 3. Rebuild only the affected target (fast!)
+cmake --build build --target yaze
+
+# 4. Run the application to test manually
+./build/bin/yaze --rom_file zelda3.sfc --editor Dungeon
+
+# 5. Run automated tests to verify
+./build/bin/yaze_test --unit
+
+# 6. If tests pass, commit
+git add src/app/editor/dungeon/object_editor_card.cc
+git commit -m "feat(dungeon): add feature X"
+```
+
+### Testing Dungeon Editor Changes
+
+```bash
+# 1. Build just the GUI app (includes dungeon editor)
+cmake --build build --target yaze
+
+# 2. Launch directly to dungeon editor with ROM
+./build/bin/yaze --rom_file zelda3.sfc --editor Dungeon
+
+# 3. To test keyboard shortcuts specifically:
+#    - Open Object Editor card
+#    - Try Ctrl+A (select all)
+#    - Try Delete key (delete selected)
+#    - Try Ctrl+D (duplicate)
+#    - Try Arrow keys (nudge objects)
+#    - Try Tab (cycle selection)
+```
+
+### Before Committing Changes
+
+```bash
+# 1. Run unit tests (fast check)
+./build/bin/yaze_test --unit
+
+# 2. Run format check (ensure code style)
+cmake --build build --target format-check
+
+# 3. If format check fails, auto-format
+cmake --build build --target format
+
+# 4. Build in release mode to catch optimization warnings
+cmake --preset mac-rel
+cmake --build build --preset mac-rel
+
+# 5. If all passes, you're ready to commit!
+```
+
+## Preset Comparison Matrix
+
+| Preset     | Platform | Build Type | AI Features | gRPC | Agent UI | Use Case |
+|------------|----------|------------|-------------|------|----------|----------|
+| mac-dbg    | macOS    | Debug      | No          | No   | No       | Daily development |
+| mac-rel    | macOS    | Release    | No          | No   | No       | Performance testing |
+| mac-ai     | macOS    | Debug      | Yes         | Yes  | Yes      | z3ed development |
+| lin-dbg    | Linux    | Debug      | No          | No   | No       | Daily development |
+| lin-rel    | Linux    | Release    | No          | No   | No       | Performance testing |
+| lin-ai     | Linux    | Debug      | Yes         | Yes  | Yes      | z3ed development |
+| win-dbg    | Windows  | Debug      | No          | No   | No       | Daily development |
+| win-rel    | Windows  | Release    | No          | No   | No       | Performance testing |
+| win-ai     | Windows  | Debug      | Yes         | Yes  | Yes      | z3ed development |
+
+## CI/CD Build Times (For Reference)
+
+GitHub Actions runners typically see these build times:
+
+- **Ubuntu 22.04**: 6-8 minutes (with caching)
+- **macOS 14**: 8-10 minutes (with caching)
+- **Windows 2022**: 12-18 minutes (gRPC adds time)
+
+Your local builds may be faster or slower depending on:
+- CPU cores (more = faster parallel builds)
+- SSD speed (affects linking time)
+- Available RAM (swap = slower builds)
+- ccache/sccache hit rate (warm cache = much faster)
+
+## Target Dependencies Reference
+
+Understanding what rebuilds when you change files:
+
+```
+yaze (GUI app)
+├── ylib (core library)
+│   ├── zelda3_dungeon (dungeon module)
+│   │   └── object_editor_card.cc ← Your changes here
+│   ├── zelda3_overworld
+│   ├── gfx (graphics system)
+│   └── core (compression, ROM I/O)
+├── imgui (UI framework)
+└── SDL2 (windowing/graphics)
+
+yaze_test (test suite)
+├── ylib (same as above)
+├── gtest (Google Test framework)
+└── test/*.cc files
+```
+
+**When you change**:
+- `object_editor_card.cc` → Rebuilds: ylib, yaze (30-60 seconds)
+- `object_editor_card.h` → Rebuilds: ylib, yaze, any test including header (1-2 minutes)
+- `rom.cc` → Rebuilds: Most of ylib, yaze, yaze_test (3-5 minutes)
+- `CMakeLists.txt` → Reconfigure + full rebuild (5-10 minutes)
+
+## Quick Command Cheat Sheet
+
+```bash
+# === Configuration ===
+cmake --list-presets                    # Show available presets
+cmake --preset mac-dbg                  # Configure for macOS debug
+
+# === Building ===
+cmake --build build --target yaze       # Build GUI app
+cmake --build build --target yaze_test  # Build test suite
+cmake --build build --target format     # Format all code
+cmake --build build -v                  # Verbose build output
+
+# === Testing ===
+./build/bin/yaze_test                   # Run all tests
+./build/bin/yaze_test --unit            # Unit tests only
+./build/bin/yaze_test "*Asar*"          # Specific test pattern
+./build/bin/yaze_test --list-tests      # List available tests
+
+# === Running ===
+./build/bin/yaze                                    # Launch GUI
+./build/bin/yaze --rom_file zelda3.sfc              # Load ROM
+./build/bin/yaze --editor Dungeon                   # Open editor
+./build/bin/yaze --rom_file zelda3.sfc --editor Dungeon  # Combined
+
+# === Cleaning ===
+cmake --build build --target clean      # Clean build artifacts
+rm -rf build                            # Full clean (reconfigure needed)
+```
+
+## Key Reminders
+
+- Use full preset names: `mac-ai` not just `ai`
+- First builds: 10-20 min (normal), incremental: 10-60 sec
+- Build specific targets: `--target yaze` faster than full build
+- Some tests require ROM file to pass

README.md

@@ -1,59 +1,100 @@
-# Yet Another Zelda3 Editor
+# YAZE - Yet Another Zelda3 Editor
 
-- Platform: Windows, macOS, iOS, GNU/Linux
+[![CI](https://github.com/scawful/yaze/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/scawful/yaze/actions)
-- Dependencies: SDL2, ImGui, abseil-cpp
+[![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. A preview web version is also available for browser-based editing.
 
-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.
+- **Web preview**: Experimental browser-based editor (WASM) - see [Web App Guide](docs/public/usage/web-app.md).
+- **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.
 
-Provides bindings in C and Python for building custom tools and utilities.
+## Project Status
+v0.5.0 is the current release. New to YAZE? Start with a clean, legally obtained ALttP (USA) ROM and the Quick Start steps below. See [`docs/public/release-notes.md`](docs/public/release-notes.md) for details.
 
-Takes heavy inspiration from ALTTP community efforts such as [Hyrule Magic](https://www.romhacking.net/utilities/200/) and [ZScream](https://github.com/Zarby89/ZScreamDungeon)
+## Quick Start
 
-Building and installation
+### Clone & Bootstrap
--------------------------
+```bash
-[CMake](http://www.cmake.org "CMake") is required to build yaze 
+git clone --recursive https://github.com/scawful/yaze.git
-
+cd yaze
-1. Clone the repository
-2. Create the build directory and configuration
-3. Build and run the application 
-4. (Optional) Run the tests
-
-```
-  git clone --recurse-submodules https://github.com/scawful/yaze.git 
-  cmake -S . -B build
-  cmake --build build
 ```
 
-By default this will build all targets. 
+Run the environment verifier once per machine:
+```bash
+# macOS / Linux
+./scripts/verify-build-environment.sh --fix
 
-- **yaze**:       Editor Application
+# Windows (PowerShell)
-- **yaze_c**:     C Library
+.\scripts\verify-build-environment.ps1 -FixIssues
-- **yaze_emu**:   SNES Emulator
+```
-- **yaze_py**:    Python Module
-- **yaze_test**:  Unit Tests
-- **z3ed**:       Command Line Interface
 
-Dependencies are included as submodules and will be built automatically. For those who want to reduce compile times, consider installing the dependencies on your system. See [build-instructions.md](docs/build-instructions.md) for more information.
+### 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.
+- **Web App (Preview)** – browser-based editor at your deployed instance; see [`docs/public/usage/web-app.md`](docs/public/usage/web-app.md) for details and limitations.
+- **`./build/bin/z3ed --tui`** – CLI/TUI companion for scripting, AI-assisted edits, and Asar workflows.
+- **`ctest --test-dir build -L 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 roms/alttp_vanilla.sfc
+
+# Apply a patch via CLI
+./build/bin/z3ed asar patch.asm --rom roms/alttp_vanilla.sfc
+
+# Run focused tests
+cmake --build --preset mac-ai --target yaze_test
+ctest --test-dir build -L unit
+```
+
+## Testing
+- `ctest --test-dir build -L unit` for fast checks; add `-L integration` or `-L e2e --output-on-failure` for broader coverage.
+- `ctest --preset dev` mirrors CI’s stable set; `ctest --preset all` runs the full matrix.
+- Set `YAZE_TEST_ROM_VANILLA` or pass `--rom-vanilla` when a test needs a real ROM image (legacy `--rom-path` still works).
 
 ## 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.
+## Contributing & Community
-- For developers, please refer to the [documentation](https://scawful.github.io/yaze/index.html) for information on the project's infrastructure.
+- 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.
-License
+- Chat with the team on [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk).
---------
-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://github.com/scawful/yaze/assets/47263509/8b62b142-1de4-4ca4-8c49-d50c08ba4c8e)
-
-![image](https://github.com/scawful/yaze/assets/47263509/d8f0039d-d2e4-47d7-b420-554b20ac626f)
-
-![image](https://github.com/scawful/yaze/assets/47263509/34b36666-cbea-420b-af90-626099470ae4)
 
+## 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

@@ -5,7 +5,7 @@
 namespace yaze
 {
 
-!YAZE_CUSTOM_MOSAIC = 1
+!YAZE_CUSTOM_MOSAIC = 0
 
 
 if !YAZE_CUSTOM_MOSAIC != 0
@@ -15,7 +15,7 @@ endif
 !ZS_CUSTOM_OVERWORLD = 1
 
 if !ZS_CUSTOM_OVERWORLD != 0
-  incsrc "ZSCustomOverworld.asm"
+  incsrc "ZSCustomOverworld_v3.asm"
 endif
 
 }

assets/layouts/overworld.zeml

@@ -1,25 +0,0 @@
-BeginTabBar title="##OwEditorTabBar" {
-  BeginTabItem title="Map Editor" {
-    Function id="owToolset",
-
-    Table id="##owEditTable" count="2" flags="Resizable|Reorderable|Hideable|BordersOuter|BordersV" {
-      TableSetupColumn title="Canvas" flags="WidthStretch",
-      TableSetupColumn title="Tile Selector" flags="WidthFixed" width="256",
-      TableHeadersRow
-      TableNextRow,
-      TableNextColumn,
-      Function id="OverworldCanvas",
-      TableNextColumn,
-      Function id="OverworldTileSelector",
-    }
-  }
-  BeginTabItem title="Tile16 Editor" {
-    Function id="OwTile16Editor"
-  }
-  BeginTabItem title "Graphics Group Editor" {
-    Function id="OwGfxGroupEditor"
-  }
-  BeginTabItem title="Usage Statistics" {
-    Function id="OwUsageStats"
-  }
-}

assets/patches/Hex Edits/File Fairy.asm

@@ -0,0 +1,12 @@
+;#ENABLED=False
+;#PATCH_NAME=File fairy skin color fix
+;#PATCH_AUTHOR=kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Fixes the file select fairy's skin color
+;#ENDPATCH_DESCRIPTION
+
+pushpc
+org $1BF02A
+	db $10
+pullpc

assets/patches/Hex Edits/Misc Small Patches.asm

@@ -0,0 +1,69 @@
+;#ENABLED=True
+;#PATCH_NAME=Misc Small Patches
+;#PATCH_AUTHOR=Zarby89
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Lots of small patches to do various things
+;No Zelda Telepathy is removing the timed message that tell you to rescue her every minute
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Titlescreen forever (no intro)
+;#type=bool
+!TitleScreenForever = $00
+
+;#name=Skip Ending (before credits)
+;#type=bool
+!SkipEnding = $00
+
+;#name=Prevent S+Q to Dark World
+;#type=bool
+!NoDwSpan = $00
+
+;#name=Disable Dungeon Map
+;#type=bool
+!NoDungeonMap = $00
+
+;#name=Disable Oveworld Map
+;#type=bool
+!NoOWnMap = $00
+
+;#name=No Zelda Telepathy
+;#type=bool
+!NoZeldaFollower = $00
+
+;#DEFINE_END
+
+if !TitleScreenForever = 1
+org $0CC2E3
+db $80
+endif
+
+if !SkipEnding = 1
+org $0E9889
+LDA #$20 : STA $11
+RTS
+endif
+
+if !NoDwSpan = 1
+org $028192
+LDA #$00 : STA $7EF3CA ; Clear the DW address so game doesn't think we are in DW
+JML $0281BD ; To the lightworld !
+endif
+
+if !NoDungeonMap = 1
+org $0288FD ; Replace a BEQ by a BRA (dungeon map removed)
+db $80
+endif
+
+if !NoOWnMap = 1
+org $02A55E ; Replace a BEQ by a BRA (overworld map removed)
+db $80
+endif
+
+if !NoZeldaFollower = 1
+org $05DEF8
+LDA.b #$00
+endif
+
+

assets/patches/Hex Edits/No Beams.asm

@@ -0,0 +1,12 @@
+;#ENABLED=True
+;#PATCH_NAME=No sword beams
+;#PATCH_AUTHOR=kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Disables sword beams
+;#ENDPATCH_DESCRIPTION
+
+pushpc
+org $079C70
+	JMP.w $079CA0
+pullpc

assets/patches/Hex Edits/No Grass Cut.asm

@@ -0,0 +1,11 @@
+;#ENABLED=True
+;#PATCH_NAME=No grass cutting
+;#PATCH_AUTHOR=kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Grass no longer gets cut by the sword
+;#ENDPATCH_DESCRIPTION
+pushpc
+org $1BBE26
+	BRA + : NOP #3 : +
+pullpc

assets/patches/Items/AST Boots.asm

@@ -0,0 +1,80 @@
+;#ENABLED=True
+;#PATCH_NAME=AST Boots
+;#PATCH_AUTHOR=Conn, Zarby89
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Copies the boots mechanics from Ancient Stone Tablets.
+;DPad changes boots directions, and transitions can be
+;optionally prevented from halting the dash
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Keep running after transition
+;#type=bool
+!KeepRunningTransition = $00
+;#DEFINE_END
+
+
+pushpc
+org $87911D
+JML AstBoots
+
+if !KeepRunningTransition != 00
+	org $828B13
+	db $80
+endif
+pullpc
+
+AstBoots:
+	BIT.b $F2
+	BPL .continue
+
+	LDA.b $F0
+	AND.b #$0F
+	BNE .pressing_direction
+
+	JML $879138
+
+.pressing_direction
+	CMP.b #$0A ; up left
+	BEQ +
+
+	CMP.b #$05 ; down right
+	BEQ +
+
+	CMP.b #$09 ; down left
+	BEQ +
+
+	CMP.b #$06 ; up right
+	BNE ++
+
++	AND.b #$0C
+
+++	CMP.b $26
+	BNE +
+
+	JML $879138
+
++	STA.b $26
+	STA.b $67
+	STA.w $0340
+
+	JSL $87E6A6
+
+	JML $879138
+
+.continue
+	LDA.b #$12
+	STA.b $5D
+
+	LDA.b $3A
+	AND.b #$7F
+	STA.b $3A
+
+	STZ.b $3C
+	STZ.b $3D
+
+	LDA.b #$11
+	STA.w $0374
+
+	JML $87915E

assets/patches/Misc/Big Bomb Requirements.asm

@@ -0,0 +1,44 @@
+;#ENABLED=True
+
+;#PATCH_NAME=Big Bomb requirement
+;#PATCH_AUTHOR=Zarby89,kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Modify the crystal and dwarf requirements for the big bomb
+;If SmithRequirement is set to 20, you will need to save the Smith first
+;#ENDPATCH_DESCRIPTION
+
+
+;#DEFINE_START
+;#name=Crystals Required
+;#type=bitfield
+;#bit0=Crystal 6
+;#bit1=Crystal 1
+;#bit2=Crystal 5
+;#bit3=Crystal 7
+;#bit4=Crystal 2
+;#bit5=Crystal 4
+;#bit6=Crystal 3
+!CrystalRequirement =$02
+
+
+;#name=Required smith saved?
+;#type=bool
+;#uncheckedvalue=$00
+;#checkedvalue=$20
+!SmithRequirement =$00
+
+
+;#DEFINE_END
+
+pushpc
+
+org $1EE16A
+
+	LDA.l $7EF37A : AND.b #!CrystalRequirement : CMP.b #!CrystalRequirement
+
+	skip 2
+
+	LDA.l $7EF3C9 : AND.b #!SmithRequirement
+
+pullpc

assets/patches/Misc/HoleOverlayFix.asm

@@ -0,0 +1,41 @@
+;#ENABLED=True
+
+;#PATCH_NAME=Hole Overlay Fix
+;#PATCH_AUTHOR=kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Allow the floor collision of the hole overlay to work on every floor types
+;#ENDPATCH_DESCRIPTION
+
+pushpc
+
+org $01B83E : JSL FigureOutFloor1
+
+; change comparisons to our dynamic values
+org $01FE6C : CMP.w $0318
+org $01FE71 : CMP.w $031A
+
+pullpc
+
+;===================================================================================================
+
+; Find floor 1 index and save its tiles
+FigureOutFloor1:
+    REP #$30
+
+    LDX.w $046A ; read floor 1 index
+
+    ; this reuses some memory related to conveyors
+    ; the memory is very temporary so it should be safe
+
+    ; databank is 0, so we can use abs,X
+    LDA.w $009B52+0,X ; find top tile
+    AND.w #$03FE ; isolate tile name
+    STA.w $0318 ; save tile
+
+    LDA.w $009B52+8,X ; find bottom tile
+    AND.w #$03FE ; isolate tile name
+    STA.w $031A ; save tile
+
+    LDA.b $BA ; vanilla code and return
+    RTL

assets/patches/Misc/IntroSkip.asm

@@ -0,0 +1,13 @@
+;#ENABLED=true
+
+;#PATCH_NAME=Intro skip
+;#PATCH_AUTHOR=kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Skip the intro sooner
+;#ENDPATCH_DESCRIPTION
+
+pushpc
+org $0CC123
+	db 4
+pullpc

assets/patches/Misc/JP1.0 Glitches.asm

@@ -0,0 +1,39 @@
+;#ENABLED=True
+
+;#PATCH_NAME=1.0 Glitches
+;#PATCH_AUTHOR=kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Restore the JP 1.0 glitches
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Mirror block erase
+;#type=bool
+!MirrorEraseBlock = $00
+
+;#name=Spin speed and Item dash
+;#type=bool
+!SpinSpeedItemDash = $00
+
+;#name=Fake flippers
+;#type=bool
+!FakeFlippers = $00
+;#DEFINE_END
+
+pushpc
+if !MirrorEraseBlock == 1
+org $07A969
+	JMP.w $07A970
+endif
+
+if !SpinSpeedItemDash == 1
+org $0781C0
+	BRA + : NOP #4 : +
+endif
+
+if !FakeFlippers == 1
+org $079665
+	JMP.w $07966C
+endif
+pullpc

assets/patches/Misc/Link Bed Start Position.asm

@@ -0,0 +1,39 @@
+;#ENABLED=True
+;#PATCH_NAME=Link Bed Starting Position
+;#PATCH_AUTHOR=Zarby89, Jared_Brian_, kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Changes where Link spawns during the opening bed cutscene
+;Positions can be found by temporarily moving the Link's house entrance to
+;the desired location
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Link Y Position
+;#type=word
+!LinkYPosition = $2182
+
+;#name=Link Y Position
+;#type=word
+!LinkXPosition = $095B
+;#DEFINE_END
+
+; Link sleep position changes
+org $079A31
+	LDA.w #!LinkYPosition : STA.b $20 ; Y link position in bed
+	LDA.w #!LinkXPosition : STA.b $22 ; X link position in bed
+
+org $05DE52 ; These values should be the same as the ones above
+	LDA.b #!LinkXPosition : STA.w $0FC2 ; X link position in bed
+	LDA.b #!LinkXPosition>>8 : STA.w $0FC3 ; X link position in bed
+
+	LDA.b #!LinkYPosition : STA.w $0FC4 ; Y link position in bed
+	LDA.b #!LinkYPosition>>8 : STA.w $0FC5 ; Y link position in bed
+
+org $0980B7
+	LDA.w #(!LinkYPosition+8) : STA.b $00 ; Y link sheet in bed
+	LDA.w #(!LinkXPosition-8) : STA.b $02 ; X link sheet in bed
+
+org $05DE8C
+	LDA.b #(!LinkYPosition-3) : STA.b $20 ; Y link position in bed when awoken
+	LDA.b #(!LinkYPosition-3)>>8 : STA.b $21 ; Y link position in bed when awoken

assets/patches/Misc/NoRocks.asm

@@ -0,0 +1,28 @@
+;#ENABLED=True
+;#PATCH_NAME=No Hardcoded Rocks
+;#PATCH_AUTHOR=Jared_Brian_
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Removes the 2 hardcoded rocks that get placed in area 33 and 2F.
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Remove rock in area 33.
+;#type=bool
+!RemoveRock1 = $01
+;#name=Remove rock in area 2F.
+;#type=bool
+!RemoveRock2 = $01
+;#DEFINE_END
+
+pushpc
+if !RemoveRock1 == 1
+    org $02EF33
+        NOP #4
+endif
+
+if !RemoveRock2 == 1
+    org $02EF3C
+        NOP #4
+endif
+pullpc

assets/patches/Misc/Rainstate Skip.asm

@@ -0,0 +1,51 @@
+;#ENABLED=True
+;#PATCH_NAME=Rainstate Skip
+;#PATCH_AUTHOR=Zarby89
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Skips over gamestates 0 and 1 (rain) straight to 2 (Zelda rescued)
+;Setting BedIntro to 00 will keep the opening bed sequence
+;#ENDPATCH_DESCRIPTION
+
+lorom
+
+;#DEFINE_START
+;#name=Remove bed intro
+;#type=bool
+!BedIntro = $00
+;#DEFINE_END
+
+if !BedIntro == 00
+
+	pushpc
+	org $828356
+	JSL NewIntroRain
+	pullpc
+
+	NewIntroRain:
+	LDA.l $7EF3C5 : BNE +
+	LDA.b #$02 : STA.l $7EF3C5 ; Set Game mode on 2
+
+	PHX
+
+	JSL $80FC62 ; Sprite_LoadGfxProperties.justLightWorld
+
+	PLX
+
+	LDA.b #$00 ; will take care of the bed intro wether we are in game rainstate or not
++	RTL
+
+else
+	pushpc
+	org $0CD8F6
+	JSL NewIntroRain
+
+	pullpc
+	NewIntroRain:
+	PHA
+	LDA.w #$1002
+	STA.l $7003C5, X
+	PLA
+	STA.l $7003D9, X
+	RTL
+endif

assets/patches/Misc/TorchTags.asm

@@ -0,0 +1,30 @@
+;#ENABLED=True
+;#PATCH_NAME=Torch Tags
+;#PATCH_AUTHOR=Jared_Brian_
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Changes the number of torches required to open doors and chests when using the "Light_Torches_to_Open" and "Light_Torches_to_get_Chest" tags.
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=torches required to make a chest appear.
+;#type=word
+;#range=$01,$08
+!ChestTorches =$01
+
+;#name=torches required to open a door.
+;#type=word
+;#range=$01,$08
+!DoorTorches =$08
+
+;#DEFINE_END
+
+pushpc
+; Changes the amount of torches required to make a chest appear.
+org $01C8CA
+    dw !ChestTorches
+
+; Changes the amount of torches required to open a door.
+org $01C645
+    dw !DoorTorches
+pullpc

assets/patches/Misc/Weathervane.asm

@@ -0,0 +1,153 @@
+;#ENABLED=True
+
+;=========================
+;TODO FINISH ADDING DEFINES
+;INCOMPLETE PATCH
+;==========================
+;#PATCH_NAME=Weathervane Position
+;#PATCH_AUTHOR=Jared_Brian_
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Modify the position of where you need to use the flute to destroy weathervane and spawn bird
+;#ENDPATCH_DESCRIPTION
+
+!AREAID = $34
+
+; Weather vane explosion changes:
+; Let the flute work in special areas.
+org $07A40A
+    NOP : NOP
+    
+org $07A418
+    JML NewVaneCheck
+
+org $07A441
+    VanePassed:
+
+org $07A44F
+    VaneFailed:
+
+org $07A453
+    SpawnBird:
+
+; Disable the area check for the weather vane sprite.
+org $06C2EB
+LDA $8A : CMP.b #!AREAID : BNE .outside_village
+    ; Check if we have the flute activated already:
+    LDA $7EF34C : CMP.b #$03 : BNE .player_lacks_bird_enabled_flute
+        STZ $0DD0, X
+        
+    .player_lacks_bird_enabled_flute
+        
+    RTS
+    
+.outside_village
+    
+; What to do in an area outside of the village:
+LDA $7EF34C : AND.b #$02 : BEQ .player_lacks_flute_completely
+    STZ $0DD0, X ; Suicide.
+.player_lacks_flute_completely
+RTS
+
+warnpc $06C309
+
+; Tile 1
+org $1BC226
+    dw $06CA
+
+; Tile 2
+org $1BC232
+    dw $06CE
+
+; Tile 3
+org $1BC243
+    dw #$074C
+
+; Bird coords
+org $098DC1
+    LDA.w #$08C8 : STA $00
+    LDA.w #$0460 : STA $02
+
+; Vane Debris coords
+org $098CED
+    .y_coords
+    db $F4, $E7, $E4, $E6, $E4, $EC, $E4, $E4, $EC, $E5, $F4, $E4
+    
+    .x_coords
+    db $7C, $5E, $6C, $60, $62, $64, $7C, $60, $64, $62, $60, $6C
+
+; Debris Y high byte
+org $098D65
+    db $08
+
+; Debris X high byte
+org $098D72
+    db $04
+
+pullpc ; Continue extended space.
+
+NewVaneCheck:
+{
+    REP #$20
+
+    ; Check if its the master sword area.
+    LDA $8A : CMP.w #!AREAID : BNE .not_weathervane_trigger2
+        LDA $20   
+        CMP.w #$0068 : BCC .not_weathervane_trigger1
+        CMP.w #$00A0 : BCS .not_weathervane_trigger1
+                
+        LDA $22
+        CMP.w #$0040 : BCC .not_weathervane_trigger1
+        CMP.w #$00A0 : BCS .not_weathervane_trigger1
+
+        SEP #$20
+        
+        ; Cancel other sounds
+        STZ $012E
+        STZ $012F
+
+        ; Stop player input
+        INC InCutScene
+
+        ; Trigger Zelda
+        INC $0642
+
+        JML VaneFailed
+
+    .not_weathervane_trigger2
+
+    SEP #$20
+
+    ; Check if we already have the bird.
+    LDA $7EF34C : CMP.b #$02 : BNE .travel_bird_not_already_released
+        REP #$20
+
+        ; Check the area for #$22.
+        LDA $8A : CMP.w #$0022 : BNE .not_weathervane_trigger1
+            LDA $20   
+            CMP.w #$0900 : BCC .not_weathervane_trigger1
+            CMP.w #$0920 : BCS .not_weathervane_trigger1
+                
+            LDA $22
+            CMP.w #$0450 : BCC .not_weathervane_trigger1
+            CMP.w #$0470 : BCS .not_weathervane_trigger1
+                SEP #$20
+                LDA $7EF2A2 : ORA.b #$20 : STA $7EF2A2
+                REP #$20
+
+                STZ FluteIndex
+
+                JML VanePassed
+
+        .not_weathervane_trigger1
+
+        JML VaneFailed
+
+    .travel_bird_not_already_released
+
+    JML SpawnBird
+}
+
+pushpc ; Pause expanded space.
+
+; ==============================================================================

assets/patches/Music/LostWoodsExitMusic.asm

@@ -0,0 +1,22 @@
+;#ENABLED=True
+
+;#PATCH_NAME=Lost Woods Exit Music
+;#PATCH_AUTHOR=Jared_Brian_
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Changes the room that plays the lost woods theme when exiting. Note: This only works for the first byte, so if you want to play music when leaving room 13, this will also cause room 113 to play the music. In vanilla this is used for room E1 Cave (Lost Woods HP).
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=The room number.
+;#type=byte
+!MusicRoomNumber = $E1
+
+;#DEFINE_END
+
+pushpc
+
+org $02844F
+    db !MusicRoomNumber
+
+pullpc

assets/patches/Npcs/Bottle Vendor.asm

@@ -0,0 +1,29 @@
+;#ENABLED=True
+;#PATCH_NAME=Bottle Vendor
+;#PATCH_AUTHOR=Zarby89
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Modify the item and price of sold by the Kakariko bottle vendor
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Item Price
+;#type=word
+;#decimal=true
+!ItemPrice = 100
+
+;#name=Item ID
+;#type=item
+!ItemID = $16
+;#DEFINE_END
+
+pushpc
+org $05EAF9
+	dw !BottlePrice
+
+org $05EB34
+	dw !BottlePrice
+
+org $05EB18
+	db !ItemID
+pullpc

assets/patches/Overworld/TailMapExpansion.asm

@@ -0,0 +1,153 @@
+;#ENABLED=false
+
+;#PATCH_NAME=Overworld Tail Map Expansion
+;#PATCH_AUTHOR=yaze
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Expands the overworld pointer tables from 160 to 192 entries,
+;enabling support for Special World tail maps (0xA0-0xBF).
+;
+;IMPORTANT: This patch MUST be applied AFTER ZSCustomOverworld v3.
+;If applied manually via Asar:
+;  1. First apply ZSCustomOverworld v3 patch to your ROM
+;  2. Then apply this patch: asar TailMapExpansion.asm your_rom.sfc
+;
+;If applied via yaze CLI:
+;  z3ed overworld-doctor --rom=your_rom.sfc --apply-tail-expansion
+;
+;Technical details:
+;  - Relocates Map32 pointer tables from $02:F94D to $28:A400
+;  - Adds 32 blank entries for maps 0xA0-0xBF pointing to $30:8000
+;  - Patches 8 code locations in bank $02 to use new table addresses
+;  - Writes detection marker 0xEA at $28:A3FF
+;#ENDPATCH_DESCRIPTION
+
+lorom
+
+;==============================================================================
+; Constants
+;==============================================================================
+!OldHighTable = $02F94D         ; Vanilla high pointer table (160 entries)
+!OldLowTable = $02FB2D          ; Vanilla low pointer table (160 entries)
+!NewHighTable = $28A400         ; New high pointer table (192 entries)
+!NewLowTable = $28A640          ; New low pointer table (192 entries)
+!BlankMapHigh = $308000         ; Blank map data for tail maps (high bytes)
+!BlankMapLow = $309000          ; Blank map data for tail maps (low bytes)
+!MarkerAddr = $28A3FF           ; Detection marker location
+!MarkerValue = $EA              ; Detection marker value (NOP opcode = "expanded")
+
+;==============================================================================
+; PC address macros (for read3 function)
+;==============================================================================
+; LoROM: PC = (bank * $8000) + (addr - $8000)
+; $02F94D -> PC = (2 * $8000) + ($F94D - $8000) = $10000 + $794D = $1794D
+!OldHighTablePC = $01794D
+!OldLowTablePC = $017B2D
+
+;==============================================================================
+; Detection marker - allows yaze to detect expanded tables
+;==============================================================================
+org !MarkerAddr
+    db !MarkerValue
+
+;==============================================================================
+; Blank map data for tail maps (0xA0-0xBF)
+; Located in safe free space at bank $30
+;==============================================================================
+org !BlankMapHigh               ; PC $180000
+BlankMap32High:
+    fillbyte $00
+    fill 188                    ; 0xBC bytes - compressed blank map32 high data
+
+org !BlankMapLow                ; PC $181000
+BlankMap32Low:
+    fillbyte $00
+    fill 4                      ; 0x04 bytes - compressed blank map32 low data
+
+;==============================================================================
+; New expanded High pointer table (192 entries x 3 bytes = 576 bytes)
+; Copies existing 160 entries, adds 32 blank entries for tail maps
+;==============================================================================
+org !NewHighTable               ; PC $142400
+ExpandedMap32HPointers:
+    ; Copy 160 vanilla entries (preserves any ZSCustomOverworld modifications)
+    ; Using Asar's read1() to copy bytes from current ROM state
+    !n = 0
+    while !n < 160
+        db read1(!OldHighTablePC+(!n*3)+0)
+        db read1(!OldHighTablePC+(!n*3)+1)
+        db read1(!OldHighTablePC+(!n*3)+2)
+        !n #= !n+1
+    endwhile
+
+    ; Add 32 blank entries for tail maps (0xA0-0xBF)
+    ; Each entry is a 24-bit pointer to BlankMap32High ($30:8000)
+    !n = 0
+    while !n < 32
+        dl BlankMap32High
+        !n #= !n+1
+    endwhile
+
+;==============================================================================
+; New expanded Low pointer table (192 entries x 3 bytes = 576 bytes)
+;==============================================================================
+org !NewLowTable                ; PC $142640
+ExpandedMap32LPointers:
+    ; Copy 160 vanilla entries (preserves any ZSCustomOverworld modifications)
+    !n = 0
+    while !n < 160
+        db read1(!OldLowTablePC+(!n*3)+0)
+        db read1(!OldLowTablePC+(!n*3)+1)
+        db read1(!OldLowTablePC+(!n*3)+2)
+        !n #= !n+1
+    endwhile
+
+    ; Add 32 blank entries for tail maps (0xA0-0xBF)
+    !n = 0
+    while !n < 32
+        dl BlankMap32Low
+        !n #= !n+1
+    endwhile
+
+;==============================================================================
+; Patch game code to use new pointer tables
+; Each LDA.l instruction is 4 bytes: AF xx xx xx (opcode + 24-bit address)
+; We patch the 3 address bytes to point to the new tables
+;==============================================================================
+
+; Function 1: Overworld_DecompressAndDrawOneQuadrant
+; Original at PC $1F59D: LDA.l $02F94D,X -> LDA.l $28A400,X
+org $02F59E                     ; Address bytes of instruction at $02F59D
+    dl ExpandedMap32HPointers   ; New high table address
+
+org $02F5A4                     ; Address bytes for +1 offset access
+    dl ExpandedMap32HPointers+1
+
+; Original at PC $1F5C8: LDA.l $02FB2D,X -> LDA.l $28A640,X
+org $02F5C9                     ; Address bytes of instruction at $02F5C8
+    dl ExpandedMap32LPointers   ; New low table address
+
+org $02F5CF                     ; Address bytes for +1 offset access
+    dl ExpandedMap32LPointers+1
+
+; Function 2: Secondary quadrant loader (parallel decompression path)
+org $02F7E4
+    dl ExpandedMap32HPointers
+
+org $02F7EA
+    dl ExpandedMap32HPointers+1
+
+org $02F80F
+    dl ExpandedMap32LPointers
+
+org $02F815
+    dl ExpandedMap32LPointers+1
+
+;==============================================================================
+; End of patch
+;==============================================================================
+print "Tail Map Expansion patch applied successfully."
+print "- New High Table: $28:A400 (192 entries)"
+print "- New Low Table: $28:A640 (192 entries)"
+print "- Blank Map Data: $30:8000, $30:9000"
+print "- Detection Marker: $28:A3FF = $EA"

assets/patches/Sprites/Crystalswitch Conveyor.asm

@@ -0,0 +1,19 @@
+;#ENABLED=True
+;#PATCH_NAME=Crystal Switch Conveyor
+;#PATCH_AUTHOR=Zarby89
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Causes crystal switches to be moved by conveyors
+;#ENDPATCH_DESCRIPTION
+lorom
+
+pushpc
+org $06B8D0
+JSL ConveyorSwitch
+NOP
+pullpc
+
+ConveyorSwitch:
+JSL $06E496 ; Sprite_CheckTileCollisionLong
+LDA.w $0F50, X : AND.b #$F1
+RTL

assets/patches/Sprites/Elemental Trinexx.asm

@@ -0,0 +1,95 @@
+;#ENABLED=True
+;#PATCH_NAME=Elemental Trinexx
+;#PATCH_AUTHOR=Jared_Brian_
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Changes Trinexx's side heads to be both ice heads, both fire heads, or swapped.
+;The heads will shoot the corrisponding beams and will also appear the correct color.
+;The main head will appear the elemental color if you set that option but otherwise will be the default palette.
+;You will still need to set the side heads to take damage from the appropriate elemental rod with the advanced damage editor.
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Changes the arrangement of side heads.
+;#type=choice
+;#choice0=Inverted Heads
+;#choice1=Ice Heads Only
+;#choice2=Fire Heads Only
+!ElementType = $00
+
+;#name=Changes the main head palette.
+;#type=choice
+;#choice0=Default Palette
+;#choice1=Ice Palette
+;#choice2=Fire Palette
+!MainHeadPalette = $00
+;#DEFINE_END
+
+pushpc
+
+if !ElementType == 0
+    ; Change the palettes of the side heads to the inverted palette.
+    org $0DB425
+        db $0D, $0B
+
+    ; Swap which head shows the apropriate particales when charging up.
+    org $1DBAD9
+        db $F0 ; Replace a BNE with a BEQ.
+
+    ; Swap which head shoots what beam.
+    org $1DBAE8
+        LDA $0E20, X : CMP.b #$CC
+
+    ; Another beam related thing.
+    org $1DBAF8
+        LDA.b #$CC
+
+elseif !ElementType == 1
+    ; Change the palettes of the side heads to the ice palette.
+    org $0DB425
+        db $0D, $0D 
+
+    ; Make the fire head show ice spakles when charging up.
+    org $1DBAD9
+        db $80 ; Replace a BNE with a BRA.
+
+    ; Make the fire head shoot ice instead of fire.
+    org $1DBAE8
+        LDA.b #$CD : NOP #5
+
+elseif !ElementType == 2
+    ; Change the palettes of the side heads to the fire palette.
+    org $0DB425
+        db $0B, $0B 
+
+    ; Make the ice head show flames when charging up.
+    org $1DBAD9
+        NOP : NOP ; Remove the BNE and never branch.
+
+    ; Make the ice head shoot fire instead of ice.
+    org $1DBAE8
+        LDA.b #$CC : NOP : NOP : NOP
+        db $80 ; Replace a BNE with a BRA.
+
+endif
+
+if !MainHeadPalette == 1
+    ; Change the palette of all the main head to the ice.
+    org $0DB424
+        db $4D
+
+    ; Change the snake trinexx palette to ice.
+    org $1DB033
+        db $0D
+
+elseif !MainHeadPalette == 2
+    ; Change the palette of all the main head to the fire.
+    org $0DB424
+        db $4B
+
+    ; Change the snake trinexx palette to fire.
+    org $1DB033
+        db $0B
+endif
+
+pullpc

assets/patches/Sprites/Eye Lasers Active.asm

@@ -0,0 +1,43 @@
+;#PATCH_NAME=Eye Lasers Active
+;#PATCH_AUTHOR=Jared_Brian_
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Changes the wall eye lasers to always be active or always inactive reguardless of what X position they are placed on.
+;Normally in vanilla every other X position is set to be inactive unless link is looking directly at them.
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Active?
+;#type=bool
+!EyeActive = $00
+;#DEFINE_END
+
+pushpc
+
+if !EyeActive == $00
+    ; Make it so the eye lazers are always inactive reguardless of what X position they are placed on.
+    org $1EA50B
+        ; Replaced code: 
+        ; LDA $0D10, X : AND.b #$10 : EOR.b #$10 : STA !requires_facing, X
+        NOP #5 : LDA.b #$00 : STA $0EB0, X
+
+    org $1EA52C
+        ; Replace code:
+        ; LDA $0D00, X : AND.b #$10 : STA !requires_facing, X
+        NOP #3 : LDA.b #$00 : STA $0EB0, X
+
+elseif !EyeActive == $01
+    ; Make it so the eye lazers are always active reguardless of what X position they are placed on.
+    org $1EA50B
+        ; Replaced code: 
+        ; LDA $0D10, X : AND.b #$10 : EOR.b #$10 : STA !requires_facing, X
+        NOP #5 : LDA.b #$01 : STA $0EB0, X
+
+    org $1EA52C
+        ; Replace code:
+        ; LDA $0D00, X : AND.b #$10 : STA !requires_facing, X
+        NOP #3 : LDA.b #$01 : STA $0EB0, X
+
+endif
+
+pullpc

assets/patches/Sprites/Khodstare Speeds.asm

@@ -0,0 +1,56 @@
+;#ENABLED=True
+;#PATCH_NAME=Kholdstare Speeds
+;#PATCH_AUTHOR=Jared_Brian_
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Changes the speeds at which kholdstare can move.
+;By default he will move the same speed on the x and y axis in all 4 diagonal directions.
+;Values above 0x80 are negative.
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=X Value 1
+;#type=byte
+!XValue1 = $0010
+
+;#name=X Value 2
+;#type=byte
+!XValue2 = $0010
+
+;#name=X Value 3
+;#type=byte
+!XValue3 = $00F0
+
+;#name=X Value 4
+;#type=byte
+!XValue4 = $00F0
+
+;#name=Y Value 1
+;#type=byte
+!YValue1 = $00F0
+
+;#name=Y Value 2
+;#type=byte
+!YValue2 = $0010
+
+;#name=Y Value 3
+;#type=byte
+!YValue3 = $0010
+
+;#name=Y Value 4
+;#type=byte
+!YValue4 = $00F0
+
+;#DEFINE_END
+
+pushpc
+
+; Speed chagnes.
+org $1E95DD
+    .x_speed_limits
+    db !XValue1, !XValue2, !XValue3, !XValue4
+    
+    .y_speed_limits
+    db !YValue1, !YValue2, !YValue3, !YValue4
+
+pullpc

assets/patches/Sprites/Spike Damage.asm

@@ -0,0 +1,24 @@
+;#ENABLED=True
+;#PATCH_NAME=Spike damage
+;#PATCH_AUTHOR=kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Allows mail upgrades to reduce sprite damage
+;$08 = 1 heart, $04 = half heart, $10 = 2 heart, etc...
+;#ENDPATCH_DESCRIPTION
+
+;#DEFINE_START
+;#name=Green Mail Damage
+!GreenMailDamage = $08
+;#name=Blue Mail Damage
+!BlueMailDamage = $08
+;#name=Red Mail Damage
+!RedMailDamage = $08
+;#DEFINE_END
+
+pushpc
+org $07BA07
+	db !GreenMailDamage
+	db !BlueMailDamage
+	db !RedMailDamage
+pullpc

assets/patches/Sprites/Spikes_Subtype.asm

@@ -0,0 +1,52 @@
+;#ENABLED=True
+
+;#PATCH_NAME=More spike directions
+;#PATCH_AUTHOR=Zarby89,kan
+;#PATCH_VERSION=1.0
+;#PATCH_DESCRIPTION
+;Allows more spike blocks Subtype (sprite property)
+;Default Values : (00) = normal, (08) = normal vertical
+;Values, ascending by speed
+;00,01,02,03,04,05,06 = Horizontal
+;08,09,0A,0B,0C,0D,0E = Vertical
+;#ENDPATCH_DESCRIPTION
+lorom
+
+pushpc
+org $0691D7 ; SpritePrep_SpikeBlock:
+	JSL NewSpikePrep
+	RTS
+
+org $1EBD0E
+	JSL NewSpikeCollision
+	RTS
+pullpc
+
+speedValuesH:
+db $20, $10, $18, $28, $30, $38, $40, $FF
+db $00, $00, $00, $00, $00, $00, $00, $FF
+
+speedValuesV:
+db $00, $00, $00, $00, $00, $00, $00, $FF
+db $20, $18, $20, $28, $30, $38, $40, $FF
+
+NewSpikePrep:
+	TXY
+
+	LDX.w $0E30,Y
+
+	LDA.l speedValuesH,X : STA.w $0D50,Y
+	LDA.l speedValuesV,X : STA.w $0D40,Y
+
+	TYX
+	RTL
+
+NewSpikeCollision:
+	LDA.b #$04 : STA.w $0DF0, X
+
+	LDA.w $0D50, X : EOR.b #$FF : INC A : STA.w $0D50, X
+	LDA.w $0D40, X : EOR.b #$FF : INC A : STA.w $0D40, X
+
+	LDA.b #$05 : JSL $0DBB7C ; Sound_SetSfx2PanLong
+
+	RTL

assets/patches/Version.txt

@@ -0,0 +1 @@
+0000

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,52 @@
+# 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
+if(NOT DEFINED CPM_USE_LOCAL_PACKAGES)
+  set(CPM_USE_LOCAL_PACKAGES OFF)
+endif()
+if(NOT DEFINED CPM_LOCAL_PACKAGES_ONLY)
+  set(CPM_LOCAL_PACKAGES_ONLY OFF)
+endif()
+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/TestInfrastructure.cmake

@@ -0,0 +1,490 @@
+# TestInfrastructure.cmake
+# Advanced test infrastructure configuration for yaze project
+# Provides optimized test builds, parallel execution, and smart test selection
+
+include(GoogleTest)
+include(CTest)
+
+# =============================================================================
+# Test Configuration Options
+# =============================================================================
+
+option(YAZE_TEST_PARALLEL "Enable parallel test execution" ON)
+option(YAZE_TEST_COVERAGE "Enable code coverage collection" OFF)
+option(YAZE_TEST_SANITIZERS "Enable address and undefined behavior sanitizers" OFF)
+option(YAZE_TEST_PROFILE "Enable test profiling" OFF)
+option(YAZE_TEST_MINIMAL_DEPS "Use minimal dependencies for faster test builds" OFF)
+option(YAZE_TEST_PCH "Use precompiled headers for tests" ON)
+
+# Test categories
+option(YAZE_TEST_SMOKE "Build smoke tests (critical path)" ON)
+option(YAZE_TEST_UNIT "Build unit tests" ON)
+option(YAZE_TEST_INTEGRATION "Build integration tests" ON)
+option(YAZE_TEST_E2E "Build end-to-end GUI tests" OFF)
+option(YAZE_TEST_BENCHMARK "Build performance benchmarks" OFF)
+option(YAZE_TEST_FUZZ "Build fuzzing tests" OFF)
+
+# Test execution settings
+set(YAZE_TEST_TIMEOUT_SMOKE 30 CACHE STRING "Timeout for smoke tests (seconds)")
+set(YAZE_TEST_TIMEOUT_UNIT 60 CACHE STRING "Timeout for unit tests (seconds)")
+set(YAZE_TEST_TIMEOUT_INTEGRATION 300 CACHE STRING "Timeout for integration tests (seconds)")
+set(YAZE_TEST_TIMEOUT_E2E 600 CACHE STRING "Timeout for E2E tests (seconds)")
+
+# =============================================================================
+# Precompiled Headers Configuration
+# =============================================================================
+
+if(YAZE_TEST_PCH)
+  set(YAZE_TEST_PCH_HEADERS
+    <gtest/gtest.h>
+    <gmock/gmock.h>
+    <absl/status/status.h>
+    <absl/status/statusor.h>
+    <absl/strings/string_view.h>
+    <memory>
+    <vector>
+    <string>
+    <unordered_map>
+  )
+
+  # Create PCH target
+  add_library(yaze_test_pch INTERFACE)
+  target_precompile_headers(yaze_test_pch INTERFACE ${YAZE_TEST_PCH_HEADERS})
+
+  message(STATUS "Test Infrastructure: Precompiled headers enabled")
+endif()
+
+# =============================================================================
+# Test Interface Library
+# =============================================================================
+
+add_library(yaze_test_interface INTERFACE)
+
+# Common compile options
+target_compile_options(yaze_test_interface INTERFACE
+  $<$<CONFIG:Debug>:-O0 -g3>
+  $<$<CONFIG:Release>:-O3 -DNDEBUG>
+  $<$<CONFIG:RelWithDebInfo>:-O2 -g>
+  $<$<BOOL:${YAZE_TEST_COVERAGE}>:--coverage -fprofile-arcs -ftest-coverage>
+  $<$<BOOL:${YAZE_TEST_PROFILE}>:-pg>
+)
+
+# Common link options
+target_link_options(yaze_test_interface INTERFACE
+  $<$<BOOL:${YAZE_TEST_COVERAGE}>:--coverage>
+  $<$<BOOL:${YAZE_TEST_PROFILE}>:-pg>
+)
+
+# Sanitizers
+if(YAZE_TEST_SANITIZERS)
+  target_compile_options(yaze_test_interface INTERFACE
+    -fsanitize=address,undefined
+    -fno-omit-frame-pointer
+    -fno-optimize-sibling-calls
+  )
+  target_link_options(yaze_test_interface INTERFACE
+    -fsanitize=address,undefined
+  )
+
+  message(STATUS "Test Infrastructure: Sanitizers enabled (ASan + UBSan)")
+endif()
+
+# Coverage
+if(YAZE_TEST_COVERAGE)
+  find_program(LCOV lcov)
+  find_program(GENHTML genhtml)
+
+  if(LCOV AND GENHTML)
+    add_custom_target(coverage
+      COMMAND ${LCOV} --capture --directory ${CMAKE_BINARY_DIR}
+              --output-file ${CMAKE_BINARY_DIR}/coverage.info
+              --ignore-errors source
+      COMMAND ${LCOV} --remove ${CMAKE_BINARY_DIR}/coverage.info
+              '*/test/*' '*/ext/*' '/usr/*' '*/build/*'
+              --output-file ${CMAKE_BINARY_DIR}/coverage_filtered.info
+      COMMAND ${GENHTML} ${CMAKE_BINARY_DIR}/coverage_filtered.info
+              --output-directory ${CMAKE_BINARY_DIR}/coverage_html
+      WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+      COMMENT "Generating code coverage report"
+    )
+
+    message(STATUS "Test Infrastructure: Coverage target available")
+  else()
+    message(WARNING "lcov/genhtml not found, coverage target disabled")
+  endif()
+endif()
+
+# =============================================================================
+# Test Creation Function
+# =============================================================================
+
+function(yaze_create_test_suite)
+  set(options GUI_TEST REQUIRES_ROM USE_PCH)
+  set(oneValueArgs NAME CATEGORY TIMEOUT PARALLEL_JOBS OUTPUT_DIR)
+  set(multiValueArgs SOURCES DEPENDENCIES LABELS COMPILE_DEFINITIONS)
+  cmake_parse_arguments(TEST "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+  # Validate required arguments
+  if(NOT TEST_NAME)
+    message(FATAL_ERROR "yaze_create_test_suite: NAME is required")
+  endif()
+  if(NOT TEST_SOURCES)
+    message(FATAL_ERROR "yaze_create_test_suite: SOURCES is required")
+  endif()
+
+  # Set defaults
+  if(NOT TEST_CATEGORY)
+    set(TEST_CATEGORY "general")
+  endif()
+  if(NOT TEST_TIMEOUT)
+    set(TEST_TIMEOUT 60)
+  endif()
+  if(NOT TEST_OUTPUT_DIR)
+    set(TEST_OUTPUT_DIR "${CMAKE_BINARY_DIR}/bin/test")
+  endif()
+
+  # Create test executable
+  set(target_name yaze_test_${TEST_NAME})
+  add_executable(${target_name} ${TEST_SOURCES})
+
+  # Set output directory
+  set_target_properties(${target_name} PROPERTIES
+    RUNTIME_OUTPUT_DIRECTORY "${TEST_OUTPUT_DIR}"
+    RUNTIME_OUTPUT_DIRECTORY_DEBUG "${TEST_OUTPUT_DIR}"
+    RUNTIME_OUTPUT_DIRECTORY_RELEASE "${TEST_OUTPUT_DIR}"
+  )
+
+  # Link libraries
+  target_link_libraries(${target_name} PRIVATE
+    yaze_test_interface
+    yaze_test_support
+    GTest::gtest_main
+    GTest::gmock
+    ${TEST_DEPENDENCIES}
+  )
+
+  # Apply PCH if requested
+  if(TEST_USE_PCH AND TARGET yaze_test_pch)
+    target_link_libraries(${target_name} PRIVATE yaze_test_pch)
+    target_precompile_headers(${target_name} REUSE_FROM yaze_test_pch)
+  endif()
+
+  # Add compile definitions
+  if(TEST_COMPILE_DEFINITIONS)
+    target_compile_definitions(${target_name} PRIVATE ${TEST_COMPILE_DEFINITIONS})
+  endif()
+
+  # GUI test configuration
+  if(TEST_GUI_TEST)
+    target_compile_definitions(${target_name} PRIVATE
+      IMGUI_ENABLE_TEST_ENGINE=1
+      YAZE_GUI_TEST_TARGET=1
+    )
+    if(TARGET ImGuiTestEngine)
+      target_link_libraries(${target_name} PRIVATE ImGuiTestEngine)
+    endif()
+  endif()
+
+  # ROM test configuration
+  if(TEST_REQUIRES_ROM)
+    target_compile_definitions(${target_name} PRIVATE
+      YAZE_ROM_TEST=1
+    )
+  endif()
+
+  # Discover tests with CTest
+  set(test_labels "${TEST_CATEGORY}")
+  if(TEST_LABELS)
+    list(APPEND test_labels ${TEST_LABELS})
+  endif()
+
+  gtest_discover_tests(${target_name}
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+    PROPERTIES
+      LABELS "${test_labels}"
+      TIMEOUT ${TEST_TIMEOUT}
+    DISCOVERY_MODE PRE_TEST
+    DISCOVERY_TIMEOUT 30
+  )
+
+  # Set parallel execution if specified
+  if(TEST_PARALLEL_JOBS)
+    set_property(TEST ${target_name} PROPERTY PROCESSORS ${TEST_PARALLEL_JOBS})
+  endif()
+
+  # Create category-specific test target
+  add_custom_target(test-${TEST_CATEGORY}-${TEST_NAME}
+    COMMAND ${CMAKE_CTEST_COMMAND} -R "^${target_name}" --output-on-failure
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+    COMMENT "Running ${TEST_CATEGORY} tests: ${TEST_NAME}"
+  )
+
+  message(STATUS "Test Suite: ${target_name} (${TEST_CATEGORY})")
+endfunction()
+
+# =============================================================================
+# Test Suites Configuration
+# =============================================================================
+
+# Smoke Tests (Critical Path)
+if(YAZE_TEST_SMOKE)
+  file(GLOB SMOKE_TEST_SOURCES
+    ${CMAKE_SOURCE_DIR}/test/smoke/*.cc
+    ${CMAKE_SOURCE_DIR}/test/smoke/*.h
+  )
+
+  if(SMOKE_TEST_SOURCES)
+    yaze_create_test_suite(
+      NAME smoke
+      CATEGORY smoke
+      SOURCES ${SMOKE_TEST_SOURCES}
+      LABELS critical fast ci-stage1
+      TIMEOUT ${YAZE_TEST_TIMEOUT_SMOKE}
+      USE_PCH
+    )
+  else()
+    message(WARNING "No smoke test sources found")
+  endif()
+endif()
+
+# Unit Tests
+if(YAZE_TEST_UNIT)
+  file(GLOB_RECURSE UNIT_TEST_SOURCES
+    ${CMAKE_SOURCE_DIR}/test/unit/*.cc
+  )
+
+  if(UNIT_TEST_SOURCES)
+    # Split unit tests into multiple binaries for parallel execution
+    list(LENGTH UNIT_TEST_SOURCES num_unit_tests)
+
+    if(num_unit_tests GREATER 50)
+      # Create sharded unit test executables
+      set(shard_size 25)
+      math(EXPR num_shards "(${num_unit_tests} + ${shard_size} - 1) / ${shard_size}")
+
+      foreach(shard RANGE 1 ${num_shards})
+        math(EXPR start "(${shard} - 1) * ${shard_size}")
+        math(EXPR end "${shard} * ${shard_size} - 1")
+
+        if(end GREATER ${num_unit_tests})
+          set(end ${num_unit_tests})
+        endif()
+
+        list(SUBLIST UNIT_TEST_SOURCES ${start} ${shard_size} shard_sources)
+
+        yaze_create_test_suite(
+          NAME unit_shard${shard}
+          CATEGORY unit
+          SOURCES ${shard_sources}
+          LABELS unit fast ci-stage2 shard${shard}
+          TIMEOUT ${YAZE_TEST_TIMEOUT_UNIT}
+          USE_PCH
+        )
+      endforeach()
+    else()
+      # Single unit test executable
+      yaze_create_test_suite(
+        NAME unit
+        CATEGORY unit
+        SOURCES ${UNIT_TEST_SOURCES}
+        LABELS unit fast ci-stage2
+        TIMEOUT ${YAZE_TEST_TIMEOUT_UNIT}
+        USE_PCH
+      )
+    endif()
+  endif()
+endif()
+
+# Integration Tests
+if(YAZE_TEST_INTEGRATION)
+  file(GLOB_RECURSE INTEGRATION_TEST_SOURCES
+    ${CMAKE_SOURCE_DIR}/test/integration/*.cc
+  )
+
+  if(INTEGRATION_TEST_SOURCES)
+    yaze_create_test_suite(
+      NAME integration
+      CATEGORY integration
+      SOURCES ${INTEGRATION_TEST_SOURCES}
+      LABELS integration medium ci-stage3
+      TIMEOUT ${YAZE_TEST_TIMEOUT_INTEGRATION}
+      PARALLEL_JOBS 2
+      USE_PCH
+    )
+  endif()
+endif()
+
+# E2E Tests
+if(YAZE_TEST_E2E)
+  file(GLOB_RECURSE E2E_TEST_SOURCES
+    ${CMAKE_SOURCE_DIR}/test/e2e/*.cc
+  )
+
+  if(E2E_TEST_SOURCES)
+    yaze_create_test_suite(
+      NAME e2e
+      CATEGORY e2e
+      SOURCES ${E2E_TEST_SOURCES}
+      LABELS e2e slow gui ci-stage3
+      TIMEOUT ${YAZE_TEST_TIMEOUT_E2E}
+      GUI_TEST
+      USE_PCH
+    )
+  endif()
+endif()
+
+# Benchmark Tests
+if(YAZE_TEST_BENCHMARK)
+  file(GLOB_RECURSE BENCHMARK_TEST_SOURCES
+    ${CMAKE_SOURCE_DIR}/test/benchmarks/*.cc
+  )
+
+  if(BENCHMARK_TEST_SOURCES)
+    yaze_create_test_suite(
+      NAME benchmark
+      CATEGORY benchmark
+      SOURCES ${BENCHMARK_TEST_SOURCES}
+      LABELS benchmark performance nightly
+      TIMEOUT 1800
+      COMPILE_DEFINITIONS BENCHMARK_BUILD=1
+    )
+  endif()
+endif()
+
+# =============================================================================
+# Custom Test Commands
+# =============================================================================
+
+# Run all fast tests
+add_custom_target(test-fast
+  COMMAND ${CMAKE_CTEST_COMMAND} -L "fast" --parallel ${CMAKE_NUMBER_OF_CORES} --output-on-failure
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Running fast tests"
+)
+
+# Run tests by stage
+add_custom_target(test-stage1
+  COMMAND ${CMAKE_CTEST_COMMAND} -L "ci-stage1" --parallel 4 --output-on-failure
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Running Stage 1 (Smoke) tests"
+)
+
+add_custom_target(test-stage2
+  COMMAND ${CMAKE_CTEST_COMMAND} -L "ci-stage2" --parallel ${CMAKE_NUMBER_OF_CORES} --output-on-failure
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Running Stage 2 (Unit) tests"
+)
+
+add_custom_target(test-stage3
+  COMMAND ${CMAKE_CTEST_COMMAND} -L "ci-stage3" --parallel 2 --output-on-failure
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Running Stage 3 (Integration/E2E) tests"
+)
+
+# Smart test selection based on changed files
+add_custom_target(test-changed
+  COMMAND ${CMAKE_COMMAND} -E env python3 ${CMAKE_SOURCE_DIR}/scripts/smart_test_selector.py
+          --output filter | xargs ${CMAKE_CTEST_COMMAND} -R --output-on-failure
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Running tests for changed files"
+)
+
+# Parallel test execution with sharding
+add_custom_target(test-parallel
+  COMMAND python3 ${CMAKE_SOURCE_DIR}/scripts/test_runner.py
+          ${CMAKE_BINARY_DIR}/bin/test/yaze_test_unit
+          --shards ${CMAKE_NUMBER_OF_CORES}
+          --output-dir ${CMAKE_BINARY_DIR}/test_results
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Running tests with parallel sharding"
+)
+
+# Test with retries for flaky tests
+add_custom_target(test-retry
+  COMMAND python3 ${CMAKE_SOURCE_DIR}/scripts/test_runner.py
+          ${CMAKE_BINARY_DIR}/bin/test/yaze_test_unit
+          --retry 2
+          --output-dir ${CMAKE_BINARY_DIR}/test_results
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Running tests with retry for failures"
+)
+
+# =============================================================================
+# CTest Configuration
+# =============================================================================
+
+set(CTEST_PARALLEL_LEVEL ${CMAKE_NUMBER_OF_CORES} CACHE STRING "Default parallel level for CTest")
+set(CTEST_OUTPUT_ON_FAILURE ON CACHE BOOL "Show output on test failure")
+set(CTEST_PROGRESS_OUTPUT ON CACHE BOOL "Show progress during test execution")
+
+# Configure test output
+set(CMAKE_CTEST_ARGUMENTS
+  --output-on-failure
+  --progress
+  --parallel ${CTEST_PARALLEL_LEVEL}
+)
+
+# Configure test timeout multiplier for slower systems
+if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
+  set(CTEST_TEST_TIMEOUT_MULTIPLIER 1.5)
+endif()
+
+# =============================================================================
+# Test Data Management
+# =============================================================================
+
+# Download test data if needed
+if(YAZE_TEST_INTEGRATION OR YAZE_TEST_E2E)
+  include(FetchContent)
+
+  # Check if test data exists
+  if(NOT EXISTS "${CMAKE_BINARY_DIR}/test_data/VERSION")
+    message(STATUS "Downloading test data...")
+
+    FetchContent_Declare(
+      yaze_test_data
+      URL https://github.com/yaze/test-data/archive/refs/tags/v1.0.0.tar.gz
+      URL_HASH SHA256=abcdef1234567890  # Replace with actual hash
+      DOWNLOAD_EXTRACT_TIMESTAMP ON
+    )
+
+    FetchContent_MakeAvailable(yaze_test_data)
+
+    set(YAZE_TEST_DATA_DIR ${yaze_test_data_SOURCE_DIR} CACHE PATH "Test data directory")
+  else()
+    set(YAZE_TEST_DATA_DIR ${CMAKE_BINARY_DIR}/test_data CACHE PATH "Test data directory")
+  endif()
+endif()
+
+# =============================================================================
+# Test Report Generation
+# =============================================================================
+
+add_custom_target(test-report
+  COMMAND python3 ${CMAKE_SOURCE_DIR}/scripts/aggregate_test_results.py
+          --input-dir ${CMAKE_BINARY_DIR}/Testing
+          --output ${CMAKE_BINARY_DIR}/test_report.json
+          --generate-html ${CMAKE_BINARY_DIR}/test_report.html
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Generating test report"
+  DEPENDS test-all
+)
+
+# =============================================================================
+# Summary Message
+# =============================================================================
+
+message(STATUS "========================================")
+message(STATUS "Test Infrastructure Configuration:")
+message(STATUS "  Parallel Testing: ${YAZE_TEST_PARALLEL}")
+message(STATUS "  Precompiled Headers: ${YAZE_TEST_PCH}")
+message(STATUS "  Code Coverage: ${YAZE_TEST_COVERAGE}")
+message(STATUS "  Sanitizers: ${YAZE_TEST_SANITIZERS}")
+message(STATUS "  Test Categories:")
+message(STATUS "    Smoke Tests: ${YAZE_TEST_SMOKE}")
+message(STATUS "    Unit Tests: ${YAZE_TEST_UNIT}")
+message(STATUS "    Integration Tests: ${YAZE_TEST_INTEGRATION}")
+message(STATUS "    E2E Tests: ${YAZE_TEST_E2E}")
+message(STATUS "    Benchmarks: ${YAZE_TEST_BENCHMARK}")
+message(STATUS "  Parallel Level: ${CTEST_PARALLEL_LEVEL}")
+message(STATUS "========================================")

cmake/absl.cmake

@@ -1,24 +1,145 @@
-if (MINGW)
+# Abseil release to use when fetching from source
-  add_subdirectory(src/lib/abseil-cpp)
+set(YAZE_ABSL_GIT_TAG "20240116.2" CACHE STRING "Abseil release tag used when fetching from source")
-else()
+
-find_package(absl)
+# Attempt to use the system package unless the build explicitly requests the
+# bundled (fetched) copy or we're on platforms where prebuilt packages are often
+# missing the required components (e.g. macOS).
+set(_yaze_use_fetched_absl ${YAZE_FORCE_BUNDLED_ABSL})
+if(NOT _yaze_use_fetched_absl)
+  # Try to find via vcpkg first on Windows
+  if(WIN32 AND DEFINED CMAKE_TOOLCHAIN_FILE)
+    find_package(absl CONFIG QUIET)
+  else()
+    find_package(absl QUIET CONFIG)
+  endif()
+  
+  if(absl_FOUND)
+    message(STATUS "✓ Using system/vcpkg Abseil package")
+  else()
+    set(_yaze_use_fetched_absl TRUE)
+    message(STATUS "○ System Abseil not found. Will fetch release ${YAZE_ABSL_GIT_TAG}")
+  endif()
 endif()
-set(ABSL_PROPAGATE_CXX_STD ON)
+
-set(ABSL_CXX_STANDARD 17)
+if(_yaze_use_fetched_absl)
-set(ABSL_USE_GOOGLETEST_HEAD ON)
+  include(FetchContent)
-set(ABSL_ENABLE_INSTALL ON)
+  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_TARGETS
-  absl::strings
-  absl::flags
-  absl::status
-  absl::statusor
-  absl::examine_stack
-  absl::stacktrace
   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()
+
+set(_yaze_absl_arm64 FALSE)
+if(APPLE)
+  if(CMAKE_OSX_ARCHITECTURES STREQUAL "arm64")
+    set(_yaze_absl_arm64 TRUE)
+  elseif(CMAKE_OSX_ARCHITECTURES STREQUAL "" AND CMAKE_SYSTEM_PROCESSOR MATCHES "arm64|aarch64")
+    # Homebrew LLVM doesn't honor -Xarch_x86_64; strip x86 flags on arm64-only builds.
+    set(_yaze_absl_arm64 TRUE)
+  endif()
+endif()
+
+if(_yaze_absl_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,39 +1,106 @@
-# Asar Assembler for 65816 SNES Assembly
+# Modern Asar 65816 Assembler Integration
-add_subdirectory(src/lib/asar/src)
+# Improved cross-platform support for macOS, Linux, and Windows
 
-set(ASAR_GEN_EXE OFF)
+# Configure Asar build options
-set(ASAR_GEN_DLL ON)
+# Build the standalone executable so we can fall back to a bundled CLI when the
-set(ASAR_GEN_LIB ON)
+# static library misbehaves.
-set(ASAR_GEN_EXE_TEST OFF)
+set(ASAR_GEN_EXE ON CACHE BOOL "Build Asar standalone executable")
-set(ASAR_GEN_DLL_TEST OFF)
+set(ASAR_GEN_DLL ON CACHE BOOL "Build Asar shared library")
-set(ASAR_STATIC_SRC_DIR "${CMAKE_SOURCE_DIR}/src/lib/asar/src/asar")
+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")
 
-get_target_property(ASAR_INCLUDE_DIR asar-static INCLUDE_DIRECTORIES)
+# Force Asar to use static MSVC runtime to match vcpkg static triplets
-list(APPEND ASAR_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/src/lib/asar/src")
+if(MSVC)
-target_include_directories(asar-static PRIVATE ${ASAR_INCLUDE_DIR})
+    set(MSVC_LIB_TYPE T CACHE STRING "Asar MSVC runtime type" FORCE)
+endif()
 
-set(ASAR_STATIC_SRC
+# Set Asar source directory
-  "${ASAR_STATIC_SRC_DIR}/interface-lib.cpp"
+set(ASAR_SRC_DIR "${CMAKE_SOURCE_DIR}/ext/asar/src")
-  "${ASAR_STATIC_SRC_DIR}/addr2line.cpp"
-  "${ASAR_STATIC_SRC_DIR}/arch-65816.cpp"
-  "${ASAR_STATIC_SRC_DIR}/arch-spc700.cpp"
-  "${ASAR_STATIC_SRC_DIR}/arch-superfx.cpp"
-  "${ASAR_STATIC_SRC_DIR}/assembleblock.cpp"
-  "${ASAR_STATIC_SRC_DIR}/crc32.cpp"
-  "${ASAR_STATIC_SRC_DIR}/libcon.cpp"
-  "${ASAR_STATIC_SRC_DIR}/libsmw.cpp"
-  "${ASAR_STATIC_SRC_DIR}/libstr.cpp"
-  "${ASAR_STATIC_SRC_DIR}/macro.cpp"
-  "${ASAR_STATIC_SRC_DIR}/main.cpp"
-  "${ASAR_STATIC_SRC_DIR}/asar_math.cpp"
-  "${ASAR_STATIC_SRC_DIR}/virtualfile.cpp"
-  "${ASAR_STATIC_SRC_DIR}/warnings.cpp"
-  "${ASAR_STATIC_SRC_DIR}/errors.cpp"
-  "${ASAR_STATIC_SRC_DIR}/platform/file-helpers.cpp"
-)
 
-if(WIN32 OR MINGW)
+# Add Asar as subdirectory with explicit binary directory
-  list(APPEND ASAR_STATIC_SRC "${ASAR_STATIC_SRC_DIR}/platform/windows/file-helpers-win32.cpp")
+add_subdirectory(${ASAR_SRC_DIR} ${CMAKE_BINARY_DIR}/asar 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(YAZE_PLATFORM_MACOS)
+        target_compile_definitions(asar-static PRIVATE
+            MACOS
+            stricmp=strcasecmp
+        )
+    elseif(YAZE_PLATFORM_IOS)
+        target_compile_definitions(asar-static PRIVATE
+            YAZE_IOS
+            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 "${ASAR_STATIC_SRC_DIR}/platform/linux/file-helpers-linux.cpp")
+    message(WARNING "Failed to configure Asar static library target")
-endif()
+    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,120 @@
+# 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 ===")
+
+# Only prefer local/system packages when explicitly requested.
+set(CPM_USE_LOCAL_PACKAGES ${YAZE_USE_SYSTEM_DEPS} CACHE BOOL "" FORCE)
+
+# Clear any previous dependency targets
+set(YAZE_ALL_DEPENDENCIES "")
+set(YAZE_SDL2_TARGETS "")
+set(YAZE_YAML_TARGETS "")
+set(YAZE_IMGUI_TARGETS "")
+set(YAZE_IMPLOT_TARGETS "")
+set(YAZE_JSON_TARGETS "")
+set(YAZE_HTTPLIB_TARGETS "")
+set(YAZE_GRPC_TARGETS "")
+set(YAZE_FTXUI_TARGETS "")
+set(YAZE_TESTING_TARGETS "")
+
+# Core dependencies (always required)
+# SDL selection: SDL2 (default) or SDL3 (experimental)
+if(YAZE_USE_SDL3)
+  include(cmake/dependencies/sdl3.cmake)
+  # Debug: message(STATUS "After SDL3 setup, YAZE_SDL3_TARGETS = '${YAZE_SDL3_TARGETS}'")
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_SDL3_TARGETS})
+else()
+  include(cmake/dependencies/sdl2.cmake)
+  # Debug: message(STATUS "After SDL2 setup, YAZE_SDL2_TARGETS = '${YAZE_SDL2_TARGETS}'")
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_SDL2_TARGETS})
+endif()
+
+include(cmake/dependencies/yaml.cmake)
+list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_YAML_TARGETS})
+
+include(cmake/dependencies/imgui.cmake)
+# Debug: message(STATUS "After ImGui setup, YAZE_IMGUI_TARGETS = '${YAZE_IMGUI_TARGETS}'")
+list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_IMGUI_TARGETS})
+
+include(cmake/dependencies/implot.cmake)
+list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_IMPLOT_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()
+
+# Native HTTP/HTTPS (cpp-httplib) for non-WASM builds
+if(NOT EMSCRIPTEN)
+  include(cmake/dependencies/httplib.cmake)
+  list(APPEND YAZE_ALL_DEPENDENCIES ${YAZE_HTTPLIB_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 AND NOT EMSCRIPTEN)
+  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}")
+message(STATUS "ImPlot: ${YAZE_IMPLOT_TARGETS}")
+if(YAZE_ENABLE_JSON)
+  message(STATUS "JSON: ${YAZE_JSON_TARGETS}")
+endif()
+if(YAZE_ENABLE_GRPC)
+  message(STATUS "gRPC: ${YAZE_GRPC_TARGETS}")
+endif()
+if(NOT EMSCRIPTEN)
+  message(STATUS "httplib: ${YAZE_HTTPLIB_TARGETS}")
+endif()
+if(YAZE_BUILD_CLI AND NOT EMSCRIPTEN)
+  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,30 @@
+# 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")
+set(NLOHMANN_JSON_VERSION "3.11.3" CACHE STRING "nlohmann/json version")
+set(HTTPLIB_VERSION "0.26.0" CACHE STRING "cpp-httplib version")
+
+# gRPC and related
+# Using v1.67.1 for MSVC compatibility (v1.75.1 has UPB compilation errors on Windows)
+set(GRPC_VERSION "1.67.1" CACHE STRING "gRPC version - MSVC compatible")
+set(PROTOBUF_VERSION "3.25.1" CACHE STRING "Protobuf version")
+set(ABSEIL_VERSION "20240116.0" CACHE STRING "Abseil version")
+# Cache revision: increment to force CPM cache invalidation (current: 2)
+
+# Testing
+set(GTEST_VERSION "1.14.0" CACHE STRING "Google Test version")
+set(BENCHMARK_VERSION "1.8.3" CACHE STRING "Google Benchmark version")
+
+# CLI tools
+set(FTXUI_VERSION "5.0.0" CACHE STRING "FTXUI version")
+
+# ImGui
+set(IMGUI_VERSION "1.90.4" CACHE STRING "Dear ImGui version")
+# Cache revision: increment to force rebuild (current: 2)
+
+# ASAR
+set(ASAR_VERSION "main" CACHE STRING "ASAR version")

cmake/dependencies/ftxui.cmake

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

cmake/dependencies/grpc.cmake

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

cmake/dependencies/httplib.cmake

@@ -0,0 +1,78 @@
+# cpp-httplib dependency management
+
+if(EMSCRIPTEN)
+  set(YAZE_HTTPLIB_TARGETS "" CACHE INTERNAL "cpp-httplib targets")
+  return()
+endif()
+
+include(cmake/CPM.cmake)
+include(cmake/dependencies.lock)
+
+message(STATUS "Setting up cpp-httplib ${HTTPLIB_VERSION}")
+
+if(YAZE_PLATFORM_IOS)
+  CPMAddPackage(
+    NAME httplib
+    VERSION ${HTTPLIB_VERSION}
+    GITHUB_REPOSITORY yhirose/cpp-httplib
+    GIT_TAG v${HTTPLIB_VERSION}
+    DOWNLOAD_ONLY YES
+  )
+
+  if(NOT TARGET httplib)
+    add_library(httplib INTERFACE)
+    target_include_directories(httplib INTERFACE ${httplib_SOURCE_DIR})
+  endif()
+  if(NOT TARGET httplib::httplib)
+    add_library(httplib::httplib ALIAS httplib)
+  endif()
+
+  set(YAZE_HTTPLIB_TARGETS httplib::httplib)
+  set(YAZE_HTTPLIB_TARGETS httplib::httplib CACHE INTERNAL "cpp-httplib targets")
+  message(STATUS "cpp-httplib configured as header-only for iOS")
+  return()
+endif()
+
+set(_YAZE_USE_SYSTEM_HTTPLIB ${YAZE_USE_SYSTEM_DEPS})
+
+# Try to use system packages first
+if(_YAZE_USE_SYSTEM_HTTPLIB)
+  find_package(httplib QUIET)
+  if(httplib_FOUND)
+    message(STATUS "Using system httplib")
+    set(YAZE_HTTPLIB_TARGETS httplib::httplib CACHE INTERNAL "cpp-httplib targets")
+    return()
+  elseif(YAZE_USE_SYSTEM_DEPS)
+    message(WARNING "System httplib not found despite YAZE_USE_SYSTEM_DEPS=ON; falling back to CPM download")
+  endif()
+endif()
+
+CPMAddPackage(
+  NAME httplib
+  VERSION ${HTTPLIB_VERSION}
+  GITHUB_REPOSITORY yhirose/cpp-httplib
+  GIT_TAG v${HTTPLIB_VERSION}
+  OPTIONS
+    "HTTPLIB_INSTALL OFF"
+    "HTTPLIB_TEST OFF"
+    "HTTPLIB_COMPILE OFF"
+    "HTTPLIB_USE_OPENSSL_IF_AVAILABLE OFF"
+    "HTTPLIB_USE_ZLIB_IF_AVAILABLE OFF"
+    "HTTPLIB_USE_BROTLI_IF_AVAILABLE OFF"
+    "HTTPLIB_USE_ZSTD_IF_AVAILABLE OFF"
+)
+
+# Verify target is available
+if(TARGET httplib::httplib)
+  message(STATUS "httplib::httplib target found")
+elseif(TARGET httplib)
+  add_library(httplib::httplib ALIAS httplib)
+  message(STATUS "Created httplib::httplib alias")
+else()
+  message(FATAL_ERROR "httplib target not found after CPM fetch")
+endif()
+
+set(YAZE_HTTPLIB_TARGETS httplib::httplib)
+set(YAZE_HTTPLIB_TARGETS httplib::httplib CACHE INTERNAL "cpp-httplib targets")
+
+message(STATUS "cpp-httplib setup complete")

cmake/dependencies/imgui.cmake

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

cmake/dependencies/implot.cmake

@@ -0,0 +1,27 @@
+# ImPlot dependency management
+# Uses the bundled ImPlot sources that ship with the ImGui Test Engine
+
+set(YAZE_IMPLOT_TARGETS "")
+
+set(IMPLOT_DIR ${CMAKE_SOURCE_DIR}/ext/imgui_test_engine/imgui_test_suite/thirdparty/implot)
+
+if(EXISTS ${IMPLOT_DIR}/implot.h)
+  message(STATUS "Setting up ImPlot from bundled sources")
+
+  add_library(ImPlot STATIC
+    ${IMPLOT_DIR}/implot.cpp
+    ${IMPLOT_DIR}/implot_items.cpp
+  )
+
+  target_include_directories(ImPlot PUBLIC
+    ${IMPLOT_DIR}
+    ${IMGUI_DIR}
+  )
+
+  target_link_libraries(ImPlot PUBLIC ImGui)
+  target_compile_features(ImPlot PUBLIC cxx_std_17)
+
+  set(YAZE_IMPLOT_TARGETS ImPlot)
+else()
+  message(WARNING "ImPlot sources not found at ${IMPLOT_DIR}. Plot widgets will be unavailable.")
+endif()