fix(linux): add missing yaze_gfx_render dependency to yaze_gfx_debug

Fixes linker error on Linux where yaze_gfx_debug.a (performance_dashboard.cc) was calling AtlasRenderer::Get() and AtlasRenderer::GetStats() but wasn't linking against yaze_gfx_render which contains atlas_renderer.cc. Root cause: yaze_gfx_debug was only linking to yaze_gfx_types and yaze_gfx_resource, missing the yaze_gfx_render dependency. This also fixes the undefined reference errors for HttpServer methods which were already properly included in the agent.cmake source list. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-20 01:38:55 -05:00
parent b556b155a5
commit e36d81f357
22 changed files with 1620 additions and 2 deletions
--- a/docs/internal/AI_API_ENHANCEMENT_HANDOFF.md
+++ b/docs/internal/AI_API_ENHANCEMENT_HANDOFF.md
@@ -0,0 +1,289 @@
+# AI API & Agentic Workflow Enhancement - Handoff Document
+
+**Date**: 2025-01-XX  
+**Status**: Phase 1 Complete, Phase 2-4 Pending  
+**Branch**: (to be determined)
+
+## Executive Summary
+
+This document tracks progress on transforming Yaze into an AI-native platform with unified model management, API interface, and enhanced agentic workflows. Phase 1 (Unified Model Management) is complete. Phases 2-4 require implementation.
+
+## Completed Work (Phase 1)
+
+### 1. Unified AI Model Management ✅
+
+#### Core Infrastructure
+- **`ModelInfo` struct** (`src/cli/service/ai/common.h`)
+  - Standardized model representation across all providers
+  - Fields: `name`, `display_name`, `provider`, `description`, `family`, `parameter_size`, `quantization`, `size_bytes`, `is_local`
+  
+- **`ModelRegistry` class** (`src/cli/service/ai/model_registry.h/.cc`)
+  - Singleton pattern for managing multiple `AIService` instances
+  - `RegisterService()` - Add service instances
+  - `ListAllModels()` - Aggregate models from all registered services
+  - Thread-safe with mutex protection
+
+#### AIService Interface Updates
+- **`AIService::ListAvailableModels()`** - Virtual method returning `std::vector<ModelInfo>`
+- **`AIService::GetProviderName()`** - Virtual method returning provider identifier
+- Default implementations provided in base class
+
+#### Provider Implementations
+- **`OllamaAIService::ListAvailableModels()`**
+  - Queries `/api/tags` endpoint
+  - Maps Ollama's model structure to `ModelInfo`
+  - Handles size, quantization, family metadata
+  
+- **`GeminiAIService::ListAvailableModels()`**
+  - Queries Gemini API `/v1beta/models` endpoint
+  - Falls back to known defaults if API key missing
+  - Filters for `gemini*` models
+
+#### UI Integration
+- **`AgentChatWidget::RefreshModels()`**
+  - Registers Ollama and Gemini services with `ModelRegistry`
+  - Aggregates models from all providers
+  - Caches results in `model_info_cache_`
+  
+- **Header updates** (`agent_chat_widget.h`)
+  - Replaced `ollama_model_info_cache_` with unified `model_info_cache_`
+  - Replaced `ollama_model_cache_` with `model_name_cache_`
+  - Replaced `ollama_models_loading_` with `models_loading_`
+
+### Files Modified
+- `src/cli/service/ai/common.h` - Added `ModelInfo` struct
+- `src/cli/service/ai/ai_service.h` - Added `ListAvailableModels()` and `GetProviderName()`
+- `src/cli/service/ai/ollama_ai_service.h/.cc` - Implemented model listing
+- `src/cli/service/ai/gemini_ai_service.h/.cc` - Implemented model listing
+- `src/cli/service/ai/model_registry.h/.cc` - New registry class
+- `src/app/editor/agent/agent_chat_widget.h/.cc` - Updated to use registry
+
+## In Progress
+
+### UI Rendering Updates (Partial)
+The `RenderModelConfigControls()` function in `agent_chat_widget.cc` still references old Ollama-specific code. It needs to be updated to:
+- Use unified `model_info_cache_` instead of `ollama_model_info_cache_`
+- Display models from all providers in a single list
+- Filter by provider when a specific provider is selected
+- Show provider badges/indicators for each model
+
+**Location**: `src/app/editor/agent/agent_chat_widget.cc:2083-2318`
+
+**Current State**: Function still has provider-specific branches that should be unified.
+
+## Remaining Work
+
+### Phase 2: API Interface & Headless Mode
+
+#### 2.1 HTTP Server Implementation
+**Goal**: Expose Yaze functionality via REST API for external agents
+
+**Tasks**:
+1. Create `HttpServer` class in `src/cli/service/api/`
+   - Use `httplib` (already in tree)
+   - Start on configurable port (default 8080)
+   - Handle CORS if needed
+   
+2. Implement endpoints:
+   - `GET /api/v1/models` - List all available models (delegate to `ModelRegistry`)
+   - `POST /api/v1/chat` - Send prompt to agent
+     - Request: `{ "prompt": "...", "provider": "ollama", "model": "...", "history": [...] }`
+     - Response: `{ "text_response": "...", "tool_calls": [...], "commands": [...] }`
+   - `POST /api/v1/tool/{tool_name}` - Execute specific tool
+     - Request: `{ "args": {...} }`
+     - Response: `{ "result": "...", "status": "ok|error" }`
+   - `GET /api/v1/health` - Health check
+   - `GET /api/v1/rom/status` - ROM loading status
+
+3. Integration points:
+   - Initialize server in `yaze.cc` main() or via CLI flag
+   - Share `Rom*` context with API handlers
+   - Use `ConversationalAgentService` for chat endpoint
+   - Use `ToolDispatcher` for tool endpoint
+
+**Files to Create**:
+- `src/cli/service/api/http_server.h`
+- `src/cli/service/api/http_server.cc`
+- `src/cli/service/api/api_handlers.h`
+- `src/cli/service/api/api_handlers.cc`
+
+**Dependencies**: `httplib`, `nlohmann/json` (already available)
+
+### Phase 3: Enhanced Agentic Workflows
+
+#### 3.1 Tool Expansion
+
+**FileSystemTool** (`src/cli/handlers/tools/filesystem_commands.h/.cc`)
+- **Purpose**: Allow agent to read/write files outside ROM (e.g., `src/` directory)
+- **Safety**: Require user confirmation or explicit scope configuration
+- **Commands**:
+  - `filesystem-read <path>` - Read file contents
+  - `filesystem-write <path> <content>` - Write file (with confirmation)
+  - `filesystem-list <directory>` - List directory contents
+  - `filesystem-search <pattern>` - Search for files matching pattern
+
+**BuildTool** (`src/cli/handlers/tools/build_commands.h/.cc`)
+- **Purpose**: Trigger builds from within agent
+- **Commands**:
+  - `build-cmake <build_dir>` - Run cmake configuration
+  - `build-ninja <build_dir>` - Run ninja build
+  - `build-status` - Check build status
+  - `build-errors` - Parse and return compilation errors
+
+**Integration**:
+- Add to `ToolDispatcher::ToolCallType` enum
+- Register in `ToolDispatcher::CreateHandler()`
+- Add to `ToolDispatcher::ToolPreferences` struct
+- Update UI toggles in `AgentChatWidget::RenderToolingControls()`
+
+#### 3.2 Editor State Context
+**Goal**: Feed editor state (open files, compilation errors) into agent context
+
+**Tasks**:
+1. Create `EditorState` struct capturing:
+   - Open file paths
+   - Active editor type
+   - Compilation errors (if any)
+   - Recent changes
+
+2. Inject into agent prompts:
+   - Add to `PromptBuilder::BuildPromptFromHistory()`
+   - Include in system prompt when editor state changes
+
+3. Update `ConversationalAgentService`:
+   - Add `SetEditorState(EditorState*)` method
+   - Pass to `PromptBuilder` when building prompts
+
+**Files to Create/Modify**:
+- `src/cli/service/agent/editor_state.h` (new)
+- `src/cli/service/ai/prompt_builder.h/.cc` (modify)
+
+### Phase 4: Refactoring
+
+#### 4.1 ToolDispatcher Structured Output
+**Goal**: Return JSON instead of capturing stdout
+
+**Current State**: `ToolDispatcher::Dispatch()` returns `absl::StatusOr<std::string>` by capturing stdout from command handlers.
+
+**Proposed Changes**:
+1. Create `ToolResult` struct:
+   ```cpp
+   struct ToolResult {
+     std::string output;  // Human-readable output
+     nlohmann::json data;  // Structured data (if applicable)
+     bool success;
+     std::vector<std::string> warnings;
+   };
+   ```
+
+2. Update command handlers to return `ToolResult`:
+   - Modify base `CommandHandler` interface
+   - Update each handler implementation
+   - Keep backward compatibility with `OutputFormatter` for CLI
+
+3. Update `ToolDispatcher::Dispatch()`:
+   - Return `absl::StatusOr<ToolResult>`
+   - Convert to JSON for API responses
+   - Keep string output for CLI compatibility
+
+**Files to Modify**:
+- `src/cli/service/agent/tool_dispatcher.h/.cc`
+- `src/cli/handlers/*/command_handlers.h/.cc` (all handlers)
+- `src/cli/service/agent/command_handler.h` (base interface)
+
+**Migration Strategy**:
+- Add new `ExecuteStructured()` method alongside existing `Execute()`
+- Gradually migrate handlers
+- Keep old path for CLI until migration complete
+
+## Technical Notes
+
+### Model Registry Usage Pattern
+```cpp
+// Register services
+auto& registry = cli::ModelRegistry::GetInstance();
+registry.RegisterService(std::make_shared<OllamaAIService>(ollama_config));
+registry.RegisterService(std::make_shared<GeminiAIService>(gemini_config));
+
+// List all models
+auto models_or = registry.ListAllModels();
+// Returns unified list sorted by name
+```
+
+### API Key Management
+- Gemini API key: Currently stored in `AgentConfigState::gemini_api_key`
+- Consider: Environment variable fallback, secure storage
+- Future: Support multiple API keys for different providers
+
+### Thread Safety
+- `ModelRegistry` uses mutex for thread-safe access
+- `HttpServer` should handle concurrent requests (httplib supports this)
+- `ToolDispatcher` may need locking if shared across threads
+
+## Testing Checklist
+
+### Phase 1 (Model Management)
+- [ ] Verify Ollama models appear in unified list
+- [ ] Verify Gemini models appear in unified list
+- [ ] Test model refresh with multiple providers
+- [ ] Test provider filtering in UI
+- [ ] Test model selection and configuration
+
+### Phase 2 (API)
+- [ ] Test `/api/v1/models` endpoint
+- [ ] Test `/api/v1/chat` with different providers
+- [ ] Test `/api/v1/tool/*` endpoints
+- [ ] Test error handling (missing ROM, invalid tool, etc.)
+- [ ] Test concurrent requests
+- [ ] Test CORS if needed
+
+### Phase 3 (Tools)
+- [ ] Test FileSystemTool with read operations
+- [ ] Test FileSystemTool write confirmation flow
+- [ ] Test BuildTool cmake/ninja execution
+- [ ] Test BuildTool error parsing
+- [ ] Test editor state injection into prompts
+
+### Phase 4 (Refactoring)
+- [ ] Verify all handlers return structured output
+- [ ] Test API endpoints with new format
+- [ ] Verify CLI still works with old format
+- [ ] Performance test (no regressions)
+
+## Known Issues
+
+1. **UI Rendering**: `RenderModelConfigControls()` still has provider-specific code that should be unified
+2. **Model Info Display**: Some fields from `ModelInfo` (like `quantization`, `modified_at`) are not displayed in unified view
+3. **Error Handling**: Model listing failures are logged but don't prevent other providers from loading
+
+## Next Steps (Priority Order)
+
+1. **Complete UI unification** - Update `RenderModelConfigControls()` to use unified model list
+2. **Implement HTTP Server** - Start with basic server and `/api/v1/models` endpoint
+3. **Add chat endpoint** - Wire up `ConversationalAgentService` to API
+4. **Add tool endpoint** - Expose `ToolDispatcher` via API
+5. **Implement FileSystemTool** - Start with read-only operations
+6. **Implement BuildTool** - Basic cmake/ninja execution
+7. **Refactor ToolDispatcher** - Begin structured output migration
+
+## References
+
+- Plan document: `plan-yaze-api-agentic-workflow-enhancement.plan.md`
+- Model Registry: `src/cli/service/ai/model_registry.h`
+- AIService interface: `src/cli/service/ai/ai_service.h`
+- ToolDispatcher: `src/cli/service/agent/tool_dispatcher.h`
+- httplib docs: (in `ext/httplib/`)
+
+## Questions for Next Developer
+
+1. Should the HTTP server be enabled by default or require a flag?
+2. What port should be used? (8080 suggested, but configurable?)
+3. Should FileSystemTool require explicit user approval per operation or a "trusted scope"?
+4. Should BuildTool be limited to specific directories (e.g., `build/`) for safety?
+5. How should API authentication work? (API key? Localhost-only? None?)
+
+---
+
+**Last Updated**: 2025-01-XX  
+**Contact**: (to be filled)
+
--- a/docs/internal/agents/gh-actions-remote.md
+++ b/docs/internal/agents/gh-actions-remote.md
@@ -0,0 +1,45 @@
+# GitHub Actions Remote Workflow Documentation
+
+This document describes how to trigger GitHub Actions workflows remotely, specifically focusing on the `ci.yml` workflow and its custom inputs.
+
+## Triggering `ci.yml` Remotely
+
+The `ci.yml` workflow can be triggered manually via the GitHub UI or programmatically using the GitHub API (or `gh` CLI) thanks to the `workflow_dispatch` event.
+
+### Inputs
+
+The `workflow_dispatch` event for `ci.yml` supports the following custom inputs:
+
+- **`build_type`**:
+  - **Description**: Specifies the CMake build type.
+  - **Type**: `choice`
+  - **Options**: `Debug`, `Release`, `RelWithDebInfo`
+  - **Default**: `RelWithDebInfo`
+
+- **`run_sanitizers`**:
+  - **Description**: A boolean flag to enable or disable memory sanitizer runs.
+  - **Type**: `boolean`
+  - **Default**: `false`
+
+- **`upload_artifacts`**:
+  - **Description**: A boolean flag to enable or disable uploading build artifacts.
+  - **Type**: `boolean`
+  - **Default**: `false`
+
+- **`enable_http_api_tests`**:
+  - **Description**: **(NEW)** A boolean flag to enable or disable an additional step that runs HTTP API tests after the build. When set to `true`, a script (`scripts/agents/test-http-api.sh`) will be executed to validate the HTTP server (checking if the port is up and the health endpoint responds).
+  - **Type**: `boolean`
+  - **Default**: `false`
+
+### Example Usage (GitHub CLI)
+
+To trigger the `ci.yml` workflow with custom inputs using the `gh` CLI:
+
+```bash
+gh workflow run ci.yml -f build_type=Release -f enable_http_api_tests=true
+```
+
+This command will:
+- Trigger the `ci.yml` workflow.
+- Set the `build_type` to `Release`.
+- Enable the HTTP API tests.
--- a/docs/internal/agents/initiative-template.md
+++ b/docs/internal/agents/initiative-template.md
@@ -0,0 +1,45 @@
+# AI Initiative Template
+
+Use this template when kicking off a sizable AI-driven effort (infrastructure, editor refactor,
+automation tooling, etc.). Keep the filled-out document alongside other planning notes and reference
+it from the coordination board.
+
+```
+# <Initiative Title>
+
+## Summary
+- Lead agent/persona:
+- Supporting agents:
+- Problem statement:
+- Success metrics:
+
+## Scope
+- In scope:
+- Out of scope:
+- Dependencies / upstream projects:
+
+## Risks & Mitigations
+- Risk 1 – mitigation
+- Risk 2 – mitigation
+
+## Testing & Validation
+- Required test targets:
+- ROM/test data requirements:
+- Manual validation steps (if any):
+
+## Documentation Impact
+- Public docs to update:
+- Internal docs/templates to update:
+- Coordination board entry link:
+- Helper scripts to use/log: `scripts/agents/smoke-build.sh`, `scripts/agents/run-tests.sh`, `scripts/agents/run-gh-workflow.sh`
+
+## Timeline / Checkpoints
+- Milestone 1 (description, ETA)
+- Milestone 2 (description, ETA)
+```
+
+After filling in the template:
+1. Check the coordination board for conflicts before starting work.
+2. Link the initiative file from your board entries so other agents can find details without copying
+   sections into multiple docs.
+3. Archive or mark the initiative as complete when the success metrics are met.
--- a/docs/internal/agents/personas.md
+++ b/docs/internal/agents/personas.md
@@ -0,0 +1,15 @@
+# Agent Personas
+
+Use these canonical identifiers when updating the
+[coordination board](coordination-board.md) or referencing responsibilities in other documents.
+
+| Agent ID        | Primary Focus                                          | Notes |
+|-----------------|--------------------------------------------------------|-------|
+| `CLAUDE_CORE`   | Core editor/engine refactors, renderer work, SDL/ImGui | Use when Claude tackles gameplay/editor features. |
+| `CLAUDE_AIINF`  | AI infrastructure (`z3ed`, agents, gRPC automation)    | Coordinates closely with Gemini automation agents. |
+| `CLAUDE_DOCS`   | Documentation, onboarding guides, product notes        | Keep docs synced with code changes and proposals. |
+| `GEMINI_AUTOM`  | Automation/testing/CLI improvements, CI integrations   | Handles scripting-heavy or test harness tasks. |
+| `CODEX`         | Codex CLI assistant / overseer                         | Default persona; also monitors docs/build coordination when noted. |
+
+Add new rows as additional personas are created. Every new persona must follow the protocol in
+`AGENTS.md` and post updates to the coordination board before starting work.
--- a/docs/internal/handoff/ai-api-phase2-handoff.md
+++ b/docs/internal/handoff/ai-api-phase2-handoff.md
@@ -0,0 +1,85 @@
+# AI API & Agentic Workflow Enhancement - Phase 2 Handoff
+
+**Date**: 2025-11-20
+**Status**: Phase 2 Implementation Complete
+**Previous Plan**: `docs/internal/AI_API_ENHANCEMENT_HANDOFF.md`
+
+## Overview
+This handoff covers the completion of Phase 2, which focused on unifying the UI for model selection and implementing the initial HTTP API server foundation. The codebase is now ready for building and verifying the API endpoints.
+
+## Completed Work
+
+### 1. UI Unification (`src/app/editor/agent/agent_chat_widget.cc`)
+- **Unified Model List**: Replaced the separate Ollama/Gemini list logic with a single, unified list derived from `ModelRegistry`.
+- **Provider Badges**: Models in the list now display their provider (e.g., `[ollama]`, `[gemini]`).
+- **Contextual Configuration**:
+  - If an **Ollama** model is selected, the "Ollama Host" input is displayed.
+  - If a **Gemini** model is selected, the "API Key" input is displayed.
+- **Favorites & Presets**: Updated to work with the unified `ModelInfo` structure.
+
+### 2. HTTP Server Implementation (`src/cli/service/api/`)
+- **`HttpServer` Class**:
+  - Wraps `httplib::Server` running in a background `std::thread`.
+  - Exposed via `Start(port)` and `Stop()` methods.
+  - Graceful shutdown handling.
+- **API Handlers**:
+  - `GET /api/v1/health`: Returns server status (JSON).
+  - `GET /api/v1/models`: Returns list of available models from `ModelRegistry`.
+- **Integration**:
+  - Updated `src/cli/agent.cmake` to include `http_server.cc`, `api_handlers.cc`, and `model_registry.cc`.
+  - Updated `src/app/main.cc` to accept `--enable_api` and `--api_port` flags.
+
+## Build & Test Instructions
+
+### 1. Building
+The project uses CMake. The new files are automatically included in the `yaze_agent` library via `src/cli/agent.cmake`.
+
+```bash
+# Generate build files (if not already done)
+cmake -B build -G Ninja
+
+# Build the main application
+cmake --build build --target yaze_app
+```
+
+### 2. Testing the UI
+1. Launch the editor:
+   ```bash
+   ./build/yaze_app --editor=Agent
+   ```
+2. Verify the **Model Configuration** panel:
+   - You should see a single list of models.
+   - Try searching for a model.
+   - Select an Ollama model -> Verify "Host" input appears.
+   - Select a Gemini model -> Verify "API Key" input appears.
+
+### 3. Testing the API
+1. Launch the editor with API enabled:
+   ```bash
+   ./build/yaze_app --enable_api --api_port=8080
+   ```
+   *(Check logs for "Starting API server on port 8080")*
+
+2. Test Health Endpoint:
+   ```bash
+   curl -v http://localhost:8080/api/v1/health
+   # Expected: {"status":"ok", "version":"1.0", ...}
+   ```
+
+3. Test Models Endpoint:
+   ```bash
+   curl -v http://localhost:8080/api/v1/models
+   # Expected: {"models": [{"name": "...", "provider": "..."}], "count": ...}
+   ```
+
+## Next Steps (Phase 3 & 4)
+
+### Phase 3: Tool Expansion
+- **FileSystemTool**: Implement safe file read/write operations (`src/cli/handlers/tools/filesystem_commands.h`).
+- **BuildTool**: Implement cmake/ninja triggers.
+- **Editor Integration**: Inject editor state (open files, errors) into the agent context.
+
+### Phase 4: Structured Output
+- Refactor `ToolDispatcher` to return JSON objects instead of capturing stdout strings.
+- Update API to expose a `/api/v1/chat` endpoint that returns these structured responses.
+
--- a/docs/internal/roadmaps/2025-11-build-performance.md
+++ b/docs/internal/roadmaps/2025-11-build-performance.md
@@ -0,0 +1,68 @@
+# Build Performance & Agent-Friendly Tooling (November 2025)
+
+Status: **Draft**  
+Owner: CODEX (open to CLAUDE/GEMINI participation)
+
+## Goals
+- Reduce incremental build times on all platforms by tightening target boundaries, isolating optional
+  components, and providing cache-friendly presets.
+- Allow long-running or optional tasks (e.g., asset generation, documentation, verification scripts)
+  to run asynchronously or on-demand so agents don’t block on them.
+- Provide monitoring/metrics hooks so agents and humans can see where build time is spent.
+- Organize helper scripts (build, verification, CI triggers) so agents can call them predictably.
+
+## Plan Overview
+
+### 1. Library Scoping & Optional Targets
+1. Audit `src/CMakeLists.txt` and per-module cmake files for broad `add_subdirectory` usage.
+   - Identify libraries that can be marked `EXCLUDE_FROM_ALL` and only built when needed (e.g.,
+     optional tools, emulator targets).
+   - Leverage `YAZE_MINIMAL_BUILD`, `YAZE_BUILD_Z3ED`, etc., but ensure presets reflect the smallest
+     viable dependency tree.
+2. Split heavy modules (e.g., `app/editor`, `app/emu`) into more granular targets if they are
+   frequently touched independently.
+3. Add caching hints (ccache, sccache) in the build scripts/presets for all platforms.
+
+### 2. Background / Async Tasks
+1. Move long-running scripts (asset bundling, doc generation, lints) into optional targets invoked by
+   a convenience meta-target (e.g., `yaze_extras`) so normal builds stay lean.
+2. Provide `scripts/run-background-tasks.sh` that uses `nohup`/`start` to launch doc builds, GH
+   workflow dispatch, or other heavy processes asynchronously; log their status for monitoring.
+3. Ensure CI workflows skip optional tasks unless explicitly requested (e.g., via workflow inputs).
+
+### 3. Monitoring & Metrics
+1. Add a lightweight timing report to `scripts/verify-build-environment.*` or a new
+   `scripts/measure-build.sh` that runs `cmake --build` with `--trace-expand`/`ninja -d stats` and
+   reports hotspots.
+2. Integrate a summary step in CI (maybe a bash step) that records build duration per preset and
+   uploads as an artifact or comment.
+3. Document how agents should capture metrics when running builds (e.g., use `time` wrappers, log
+   output to `logs/build_<preset>.log`).
+
+### 4. Agent-Friendly Script Organization
+1. Gather recurring helper commands into `scripts/agents/`:
+   - `run-gh-workflow.sh` (wrapper around `gh workflow run`)
+   - `smoke-build.sh <preset>` (configures & builds a preset in a dedicated directory, records time)
+   - `run-tests.sh <preset> <labels>` (standardizes test selections)
+2. Provide short README in `scripts/agents/` explaining parameters, sample usage, and expected output
+   files for logging back to the coordination board.
+3. Update `AGENTS.md` to reference these scripts so every persona knows the canonical tooling.
+
+### 5. Deliverables / Tracking
+- Update CMake targets/presets to reflect modular build improvements.
+- New scripts under `scripts/agents/` + documentation.
+- Monitoring notes in CI (maybe via job summary) and local scripts.
+- Coordination board entries per major milestone (library scoping, background tooling, metrics,
+  script rollout).
+
+## Dependencies / Risks
+- Coordinate with CLAUDE_AIINF when touching presets or build scripts—they may modify the same files
+  for AI workflow fixes.
+- When changing CMake targets, ensure existing presets still configure successfully (run verification
+  scripts + smoke builds on mac/linux/win).
+- Adding background tasks/scripts should not introduce new global dependencies; use POSIX Bash and
+  PowerShell equivalents where required.
+## Windows Stability Focus (New)
+- **Tooling verification**: expand `scripts/verify-build-environment.ps1` to check for Visual Studio workload, Ninja, and vcpkg caches so Windows builds fail fast when the environment is incomplete.
+- **CMake structure**: ensure optional components (HTTP API, emulator, CLI helpers) are behind explicit options and do not affect default Windows presets; verify each target links the right runtime/library deps even when `YAZE_ENABLE_*` flags change.
+- **Preset validation**: add Windows smoke builds (Ninja + VS) to the helper scripts/CI so we can trigger focused runs when changes land.
--- a/docs/internal/roadmaps/2025-11-modernization.md
+++ b/docs/internal/roadmaps/2025-11-modernization.md
@@ -0,0 +1,46 @@
+# Modernization Plan – November 2025
+
+Status: **Draft**  
+Owner: Core tooling team  
+Scope: `core/asar_wrapper`, CLI/GUI flag system, project persistence, docs
+
+## Context
+- The Asar integration is stubbed out (`src/core/asar_wrapper.cc`), yet the GUI, CLI, and docs still advertise a working assembler workflow.
+- The GUI binary (`yaze`) still relies on the legacy `util::Flag` parser while the rest of the tooling has moved to Abseil flags, leading to inconsistent UX and duplicated parsing logic.
+- Project metadata initialization uses `std::localtime` (`src/core/project.cc`), which is not thread-safe and can race when the agent/automation stack spawns concurrent project creation tasks.
+- Public docs promise Dungeon Editor rendering details and “Examples & Recipes,” but those sections are either marked TODO or empty.
+
+## Goals
+1. Restore a fully functioning Asar toolchain across GUI/CLI and make sure automated tests cover it.
+2. Unify flag parsing by migrating the GUI binary (and remaining utilities) to Abseil flags, then retire `util::flag`.
+3. Harden project/workspace persistence by replacing unsafe time handling and improving error propagation during project bootstrap.
+4. Close the documentation gaps so the Dungeon Editor guide reflects current rendering, and the `docs/public/examples/` tree provides actual recipes.
+
+## Work Breakdown
+
+### 1. Asar Restoration
+- Fix the Asar CMake integration under `ext/asar` and link it back into `yaze_core_lib`.
+- Re-implement `AsarWrapper` methods (patch, symbol extraction, validation) and add regression tests in `test/integration/asar_*`.
+- Update `z3ed`/GUI code paths to surface actionable errors when the assembler fails.
+- Once complete, scrub docs/README claims to ensure they match the restored behavior.
+
+### 2. Flag Standardization
+- Replace `DEFINE_FLAG` usage in `src/app/main.cc` with `ABSL_FLAG` + `absl::ParseCommandLine`.
+- Delete `util::flag.*` and migrate any lingering consumers (e.g., dev tools) to Abseil.
+- Document the shared flag set in a single reference (README + `docs/public/developer/debug-flags.md`).
+
+### 3. Project Persistence Hardening
+- Swap `std::localtime` for `absl::Time` or platform-safe helpers and handle failures explicitly.
+- Ensure directory creation and file writes bubble errors back to the UI/CLI instead of silently failing.
+- Add regression tests that spawn concurrent project creations (possibly via the CLI) to confirm deterministic metadata.
+
+### 4. Documentation Updates
+- Finish the Dungeon Editor rendering pipeline description (remove the TODO block) so it reflects the current draw path.
+- Populate `docs/public/examples/` with at least a handful of ROM-editing recipes (overworld tile swap, dungeon entrance move, palette tweak, CLI plan/accept flow).
+- Add a short “automation journey” that links `README` → gRPC harness (`src/app/service/imgui_test_harness_service.cc`) → `z3ed` agent commands.
+
+## Exit Criteria
+- `AsarWrapper` integration tests green on macOS/Linux/Windows runners.
+- No binaries depend on `util::flag`; `absl::flags` is the single source of truth.
+- Project creation succeeds under parallel stress and metadata timestamps remain valid.
+- Public docs no longer contain TODO placeholders or empty directories for the sections listed above.
--- a/docs/public/build/quick-reference.md
+++ b/docs/public/build/quick-reference.md
@@ -0,0 +1,80 @@
+# Build & Test Quick Reference
+
+Use this document as the single source of truth for configuring, building, and testing YAZE across
+platforms. Other guides (README, CLAUDE.md, GEMINI.md, etc.) should link here instead of duplicating
+steps.
+
+## 1. Environment Prep
+- Clone with submodules: `git clone --recursive https://github.com/scawful/yaze.git`
+- Run the verifier once per machine:
+  - macOS/Linux: `./scripts/verify-build-environment.sh --fix`
+  - Windows PowerShell: `.\scripts\verify-build-environment.ps1 -FixIssues`
+
+## 2. Build Presets
+Use `cmake --preset <name>` followed by `cmake --build --preset <name> [--target …]`.
+
+| Preset      | Platform(s) | Notes |
+|-------------|-------------|-------|
+| `mac-dbg`, `lin-dbg`, `win-dbg` | macOS/Linux/Windows | Standard debug builds, tests on by default. |
+| `mac-ai`, `lin-ai`, `win-ai` | macOS/Linux/Windows | Enables gRPC, agent UI, `z3ed`, and AI runtime. |
+| `mac-rel`, `lin-rel`, `win-rel` | macOS/Linux/Windows | Optimized release builds. |
+| `mac-dev`, `lin-dev`, `win-dev` | macOS/Linux/Windows | Development builds with ROM-dependent tests enabled. |
+| `mac-uni` | macOS | Universal binary (ARM64 + x86_64) for distribution. |
+| `ci-*` presets | Platform-specific | Mirrors CI matrix; see `CMakePresets.json`. |
+
+**Verbose builds**: add `-v` suffix (e.g., `mac-dbg-v`, `lin-dbg-v`, `win-dbg-v`) to turn off compiler warning suppression.
+
+## 3. AI/Assistant Build Policy
+- Human developers typically use `build` or `build_test` directories.
+- AI assistants **must use dedicated directories** (`build_ai`, `build_agent`, etc.) to avoid
+  clobbering user builds.
+- When enabling AI features, prefer the `*-ai` presets and target only the binaries you need
+  (`yaze`, `z3ed`, `yaze_test`, …).
+- Windows helpers: use `scripts/agents/windows-smoke-build.ps1` for quick builds and `scripts/agents/run-tests.sh` (or its PowerShell equivalent) for test runs so preset + generator settings stay consistent.
+
+## 4. Common Commands
+```bash
+# Debug GUI build (macOS)
+cmake --preset mac-dbg
+cmake --build --preset mac-dbg --target yaze
+
+# Debug GUI build (Linux)
+cmake --preset lin-dbg
+cmake --build --preset lin-dbg --target yaze
+
+# Debug GUI build (Windows)
+cmake --preset win-dbg
+cmake --build --preset win-dbg --target yaze
+
+# AI-enabled build with gRPC (macOS)
+cmake --preset mac-ai
+cmake --build --preset mac-ai --target yaze z3ed
+
+# AI-enabled build with gRPC (Linux)
+cmake --preset lin-ai
+cmake --build --preset lin-ai --target yaze z3ed
+
+# AI-enabled build with gRPC (Windows)
+cmake --preset win-ai
+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.
+
+## 6. Troubleshooting & References
+- Detailed troubleshooting: `docs/public/build/troubleshooting.md`
+- Platform compatibility: `docs/public/build/platform-compatibility.md`
+- Internal agents must follow coordination protocol in
+  `docs/internal/agents/coordination-board.md` before running builds/tests.
--- a/docs/public/examples/README.md
+++ b/docs/public/examples/README.md
@@ -0,0 +1,49 @@
+# Examples & Recipes
+
+Short, task-focused snippets for everyday YAZE workflows. These examples supplement the primary
+guides (Getting Started, z3ed CLI, Dungeon/Overworld editors) and should remain concise. When in
+doubt, link back to the relevant guide instead of duplicating long explanations.
+
+## 1. Launching Common Editors
+```bash
+# Open YAZE directly in the Dungeon editor with room cards preset
+./build/bin/yaze --rom_file=zelda3.sfc \
+  --editor=Dungeon \
+  --cards="Rooms List,Room Graphics,Object Editor"
+
+# Jump to an Overworld map from the CLI/TUI companion
+./build/bin/z3ed overworld describe-map --map 0x80 --rom zelda3.sfc
+```
+
+## 2. AI/Automation Recipes
+```bash
+# Generate an AI plan to reposition an entrance, but do not apply yet
+./build/bin/z3ed agent plan \
+  --rom zelda3.sfc \
+  --prompt "Move the desert palace entrance 2 tiles north" \
+  --sandbox
+
+# Resume the plan and apply it once reviewed
+./build/bin/z3ed agent accept --proposal-id <ID> --rom zelda3.sfc --sandbox
+```
+
+## 3. Building & Testing Snippets
+```bash
+# Debug build with tests
+cmake --preset mac-dbg
+cmake --build --preset mac-dbg --target yaze yaze_test
+./build/bin/yaze_test --unit
+
+# AI-focused build in a dedicated directory (recommended for assistants)
+cmake --preset mac-ai -B build_ai
+cmake --build build_ai --target yaze z3ed
+```
+
+## 4. Quick Verification
+- Run `./scripts/verify-build-environment.sh --fix` (or the PowerShell variant on Windows) whenever
+  pulling major build changes.
+- See the [Build & Test Quick Reference](../build/quick-reference.md) for the canonical list of
+  commands and testing recipes.
+
+Want to contribute another recipe? Add it here with a short description and reference the relevant
+guide so the examples stay focused.