yaze/docs/z3ed/README.md

z3ed: AI-Powered CLI for YAZE

Status: Active Development

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 for developers and machine-readable APIs for LLM integration, forming the backbone of an agentic development ecosystem.

This directory contains the primary documentation for the z3ed system.

Core Documentation

Start here to understand the architecture, learn how to use the commands, and see the current development status.

1. E6-z3ed-cli-design.md - Design & Architecture

   • The "source of truth" for the system's architecture, design goals, and the agentic workflow framework. Read this first to understand why the system is built the way it is.

2. E6-z3ed-reference.md - Technical Reference & Guides

   • A complete command reference, API documentation, implementation guides, and troubleshooting tips. Use this as your day-to-day manual for working with z3ed.

3. E6-z3ed-implementation-plan.md - Roadmap & Status

   • The project's task backlog, roadmap, progress tracking, and a list of known issues. Check this document for current priorities and to see what's next.

Quick Start

Build z3ed

# Basic build (without GUI automation support)
cmake --build build --target z3ed

# Build with gRPC support (for GUI automation)
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
cmake --build build-grpc-test --target z3ed

Common Commands

# Create an agent proposal in a safe sandbox
z3ed agent run --prompt "Make all soldier armor red" --rom=zelda3.sfc --sandbox

# List all active and past proposals
z3ed agent list

# View the changes for the latest proposal
z3ed agent diff

# Run an automated GUI test (requires test harness to be running)
z3ed agent test --prompt "Open the Overworld editor and verify it loads"

See the Technical Reference for a full command list.