build: add Homebrew fallback for googletest in sandboxed environments

Adds automatic detection of Homebrew-installed googletest to support
offline/sandboxed builds (e.g., Claude Code, restricted networks).

Changes:
- Add Homebrew detection logic to cmake/dependencies/testing.cmake
- Check /opt/homebrew/opt/googletest and /usr/local/opt/googletest
- Use brew --prefix googletest for dynamic detection
- Create target aliases (gtest -> GTest::gtest) for compatibility
- Only fetch from GitHub if no local installation found
- Update macOS build docs with yaml-cpp and googletest installation

Pattern mirrors existing yaml.cmake implementation. Complements the
pre-existing yaml-cpp Homebrew fallback to minimize network dependencies.

Tested with: brew install googletest (1.17.0, 2.4MB)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/public/build/build-from-source.md

@@ -1,6 +1,8 @@
 # Build Instructions
 
-yaze uses a modern CMake build system with presets for easy configuration. This guide covers how to build yaze on macOS, Linux, and Windows.
+yaze uses a modern CMake build system with presets for easy configuration. This guide explains the
+environment checks, dependencies, and platform-specific considerations. For concise per-platform
+commands, always start with the [Build & Test Quick Reference](quick-reference.md).
 
 ## 1. Environment Verification
 
@@ -25,52 +27,14 @@ yaze uses a modern CMake build system with presets for easy configuration. This
 
 The script checks for required tools like CMake, a C++23 compiler, and platform-specific dependencies.
 
-## 2. Quick Start: Building with Presets
+## 2. Using Presets
 
-We use CMake Presets for simple, one-command builds. See the [CMake Presets Guide](presets.md) for a full list.
-
-### macOS
-```bash
-# Configure a debug build (Apple Silicon)
-cmake --preset mac-dbg
-
-# Build the project
-cmake --build --preset mac-dbg
-```
-
-### Linux
-```bash
-# Configure a debug build
-cmake --preset lin-dbg
-
-# Build the project
-cmake --build --preset lin-dbg
-```
-
-### Windows
-```bash
-# Configure a debug build for Visual Studio (x64)
-cmake --preset win-dbg
-
-# Build the project
-cmake --build --preset win-dbg
-
-# Enable the full AI/gRPC stack
-cmake --preset win-ai
-cmake --build --preset win-ai
-```
-
-### AI-Enabled Build (All Platforms)
-To build with the `z3ed` AI agent features:
-```bash
-# macOS
-cmake --preset mac-ai
-cmake --build --preset mac-ai
-
-# Windows
-cmake --preset win-ai
-cmake --build --preset win-ai
-```
+- Pick the preset that matches your platform/workflow (debug: `mac-dbg` / `lin-dbg` / `win-dbg`,
+  AI-enabled: `mac-ai` / `win-ai`, release: `*-rel`, etc.).
+- Configure with `cmake --preset <name>` and build with `cmake --build --preset <name> [--target …]`.
+- Add `-v` to a preset name (e.g., `mac-dbg-v`) to surface compiler warnings.
+- Need a full matrix? See the [CMake Presets Guide](presets.md) for every preset and the quick
+  reference for ready-to-run command snippets.
 
 ## Feature Toggles & Windows Profiles
 
@@ -110,8 +74,15 @@ xcode-select --install
 
 # Recommended: Install build tools via Homebrew
 brew install cmake pkg-config
+
+# For sandboxed/offline builds: Install dependencies to avoid network fetch
+brew install yaml-cpp googletest
 ```
 
+**Note**: When building in sandboxed/offline environments (e.g., via Claude Code or restricted networks), install `yaml-cpp` and `googletest` via Homebrew to avoid GitHub fetch failures. The build system automatically detects Homebrew installations and uses them as fallback:
+- yaml-cpp: `/opt/homebrew/opt/yaml-cpp`, `/usr/local/opt/yaml-cpp`
+- googletest: `/opt/homebrew/opt/googletest`, `/usr/local/opt/googletest`
+
 ### Linux (Ubuntu/Debian)
 ```bash
 sudo apt-get update
@@ -120,10 +91,15 @@ sudo apt-get install -y build-essential cmake ninja-build pkg-config \
 ```
 
 ### Windows
--   **Visual Studio 2022** is required, with the "Desktop development with C++" workload.
--   The updated `verify-build-environment.ps1` script checks clang-cl, Ninja, vcpkg caches, and ROM assets.
--   Run `.\scripts\setup-vcpkg-windows.ps1` once per machine to bootstrap vcpkg and prefetch SDL2/yaml-cpp.
--   For building with gRPC, see the "Windows Build Optimization" section below.
+1. **Install Visual Studio 2022** with the “Desktop development with C++” workload (requires MSVC + MSBuild).  
+2. **Install Ninja** (recommended): `choco install ninja` or enable the “CMake tools for Windows” optional component.  
+3. Run the verifier: `.\scripts\verify-build-environment.ps1 -FixIssues` – this checks Visual Studio workloads, Ninja, clang-cl, Git settings, and vcpkg cache.  
+4. Bootstrap vcpkg once: `.\scripts\setup-vcpkg-windows.ps1` (prefetches SDL2, yaml-cpp, etc.).  
+5. Use the `win-*` presets (Ninja) or `win-vs-*` presets (Visual Studio generator) as needed. For AI/gRPC features, prefer `win-ai` / `win-vs-ai`.  
+6. For quick validation, run the PowerShell helper:  
+   ```powershell
+   pwsh -File scripts/agents/windows-smoke-build.ps1 -Preset win-ai -Target z3ed
+   ```
 
 ## 5. Testing
 
@@ -170,7 +146,7 @@ ctest --test-dir build --label-exclude "ROM_DEPENDENT"
 ### VS Code (Recommended)
 1.  Install the **CMake Tools** extension.
 2.  Open the project folder.
-3.  Select a preset from the status bar (e.g., `mac-ai`).
+3.  Select a preset from the status bar (e.g., `mac-ai`). On Windows, choose the desired kit (e.g., “Visual Studio Build Tools 2022”) so the generator matches your preset (`win-*` uses Ninja, `win-vs-*` uses Visual Studio).
 4.  Press F5 to build and debug.
 5.  After changing presets, run `cp build/compile_commands.json .` to update IntelliSense.