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

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