scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)

Browse Source
This commit is contained in:
scawful
2025-12-22 00:20:49 +00:00
parent 2934c82b75
commit 5c4cd57ff8
1259 changed files with 239160 additions and 43801 deletions
Download Patch File Download Diff File Expand all files Collapse all files

171
docs/public/usage/dungeon-editor.md
View File

@@ -1,116 +1,117 @@
# F2: Dungeon Editor v2 Guide
# Dungeon Editor Guide
**Scope**: DungeonEditorV2 (card-based UI), DungeonEditorSystem, dungeon canvases
**Related**: [Architecture Overview](../developer/architecture.md), [Canvas System](../developer/canvas-system.md)
The Dungeon Editor provides a multi-panel workspace for editing Zelda 3 dungeon rooms. Each room has isolated graphics, objects, and palette data, allowing you to work on multiple rooms simultaneously.
---
## 1. Overview
The Dungeon Editor ships with the multi-card workspace introduced in the 0.3.x releases.
Self-contained room buffers keep graphics, objects, and palettes isolated so you can switch between
rooms without invalidating the entire renderer.
## Overview
### Key Features
- 512×512 canvas per room with pan/zoom, grid, and collision overlays.
- Layer-specific visualization (BG1/BG2 toggles, colored object outlines, slot labels).
- Modular cards for rooms, objects, palettes, entrances, and toolsets.
- Undo/Redo shared across cards via `DungeonEditorSystem`.
- Tight overworld integration: double-click an entrance to open the linked dungeon room.
- **512x512 canvas** per room with pan, zoom, grid, and collision overlays
- **Layer visualization** with BG1/BG2 toggles and colored object outlines
- **Modular panels** for rooms, objects, palettes, and entrances
- **Undo/Redo** shared across all panels
- **Overworld integration** - double-click entrances to open linked rooms
**Related Documentation:**
- [Architecture Overview](../developer/architecture.md)
- [Canvas System](../developer/canvas-system.md)
---
## 2. Architecture Snapshot
## Architecture
```
DungeonEditorV2 (UI)
├─ Cards & docking
├─ Canvas presenter
└─ Menu + toolbar actions
The editor uses a three-layer architecture:
DungeonEditorSystem (Backend)
├─ Room/session state
├─ Undo/Redo stack
├─ Sprite/entrance/item helpers
└─ Persistence + ROM writes
| Layer | Components | Responsibility |
|-------|------------|----------------|
| **UI** | DungeonEditorV2 | Panels, canvas, menus, toolbar |
| **Backend** | DungeonEditorSystem | State management, undo/redo, persistence |
| **Data** | Room Model | Buffers, objects, palettes, blocksets |
Room Model (Data)
├─ bg1_buffer_, bg2_buffer_
├─ tile_objects_, door data, metadata
└─ Palette + blockset caches
```
### Rendering Pipeline
### Room Rendering Pipeline
1. **Load** – `DungeonRoomLoader` reads the room header, blockset pointers, and door/entrance
metadata, producing a `Room` instance with immutable layout info.
2. **Decode** – The requested blockset is converted into `current_gfx16_` bitmaps; objects are parsed
into `tile_objects_` grouped by layer and palette slot.
3. **Draw** – `DungeonCanvasViewer` builds BG1/BG2 bitmaps, then overlays each object layer via
`ObjectDrawer`. Palette state comes from the room’s 90-color dungeon palette.
4. **Queue** – The finished bitmaps are pushed into the graphics `Arena`, which uploads a bounded
number of textures per frame so UI latency stays flat.
5. **Present** – When textures become available, the canvas displays the layers, draws interaction
widgets (selection rectangles, door gizmos, entity labels), and applies zoom/grid settings.
1. **Load** - Read room header, blockset pointers, and door/entrance metadata
2. **Decode** - Convert blockset into bitmaps; parse objects by layer
3. **Draw** - Build BG1/BG2 bitmaps with object overlays
4. **Queue** - Push bitmaps to texture queue for GPU upload
5. **Present** - Display layers with selection widgets and grid
Changing tiles, palettes, or objects invalidates the affected room cache so steps 2–5 rerun only for
that room.
Changes to tiles, palettes, or objects invalidate only the affected room's cache.
---
## 3. Editing Workflow
## Editing Workflow
### Opening Rooms
1. Launch `yaze` with a ROM (`./build/bin/yaze --rom_file=zelda3.sfc`).
2. Use the **Room Matrix** or **Rooms List** card to choose a room. The toolbar “+” button also opens
the selector.
3. Pin multiple rooms by opening them in separate cards; each card maintains its own canvas state.
### Working with Cards
1. Launch YAZE with a ROM: `./build/bin/yaze --rom_file=zelda3.sfc`
2. Select a room from **Room Matrix** or **Rooms List** panel
3. Open multiple rooms in separate panels for comparison
| Card | Purpose |
|------|---------|
| **Room Graphics** | Primary canvas, BG toggles, collision/grid switches. |
| **Object Editor** | Filter by type/layer, edit coordinates, duplicate/delete objects. |
| **Palette Editor** | Adjust per-room palette slots and preview results immediately. |
| **Entrances List** | Jump between overworld entrances and their mapped rooms. |
| **Room Matrix** | Visual grid of all rooms grouped per dungeon for quick navigation. |
### Available Panels
Cards can be docked, detached, or saved as workspace presets; use the sidebar to store favorite
layouts (e.g., Room Graphics + Object Editor + Palette).
| Panel | Purpose |
|-------|---------|
| **Room Graphics** | Main canvas with BG toggles and grid options |
| **Object Editor** | Edit objects by type, layer, and coordinates |
| **Palette Editor** | Adjust room palettes with live preview |
| **Entrances List** | Navigate between overworld entrances and rooms |
| **Room Matrix** | Visual dungeon room grid for quick navigation |
### Canvas Interactions
- Left-click to select an object; Shift-click to add to the selection.
- Drag handles to move objects or use the property grid for precise coordinates.
- Right-click to open the context menu, which includes quick inserts for common objects and a “jump
to entrance” helper.
- Hold Space to pan, use mouse wheel (or trackpad pinch) to zoom. The status footer shows current
zoom and cursor coordinates.
- Enable **Object Labels** from the toolbar to show layer-colored labels (e.g., `L1 Chest 0x23`).
Panels can be docked, detached, or saved as workspace presets.
### Saving & Undo
- The editor queues every change through `DungeonEditorSystem`. Use `Cmd/Ctrl+Z` and `Cmd/Ctrl+Shift+Z`
to undo/redo across cards.
- Saving writes back the room buffers, door metadata, and palettes for the active session. Keep
backups enabled (`File → Options → Experiment Flags`) for safety.
### Canvas Controls
| Action | Control |
|--------|---------|
| Select object | Left-click |
| Add to selection | Shift + Left-click |
| Move object | Drag handles |
| Pan canvas | Hold Space + drag |
| Zoom | Mouse wheel or trackpad pinch |
| Context menu | Right-click |
Enable **Object Labels** from the toolbar to display layer-colored labels.
### Saving
- **Undo/Redo**: `Cmd/Ctrl+Z` and `Cmd/Ctrl+Shift+Z`
- Changes are tracked across all panels
- Keep backups enabled in `File > Options > Experiment Flags`
---
## 4. Tips & Troubleshooting
## Troubleshooting
- **Layer sanity**: If objects appear on the wrong layer, check the BG toggles in Room Graphics and
the layer filter in Object Editor—they operate independently.
- **Palette issues**: Palettes are per room. After editing, ensure `Palette Editor` writes the new
values before switching rooms; the status footer confirms pending writes.
- **Door alignment**: Use the entrance/door inspector popup (right-click a door marker) to verify
leads-to IDs without leaving the canvas.
- **Performance**: Large ROMs with many rooms can accumulate textures. If the editor feels sluggish,
close unused room cards; each card releases its textures when closed.
| Issue | Solution |
|-------|----------|
| Objects on wrong layer | Check BG toggles in Room Graphics and layer filter in Object Editor |
| Palette not saving | Ensure Palette Editor writes values before switching rooms |
| Door alignment issues | Right-click door markers to verify leads-to IDs |
| Sluggish performance | Close unused room panels to release textures |
---
## 5. Related Docs
- [Developer Architecture Overview](../developer/architecture.md) – patterns shared across editors.
- [Canvas System Guide](../developer/canvas-system.md) – detailed explanation of canvas usage,
context menus, and popups.
- [Debugging Guide](../developer/debugging-guide.md) – startup flags and logging tips (e.g.,
`--editor=Dungeon --cards="Room 0"` for focused debugging).
## Quick Launch Examples
```bash
# Open specific room for testing
./yaze --rom_file=zelda3.sfc --editor=Dungeon --open_panels="Room 0"
# Compare multiple rooms
./yaze --rom_file=zelda3.sfc --editor=Dungeon --open_panels="Room 0,Room 1,Room 105"
# Full workspace with all tools
./yaze --rom_file=zelda3.sfc --editor=Dungeon \
--open_panels="Rooms List,Room Matrix,Object Editor,Palette Editor"
```
---
## Related Documentation
- [Architecture Overview](../developer/architecture.md) - Patterns shared across editors
- [Canvas System](../developer/canvas-system.md) - Canvas controls and context menus
- [Debugging Guide](../developer/debugging-guide.md) - Startup flags and logging

