yaze/docs/z3ed/README.md

z3ed: AI-Powered CLI for YAZE

Status: Active Development
Version: 0.1.0-alpha
Last Updated: October 2, 2025 (Documentation Consolidated)

Overview

z3ed is a command-line interface for YAZE (Yet Another Zelda3 Editor) that enables AI-driven ROM modifications through a proposal-based workflow. It allows AI agents to suggest changes, which are then reviewed and accepted/rejected by human operators via the YAZE GUI.

Documentation Index

🎯 Start Here

• State Summary - 📊 NEW USERS START HERE - Complete current state, architecture, workflows, and testing
• Implementation Plan - ⭐ DEVELOPERS START HERE - Master tracking with tasks, priorities, progress, and IT-01 quick reference
• CLI Design - High-level vision, command structure, service architecture, and API design

📚 Implementation Guides

• IT-01: gRPC Evaluation - Decision rationale: Why gRPC for ImGuiTestHarness
• IT-01: Getting Started - Step-by-step gRPC integration guide
• IT-01 Phase 2: ImGuiTestEngine - Detailed code examples for GUI automation
• Dependency Management - Cross-platform dependency strategy

🔧 Technical Reference

• gRPC Technical Notes - Build issues, solutions, version compatibility
• gRPC Test Success - Complete Phase 1 testing log and validation
• File Modification Checklist - Build system changes

📝 Recent Changes

• Documentation Consolidation (Oct 2) - Removed 5 redundant summaries, consolidated into core docs

Architecture

┌─────────────────────────────────────────────────────────┐
│ z3ed CLI                                                │
│  └─ agent subcommand                                    │
│     ├─ run <prompt> [--sandbox]                         │
│     ├─ list                                             │
│     └─ test <prompt>                                    │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│ Services Layer (Singleton Services)                     │
│  ├─ ProposalRegistry                                    │
│  │   ├─ CreateProposal()                                │
│  │   ├─ ListProposals()                                 │
│  │   └─ LoadProposalsFromDiskLocked()                   │
│  ├─ RomSandboxManager                                   │
│  │   ├─ CreateSandbox()                                 │
│  │   └─ FindSandbox()                                   │
│  └─ PolicyEvaluator (Planned)                           │
│      ├─ LoadPolicies()                                  │
│      └─ EvaluateProposal()                              │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│ Filesystem Layer                                        │
│  ├─ /tmp/yaze/proposals/<id>/                          │
│  │   ├─ metadata.json                                   │
│  │   ├─ execution.log                                   │
│  │   └─ diff.txt                                        │
│  └─ /tmp/yaze/sandboxes/<id>/                          │
│      └─ zelda3.sfc (copy)                               │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│ YAZE GUI                                                │
│  └─ ProposalDrawer (400px right panel)                  │
│     ├─ List View (proposals from registry)              │
│     ├─ Detail View (metadata, diff, log)                │
│     └─ AcceptProposal() → ROM merging                   │
└─────────────────────────────────────────────────────────┘

Current Status

✅ Phase 6: Resource Catalogue (COMPLETE)

• Resource Catalog System: Comprehensive schema for all CLI commands
• Agent Describe: Machine-readable API catalog export (JSON/YAML)
• API Documentation: docs/api/z3ed-resources.yaml for AI/LLM consumption

✅ AW-01 & AW-02: Proposal Infrastructure (COMPLETE)

• ProposalRegistry: Disk persistence with lazy loading
• RomSandboxManager: Isolated ROM copies for safe testing
• Cross-Session Tracking: Proposals persist between CLI runs

✅ AW-03: ProposalDrawer GUI (COMPLETE)

• ProposalDrawer GUI: Split view, proposal list, detail panel
• ROM Merging: Sandbox-to-main ROM data copy on acceptance
• Full Lifecycle: Create (CLI) → Review (GUI) → Accept/Reject → Commit

✅ IT-01 Phase 1+2: gRPC Infrastructure (COMPLETE)

• gRPC Server: All 6 RPCs tested and working (Ping, Click, Type, Wait, Assert, Screenshot)
• TestManager Integration: Service receives TestManager reference
• Dynamic Test Registration: Click RPC uses ImGuiTestEngine properly
• See: Implementation plan for Phase 2 completion details and quick reference commands

