docs: Enhance GUI Testing Framework and Introduce z3ed Agent Documentation

- Expanded the testing guide with detailed sections on widget registration, state introspection, and integration with AI agents for automated testing.
- Added a new comprehensive readme for the z3ed agent, outlining its architecture, capabilities, and quick start instructions for AI-driven ROM hacking.
- Updated the changelog to reflect recent enhancements in GUI and UX, including a theme system and modular architecture for the Overworld Editor.
- Removed outdated networking documentation to streamline resources and improve clarity.

docs/A1-testing-guide.md

@@ -176,6 +176,26 @@ An agent-friendly, end-to-end testing framework built on `ImGuiTestEngine` to au
 - `test/e2e/canvas_selection_test.cc` - Canvas interaction tests
 - `test/test_utils.h` - High-level action wrappers (LoadRomInTest, OpenEditorInTest, etc.)
 
+### Widget Registration for Automation
+
+All modern UI components are fully integrated with the ImGui Test Engine for seamless automation.
+
+**Toolbar Components:**
+All toolbar buttons are automatically registered with descriptive paths:
+- `ModeButton:Pan (1)`
+- `ModeButton:Draw (2)`
+- `ToolbarAction:Toggle Tile16 Selector`
+- `ToolbarAction:Open Tile16 Editor`
+
+**Editor Cards:**
+All EditorCard windows are registered as discoverable windows:
+- `EditorCard:Tile16 Selector`
+- `EditorCard:Area Graphics`
+
+**State Introspection:**
+Card visibility states are tracked for test automation:
+- `OverworldToolbar/state:tile16_selector_visible`
+
 ### Writing E2E Tests
 
 ```cpp
@@ -202,15 +222,57 @@ void RegisterCanvasSelectionTest() {
 }
 ```
 
-### Running GUI Tests
+### Running GUI Tests with `z3ed`
+
+The `z3ed` CLI provides a powerful interface for running GUI tests.
 
 ```bash
 # Run all E2E tests
-z3ed test-gui --rom zelda3.sfc --test all
+z3ed gui replay --ci-mode
 
-# Run specific test suite
-z3ed test-gui --rom zelda3.sfc --test canvas_selection
+# Run a specific test suite from a YAML file
+z3ed gui replay test_overworld_workflow.yaml --ci-mode
 
-# Run in headless mode (CI)
-z3ed test-gui --rom zelda3.sfc --test all --headless
+# Click a specific button
+z3ed gui click "ModeButton:Draw (2)"
+
+# Wait for a window to become visible
+z3ed gui wait "window_visible:Tile16 Selector"
+
+# Assert that a card is visible
+z3ed gui assert "visible:EditorCard:Tile16 Selector"
 ```
+
+### Widget Discovery
+
+You can discover all registered UI elements for scripting and testing.
+
+```bash
+# List all widgets in the Overworld window
+z3ed gui discover --window="Overworld" --format=yaml > overworld_widgets.yaml
+
+# Find all toolbar actions
+z3ed gui discover --path-prefix="ToolbarAction:"
+
+# Find all editor cards
+z3ed gui discover --path-prefix="EditorCard:"
+```
+
+### Integration with AI Agent
+
+The agent can leverage the GUI testing framework to perform actions.
+
+1.  **Discover UI Elements**: `Agent> describe gui`
+2.  **Interact with UI**: `Agent> click toolbar button "Toggle Tile16 Selector"`
+3.  **Monitor State**: `Agent> check if "Tile16 Selector" is visible`
+
+### Visual Testing
+
+For vision-based testing, overworld entities are rendered with high-visibility colors:
+- **Entrances**: Bright yellow-gold
+- **Exits**: Cyan-white
+- **Items**: Bright red
+- **Sprites**: Bright magenta
+
+### Performance
+Widget registration has zero runtime overhead, using efficient hash map lookups and automatic cleanup of stale widgets.

docs/C1-changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.3 (October 2025)
+
+### GUI & UX Modernization
+- **Theme System**: Implemented a comprehensive theme system (`AgentUITheme`) that centralizes all UI colors. All Agent UI components are now theme-aware, deriving colors from the main application theme.
+- **UI Helper Library**: Created a library of 30+ reusable UI helper functions (`AgentUI::*` and `gui::*`) to standardize panel styles, section headers, status indicators, and buttons, reducing boilerplate code by over 50%.
+- **Visual Polish**: Enhanced numerous UI panels (Agent Chat, Test Harness, Collaboration) with theme-aware colors, status badges (PASS/FAIL/RUN), connection indicators, and provider badges (Ollama/Gemini).
+
+### Overworld Editor Refactoring
+- **Modular Architecture**: Refactored the 3,400-line `OverworldEditor` into smaller, focused modules, including `OverworldEntityRenderer`.
+- **Progressive Loading**: Implemented a priority-based progressive loading system in the central `gfx::Arena` to prevent UI freezes during asset loading. This benefits all editors.
+- **Critical Graphics Fixes**: Resolved major bugs related to graphics not refreshing immediately, multi-quadrant map updates, and incorrect feature visibility on vanilla ROMs.
+- **Multi-Area Map Configuration**: Implemented a robust `ConfigureMultiAreaMap()` method to correctly handle parent/child relationships for all area sizes (Small, Large, Wide, Tall).
+
+### Build System & Stability
+- **Build Fixes**: Resolved 7 critical build errors, including linker issues, missing virtual methods, and filesystem crashes.
+- **C API Separation**: Decoupled the C API library from the main application to improve build modularity.
+
+
 ## 0.3.2 (December 2025) - In Development
 
 ### Tile16 Editor Improvements (In Progress)

docs/index.md

@@ -10,6 +10,8 @@ Welcome to the official documentation for yaze, a comprehensive ROM editor for T
 
 ## Development & API
 
+- [Development Guide](development_guide.md) - Core architectural patterns, UI systems, and best practices.
+- [GUI Testing Guide](gui_testing.md) - The end-to-end GUI testing framework.
 - [API Reference](04-api-reference.md) - C/C++ API documentation for extensions.
 - [Testing Guide](A1-testing-guide.md) - The testing framework and best practices.
 - [Assembly Style Guide](E1-asm-style-guide.md) - 65816 assembly coding standards.

docs/networking.md

@@ -207,4 +207,4 @@ z3ed net proposal status --id prop_123
 -   **Automatic reconnection with exponential backoff**
 -   **Connection pooling for multiple sessions**
 -   **NAT traversal for home networks**
--   **End-to-end encryption for proposals**
+-   **End-to-end encryption for proposals**