yaze/docs/z3ed/README.md

z3ed: AI-Powered CLI for YAZE

Status: Active Development
Version: 0.1.0-alpha
Last Updated: October 2, 2025 (E2E Validation 80% Complete)

Overview

z3ed is a command-line interface for YAZE that enables AI-driven ROM modifications through a proposal-based workflow. It provides both human-accessible commands and machine-readable APIs for LLM integration.

Core Documentation

Essential Documents (Read These First)

1. E6-z3ed-cli-design.md - SOURCE OF TRUTH

   • Architecture overview
   • Design goals and principles
   • Command structure
   • Agentic workflow framework

2. E6-z3ed-reference.md - TECHNICAL REFERENCE

   • Complete command reference
   • API documentation
   • Implementation guides
   • Troubleshooting

3. E6-z3ed-implementation-plan.md - IMPLEMENTATION TRACKER

   • Task backlog and roadmap
   • Progress tracking
   • Known issues
   • Next priorities

Quick Start Guides

4. IT-01-QUICKSTART.md - Test harness quick start

   • Starting the gRPC server
   • Testing with grpcurl
   • Common workflows

5. AGENT_TEST_QUICKREF.md - CLI agent test command

   • Supported prompt patterns
   • Example workflows
   • Error handling

6. E2E_VALIDATION_GUIDE.md - Complete validation checklist

   • Testing procedures
   • Success criteria
   • Issue reporting

Status Documents

7. PROJECT_STATUS_OCT2.md - Current project status

   • Component completion percentages
   • Performance metrics
   • Known limitations

8. NEXT_PRIORITIES_OCT2.md - Detailed next steps

   • Priority 0-3 task breakdowns
   • Implementation guides
   • Time estimates

Quick Start

Build z3ed

# Basic build (without gRPC)
cmake --build build --target z3ed -j8

# With gRPC support (for GUI automation)
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
cmake --build build-grpc-test --target z3ed -j$(sysctl -n hw.ncpu)

Basic Usage

# Display ROM info
z3ed rom info --rom=zelda3.sfc

# Export a palette
z3ed palette export sprites_aux1 4 soldier.col

# Create an agent proposal
z3ed agent run --prompt "Make soldiers red" --rom=zelda3.sfc --sandbox

# List all proposals
z3ed agent list

# View proposal changes
z3ed agent diff

# Automated GUI testing (requires test harness)
z3ed agent test --prompt "Open Overworld editor and verify it loads"

Start Test Harness (Optional)

# Terminal 1: Start YAZE with test harness
./build-grpc-test/bin/yaze.app/Contents/MacOS/yaze \
  --enable_test_harness \
  --test_harness_port=50052 \
  --rom_file=assets/zelda3.sfc &

# Terminal 2: Run automated test
./build-grpc-test/bin/z3ed agent test \
  --prompt "Open Overworld editor"

Documentation Structure

docs/z3ed/
├── Core Documentation (3 files)
│   ├── E6-z3ed-cli-design.md        [Source of Truth]
│   ├── E6-z3ed-reference.md         [Technical Reference]
│   └── E6-z3ed-implementation-plan.md [Tracker]
│
├── Quick Start Guides (3 files)
│   ├── IT-01-QUICKSTART.md          [Test Harness]
│   ├── AGENT_TEST_QUICKREF.md       [CLI Agent Test]
│   └── E2E_VALIDATION_GUIDE.md      [Validation]
│
├── Status Documents (4 files)
│   ├── README.md                    [This file]
│   ├── PROJECT_STATUS_OCT2.md       [Current Status]
│   ├── NEXT_PRIORITIES_OCT2.md      [Next Steps]
│   └── WORK_SUMMARY_OCT2.md         [Recent Work]
│
└── Archive (15+ files)
    └── Historical documentation and implementation notes

Key Features

✅ Completed (Production-Ready on macOS)

• Resource-Oriented CLI: Clean command structure (z3ed <resource> <action>)
• Resource Catalogue: Machine-readable API specs (docs/api/z3ed-resources.yaml)
• Acceptance Workflow: Proposal tracking, sandbox management, GUI review
• ImGuiTestHarness (IT-01): gRPC-based GUI automation (6 RPC methods)
• CLI Agent Test (IT-02): Natural language → automated GUI tests
• ProposalDrawer: Integrated proposal review UI in YAZE
• ROM Operations: info, validate, diff, generate-golden
• Palette Operations: export, import, list
• Overworld Operations: get-tile, set-tile
• Dungeon Operations: list-rooms, add-object

🔄 In Progress (80% Complete)

• E2E Validation: Full workflow testing (window detection needs fix)

📋 Planned (Next Priorities)

1. Policy Evaluation Framework (AW-04): YAML-based constraints
2. Windows Cross-Platform Testing: Validate on Windows with vcpkg
3. Production Readiness: Telemetry, screenshot, expanded tests

Architecture Highlights

Proposal-Based Workflow

User Prompt → AI Service → Sandbox ROM → Execute Commands → 
Create Proposal → Review in GUI → Accept/Reject → Commit to ROM

Component Stack

┌─────────────────────────────────┐
│ AI Agent (LLM)                  │
├─────────────────────────────────┤
│ z3ed CLI                        │
├─────────────────────────────────┤
│ Service Layer                   │
│  • ProposalRegistry             │
│  • RomSandboxManager            │
│  • GuiAutomationClient          │
│  • TestWorkflowGenerator        │
├─────────────────────────────────┤
│ ImGuiTestHarness (gRPC)         │
├─────────────────────────────────┤
│ YAZE GUI + ProposalDrawer       │
└─────────────────────────────────┘

Resources

Machine-Readable API: docs/api/z3ed-resources.yaml
Proto Schema: src/app/core/proto/imgui_test_harness.proto
Test Script: scripts/test_harness_e2e.sh

Contributing

See B1-contributing.md for general contribution guidelines.

For z3ed-specific development:

1. Read E6-z3ed-cli-design.md for architecture
2. Check E6-z3ed-implementation-plan.md for open tasks
3. Use E6-z3ed-reference.md for API details
4. Follow NEXT_PRIORITIES_OCT2.md for current work

License

Same as YAZE - see LICENSE in repository root.

---

Last Updated: October 2, 2025
Contributors: @scawful, GitHub Copilot
Next Milestone: E2E Validation Complete (Est. Oct 3, 2025)