📋 IT-01 Phase 3: ImGuiTestEngine Full Integration (NEXT)

• Critical Path: Fix TestEngine initialization timing (SIGSEGV issue)
• Complete RPCs: Click/Type/Wait/Assert with real widget interaction
• End-to-End Testing: Automated GUI testing workflows
• Estimated Effort: 6-8 hours

📋 AW-04: Policy Evaluation (PLANNED)

• Policy Framework: YAML-based rule engine
• Change Constraints: Byte limits, bank restrictions, protected regions
• Review Requirements: Human approval thresholds

Quick Start

Building z3ed

cd /Users/scawful/Code/yaze
cmake --build build --target z3ed -j8

Running Commands

# List all proposals (shows in-memory + disk proposals)
./build/bin/z3ed agent list

# Create a proposal from AI prompt (with sandbox)
./build/bin/z3ed agent run "Fix palette corruption in overworld tile $1234" --sandbox

# Future: Test GUI operations
./build/bin/z3ed agent test "Open ROM and navigate to Overworld Editor"

Reviewing Proposals in GUI

1. Launch YAZE: ./build/bin/yaze.app/Contents/MacOS/yaze
2. Open ROM: File → Open ROM
3. Open drawer: Debug → Agent Proposals (or Cmd+Shift+P)
4. Select proposal → Review diff/log → Click Accept or Reject

Key Files

CLI Entry Points

• src/cli/main.cc - z3ed binary entry point
• src/cli/command_runner.cc - Command dispatcher
• src/cli/handlers/agent_handler.cc - Agent subcommand handler

Services

• src/cli/service/proposal_registry.{h,cc} - Proposal tracking singleton
• src/cli/service/rom_sandbox_manager.{h,cc} - Isolated ROM copies
• src/cli/service/policy_evaluator.{h,cc} - (Planned) Policy rules engine

GUI Integration

• src/app/editor/system/proposal_drawer.{h,cc} - Right-side proposal panel
• src/app/editor/editor_manager.{h,cc} - Integration point for drawer

Configuration

• .yaze/policies/agent.yaml - (Planned) Policy rules
• docs/api/z3ed-resources.yaml - API catalog and examples

Development Workflow

Adding a New Feature

1. Update E6-z3ed-implementation-plan.md with task estimate
2. Create implementation branch: git checkout -b feature/task-name
3. Implement code following YAZE style guide
4. Update documentation in this folder
5. Test with real proposals
6. Create PR and link to implementation plan section

Testing Changes

# Build and test CLI
cmake --build build --target z3ed -j8
./build/bin/z3ed agent list

# Build and test GUI integration
cmake --build build --target yaze -j8
./build/bin/yaze.app/Contents/MacOS/yaze

# Future: Run automated tests
cmake --build build --target yaze_test -j8
./build/bin/yaze_test --gtest_filter=ProposalRegistry*

Next Steps

Immediate (This Week)

1. IT-01 Phase 1: Add gRPC to vcpkg with careful cross-platform setup
2. IT-01 Phase 2: Implement Ping service and test on macOS
3. Documentation: Update this README as implementation progresses

Short Term (Next 2 Weeks)

1. IT-01 Complete: Full gRPC service with Click/Type/Wait/Assert
2. Windows Testing: Validate vcpkg setup on Windows VM
3. AW-04 Design: Policy YAML schema and PolicyEvaluator API

Long Term (Next Month)

1. Policy Framework: Complete AW-04 implementation
2. CLI Testing: Integration tests for agent workflow
3. Production Readiness: Error handling, logging, telemetry

Contributing

See parent docs/B1-contributing.md for general contribution guidelines.

z3ed-Specific Guidelines

• CLI Design: Follow existing z3ed agent subcommand pattern
• Services: Use singleton pattern with Instance() accessor
• Error Handling: Return absl::Status or absl::StatusOr<T>
• Documentation: Update this README and implementation plan
• Testing: Add test cases before merging (when test harness ready)

Resources

• Parent Docs: ../ (YAZE editor documentation)
• API Catalog: ../api/z3ed-resources.yaml
• Build Guide: ../02-build-instructions.md
• Platform Compatibility: ../B2-platform-compatibility.md

License

Same as YAZE - See ../../LICENSE for details.

---

Questions? Open an issue or discuss in #yaze-dev Discord channel.