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

docs/public/build/quick-reference.md

@@ -60,18 +60,87 @@ cmake --build --preset win-ai --target yaze z3ed
 ```
 
 ## 5. Testing
-- Build target: `cmake --build --preset <preset> --target yaze_test`
-- Run all tests: `./build/bin/yaze_test`
-- Filtered runs:
-  - `./build/bin/yaze_test --unit`
-  - `./build/bin/yaze_test --integration`
-  - `./build/bin/yaze_test --e2e --show-gui`
-  - `./build/bin/yaze_test --rom-dependent --rom-path path/to/zelda3.sfc`
-- Preset-based ctest: `ctest --preset dev`
 
-Environment variables:
-- `YAZE_TEST_ROM_PATH` – default ROM for ROM-dependent tests.
-- `YAZE_SKIP_ROM_TESTS`, `YAZE_ENABLE_UI_TESTS` – gate expensive suites.
+### Default Tests (Always Available)
+
+Default test suites run automatically with debug/dev presets. Include stable unit/integration tests and GUI smoke tests:
+
+```bash
+# Build stable test suite (always included in debug presets)
+cmake --build --preset mac-dbg --target yaze_test_stable
+
+# Run with ctest (recommended approach)
+ctest --preset mac-dbg -L stable          # Stable tests only
+ctest --preset mac-dbg -L gui             # GUI smoke tests
+ctest --test-dir build -L "stable|gui"    # Both stable + GUI
+```
+
+### Optional: ROM-Dependent Tests
+
+For tests requiring Zelda3 ROM file (ASAR ROM tests, complete edit workflows, ZSCustomOverworld upgrades):
+
+```bash
+# Configure with ROM path
+cmake --preset mac-dbg -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=~/zelda3.sfc
+
+# Build ROM test suite
+cmake --build --preset mac-dbg --target yaze_test_rom_dependent
+
+# Run ROM tests
+ctest --test-dir build -L rom_dependent
+```
+
+### Optional: Experimental AI Tests
+
+For AI-powered feature tests (requires `YAZE_ENABLE_AI_RUNTIME=ON`):
+
+```bash
+# Use AI-enabled preset
+cmake --preset mac-ai
+
+# Build experimental test suite
+cmake --build --preset mac-ai --target yaze_test_experimental
+
+# Run AI tests
+ctest --test-dir build -L experimental
+```
+
+### Test Commands Reference
+
+```bash
+# Stable tests only (recommended for quick iteration)
+ctest --test-dir build -L stable -j4
+
+# All enabled tests (respects preset configuration)
+ctest --test-dir build --output-on-failure
+
+# GUI smoke tests
+ctest --test-dir build -L gui
+
+# Headless GUI tests (CI mode)
+ctest --test-dir build -L headless_gui
+
+# Tests matching pattern
+ctest --test-dir build -R "Dungeon"
+
+# Verbose output
+ctest --test-dir build --verbose
+```
+
+### Test Organization by Preset
+
+| Preset | Stable | GUI | ROM-Dep | Experimental |
+|--------|--------|-----|---------|--------------|
+| `mac-dbg`, `lin-dbg`, `win-dbg` | Yes | Yes | No | No |
+| `mac-ai`, `lin-ai`, `win-ai` | Yes | Yes | No | Yes |
+| `mac-dev`, `lin-dev`, `win-dev` | Yes | Yes | Yes | No |
+| `mac-rel`, `lin-rel`, `win-rel` | No | No | No | No |
+
+### Environment Variables
+
+- `YAZE_TEST_ROM_PATH` - Set ROM path for ROM-dependent tests (or use `-DYAZE_TEST_ROM_PATH=...` in CMake)
+- `YAZE_SKIP_ROM_TESTS` - Skip ROM tests if set (useful for CI without ROM)
+- `YAZE_ENABLE_UI_TESTS` - Enable GUI tests (default if display available)
 
 ## 6. Troubleshooting & References
 - Detailed troubleshooting: `docs/public/build/troubleshooting.md`