43
docs/public/usage/overworld-loading.md
View File

@@ -495,6 +495,49 @@ class OverworldMap {
- Ensure proper sprite graphics table selection for v2 vs v3 ROMs
- Verify that special area maps use the correct graphics from referenced LW/DW maps
## Save Operations and Version Safety
### Version Checking for Save Functions
**CRITICAL**: All save functions that write to custom ASM address space (0x140000+) must check the ROM version before writing. Failing to do so will corrupt vanilla ROMs by overwriting game data with uninitialized values.
```cpp
// CORRECT: Check version before writing to custom address space
absl::Status Overworld::SaveAreaSpecificBGColors() {
auto version = OverworldVersionHelper::GetVersion(*rom_);
if (!OverworldVersionHelper::SupportsCustomBGColors(version)) {
return absl::OkStatus(); // Vanilla/v1 ROM - skip custom address writes
}
// Safe to write to 0x140000+ for v2+ ROMs
}
// INCORRECT: Writing without version check
absl::Status Overworld::SaveAreaSpecificBGColors() {
// BUG: This writes to 0x140000 even for vanilla ROMs!
for (int i = 0; i < 160; ++i) {
rom_->Write(OverworldCustomAreaSpecificBGPalette + i * 2, color);
}
}
```
### Version-Gated Save Functions
| Save Function | Required Version | Address Range |
|---------------|------------------|---------------|
| `SaveAreaSpecificBGColors()` | v2+ | 0x140000-0x140140 |
| `SaveCustomOverworldASM()` (v2 features) | v2+ | 0x140140-0x140180 |
| `SaveCustomOverworldASM()` (v3 features) | v3+ | 0x140200+ |
| `SaveDiggableTiles()` | v3+ | 0x140980+ |
| `SaveAreaSizes()` | v3+ | 0x1417F8+ |
### ROM Upgrade Path
To enable v2/v3 features on a vanilla ROM:
1. Use the toolbar version badge to identify current ROM version
2. Click "Upgrade" button to apply ZSCustomOverworld ASM patch
3. Editor automatically reinitializes custom tables with sensible defaults
4. New UI controls become visible after upgrade
## Best Practices
### 1. Version-Specific Code

278
docs/public/usage/web-app.md Normal file
View File

@@ -0,0 +1,278 @@
# Web App Guide (Preview)
YAZE is available as a **preview** web application that runs in your browser. The web port is under active development - expect bugs and incomplete features.
> **⚠️ Preview Status**: The web app is experimental. For production ROM hacking, use the [desktop build](../build/quick-reference.md).
## Quick Start
### Try it Now
Visit your deployed instance to access the web version. The application is served via GitHub Pages or custom deployment.
### Loading a ROM
1. Click **"Open ROM"** or drag and drop your Zelda 3 ROM file onto the page
2. The ROM is stored locally in your browser using IndexedDB - it never leaves your computer
3. Start editing using a subset of the desktop interface
### Saving Your Work
- **Auto-save**: Changes are automatically saved to browser storage (when working)
- **Download ROM**: Click the download button to save your modified ROM to disk
- **Backup recommended**: Download frequently; browser storage can be cleared
## Feature Status
The web version is in preview with varying editor support:
| Feature | Status | Notes |
|---------|--------|-------|
| ROM Loading | ✅ Working | Drag & drop, file picker |
| Overworld Editor | ⚡ Preview | Basic tile editing, incomplete features |
| Dungeon Editor | ⚡ Preview | Room viewing, editing incomplete |
| Palette Editor | ⚡ Preview | Basic palette viewing/editing |
| Graphics Editor | ⚡ Preview | Tile viewing, editing incomplete |
| Sprite Editor | ⚡ Preview | Limited functionality |
| Message Editor | ⚡ Preview | Text viewing, editing incomplete |
| Hex Editor | ✅ Working | Direct ROM editing |
| Asar Patching | ⚡ Preview | Basic assembly patching |
| Emulator | ❌ Not Available | Use desktop build |
| Real-time Collaboration | ⚡ Experimental | Requires server setup |
| Audio Playback | ⚡ Experimental | Limited SPC700 support |
**Legend**: ✅ Working | ⚡ Preview/Incomplete | ❌ Not Available
## Browser Requirements
### Recommended Browsers
- **Chrome/Edge** 90+ (best performance)
- **Firefox** 88+
- **Safari** 15.4+ (macOS/iOS)
### Required Features
The web app requires modern browser features:
- **WebAssembly**: Core application runtime
- **SharedArrayBuffer**: Multi-threading support (requires HTTPS or localhost)
- **IndexedDB**: Local ROM and project storage
- **File System Access API**: Better file handling (Chrome/Edge)
### Mobile Support
✅ **Tablets**: Full support on iPad and Android tablets
⚠️ **Phones**: Limited - interface designed for larger screens
## Performance Tips
### For Best Performance
1. **Use Chrome or Edge** - Fastest WebAssembly implementation
2. **Close other tabs** - Free up browser memory
3. **Desktop/laptop recommended** - Better than mobile for complex editing
4. **Stable internet** - Only needed for initial load; works offline after
### Troubleshooting Slow Performance
- Clear browser cache and reload
- Disable browser extensions temporarily
- Check browser console for errors (F12)
- Use the debug build for better error messages (see Development section)
## Storage & Privacy
### What's Stored Locally
- ROM files (IndexedDB)
- Project settings and preferences
- Auto-save data
- Recent file history
### Privacy Guarantee
- **All data stays in your browser** - ROMs and edits never uploaded to servers
- **No tracking** - No analytics or user data collection
- **No login required** - No accounts or personal information needed
### Clearing Data
```javascript
// Open browser console (F12) and run:
localStorage.clear();
sessionStorage.clear();
// Then reload the page
```
Or use your browser's "Clear browsing data" feature.
## Keyboard Shortcuts
The web app supports desktop keyboard shortcuts:
| Shortcut | Action |
|----------|--------|
| **Ctrl/Cmd + O** | Open ROM |
| **Ctrl/Cmd + S** | Save/Download ROM |
| **Ctrl/Cmd + Z** | Undo |
| **Ctrl/Cmd + Y** | Redo |
| **`** (backtick) | Toggle terminal |
| **Esc** | Close panels/dialogs |
| **Tab** | Cycle through editors |
**Note**: Some shortcuts may conflict with browser defaults. Use the menu bar as an alternative.
## Advanced Features
### Terminal Access
Press **`** (backtick) to open the integrated terminal:
```bash
# List all dungeons
z3ed dungeon list --rom current
# Get overworld info
z3ed overworld info --map 0
# Apply a patch
z3ed asar my_patch.asm
```
### Collaboration (Experimental)
When enabled, multiple users can edit the same ROM simultaneously:
1. Click **"Start Collaboration"** in the toolbar
2. Share the session URL with collaborators
3. See real-time cursors and changes from other users
**Note**: Requires a collaboration server to be deployed. See deployment docs for setup.
### Developer Tools
Open browser console (F12) for debugging:
```javascript
// Check if WASM module is ready
window.yazeDebug.isReady()
// Get ROM status
window.yazeDebug.rom.getStatus()
// Get current editor state
window.yaze.editor.getActiveEditor()
// Read ROM data
window.yaze.data.getRoomTiles(roomId)
```
See [`docs/internal/wasm-yazeDebug-api-reference.md`](../../internal/wasm-yazeDebug-api-reference.md) for full API documentation.
## Known Limitations
### Not Yet Supported
- **Emulator**: No built-in emulator in web version (use desktop)
- **Custom plugins**: Plugin system requires desktop build
- **Large file export**: Browser limits on file size (typically 2GB+)
### Browser-Specific Issues
- **Safari**: Slower performance, some SharedArrayBuffer limitations
- **Firefox**: Clipboard access may require permissions
- **Mobile Chrome**: Touch controls under development
## Offline Usage
After first load, the web app works offline:
1. Visit the site once while online
2. Service worker caches the application
3. Disconnect from internet
4. App continues to function normally
**Note**: Initial load requires internet; updates require reconnection.
## Building from Source
To build and deploy your own instance:
```bash
# Build the web app
./scripts/build-wasm.sh
# Serve locally for testing
./scripts/serve-wasm.sh
# Deploy dist/ folder to your web server
# Artifacts are in build-wasm/dist/
```
See [`docs/internal/agents/wasm-development-guide.md`](../../internal/agents/wasm-development-guide.md) for detailed build instructions.
## Deployment
### GitHub Pages (Automated)
Pushes to `master` automatically build and deploy via GitHub Actions:
```yaml
# See .github/workflows/web-build.yml
```
### Custom Server
Requirements:
- Static file server (nginx, Apache, etc.)
- HTTPS enabled (required for SharedArrayBuffer)
- Proper CORS headers
Minimal nginx config:
```nginx
server {
listen 443 ssl http2;
server_name yaze.yourdomain.com;
root /var/www/yaze;
# Required for SharedArrayBuffer
add_header Cross-Origin-Opener-Policy same-origin;
add_header Cross-Origin-Embedder-Policy require-corp;
# Cache WASM files
location ~* \.(wasm|js)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
```
## Getting Help
- **Discord**: [Oracle of Secrets](https://discord.gg/MBFkMTPEmk)
- **Issues**: [GitHub Issues](https://github.com/scawful/yaze/issues)
- **Docs**: [`docs/public/index.md`](../index.md)
## Comparison: Web vs Desktop
| Feature | Web (Preview) | Desktop (Stable) |
|---------|---------------|------------------|
| **Installation** | None required | Download & install |
| **Platforms** | Modern browsers | Windows, macOS, Linux |
| **Performance** | Moderate | Excellent |
| **Editor Completeness** | Preview/Incomplete | Full-featured |
| **Emulator** | ❌ | ✅ |
| **Plugins** | ❌ | ✅ |
| **Stability** | Experimental | Production-ready |
| **Updates** | Automatic | Manual download |
| **Offline** | After first load | Always |
| **Collaboration** | Experimental | Via server |
| **Mobile** | Tablets (limited) | No |
**Recommendation**:
- **For serious ROM hacking**: Use the desktop build
- **For quick previews or demos**: Web app is suitable
- **For learning/exploration**: Either works, but desktop is more complete

147
docs/public/usage/z3ed-cli.md
View File

@@ -1,107 +1,116 @@
# z3ed CLI Guide
_Last reviewed: November 2025. `z3ed` ships alongside the main editor in every `*-ai` preset and
runs on Windows, macOS, and Linux._
The `z3ed` command-line tool provides scriptable ROM editing, AI-assisted workflows, and resource inspection. It ships with all `*-ai` preset builds and runs on Windows, macOS, and Linux.
`z3ed` exposes the same ROM-editing capabilities as the GUI but in a scriptable form. Use it to
apply patches, inspect resources, run batch conversions, or drive the AI-assisted workflows that
feed the in-editor proposals.
---
## 1. Building & Configuration
## Building
```bash
# Enable the agent/CLI toolchain
# Build with AI features
cmake --preset mac-ai
cmake --build --preset mac-ai --target z3ed
# Run the text UI (FTXUI)
# Run the text UI
./build/bin/z3ed --tui
```
The AI features require at least one provider:
- **Ollama (local)** – install via `brew install ollama`, run `ollama serve`, then set
`OLLAMA_MODEL=qwen2.5-coder:0.5b` (the lightweight default used in CI) or any other supported
model. Pass `--ai_model "$OLLAMA_MODEL"` on the CLI to override per-run.
- **Gemini (cloud)** – export `GEMINI_API_KEY` before launching `z3ed`.
## AI Provider Configuration
If no provider is configured the CLI still works, but agent subcommands will fall back to manual
plans.
AI features require at least one provider:
## 2. Everyday Commands
| Provider | Setup |
|----------|-------|
| **Ollama** (local) | `brew install ollama && ollama serve` |
| **Gemini** (cloud) | `export GEMINI_API_KEY=your_key` |
| Task | Example |
| --- | --- |
| Apply an Asar patch | `z3ed asar patch.asm --rom zelda3.sfc` |
| Export all sprites from a dungeon | `z3ed dungeon list-sprites --dungeon 2 --rom zelda3.sfc --format json` |
| Inspect an overworld map | `z3ed overworld describe-map --map 80 --rom zelda3.sfc` |
| Dump palette data | `z3ed palette export --rom zelda3.sfc --output palettes.json` |
| Validate ROM headers | `z3ed rom info --rom zelda3.sfc` |
Set the model with `--ai_model` or `OLLAMA_MODEL` environment variable.
Pass `--help` after any command to see its flags. Most resource commands follow the
`<noun> <verb>` convention (`overworld set-tile`, `dungeon import-room`, etc.).
> Without a provider, z3ed still works but agent commands use manual plans.
## 3. Agent & Proposal Workflow
---
## Common Commands
| Task | Command |
|------|---------|
| Apply assembly patch | `z3ed asar patch.asm --rom zelda3.sfc` |
| List dungeon sprites | `z3ed dungeon list-sprites --dungeon 2 --rom zelda3.sfc` |
| Describe overworld map | `z3ed overworld describe-map --map 80 --rom zelda3.sfc` |
| Export palettes | `z3ed palette export --rom zelda3.sfc --output palettes.json` |
| Validate ROM | `z3ed rom info --rom zelda3.sfc` |
Commands follow `<noun> <verb>` convention. Use `--help` for flag details:
```bash
z3ed dungeon --help
z3ed dungeon list-sprites --help
```
---
## AI Agent Workflows
### Interactive Chat
### 3.1 Interactive Chat
```bash
z3ed agent chat --rom zelda3.sfc --theme overworld
```
- Maintains conversation history on disk so you can pause/resume.
- Supports tool-calling: the agent invokes subcommands (e.g., `overworld describe-map`) and
returns structured diffs.
### 3.2 Plans & Batches
Chat sessions maintain conversation history and can invoke ROM commands automatically.
### Plan and Apply
```bash
# Generate a proposal but do not apply it
z3ed agent plan --prompt "Move the eastern palace entrance 3 tiles east" --rom zelda3.sfc
# Create a plan without applying
z3ed agent plan --prompt "Move eastern palace entrance 3 tiles east" --rom zelda3.sfc
# List pending plans
z3ed agent list
# Apply a plan after review
# Apply after review
z3ed agent accept --proposal-id <id> --rom zelda3.sfc
```
Plans store the command transcript, diffs, and metadata inside
`$XDG_DATA_HOME/yaze/proposals/` (or `%APPDATA%\yaze\proposals\`). Review them before applying to
non-sandbox ROMs.
### 3.3 Non-interactive Scripts
Plans are stored in `$XDG_DATA_HOME/yaze/proposals/` (or `%APPDATA%\yaze\proposals\` on Windows).
### Scripted Prompts
```bash
# Run prompts from a file
z3ed agent simple-chat --file scripts/queries.txt --rom zelda3.sfc --stdout
# From file
z3ed agent simple-chat --file queries.txt --rom zelda3.sfc --stdout
# Feed stdin (useful in CI)
cat <<'PROMPTS' | z3ed agent simple-chat --rom zelda3.sfc --stdout
Describe tile 0x3A in map 0x80.
Suggest palette swaps for dungeon 2.
PROMPTS
# From stdin
echo "Describe tile 0x3A in map 0x80" | z3ed agent simple-chat --rom zelda3.sfc --stdout
```
## 4. Automation Tips
---
1. **Sandbox first** – point the agent at a copy of your ROM (`--sandbox` flag) so you can review
patches safely.
2. **Log everything** – `--log-file agent.log` captures the provider transcript for auditing.
3. **Structure output** – most list/describe commands support `--format json` or `--format yaml`
for downstream tooling.
4. **Combine with `yaze_test`** – run `./build_ai/bin/yaze_test --unit` after batch patches to
confirm nothing regressed.
5. **Use TUI filters** – in `--tui`, press `:` to open the command palette, type part of a command,
hit Enter, and the tool auto-fills the available flags.
## Best Practices
## 5. Troubleshooting
| Tip | Description |
|-----|-------------|
| **Use sandbox mode** | `--sandbox` flag creates a copy for safe testing |
| **Log sessions** | `--log-file agent.log` captures transcripts |
| **Structured output** | `--format json` or `--format yaml` for scripting |
| **Run tests after patches** | `./build/bin/yaze_test --unit` |
| **TUI command palette** | Press `:` in TUI mode to search commands |
| Symptom | Fix |
| --- | --- |
| `agent chat` hangs after a prompt | Ensure `ollama serve` or the Gemini API key is configured. |
| `libgrpc` or `absl` missing | Re-run the `*-ai` preset; plain debug presets do not pull the agent stack. |
| CLI cannot find the ROM | Use absolute paths or set `YAZE_DEFAULT_ROM=/path/to/zelda3.sfc`. |
| Tool reports "command not found" | Run `z3ed --help` to refresh the command index; stale binaries from older builds lack new verbs. |
| Proposal diffs are empty | Provide `--rom` plus either `--sandbox` or `--workspace` so the agent knows where to stage files. |
---
## 6. Related Documentation
- `docs/public/developer/testing-without-roms.md` – ROM-less fixtures for CI.
- `docs/public/developer/debugging-guide.md` – logging and instrumentation tips shared between the
GUI and CLI.
- `docs/internal/agents/` – deep dives into the agent architecture and refactor plans (internal
audience only).
## Troubleshooting
| Issue | Solution |
|-------|----------|
| `agent chat` hangs | Verify `ollama serve` is running or `GEMINI_API_KEY` is set |
| Missing `libgrpc` or `absl` | Rebuild with `*-ai` preset |
| ROM not found | Use absolute paths or set `YAZE_DEFAULT_ROM` |
| Command not found | Run `z3ed --help` to verify build is current |
| Empty proposal diffs | Include `--rom` with `--sandbox` or `--workspace` |
---
## Related Documentation
- [Testing Without ROMs](../developer/testing-without-roms.md) - CI fixtures
- [Debugging Guide](../developer/debugging-guide.md) - Logging and instrumentation
- [CLI Reference](../cli/README.md) - Complete command documentation