backend-infra-engineer: Release v0.3.3 snapshot

scripts/agents/README.md

@@ -0,0 +1,101 @@
+# Agent Helper Scripts
+
+| Script | Description |
+|--------|-------------|
+| `run-gh-workflow.sh` | Wrapper for `gh workflow run`, prints the run URL for easy tracking. |
+| `get-gh-workflow-status.sh` | Checks the status of a GitHub Actions workflow run using `gh run view`. |
+| `smoke-build.sh` | Runs `cmake --preset` configure/build in place and reports timing. |
+| `run-tests.sh` | Configures the preset (if needed), builds `yaze_test`, and runs `ctest` with optional args. |
+| `test-http-api.sh` | Polls the HTTP API `/api/v1/health` endpoint using curl (defaults to localhost:8080). |
+| `windows-smoke-build.ps1` | PowerShell variant of the smoke build helper for Visual Studio/Ninja presets on Windows. |
+
+Usage examples:
+```bash
+# Trigger CI workflow with artifacts and HTTP API tests enabled
+scripts/agents/run-gh-workflow.sh ci.yml --ref develop upload_artifacts=true enable_http_api_tests=true
+
+# Get the status of a workflow run (using either a URL or just the ID)
+scripts/agents/get-gh-workflow-status.sh https://github.com/scawful/yaze/actions/runs/19529930066
+scripts/agents/get-gh-workflow-status.sh 19529930066
+
+# Smoke build mac-ai preset
+scripts/agents/smoke-build.sh mac-ai
+
+# Build & run tests for mac-dbg preset with verbose ctest output
+scripts/agents/run-tests.sh mac-dbg --output-on-failure
+
+# Check HTTP API health (defaults to localhost:8080)
+scripts/agents/test-http-api.sh
+
+# Windows smoke build using PowerShell
+pwsh -File scripts/agents/windows-smoke-build.ps1 -Preset win-ai -Target z3ed
+```
+
+When invoking these scripts, log the results on the coordination board so other agents know which
+workflows/builds were triggered and where to find artifacts/logs.
+
+## Reducing Build Times
+
+Local builds can take 10-15+ minutes from scratch. Follow these practices to minimize rebuild time:
+
+### Use Dedicated Build Directories
+Always use a dedicated build directory like `build_ai` or `build_agent` to avoid interfering with the user's `build` directory:
+```bash
+cmake --preset mac-dbg -B build_ai
+cmake --build build_ai -j8 --target yaze
+```
+
+### Incremental Builds
+Once configured, only rebuild—don't reconfigure unless CMakeLists.txt changed:
+```bash
+# GOOD: Just rebuild (fast, only recompiles changed files)
+cmake --build build_ai -j8 --target yaze
+
+# AVOID: Reconfiguring when unnecessary (triggers full dependency resolution)
+cmake --preset mac-dbg -B build_ai && cmake --build build_ai
+```
+
+### Build Specific Targets
+Don't build everything when you only need to verify a specific component:
+```bash
+# Build only the main editor (skips CLI, tests, etc.)
+cmake --build build_ai -j8 --target yaze
+
+# Build only the CLI tool
+cmake --build build_ai -j8 --target z3ed
+
+# Build only tests
+cmake --build build_ai -j8 --target yaze_test
+```
+
+### Parallel Compilation
+Always use `-j8` or higher based on CPU cores:
+```bash
+cmake --build build_ai -j$(sysctl -n hw.ncpu)  # macOS
+cmake --build build_ai -j$(nproc)              # Linux
+```
+
+### Quick Syntax Check
+For rapid iteration on compile errors, build just the affected library:
+```bash
+# If fixing errors in src/app/editor/dungeon/, build just the editor lib
+cmake --build build_ai -j8 --target yaze_editor
+```
+
+### Verifying Changes Before CI
+Before pushing to trigger CI builds (which take 15-20 minutes each):
+1. Run an incremental local build to catch obvious errors
+2. If you modified a specific component, build just that target
+3. Only push when local build succeeds
+
+### ccache/sccache (Advanced)
+If available, these tools cache compilation results across rebuilds:
+```bash
+# Check if ccache is installed
+which ccache
+
+# View cache statistics
+ccache -s
+```
+
+The project's CMake configuration automatically uses ccache when available.