From 40a4e43db931d259d50f316973fea62f4329fa32 Mon Sep 17 00:00:00 2001
From: scawful <justin.scofield@outlook.com>
Date: Fri, 3 Oct 2025 00:51:05 -0400
Subject: [PATCH] Add LLM integration summary and quickstart script for Ollama

- Created LLM-INTEGRATION-SUMMARY.md detailing the integration plan for Ollama, Gemini, and Claude.
- Updated README.md to reflect the shift in focus towards LLM integration.
- Added quickstart_ollama.sh script to facilitate testing of Ollama integration with z3ed.
---
 docs/z3ed/E6-z3ed-implementation-plan.md  |   77 +-
 docs/z3ed/LLM-IMPLEMENTATION-CHECKLIST.md |  261 +++++
 docs/z3ed/LLM-INTEGRATION-ARCHITECTURE.md |  421 +++++++++
 docs/z3ed/LLM-INTEGRATION-PLAN.md         | 1048 +++++++++++++++++++++
 docs/z3ed/LLM-INTEGRATION-SUMMARY.md      |  311 ++++++
 docs/z3ed/README.md                       |   15 +-
 scripts/quickstart_ollama.sh              |  128 +++
 7 files changed, 2254 insertions(+), 7 deletions(-)
 create mode 100644 docs/z3ed/LLM-IMPLEMENTATION-CHECKLIST.md
 create mode 100644 docs/z3ed/LLM-INTEGRATION-ARCHITECTURE.md
 create mode 100644 docs/z3ed/LLM-INTEGRATION-PLAN.md
 create mode 100644 docs/z3ed/LLM-INTEGRATION-SUMMARY.md
 create mode 100755 scripts/quickstart_ollama.sh

diff --git a/docs/z3ed/E6-z3ed-implementation-plan.md b/docs/z3ed/E6-z3ed-implementation-plan.md
index 07dbddce..da41b65f 100644
--- a/docs/z3ed/E6-z3ed-implementation-plan.md
+++ b/docs/z3ed/E6-z3ed-implementation-plan.md
@@ -20,9 +20,10 @@ The z3ed CLI and AI agent workflow system has completed major infrastructure mil
 - **Test Harness Enhancements (IT-05 to IT-09)**: Expanding from basic automation to comprehensive testing platform with a renewed emphasis on system-wide error reporting
 
 **📋 Next Phases**:
-- **Priority 1**: Test Introspection API (IT-05) - Enable test status querying and result polling
+- **Priority 1**: LLM Integration (Ollama + Gemini + Claude) - Make AI agent system production-ready (see [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md))
 - **Priority 2**: Widget Discovery API (IT-06) - AI agents enumerate available GUI interactions
-- **Priority 3**: Enhanced Error Reporting (IT-08+) - Holistic improvements spanning z3ed, ImGuiTestHarness, EditorManager, and core application services
+- **Priority 3**: Windows Cross-Platform Testing - Validate on Windows with vcpkg
+- **Deprioritized**: Collaborative Editing (IT-10) - Postponed in favor of practical LLM integration
 
 **Recent Accomplishments** (Updated: October 2025):
 - **✅ IT-08 Enhanced Error Reporting Complete**: Full diagnostic capture operational
@@ -404,8 +405,76 @@ jobs:
 
 ---
 
-#### IT-10: Collaborative Editing & Multiplayer Sessions (12-15 hours)
-**Implementation Tasks**:
+#### IT-10: Collaborative Editing & Multiplayer Sessions ⏸️ DEPRIORITIZED
+
+**Status**: Postponed in favor of LLM integration work  
+**Rationale**: While collaborative editing is an interesting feature, practical LLM integration provides more immediate value for the agentic workflow system. The core infrastructure is complete, and enabling real AI agents to interact with z3ed is the critical next step.
+
+**Future Consideration**: IT-10 may be revisited after LLM integration is production-ready and validated by users. The collaborative editing design is preserved in the documentation for future reference.
+
+**See**: [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md) for the new priority work.
+
+---
+
+### Priority 2: LLM Integration (Ollama + Gemini + Claude) 🤖 NEW PRIORITY
+
+**Goal**: Enable practical AI-driven ROM modifications with local and remote LLM providers  
+**Time Estimate**: 12-15 hours total  
+**Status**: Ready to Implement
+
+**Why This is Critical**: The z3ed infrastructure is complete (CLI, proposals, sandbox, GUI automation), but currently uses `MockAIService` with hardcoded commands. Real LLM integration unlocks the full potential of the agentic workflow system.
+
+**📋 Complete Documentation**:
+- **[LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md)** - Detailed technical implementation guide (60+ pages)
+- **[LLM-IMPLEMENTATION-CHECKLIST.md](LLM-IMPLEMENTATION-CHECKLIST.md)** - Step-by-step task list with checkboxes
+- **[LLM-INTEGRATION-SUMMARY.md](LLM-INTEGRATION-SUMMARY.md)** - Executive summary and getting started
+
+**Implementation Phases**:
+
+#### Phase 1: Ollama Local Integration (4-6 hours) 🎯 START HERE
+- Create `OllamaAIService` class with health checks and model management
+- Wire into agent commands with provider selection mechanism
+- Add CMake configuration for httplib support
+- End-to-end testing with `qwen2.5-coder:7b` model
+
+**Key Benefits**: Local, free, private, no rate limits
+
+#### Phase 2: Gemini Fixes (2-3 hours)
+- Fix existing `GeminiAIService` implementation
+- Improve prompting with resource catalogue
+- Add markdown code block stripping for reliable parsing
+
+#### Phase 3: Claude Integration (2-3 hours)
+- Create `ClaudeAIService` class
+- Implement Messages API integration
+- Same interface as other services for easy swapping
+
+#### Phase 4: Enhanced Prompt Engineering (3-4 hours)
+- Create `PromptBuilder` utility class
+- Load resource catalogue (`z3ed-resources.yaml`) into system prompts
+- Add few-shot examples for improved accuracy (>90%)
+- Inject ROM context (current state, loaded editors)
+
+**Quick Start After Implementation**:
+```bash
+# Install Ollama
+brew install ollama
+ollama serve &
+ollama pull qwen2.5-coder:7b
+
+# Configure z3ed
+export YAZE_AI_PROVIDER=ollama
+
+# Use natural language
+z3ed agent run --prompt "Make all soldier armor red" --rom zelda3.sfc --sandbox
+z3ed agent diff  # Review changes
+```
+
+**Testing Script**: `./scripts/quickstart_ollama.sh` (automated setup validation)
+
+---
+
+### Priority 3: Windows Cross-Platform Testing 🪟
 1. **Collaboration Server**:
    - WebSocket server for real-time client communication
    - Session management (create, join, authentication)
diff --git a/docs/z3ed/LLM-IMPLEMENTATION-CHECKLIST.md b/docs/z3ed/LLM-IMPLEMENTATION-CHECKLIST.md
new file mode 100644
index 00000000..fe0b2a91
--- /dev/null
+++ b/docs/z3ed/LLM-IMPLEMENTATION-CHECKLIST.md
@@ -0,0 +1,261 @@
+# LLM Integration Implementation Checklist
+
+**Created**: October 3, 2025  
+**Status**: Ready to Begin  
+**Estimated Time**: 12-15 hours total
+
+> 📋 **Main Guide**: See [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md) for detailed implementation instructions.
+
+## Phase 1: Ollama Local Integration (4-6 hours) 🎯 START HERE
+
+### Prerequisites
+- [ ] Install Ollama: `brew install ollama` (macOS)
+- [ ] Start Ollama server: `ollama serve`
+- [ ] Pull recommended model: `ollama pull qwen2.5-coder:7b`
+- [ ] Test connectivity: `curl http://localhost:11434/api/tags`
+
+### Implementation Tasks
+
+#### 1.1 Create OllamaAIService Class
+- [ ] Create `src/cli/service/ollama_ai_service.h`
+  - [ ] Define `OllamaConfig` struct
+  - [ ] Declare `OllamaAIService` class with `GetCommands()` override
+  - [ ] Add `CheckAvailability()` and `ListAvailableModels()` methods
+- [ ] Create `src/cli/service/ollama_ai_service.cc`
+  - [ ] Implement constructor with config
+  - [ ] Implement `BuildSystemPrompt()` with z3ed command documentation
+  - [ ] Implement `CheckAvailability()` with health check
+  - [ ] Implement `GetCommands()` with Ollama API call
+  - [ ] Add JSON parsing for command extraction
+  - [ ] Add error handling for connection failures
+
+#### 1.2 Update CMake Configuration
+- [ ] Add `YAZE_WITH_HTTPLIB` option to `CMakeLists.txt`
+- [ ] Add httplib detection (vcpkg or bundled)
+- [ ] Add compile definition `YAZE_WITH_HTTPLIB`
+- [ ] Update z3ed target to link httplib when available
+
+#### 1.3 Wire into Agent Commands
+- [ ] Update `src/cli/handlers/agent/general_commands.cc`
+  - [ ] Add `#include "cli/service/ollama_ai_service.h"`
+  - [ ] Create `CreateAIService()` helper function
+  - [ ] Implement provider selection logic (env vars)
+  - [ ] Add health check with fallback to MockAIService
+  - [ ] Update `HandleRunCommand()` to use service factory
+  - [ ] Update `HandlePlanCommand()` to use service factory
+
+#### 1.4 Testing & Validation
+- [ ] Create `scripts/test_ollama_integration.sh`
+  - [ ] Check Ollama server availability
+  - [ ] Verify model is pulled
+  - [ ] Test `z3ed agent run` with simple prompt
+  - [ ] Verify proposal creation
+  - [ ] Review generated commands
+- [ ] Run end-to-end test
+- [ ] Document any issues encountered
+
+### Success Criteria
+- [ ] `z3ed agent run --prompt "Validate ROM"` generates correct command
+- [ ] Health check reports clear errors when Ollama unavailable
+- [ ] Service fallback to MockAIService works correctly
+- [ ] Test script passes without manual intervention
+
+---
+
+## Phase 2: Improve Gemini Integration (2-3 hours)
+
+### Implementation Tasks
+
+#### 2.1 Fix GeminiAIService
+- [ ] Update `src/cli/service/gemini_ai_service.cc`
+  - [ ] Fix system instruction format
+  - [ ] Update to use `gemini-1.5-flash` model
+  - [ ] Add generation config (temperature, maxOutputTokens)
+  - [ ] Add safety settings
+  - [ ] Implement markdown code block stripping
+  - [ ] Improve error messages with actionable guidance
+
+#### 2.2 Wire into Service Factory
+- [ ] Update `CreateAIService()` to check for `GEMINI_API_KEY`
+- [ ] Add Gemini as provider option
+- [ ] Test with real API key
+
+#### 2.3 Testing
+- [ ] Test with various prompts
+- [ ] Verify JSON array parsing
+- [ ] Test error handling (invalid key, network issues)
+
+### Success Criteria
+- [ ] Gemini generates valid command arrays
+- [ ] Markdown stripping works reliably
+- [ ] Error messages guide user to API key setup
+
+---
+
+## Phase 3: Add Claude Integration (2-3 hours)
+
+### Implementation Tasks
+
+#### 3.1 Create ClaudeAIService
+- [ ] Create `src/cli/service/claude_ai_service.h`
+  - [ ] Define class with API key constructor
+  - [ ] Add `GetCommands()` override
+- [ ] Create `src/cli/service/claude_ai_service.cc`
+  - [ ] Implement Claude Messages API call
+  - [ ] Use `claude-3-5-sonnet-20241022` model
+  - [ ] Add markdown stripping
+  - [ ] Add error handling
+
+#### 3.2 Wire into Service Factory
+- [ ] Update `CreateAIService()` to check for `CLAUDE_API_KEY`
+- [ ] Add Claude as provider option
+
+#### 3.3 Testing
+- [ ] Test with various prompts
+- [ ] Compare output quality vs Gemini/Ollama
+
+### Success Criteria
+- [ ] Claude service works interchangeably with others
+- [ ] Quality comparable or better than Gemini
+
+---
+
+## Phase 4: Enhanced Prompt Engineering (3-4 hours)
+
+### Implementation Tasks
+
+#### 4.1 Create PromptBuilder Utility
+- [ ] Create `src/cli/service/prompt_builder.h`
+- [ ] Create `src/cli/service/prompt_builder.cc`
+  - [ ] Implement `LoadResourceCatalogue()` (read z3ed-resources.yaml)
+  - [ ] Implement `BuildSystemPrompt()` with full command docs
+  - [ ] Implement `BuildFewShotExamples()` with proven examples
+  - [ ] Implement `BuildContextPrompt()` with ROM state
+
+#### 4.2 Integrate into Services
+- [ ] Update OllamaAIService to use PromptBuilder
+- [ ] Update GeminiAIService to use PromptBuilder
+- [ ] Update ClaudeAIService to use PromptBuilder
+
+#### 4.3 Testing
+- [ ] Test with complex prompts
+- [ ] Measure accuracy improvement
+- [ ] Document which models perform best
+
+### Success Criteria
+- [ ] System prompts include full resource catalogue
+- [ ] Few-shot examples improve accuracy >90%
+- [ ] Context injection provides relevant ROM info
+
+---
+
+## Configuration & Documentation
+
+### Environment Variables Setup
+- [ ] Document `YAZE_AI_PROVIDER` options
+- [ ] Document `OLLAMA_MODEL` override
+- [ ] Document API key requirements
+- [ ] Create example `.env` file
+
+### User Documentation
+- [ ] Create `docs/z3ed/AI-SERVICE-SETUP.md`
+  - [ ] Ollama quick start
+  - [ ] Gemini setup guide
+  - [ ] Claude setup guide
+  - [ ] Troubleshooting section
+- [ ] Update README with LLM setup instructions
+- [ ] Add examples to main docs
+
+### CLI Enhancements
+- [ ] Add `--ai-provider` flag to override env
+- [ ] Add `--ai-model` flag to override model
+- [ ] Add `--dry-run` flag to see commands without executing
+- [ ] Add `--interactive` flag to confirm each command
+
+---
+
+## Testing Matrix
+
+| Provider | Model | Test Prompt | Expected Commands | Status |
+|----------|-------|-------------|-------------------|--------|
+| Ollama | qwen2.5-coder:7b | "Validate ROM" | `["rom validate --rom zelda3.sfc"]` | ⬜ |
+| Ollama | codellama:13b | "Export first palette" | `["palette export ..."]` | ⬜ |
+| Gemini | gemini-1.5-flash | "Make soldiers red" | `["palette export ...", "palette set-color ...", ...]` | ⬜ |
+| Claude | claude-3.5-sonnet | "Change tile at (10,20)" | `["overworld set-tile ..."]` | ⬜ |
+
+---
+
+## Rollout Plan
+
+### Week 1 (Oct 7-11, 2025)
+- **Monday**: Phase 1 implementation (OllamaAIService class)
+- **Tuesday**: Phase 1 CMake + wiring
+- **Wednesday**: Phase 1 testing + documentation
+- **Thursday**: Phase 2 (Gemini fixes)
+- **Friday**: Buffer day + code review
+
+### Week 2 (Oct 14-18, 2025)
+- **Monday**: Phase 3 (Claude integration)
+- **Tuesday**: Phase 4 (PromptBuilder)
+- **Wednesday**: Enhanced testing across all services
+- **Thursday**: Documentation completion
+- **Friday**: User validation + demos
+
+---
+
+## Known Risks & Mitigation
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| Ollama not available on CI | Medium | Low | Add `YAZE_AI_PROVIDER=mock` for CI builds |
+| LLM output format inconsistent | High | Medium | Strict system prompts + validation layer |
+| API rate limits | Medium | Medium | Cache responses, implement retry backoff |
+| Model accuracy insufficient | High | Low | Multiple few-shot examples + prompt tuning |
+
+---
+
+## Success Metrics
+
+**Phase 1 Complete**: 
+- ✅ Ollama service operational on local machine
+- ✅ Can generate valid z3ed commands from prompts
+- ✅ End-to-end test passes
+
+**Phase 2-3 Complete**:
+- ✅ All three providers (Ollama, Gemini, Claude) work interchangeably
+- ✅ Service selection transparent to user
+
+**Phase 4 Complete**:
+- ✅ Command accuracy >90% on standard prompts
+- ✅ Resource catalogue integrated into system prompts
+
+**Production Ready**:
+- ✅ Documentation complete with setup guides
+- ✅ Error messages are actionable
+- ✅ Works on macOS (primary target)
+- ✅ At least one user validates the workflow
+
+---
+
+## Next Steps After Completion
+
+1. **Gather User Feedback**: Share with ROM hacking community
+2. **Measure Accuracy**: Track success rate of generated commands
+3. **Model Comparison**: Document which models work best
+4. **Fine-Tuning**: Consider fine-tuning local models on z3ed corpus
+5. **Agentic Loop**: Add self-correction based on execution results
+
+---
+
+## Notes & Observations
+
+_Add notes here as you progress through implementation:_
+
+- 
+- 
+- 
+
+---
+
+**Last Updated**: October 3, 2025  
+**Next Review**: After Phase 1 completion
diff --git a/docs/z3ed/LLM-INTEGRATION-ARCHITECTURE.md b/docs/z3ed/LLM-INTEGRATION-ARCHITECTURE.md
new file mode 100644
index 00000000..637b7cc9
--- /dev/null
+++ b/docs/z3ed/LLM-INTEGRATION-ARCHITECTURE.md
@@ -0,0 +1,421 @@
+# LLM Integration Architecture
+
+**Visual Overview of z3ed Agent System with LLM Providers**
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         User / Developer                             │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             │ Natural Language Prompt
+                             │ "Make soldier armor red"
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       z3ed CLI (Entry Point)                         │
+│                                                                       │
+│  ┌────────────────────────────────────────────────────────────┐     │
+│  │  z3ed agent run --prompt "..." --rom zelda3.sfc --sandbox  │     │
+│  └────────────────────────────────────────────────────────────┘     │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             │ Invoke
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    Agent Command Handler                             │
+│                  (src/cli/handlers/agent/)                           │
+│                                                                       │
+│  • Parse arguments                                                   │
+│  • Create proposal                                                   │
+│  • Select AI service ◄────────── Environment Variables              │
+│  • Execute commands                                                  │
+│  • Track in registry                                                 │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             │ Get Commands
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      AI Service Factory                              │
+│                   (CreateAIService() helper)                         │
+│                                                                       │
+│  Environment Detection:                                              │
+│  • YAZE_AI_PROVIDER=ollama   → OllamaAIService                       │
+│  • GEMINI_API_KEY set        → GeminiAIService                       │
+│  • CLAUDE_API_KEY set        → ClaudeAIService                       │
+│  • Default                   → MockAIService                         │
+└─────────┬───────────────────┬────────────────┬───────────────────────┘
+          │                   │                │
+          │                   │                │
+          ▼                   ▼                ▼
+┌──────────────────┐ ┌──────────────┐ ┌─────────────────┐
+│ OllamaAIService  │ │ GeminiAI     │ │ ClaudeAIService │
+│                  │ │ Service      │ │                 │
+│ • Local LLM     │ │ • Remote API │ │ • Remote API    │
+│ • Free          │ │ • API Key    │ │ • API Key       │
+│ • Private       │ │ • $0.10/1M   │ │ • Free tier     │
+│ • Fast          │ │   tokens     │ │ • Best quality  │
+└────────┬─────────┘ └──────┬───────┘ └────────┬────────┘
+         │                  │                   │
+         │                  │                   │
+         ▼                  ▼                   ▼
+┌──────────────────────────────────────────────────────────┐
+│              AIService Interface                          │
+│                                                            │
+│  virtual absl::StatusOr<vector<string>>                   │
+│      GetCommands(const string& prompt) = 0;               │
+└────────────────────────────┬──────────────────────────────┘
+                             │
+                             │ Return Commands
+                             ▼
+                   ["rom validate --rom zelda3.sfc",
+                    "palette export --group sprites ...",
+                    "palette set-color --file ... --color FF0000"]
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    Command Execution Engine                          │
+│                                                                       │
+│  For each command:                                                   │
+│  1. Parse command string                                             │
+│  2. Lookup handler in ModernCLI registry                            │
+│  3. Execute in sandbox ROM                                           │
+│  4. Log to ProposalRegistry                                          │
+│  5. Capture output/errors                                            │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      Proposal Registry                               │
+│                 (Cross-session persistence)                          │
+│                                                                       │
+│  • Proposal metadata (ID, timestamp, prompt)                        │
+│  • Execution logs (commands, status, duration)                      │
+│  • ROM diff (before/after sandbox state)                            │
+│  • Status (pending, accepted, rejected)                             │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    Human Review (GUI)                                │
+│                 YAZE Editor → Debug → Agent Proposals                │
+│                                                                       │
+│  • View proposal details                                             │
+│  • Inspect ROM diff visually                                         │
+│  • Test in GUI editors                                               │
+│  • Accept → Merge to main ROM                                        │
+│  • Reject → Discard sandbox                                          │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## LLM Provider Flow
+
+### Ollama (Local)
+
+```
+User Prompt
+     │
+     ▼
+OllamaAIService
+     │
+     ├─► Check Health (http://localhost:11434/api/tags)
+     │   └─► Model Available? ────No──► Error: "Pull qwen2.5-coder:7b"
+     │                          └─Yes
+     │
+     ├─► Build System Prompt
+     │   • Load z3ed-resources.yaml
+     │   • Add few-shot examples
+     │   • Inject ROM context
+     │
+     ├─► POST /api/generate
+     │   {
+     │     "model": "qwen2.5-coder:7b",
+     │     "prompt": "<system> + <user>",
+     │     "temperature": 0.1,
+     │     "format": "json"
+     │   }
+     │
+     ├─► Parse Response
+     │   ["command1", "command2", ...]
+     │
+     └─► Return to Agent Handler
+```
+
+### Gemini (Remote)
+
+```
+User Prompt
+     │
+     ▼
+GeminiAIService
+     │
+     ├─► Check API Key
+     │   └─► Not Set? ────► Error: "Set GEMINI_API_KEY"
+     │
+     ├─► Build Request
+     │   {
+     │     "contents": [{
+     │       "role": "user",
+     │       "parts": [{"text": "<system> + <prompt>"}]
+     │     }],
+     │     "generationConfig": {
+     │       "temperature": 0.1,
+     │       "maxOutputTokens": 2048
+     │     }
+     │   }
+     │
+     ├─► POST https://generativelanguage.googleapis.com/
+     │         v1beta/models/gemini-1.5-flash:generateContent
+     │
+     ├─► Parse Response
+     │   • Extract text from nested JSON
+     │   • Strip markdown code blocks if present
+     │   • Parse JSON array
+     │
+     └─► Return Commands
+```
+
+### Claude (Remote)
+
+```
+User Prompt
+     │
+     ▼
+ClaudeAIService
+     │
+     ├─► Check API Key
+     │   └─► Not Set? ────► Error: "Set CLAUDE_API_KEY"
+     │
+     ├─► Build Request
+     │   {
+     │     "model": "claude-3-5-sonnet-20241022",
+     │     "max_tokens": 2048,
+     │     "temperature": 0.1,
+     │     "system": "<system instructions>",
+     │     "messages": [{
+     │       "role": "user",
+     │       "content": "<prompt>"
+     │     }]
+     │   }
+     │
+     ├─► POST https://api.anthropic.com/v1/messages
+     │
+     ├─► Parse Response
+     │   • Extract text from content[0].text
+     │   • Strip markdown if present
+     │   • Parse JSON array
+     │
+     └─► Return Commands
+```
+
+## Prompt Engineering Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         PromptBuilder                                │
+│                   (Comprehensive System Prompt)                      │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ├─► 1. Load Resource Catalogue
+                             │   Source: docs/api/z3ed-resources.yaml
+                             │   • All command schemas
+                             │   • Argument types & descriptions
+                             │   • Expected effects & returns
+                             │
+                             ├─► 2. Add Few-Shot Examples
+                             │   Proven prompt → command pairs:
+                             │   • "Validate ROM" → ["rom validate ..."]
+                             │   • "Red armor" → ["palette export ...", ...]
+                             │
+                             ├─► 3. Inject ROM Context
+                             │   Current state from application:
+                             │   • Loaded ROM path
+                             │   • Open editors (Overworld, Dungeon)
+                             │   • Recently modified assets
+                             │
+                             ├─► 4. Set Output Format Rules
+                             │   • MUST return JSON array of strings
+                             │   • Each string is executable z3ed command
+                             │   • No explanations or markdown
+                             │
+                             └─► 5. Combine into Final Prompt
+                                 System Prompt (~2K tokens) + User Prompt
+                                      │
+                                      ▼
+                              Sent to LLM Provider
+```
+
+## Error Handling & Fallback Chain
+
+```
+User Request
+     │
+     ▼
+Select Provider (YAZE_AI_PROVIDER)
+     │
+     ├─► Ollama Selected
+     │   │
+     │   ├─► Health Check
+     │   │   └─► Failed? ────► Warn + Fallback to MockAIService
+     │   │                     "⚠️ Ollama unavailable, using mock"
+     │   │
+     │   └─► Model Check
+     │       └─► Missing? ───► Error + Suggestion
+     │                         "Pull model: ollama pull qwen2.5-coder:7b"
+     │
+     ├─► Gemini Selected
+     │   │
+     │   ├─► API Key Check
+     │   │   └─► Missing? ───► Fallback to MockAIService
+     │   │                     "Set GEMINI_API_KEY or use Ollama"
+     │   │
+     │   └─► API Call
+     │       ├─► Network Error? ───► Retry (3x with backoff)
+     │       └─► Rate Limit? ──────► Error + Wait Suggestion
+     │
+     └─► Claude Selected
+         │
+         └─► Similar to Gemini
+             (API key check → Fallback → Retry logic)
+```
+
+## File Structure
+
+```
+yaze/
+├── src/cli/service/
+│   ├── ai_service.h              # Base interface
+│   ├── ai_service.cc             # MockAIService implementation
+│   ├── ollama_ai_service.h       # 🆕 Ollama integration
+│   ├── ollama_ai_service.cc      # 🆕 Implementation
+│   ├── gemini_ai_service.h       # Existing (needs fixes)
+│   ├── gemini_ai_service.cc      # Existing (needs fixes)
+│   ├── claude_ai_service.h       # 🆕 Claude integration
+│   ├── claude_ai_service.cc      # 🆕 Implementation
+│   ├── prompt_builder.h          # 🆕 Prompt engineering utility
+│   └── prompt_builder.cc         # 🆕 Implementation
+│
+├── src/cli/handlers/agent/
+│   └── general_commands.cc       # 🔧 Add CreateAIService() factory
+│
+├── docs/z3ed/
+│   ├── LLM-INTEGRATION-PLAN.md           # 📋 Complete guide (this file)
+│   ├── LLM-IMPLEMENTATION-CHECKLIST.md   # ✅ Task checklist
+│   ├── LLM-INTEGRATION-SUMMARY.md        # 📄 Executive summary
+│   ├── LLM-INTEGRATION-ARCHITECTURE.md   # 🏗️ Visual diagrams (this file)
+│   └── AI-SERVICE-SETUP.md               # 📖 User guide (future)
+│
+└── scripts/
+    ├── quickstart_ollama.sh      # 🚀 Automated setup test
+    └── test_ai_services.sh       # 🧪 Integration tests
+```
+
+## Data Flow Example: "Make soldier armor red"
+
+```
+1. User Input
+   $ z3ed agent run --prompt "Make soldier armor red" --rom zelda3.sfc --sandbox
+
+2. Agent Handler
+   • Create proposal (ID: agent_20251003_143022)
+   • Create sandbox (/tmp/yaze_sandbox_abc123/zelda3.sfc)
+   • Select AI service (Ollama detected)
+
+3. Ollama Service
+   • Check health: ✓ Running on localhost:11434
+   • Check model: ✓ qwen2.5-coder:7b available
+   • Build prompt:
+     System: "<full resource catalogue> + <few-shot examples>"
+     User: "Make soldier armor red"
+   • Call API: POST /api/generate
+   • Response: 
+     ```json
+     {
+       "response": "[\"palette export --group sprites --id soldier --to /tmp/soldier.pal\", \"palette set-color --file /tmp/soldier.pal --index 5 --color FF0000\", \"palette import --group sprites --id soldier --from /tmp/soldier.pal\"]"
+     }
+     ```
+   • Parse: Extract 3 commands
+
+4. Command Execution
+   ┌────────────────────────────────────────────────────────┐
+   │ Command 1: palette export --group sprites --id soldier │
+   │ Handler: PaletteHandler::HandleExport()                │
+   │ Status: ✓ Success (wrote /tmp/soldier.pal)             │
+   │ Duration: 45ms                                          │
+   ├────────────────────────────────────────────────────────┤
+   │ Command 2: palette set-color --file /tmp/soldier.pal   │
+   │ Handler: PaletteHandler::HandleSetColor()              │
+   │ Status: ✓ Success (modified index 5 → #FF0000)         │
+   │ Duration: 12ms                                          │
+   ├────────────────────────────────────────────────────────┤
+   │ Command 3: palette import --group sprites --id soldier │
+   │ Handler: PaletteHandler::HandleImport()                │
+   │ Status: ✓ Success (applied to sandbox ROM)             │
+   │ Duration: 78ms                                          │
+   └────────────────────────────────────────────────────────┘
+
+5. Proposal Registry
+   • Log all commands
+   • Calculate ROM diff (before/after)
+   • Set status: PENDING_REVIEW
+
+6. Output to User
+   ✅ Agent run completed successfully.
+      Proposal ID: agent_20251003_143022
+      Sandbox: /tmp/yaze_sandbox_abc123/zelda3.sfc
+      Use 'z3ed agent diff' to review changes
+
+7. User Review
+   $ z3ed agent diff
+   
+   Proposal: agent_20251003_143022
+   Prompt: "Make soldier armor red"
+   Status: pending
+   Created: 2025-10-03 14:30:22
+   
+   Executed Commands:
+     1. palette export --group sprites --id soldier --to /tmp/soldier.pal
+     2. palette set-color --file /tmp/soldier.pal --index 5 --color FF0000
+     3. palette import --group sprites --id soldier --from /tmp/soldier.pal
+   
+   ROM Diff:
+     Modified palettes: [sprites/soldier]
+     Changed bytes: 6
+     Offset 0x12345: [old] 00 7C 00 → [new] 00 00 FF
+
+8. GUI Review
+   Open YAZE → Debug → Agent Proposals
+   • Visual diff shows red soldier sprite
+   • Click "Accept" → Merge sandbox to main ROM
+   • Or "Reject" → Discard sandbox
+
+9. Finalization
+   $ z3ed agent commit
+   ✅ Proposal accepted and merged to zelda3.sfc
+```
+
+## Comparison Matrix
+
+| Feature | Ollama | Gemini | Claude | Mock |
+|---------|--------|--------|--------|------|
+| **Cost** | Free | $0.10/1M tokens | Free tier | Free |
+| **Privacy** | ✅ Local | ❌ Remote | ❌ Remote | ✅ Local |
+| **Setup** | `brew install` | API key | API key | None |
+| **Speed** | Fast (~1-2s) | Medium (~2-4s) | Medium (~2-4s) | Instant |
+| **Quality** | Good (7B-70B) | Excellent | Excellent | Hardcoded |
+| **Internet** | No | Yes | Yes | No |
+| **Rate Limits** | None | 60 req/min | 5 req/min | None |
+| **Model Choice** | Many | Fixed | Fixed | N/A |
+| **Use Case** | Development | Production | Premium | Testing |
+
+## Next Steps
+
+1. **Read**: [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md) for implementation details
+2. **Follow**: [LLM-IMPLEMENTATION-CHECKLIST.md](LLM-IMPLEMENTATION-CHECKLIST.md) step-by-step
+3. **Test**: Run `./scripts/quickstart_ollama.sh` when ready
+4. **Document**: Update this architecture diagram as system evolves
+
+---
+
+**Last Updated**: October 3, 2025  
+**Status**: Documentation Complete | Ready to Implement
diff --git a/docs/z3ed/LLM-INTEGRATION-PLAN.md b/docs/z3ed/LLM-INTEGRATION-PLAN.md
new file mode 100644
index 00000000..3474bcaa
--- /dev/null
+++ b/docs/z3ed/LLM-INTEGRATION-PLAN.md
@@ -0,0 +1,1048 @@
+# LLM Integration Plan for z3ed Agent System
+
+**Status**: Implementation Ready | Priority: High  
+**Created**: October 3, 2025  
+**Estimated Time**: 12-15 hours
+
+## Executive Summary
+
+This document outlines the practical implementation plan for integrating LLM capabilities into the z3ed agent system. The infrastructure is **already in place** with the `AIService` interface, `MockAIService` for testing, and a partially implemented `GeminiAIService`. This plan focuses on making LLM integration production-ready with both local (Ollama) and remote (Gemini, Claude) options.
+
+**Current State**:
+- ✅ `AIService` interface defined (`src/cli/service/ai_service.h`)
+- ✅ `MockAIService` operational (returns hardcoded test commands)
+- ✅ `GeminiAIService` skeleton implemented (needs fixes + proper prompting)
+- ✅ Agent workflow fully functional with proposal system
+- ✅ Resource catalogue (command schemas) ready for LLM consumption
+- ✅ GUI automation harness operational for verification
+
+**What's Missing**:
+- 🔧 Ollama integration for local LLM support
+- 🔧 Improved Gemini prompting with resource catalogue
+- 🔧 Claude API integration as alternative remote option
+- 🔧 AI service selection mechanism (env vars + CLI flags)
+- 🔧 Proper prompt engineering with system instructions
+- 🔧 Error handling and retry logic for API failures
+- 🔧 Token usage monitoring and cost tracking
+
+---
+
+## 1. Implementation Priorities
+
+### Phase 1: Ollama Local Integration (4-6 hours) 🎯 START HERE
+
+**Rationale**: Ollama provides the fastest path to a working LLM agent with no API keys, costs, or rate limits. Perfect for development and testing.
+
+**Benefits**:
+- **Privacy**: All processing happens locally
+- **Zero Cost**: No API charges or token limits
+- **Offline**: Works without internet connection
+- **Fast Iteration**: No rate limits for testing
+- **Model Flexibility**: Easily swap between codellama, llama3, qwen2.5-coder, etc.
+
+#### 1.1. Create OllamaAIService Class
+
+**File**: `src/cli/service/ollama_ai_service.h`
+
+```cpp
+#ifndef YAZE_SRC_CLI_OLLAMA_AI_SERVICE_H_
+#define YAZE_SRC_CLI_OLLAMA_AI_SERVICE_H_
+
+#include <string>
+#include <vector>
+
+#include "absl/status/status.h"
+#include "absl/status/statusor.h"
+#include "cli/service/ai_service.h"
+
+namespace yaze {
+namespace cli {
+
+// Ollama configuration for local LLM inference
+struct OllamaConfig {
+  std::string base_url = "http://localhost:11434";  // Default Ollama endpoint
+  std::string model = "qwen2.5-coder:7b";           // Recommended for code generation
+  float temperature = 0.1;                          // Low temp for deterministic commands
+  int max_tokens = 2048;                            // Sufficient for command lists
+  std::string system_prompt;                        // Injected from resource catalogue
+};
+
+class OllamaAIService : public AIService {
+ public:
+  explicit OllamaAIService(const OllamaConfig& config);
+  
+  // Generate z3ed commands from natural language prompt
+  absl::StatusOr<std::vector<std::string>> GetCommands(
+      const std::string& prompt) override;
+  
+  // Health check: verify Ollama server is running and model is available
+  absl::Status CheckAvailability();
+  
+  // List available models on Ollama server
+  absl::StatusOr<std::vector<std::string>> ListAvailableModels();
+
+ private:
+  OllamaConfig config_;
+  
+  // Build system prompt from resource catalogue
+  std::string BuildSystemPrompt();
+  
+  // Parse JSON response from Ollama API
+  absl::StatusOr<std::string> ParseOllamaResponse(const std::string& json_response);
+};
+
+}  // namespace cli
+}  // namespace yaze
+
+#endif  // YAZE_SRC_CLI_OLLAMA_AI_SERVICE_H_
+```
+
+**File**: `src/cli/service/ollama_ai_service.cc`
+
+```cpp
+#include "cli/service/ollama_ai_service.h"
+
+#include <cstdlib>
+
+#include "absl/strings/str_cat.h"
+#include "absl/strings/str_format.h"
+
+#ifdef YAZE_WITH_HTTPLIB
+#include "incl/httplib.h"
+#include "third_party/json/src/json.hpp"
+#endif
+
+namespace yaze {
+namespace cli {
+
+OllamaAIService::OllamaAIService(const OllamaConfig& config) : config_(config) {
+  if (config_.system_prompt.empty()) {
+    config_.system_prompt = BuildSystemPrompt();
+  }
+}
+
+std::string OllamaAIService::BuildSystemPrompt() {
+  // TODO: Read from docs/api/z3ed-resources.yaml
+  return R"(You are an expert ROM hacking assistant for The Legend of Zelda: A Link to the Past.
+Your role is to generate PRECISE z3ed CLI commands to fulfill user requests.
+
+CRITICAL RULES:
+1. Output ONLY a JSON array of command strings
+2. Each command must follow exact z3ed syntax
+3. Commands must be executable without modification
+4. Use only commands from the available command set
+5. Include all required arguments with proper flags
+
+AVAILABLE COMMANDS:
+- rom info --rom <path>
+- rom validate --rom <path>
+- palette export --group <group> --id <id> --to <file>
+- palette import --group <group> --id <id> --from <file>
+- palette set-color --file <file> --index <index> --color <hex_color>
+- overworld get-tile --map <map_id> --x <x> --y <y>
+- overworld set-tile --map <map_id> --x <x> --y <y> --tile <tile_id>
+- dungeon export-room --room <room_id> --to <file>
+- dungeon import-room --room <room_id> --from <file>
+
+RESPONSE FORMAT:
+["command1", "command2", "command3"]
+
+EXAMPLE USER REQUEST: "Make all soldier armors red"
+CORRECT RESPONSE:
+["palette export --group sprites --id soldier --to /tmp/soldier.pal",
+ "palette set-color --file /tmp/soldier.pal --index 5 --color FF0000",
+ "palette import --group sprites --id soldier --from /tmp/soldier.pal"]
+
+Begin your response now.)";
+}
+
+absl::Status OllamaAIService::CheckAvailability() {
+#ifndef YAZE_WITH_HTTPLIB
+  return absl::UnimplementedError(
+      "Ollama service requires httplib. Build with vcpkg or system httplib.");
+#else
+  try {
+    httplib::Client cli(config_.base_url);
+    cli.set_connection_timeout(5);  // 5 second timeout
+    
+    auto res = cli.Get("/api/tags");
+    if (!res) {
+      return absl::UnavailableError(absl::StrFormat(
+          "Cannot connect to Ollama server at %s. "
+          "Make sure Ollama is installed and running (ollama serve).",
+          config_.base_url));
+    }
+    
+    if (res->status != 200) {
+      return absl::InternalError(absl::StrFormat(
+          "Ollama server error: HTTP %d", res->status));
+    }
+    
+    // Check if requested model is available
+    nlohmann::json models_json = nlohmann::json::parse(res->body);
+    bool model_found = false;
+    for (const auto& model : models_json["models"]) {
+      if (model["name"].get<std::string>().find(config_.model) != std::string::npos) {
+        model_found = true;
+        break;
+      }
+    }
+    
+    if (!model_found) {
+      return absl::NotFoundError(absl::StrFormat(
+          "Model '%s' not found. Pull it with: ollama pull %s",
+          config_.model, config_.model));
+    }
+    
+    return absl::OkStatus();
+  } catch (const std::exception& e) {
+    return absl::InternalError(absl::StrCat("Ollama check failed: ", e.what()));
+  }
+#endif
+}
+
+absl::StatusOr<std::vector<std::string>> OllamaAIService::ListAvailableModels() {
+#ifndef YAZE_WITH_HTTPLIB
+  return absl::UnimplementedError("Requires httplib support");
+#else
+  httplib::Client cli(config_.base_url);
+  auto res = cli.Get("/api/tags");
+  
+  if (!res || res->status != 200) {
+    return absl::UnavailableError("Cannot list Ollama models");
+  }
+  
+  nlohmann::json models_json = nlohmann::json::parse(res->body);
+  std::vector<std::string> models;
+  for (const auto& model : models_json["models"]) {
+    models.push_back(model["name"].get<std::string>());
+  }
+  return models;
+#endif
+}
+
+absl::StatusOr<std::vector<std::string>> OllamaAIService::GetCommands(
+    const std::string& prompt) {
+#ifndef YAZE_WITH_HTTPLIB
+  return absl::UnimplementedError(
+      "Ollama service requires httplib. Build with vcpkg or system httplib.");
+#else
+  
+  // Build request payload
+  nlohmann::json request_body = {
+    {"model", config_.model},
+    {"prompt", config_.system_prompt + "\n\nUSER REQUEST: " + prompt},
+    {"stream", false},
+    {"temperature", config_.temperature},
+    {"max_tokens", config_.max_tokens},
+    {"format", "json"}  // Force JSON output
+  };
+  
+  httplib::Client cli(config_.base_url);
+  cli.set_read_timeout(60);  // Longer timeout for inference
+  
+  auto res = cli.Post("/api/generate", request_body.dump(), "application/json");
+  
+  if (!res) {
+    return absl::UnavailableError(
+        "Failed to connect to Ollama. Is 'ollama serve' running?");
+  }
+  
+  if (res->status != 200) {
+    return absl::InternalError(absl::StrFormat(
+        "Ollama API error: HTTP %d - %s", res->status, res->body));
+  }
+  
+  // Parse response
+  try {
+    nlohmann::json response_json = nlohmann::json::parse(res->body);
+    std::string generated_text = response_json["response"].get<std::string>();
+    
+    // Parse the command array from generated text
+    nlohmann::json commands_json = nlohmann::json::parse(generated_text);
+    
+    if (!commands_json.is_array()) {
+      return absl::InvalidArgumentError(
+          "LLM did not return a JSON array. Response: " + generated_text);
+    }
+    
+    std::vector<std::string> commands;
+    for (const auto& cmd : commands_json) {
+      if (cmd.is_string()) {
+        commands.push_back(cmd.get<std::string>());
+      }
+    }
+    
+    if (commands.empty()) {
+      return absl::InvalidArgumentError(
+          "LLM returned empty command list. Prompt may be unclear.");
+    }
+    
+    return commands;
+    
+  } catch (const nlohmann::json::exception& e) {
+    return absl::InternalError(absl::StrCat(
+        "Failed to parse Ollama response: ", e.what(), "\nRaw: ", res->body));
+  }
+#endif
+}
+
+}  // namespace cli
+}  // namespace yaze
+```
+
+#### 1.2. Add CMake Configuration
+
+**File**: `CMakeLists.txt` (add to dependencies section)
+
+```cmake
+# Optional httplib for AI services (Ollama, Gemini)
+option(YAZE_WITH_HTTPLIB "Enable HTTP client for AI services" ON)
+
+if(YAZE_WITH_HTTPLIB)
+  find_package(httplib CONFIG)
+  if(httplib_FOUND)
+    set(YAZE_WITH_HTTPLIB ON)
+    add_compile_definitions(YAZE_WITH_HTTPLIB)
+    message(STATUS "httplib found - AI services enabled")
+  else()
+    # Try to use bundled httplib from third_party
+    if(EXISTS "${CMAKE_SOURCE_DIR}/third_party/httplib")
+      set(YAZE_WITH_HTTPLIB ON)
+      add_compile_definitions(YAZE_WITH_HTTPLIB)
+      message(STATUS "Using bundled httplib - AI services enabled")
+    else()
+      set(YAZE_WITH_HTTPLIB OFF)
+      message(WARNING "httplib not found - AI services disabled")
+    endif()
+  endif()
+endif()
+```
+
+#### 1.3. Wire into Agent Commands
+
+**File**: `src/cli/handlers/agent/general_commands.cc`
+
+Replace hardcoded `MockAIService` usage with service selection:
+
+```cpp
+#include "cli/service/ollama_ai_service.h"
+#include "cli/service/gemini_ai_service.h"
+
+// Helper: Select AI service based on environment
+std::unique_ptr<AIService> CreateAIService() {
+  // Priority: Ollama (local) > Gemini (remote) > Mock (testing)
+  
+  const char* ollama_env = std::getenv("YAZE_AI_PROVIDER");
+  const char* gemini_key = std::getenv("GEMINI_API_KEY");
+  
+  // Explicit provider selection
+  if (ollama_env && std::string(ollama_env) == "ollama") {
+    OllamaConfig config;
+    // Allow model override via env
+    if (const char* model = std::getenv("OLLAMA_MODEL")) {
+      config.model = model;
+    }
+    auto service = std::make_unique<OllamaAIService>(config);
+    
+    // Health check
+    if (auto status = service->CheckAvailability(); !status.ok()) {
+      std::cerr << "⚠️  Ollama unavailable: " << status.message() << std::endl;
+      std::cerr << "   Falling back to MockAIService" << std::endl;
+      return std::make_unique<MockAIService>();
+    }
+    
+    std::cout << "🤖 Using Ollama AI with model: " << config.model << std::endl;
+    return service;
+  }
+  
+  // Gemini if API key provided
+  if (gemini_key && std::strlen(gemini_key) > 0) {
+    std::cout << "🤖 Using Gemini AI (remote)" << std::endl;
+    return std::make_unique<GeminiAIService>(gemini_key);
+  }
+  
+  // Default: Mock service for testing
+  std::cout << "🤖 Using MockAIService (no LLM configured)" << std::endl;
+  std::cout << "   Set YAZE_AI_PROVIDER=ollama or GEMINI_API_KEY to enable LLM" << std::endl;
+  return std::make_unique<MockAIService>();
+}
+
+// Update HandleRunCommand:
+absl::Status HandleRunCommand(const std::vector<std::string>& arg_vec) {
+  // ... existing setup code ...
+  
+  auto ai_service = CreateAIService();  // ← Replace MockAIService instantiation
+  auto commands_or = ai_service->GetCommands(prompt);
+  
+  // ... rest of execution logic ...
+}
+```
+
+#### 1.4. Testing & Validation
+
+**Prerequisites**:
+```bash
+# Install Ollama (macOS)
+brew install ollama
+
+# Start Ollama server
+ollama serve &
+
+# Pull recommended model
+ollama pull qwen2.5-coder:7b
+
+# Test connectivity
+curl http://localhost:11434/api/tags
+```
+
+**End-to-End Test Script** (`scripts/test_ollama_integration.sh`):
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🧪 Testing Ollama AI Integration"
+
+# 1. Check Ollama availability
+echo "Checking Ollama server..."
+if ! curl -s http://localhost:11434/api/tags > /dev/null; then
+  echo "❌ Ollama not running. Start with: ollama serve"
+  exit 1
+fi
+
+# 2. Check model availability
+echo "Checking qwen2.5-coder:7b model..."
+if ! ollama list | grep -q "qwen2.5-coder:7b"; then
+  echo "⚠️  Model not found. Pulling..."
+  ollama pull qwen2.5-coder:7b
+fi
+
+# 3. Test agent run with simple prompt
+echo "Testing agent run command..."
+export YAZE_AI_PROVIDER=ollama
+export OLLAMA_MODEL=qwen2.5-coder:7b
+
+./build/bin/z3ed agent run \
+  --prompt "Export the first overworld palette to /tmp/test.pal" \
+  --rom zelda3.sfc \
+  --sandbox
+
+# 4. Verify proposal created
+echo "Checking proposal registry..."
+if ! ./build/bin/z3ed agent list | grep -q "pending"; then
+  echo "❌ No pending proposal found"
+  exit 1
+fi
+
+# 5. Review generated commands
+echo "✅ Reviewing generated commands..."
+./build/bin/z3ed agent diff --format yaml
+
+echo "✅ Ollama integration test passed!"
+```
+
+---
+
+### Phase 2: Improve Gemini Integration (2-3 hours)
+
+The existing `GeminiAIService` needs fixes and better prompting:
+
+#### 2.1. Fix GeminiAIService Implementation
+
+**File**: `src/cli/service/gemini_ai_service.cc`
+
+```cpp
+absl::StatusOr<std::vector<std::string>> GeminiAIService::GetCommands(
+    const std::string& prompt) {
+#ifndef YAZE_WITH_HTTPLIB
+  return absl::UnimplementedError(
+      "Gemini AI service requires httplib. Build with vcpkg.");
+#else
+  if (api_key_.empty()) {
+    return absl::FailedPreconditionError(
+        "GEMINI_API_KEY not set. Get key from: https://makersuite.google.com/app/apikey");
+  }
+
+  // Build comprehensive system instruction
+  std::string system_instruction = R"({
+    "role": "system",
+    "content": "You are an expert ROM hacking assistant for The Legend of Zelda: A Link to the Past. Generate ONLY a JSON array of z3ed CLI commands. Each command must be executable without modification. Available commands: rom info, rom validate, palette export/import/set-color, overworld get-tile/set-tile, dungeon export-room/import-room. Response format: [\"command1\", \"command2\"]"
+  })";
+
+  httplib::Client cli("https://generativelanguage.googleapis.com");
+  cli.set_read_timeout(60);
+  
+  nlohmann::json request_body = {
+    {"contents", {{
+      {"role", "user"},
+      {"parts", {{
+        {"text", absl::StrFormat("System: %s\n\nUser: %s", 
+                                 system_instruction, prompt)}
+      }}}
+    }}},
+    {"generationConfig", {
+      {"temperature", 0.1},          // Low temp for deterministic output
+      {"maxOutputTokens", 2048},
+      {"topP", 0.8},
+      {"topK", 10}
+    }},
+    {"safetySettings", {
+      {{"category", "HARM_CATEGORY_DANGEROUS_CONTENT"}, {"threshold", "BLOCK_NONE"}}
+    }}
+  };
+
+  httplib::Headers headers = {
+      {"Content-Type", "application/json"},
+  };
+  
+  std::string endpoint = absl::StrFormat(
+      "/v1beta/models/gemini-1.5-flash:generateContent?key=%s", api_key_);
+
+  auto res = cli.Post(endpoint, headers, request_body.dump(), "application/json");
+
+  if (!res) {
+    return absl::UnavailableError(
+        "Failed to connect to Gemini API. Check internet connection.");
+  }
+
+  if (res->status != 200) {
+    return absl::InternalError(absl::StrFormat(
+        "Gemini API error: HTTP %d - %s", res->status, res->body));
+  }
+
+  // Parse response
+  try {
+    nlohmann::json response_json = nlohmann::json::parse(res->body);
+    
+    // Extract text from nested structure
+    std::string text_content = 
+        response_json["candidates"][0]["content"]["parts"][0]["text"]
+        .get<std::string>();
+    
+    // Gemini may wrap JSON in markdown code blocks - strip them
+    if (text_content.find("```json") != std::string::npos) {
+      size_t start = text_content.find("[");
+      size_t end = text_content.rfind("]");
+      if (start != std::string::npos && end != std::string::npos) {
+        text_content = text_content.substr(start, end - start + 1);
+      }
+    }
+    
+    nlohmann::json commands_array = nlohmann::json::parse(text_content);
+    
+    if (!commands_array.is_array()) {
+      return absl::InvalidArgumentError(
+          "Gemini did not return a JSON array. Response: " + text_content);
+    }
+    
+    std::vector<std::string> commands;
+    for (const auto& cmd : commands_array) {
+      if (cmd.is_string()) {
+        commands.push_back(cmd.get<std::string>());
+      }
+    }
+    
+    return commands;
+    
+  } catch (const nlohmann::json::exception& e) {
+    return absl::InternalError(absl::StrCat(
+        "Failed to parse Gemini response: ", e.what(), "\nRaw: ", res->body));
+  }
+#endif
+}
+```
+
+---
+
+### Phase 3: Add Claude Integration (2-3 hours)
+
+Claude 3.5 Sonnet is excellent for code generation and has a generous free tier.
+
+#### 3.1. Create ClaudeAIService
+
+**File**: `src/cli/service/claude_ai_service.h`
+
+```cpp
+#ifndef YAZE_SRC_CLI_CLAUDE_AI_SERVICE_H_
+#define YAZE_SRC_CLI_CLAUDE_AI_SERVICE_H_
+
+#include <string>
+#include <vector>
+
+#include "absl/status/statusor.h"
+#include "cli/service/ai_service.h"
+
+namespace yaze {
+namespace cli {
+
+class ClaudeAIService : public AIService {
+ public:
+  explicit ClaudeAIService(const std::string& api_key);
+  
+  absl::StatusOr<std::vector<std::string>> GetCommands(
+      const std::string& prompt) override;
+
+ private:
+  std::string api_key_;
+  std::string model_ = "claude-3-5-sonnet-20241022";  // Latest version
+};
+
+}  // namespace cli
+}  // namespace yaze
+
+#endif  // YAZE_SRC_CLI_CLAUDE_AI_SERVICE_H_
+```
+
+**File**: `src/cli/service/claude_ai_service.cc`
+
+```cpp
+#include "cli/service/claude_ai_service.h"
+
+#include "absl/strings/str_format.h"
+
+#ifdef YAZE_WITH_HTTPLIB
+#include "incl/httplib.h"
+#include "third_party/json/src/json.hpp"
+#endif
+
+namespace yaze {
+namespace cli {
+
+ClaudeAIService::ClaudeAIService(const std::string& api_key) 
+    : api_key_(api_key) {}
+
+absl::StatusOr<std::vector<std::string>> ClaudeAIService::GetCommands(
+    const std::string& prompt) {
+#ifndef YAZE_WITH_HTTPLIB
+  return absl::UnimplementedError("Claude service requires httplib");
+#else
+  if (api_key_.empty()) {
+    return absl::FailedPreconditionError(
+        "CLAUDE_API_KEY not set. Get key from: https://console.anthropic.com/");
+  }
+
+  httplib::Client cli("https://api.anthropic.com");
+  cli.set_read_timeout(60);
+  
+  nlohmann::json request_body = {
+    {"model", model_},
+    {"max_tokens", 2048},
+    {"temperature", 0.1},
+    {"system", "You are an expert ROM hacking assistant. Generate ONLY a JSON array of z3ed commands. No explanations."},
+    {"messages", {{
+      {"role", "user"},
+      {"content", prompt}
+    }}}
+  };
+
+  httplib::Headers headers = {
+    {"Content-Type", "application/json"},
+    {"x-api-key", api_key_},
+    {"anthropic-version", "2023-06-01"}
+  };
+
+  auto res = cli.Post("/v1/messages", headers, request_body.dump(), 
+                      "application/json");
+
+  if (!res) {
+    return absl::UnavailableError("Failed to connect to Claude API");
+  }
+
+  if (res->status != 200) {
+    return absl::InternalError(absl::StrFormat(
+        "Claude API error: HTTP %d - %s", res->status, res->body));
+  }
+
+  try {
+    nlohmann::json response_json = nlohmann::json::parse(res->body);
+    std::string text_content = 
+        response_json["content"][0]["text"].get<std::string>();
+    
+    // Claude may wrap in markdown - strip if present
+    if (text_content.find("```json") != std::string::npos) {
+      size_t start = text_content.find("[");
+      size_t end = text_content.rfind("]");
+      if (start != std::string::npos && end != std::string::npos) {
+        text_content = text_content.substr(start, end - start + 1);
+      }
+    }
+    
+    nlohmann::json commands_json = nlohmann::json::parse(text_content);
+    
+    std::vector<std::string> commands;
+    for (const auto& cmd : commands_json) {
+      if (cmd.is_string()) {
+        commands.push_back(cmd.get<std::string>());
+      }
+    }
+    
+    return commands;
+    
+  } catch (const std::exception& e) {
+    return absl::InternalError(absl::StrCat(
+        "Failed to parse Claude response: ", e.what()));
+  }
+#endif
+}
+
+}  // namespace cli
+}  // namespace yaze
+```
+
+---
+
+### Phase 4: Enhanced Prompt Engineering (3-4 hours)
+
+#### 4.1. Load Resource Catalogue into System Prompt
+
+**File**: `src/cli/service/prompt_builder.h`
+
+```cpp
+#ifndef YAZE_SRC_CLI_PROMPT_BUILDER_H_
+#define YAZE_SRC_CLI_PROMPT_BUILDER_H_
+
+#include <string>
+#include "absl/status/statusor.h"
+
+namespace yaze {
+namespace cli {
+
+// Utility for building comprehensive LLM prompts from resource catalogue
+class PromptBuilder {
+ public:
+  // Load command schemas from docs/api/z3ed-resources.yaml
+  static absl::StatusOr<std::string> LoadResourceCatalogue();
+  
+  // Build system prompt with full command documentation
+  static std::string BuildSystemPrompt();
+  
+  // Build few-shot examples for better LLM performance
+  static std::string BuildFewShotExamples();
+  
+  // Inject ROM context (current ROM info, loaded editors, etc.)
+  static std::string BuildContextPrompt();
+};
+
+}  // namespace cli
+}  // namespace yaze
+
+#endif  // YAZE_SRC_CLI_PROMPT_BUILDER_H_
+```
+
+#### 4.2. Few-Shot Examples
+
+Include proven examples in system prompt:
+
+```cpp
+std::string PromptBuilder::BuildFewShotExamples() {
+  return R"(
+EXAMPLE 1:
+User: "Make soldier armor red"
+Response: ["palette export --group sprites --id soldier --to /tmp/soldier.pal", 
+           "palette set-color --file /tmp/soldier.pal --index 5 --color FF0000",
+           "palette import --group sprites --id soldier --from /tmp/soldier.pal"]
+
+EXAMPLE 2:
+User: "Validate ROM integrity"
+Response: ["rom validate --rom zelda3.sfc"]
+
+EXAMPLE 3:
+User: "Change tile at coordinates (10, 20) in Light World to grass"
+Response: ["overworld set-tile --map 0 --x 10 --y 20 --tile 0x40"]
+)";
+}
+```
+
+---
+
+## 2. Configuration & User Experience
+
+### Environment Variables
+
+```bash
+# AI Provider Selection
+export YAZE_AI_PROVIDER=ollama    # Options: ollama, gemini, claude, mock
+export OLLAMA_MODEL=qwen2.5-coder:7b
+export OLLAMA_URL=http://localhost:11434
+
+# API Keys (remote providers)
+export GEMINI_API_KEY=your_key_here
+export CLAUDE_API_KEY=your_key_here
+
+# Logging & Debugging
+export YAZE_AI_DEBUG=1            # Log full prompts and responses
+export YAZE_AI_CACHE_DIR=/tmp/yaze_ai_cache  # Cache LLM responses
+```
+
+### CLI Flags
+
+Add new flags to `z3ed agent run`:
+
+```bash
+# Override provider for single command
+z3ed agent run --prompt "..." --ai-provider ollama
+
+# Override model
+z3ed agent run --prompt "..." --ai-model "llama3:70b"
+
+# Dry run: show generated commands without executing
+z3ed agent run --prompt "..." --dry-run
+
+# Interactive mode: confirm each command before execution
+z3ed agent run --prompt "..." --interactive
+```
+
+---
+
+## 3. Testing & Validation
+
+### Unit Tests
+
+**File**: `test/cli/ai_service_test.cc`
+
+```cpp
+#include "cli/service/ollama_ai_service.h"
+#include "cli/service/gemini_ai_service.h"
+#include "cli/service/claude_ai_service.h"
+#include <gtest/gtest.h>
+
+TEST(OllamaAIServiceTest, CheckAvailability) {
+  OllamaConfig config;
+  config.base_url = "http://localhost:11434";
+  OllamaAIService service(config);
+  
+  // Should not crash, may return unavailable if Ollama not running
+  auto status = service.CheckAvailability();
+  EXPECT_TRUE(status.ok() || 
+              absl::IsUnavailable(status) || 
+              absl::IsNotFound(status));
+}
+
+TEST(OllamaAIServiceTest, GetCommands) {
+  // Skip if Ollama not available
+  OllamaConfig config;
+  OllamaAIService service(config);
+  if (!service.CheckAvailability().ok()) {
+    GTEST_SKIP() << "Ollama not available";
+  }
+  
+  auto result = service.GetCommands("Validate the ROM");
+  ASSERT_TRUE(result.ok()) << result.status();
+  
+  auto commands = result.value();
+  EXPECT_GT(commands.size(), 0);
+  EXPECT_THAT(commands[0], testing::HasSubstr("rom validate"));
+}
+```
+
+### Integration Tests
+
+**File**: `scripts/test_ai_services.sh`
+
+```bash
+#!/bin/bash
+set -e
+
+echo "🧪 Testing AI Services Integration"
+
+# Test 1: Ollama (if available)
+if curl -s http://localhost:11434/api/tags > /dev/null 2>&1; then
+  echo "✓ Ollama available - testing..."
+  export YAZE_AI_PROVIDER=ollama
+  ./build/bin/z3ed agent plan --prompt "Export first palette"
+else
+  echo "⊘ Ollama not running - skipping"
+fi
+
+# Test 2: Gemini (if key set)
+if [ -n "$GEMINI_API_KEY" ]; then
+  echo "✓ Gemini API key set - testing..."
+  export YAZE_AI_PROVIDER=gemini
+  ./build/bin/z3ed agent plan --prompt "Validate ROM"
+else
+  echo "⊘ GEMINI_API_KEY not set - skipping"
+fi
+
+# Test 3: Claude (if key set)
+if [ -n "$CLAUDE_API_KEY" ]; then
+  echo "✓ Claude API key set - testing..."
+  export YAZE_AI_PROVIDER=claude
+  ./build/bin/z3ed agent plan --prompt "Export dungeon room"
+else
+  echo "⊘ CLAUDE_API_KEY not set - skipping"
+fi
+
+echo "✅ All available AI services tested successfully"
+```
+
+---
+
+## 4. Documentation Updates
+
+### User Guide
+
+**File**: `docs/z3ed/AI-SERVICE-SETUP.md`
+
+```markdown
+# Setting Up LLM Integration for z3ed
+
+## Quick Start: Ollama (Recommended)
+
+1. **Install Ollama**:
+   ```bash
+   # macOS
+   brew install ollama
+   
+   # Linux
+   curl -fsSL https://ollama.com/install.sh | sh
+   ```
+
+2. **Start Server**:
+   ```bash
+   ollama serve
+   ```
+
+3. **Pull Model**:
+   ```bash
+   ollama pull qwen2.5-coder:7b  # Recommended: fast + accurate
+   ```
+
+4. **Configure z3ed**:
+   ```bash
+   export YAZE_AI_PROVIDER=ollama
+   ```
+
+5. **Test**:
+   ```bash
+   z3ed agent run --prompt "Validate my ROM" --rom zelda3.sfc
+   ```
+
+## Alternative: Gemini API (Remote)
+
+1. Get API key: https://makersuite.google.com/app/apikey
+2. Configure:
+   ```bash
+   export GEMINI_API_KEY=your_key_here
+   export YAZE_AI_PROVIDER=gemini
+   ```
+3. Run: `z3ed agent run --prompt "..."`
+
+## Alternative: Claude API (Remote)
+
+1. Get API key: https://console.anthropic.com/
+2. Configure:
+   ```bash
+   export CLAUDE_API_KEY=your_key_here
+   export YAZE_AI_PROVIDER=claude
+   ```
+3. Run: `z3ed agent run --prompt "..."`
+
+## Troubleshooting
+
+**Issue**: "Cannot connect to Ollama"  
+**Solution**: Make sure `ollama serve` is running
+
+**Issue**: "Model not found"  
+**Solution**: Run `ollama pull <model_name>`
+
+**Issue**: "LLM returned empty command list"  
+**Solution**: Rephrase prompt to be more specific
+```
+
+---
+
+## 5. Implementation Timeline
+
+### Week 1 (October 7-11)
+- **Day 1-2**: Implement `OllamaAIService` class
+- **Day 3**: Wire into agent commands with service selection
+- **Day 4**: Testing and validation
+- **Day 5**: Documentation and examples
+
+### Week 2 (October 14-18)
+- **Day 1**: Fix and improve `GeminiAIService`
+- **Day 2**: Implement `ClaudeAIService`
+- **Day 3**: Enhanced prompt engineering with resource catalogue
+- **Day 4**: Integration tests across all services
+- **Day 5**: User guide and troubleshooting docs
+
+---
+
+## 6. Success Criteria
+
+✅ **Phase 1 Complete When**:
+- Ollama service connects and generates valid commands
+- `z3ed agent run` works end-to-end with local LLM
+- Health checks report clear error messages
+- Test script passes on macOS with Ollama installed
+
+✅ **Phase 2 Complete When**:
+- Gemini API calls succeed with valid responses
+- Markdown code block stripping works reliably
+- Error messages are actionable (e.g., "API key invalid")
+
+✅ **Phase 3 Complete When**:
+- Claude service implemented with same interface
+- All three services (Ollama, Gemini, Claude) work interchangeably
+- Service selection mechanism is transparent to user
+
+✅ **Phase 4 Complete When**:
+- System prompts include full resource catalogue
+- Few-shot examples improve command accuracy >90%
+- LLM responses consistently match expected command format
+
+---
+
+## 7. Future Enhancements (Post-MVP)
+
+- **Response Caching**: Cache LLM responses by prompt hash to reduce costs/latency
+- **Token Usage Tracking**: Monitor and report token consumption per session
+- **Model Comparison**: A/B test different models for accuracy/cost trade-offs
+- **Fine-Tuning**: Fine-tune local models on z3ed command corpus
+- **Multi-Turn Dialogue**: Support follow-up questions and clarifications
+- **Agentic Loop**: LLM self-corrects based on execution results
+- **GUI Integration**: In-app AI assistant panel in YAZE editor
+
+---
+
+## Appendix A: Recommended Models
+
+| Model | Provider | Size | Speed | Accuracy | Use Case |
+|-------|----------|------|-------|----------|----------|
+| qwen2.5-coder:7b | Ollama | 7B | Fast | High | **Recommended**: Best balance |
+| codellama:13b | Ollama | 13B | Medium | Higher | Complex tasks |
+| llama3:70b | Ollama | 70B | Slow | Highest | Maximum accuracy |
+| gemini-1.5-flash | Gemini | N/A | Fast | High | Remote option, low cost |
+| claude-3.5-sonnet | Claude | N/A | Medium | Highest | Premium remote option |
+
+## Appendix B: Example Prompts
+
+**Simple**:
+- "Validate the ROM"
+- "Export the first palette"
+- "Show ROM info"
+
+**Moderate**:
+- "Make soldier armor red"
+- "Change tile at (10, 20) in Light World to grass"
+- "Export dungeon room 5 to /tmp/room5.bin"
+
+**Complex**:
+- "Find all palettes using color #FF0000 and change to #00FF00"
+- "Export all dungeon rooms, modify object 3 in each, then reimport"
+- "Generate a comparison report between two ROM versions"
+
+---
+
+## Next Steps
+
+**👉 START HERE**: Implement Phase 1 (Ollama Integration) by following section 1.1-1.4 above.
+
+Once complete, update this document with:
+- Actual time spent vs. estimates
+- Issues encountered and solutions
+- Model performance observations
+- User feedback
+
+**Questions? Blockers?** Open an issue or ping @scawful in Discord.
diff --git a/docs/z3ed/LLM-INTEGRATION-SUMMARY.md b/docs/z3ed/LLM-INTEGRATION-SUMMARY.md
new file mode 100644
index 00000000..0aa5f114
--- /dev/null
+++ b/docs/z3ed/LLM-INTEGRATION-SUMMARY.md
@@ -0,0 +1,311 @@
+# LLM Integration: Executive Summary & Getting Started
+
+**Date**: October 3, 2025  
+**Author**: GitHub Copilot  
+**Status**: Ready to Implement
+
+## What Changed?
+
+After reviewing the z3ed CLI design and implementation plan, we've **deprioritized IT-10 (Collaborative Editing)** in favor of **practical LLM integration**. This is the critical next step to make the agentic workflow system production-ready.
+
+## Why This Matters
+
+The z3ed infrastructure is **already complete**:
+- ✅ Resource-oriented CLI with comprehensive commands
+- ✅ Proposal-based workflow with sandbox execution
+- ✅ Machine-readable API catalogue (`z3ed-resources.yaml`)
+- ✅ GUI automation harness for verification
+- ✅ ProposalDrawer for human review
+
+**What's missing**: Real LLM integration to turn prompts into actions.
+
+Currently, `z3ed agent run` uses `MockAIService` which returns hardcoded test commands. We need to connect real LLMs (Ollama, Gemini, Claude) to make the agent system useful.
+
+## What You Get
+
+After implementing this plan, users will be able to:
+
+```bash
+# Install Ollama (one-time setup)
+brew install ollama
+ollama serve &
+ollama pull qwen2.5-coder:7b
+
+# Configure z3ed
+export YAZE_AI_PROVIDER=ollama
+
+# Use natural language to modify ROMs
+z3ed agent run \
+  --prompt "Make all soldier armor red" \
+  --rom zelda3.sfc \
+  --sandbox
+
+# Review generated commands
+z3ed agent diff
+
+# Accept changes
+# (Open YAZE GUI → Debug → Agent Proposals → Review → Accept)
+```
+
+The LLM will automatically:
+1. Parse the natural language prompt
+2. Generate appropriate `z3ed` commands
+3. Execute them in a sandbox
+4. Present results for human review
+
+## Implementation Roadmap
+
+### Phase 1: Ollama Integration (4-6 hours) 🎯 START HERE
+**Priority**: Highest  
+**Why First**: Local, free, no API keys, fast iteration
+
+**Deliverables**:
+- `OllamaAIService` class with health checks
+- CMake integration for httplib
+- Service selection mechanism (env vars)
+- End-to-end test script
+
+**Key Files**:
+- `src/cli/service/ollama_ai_service.{h,cc}` (new)
+- `src/cli/handlers/agent/general_commands.cc` (update)
+- `CMakeLists.txt` (add httplib support)
+
+### Phase 2: Gemini Fixes (2-3 hours)
+**Deliverables**:
+- Fix existing `GeminiAIService` implementation
+- Better prompting with resource catalogue
+- Markdown code block stripping
+
+### Phase 3: Claude Integration (2-3 hours)
+**Deliverables**:
+- `ClaudeAIService` class
+- Messages API integration
+- Same interface as other services
+
+### Phase 4: Enhanced Prompting (3-4 hours)
+**Deliverables**:
+- `PromptBuilder` utility class
+- Resource catalogue integration
+- Few-shot examples
+- Context injection (ROM state)
+
+## Quick Start (After Implementation)
+
+### For Developers (Implement Now)
+
+1. **Read the implementation plan**:
+   - [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md) - Complete technical guide
+   - [LLM-IMPLEMENTATION-CHECKLIST.md](LLM-IMPLEMENTATION-CHECKLIST.md) - Step-by-step tasks
+
+2. **Start with Phase 1**:
+   ```bash
+   # Follow checklist in LLM-IMPLEMENTATION-CHECKLIST.md
+   # Implementation time: ~4-6 hours
+   ```
+
+3. **Test as you go**:
+   ```bash
+   # Run quickstart script when ready
+   ./scripts/quickstart_ollama.sh
+   ```
+
+### For End Users (After Development)
+
+1. **Install Ollama**:
+   ```bash
+   brew install ollama  # macOS
+   ollama serve &
+   ollama pull qwen2.5-coder:7b
+   ```
+
+2. **Configure z3ed**:
+   ```bash
+   export YAZE_AI_PROVIDER=ollama
+   ```
+
+3. **Try it out**:
+   ```bash
+   z3ed agent run --prompt "Validate my ROM" --rom zelda3.sfc
+   ```
+
+## Alternative Providers
+
+### Gemini (Remote, API Key Required)
+```bash
+export GEMINI_API_KEY=your_key_here
+export YAZE_AI_PROVIDER=gemini
+z3ed agent run --prompt "..."
+```
+
+### Claude (Remote, API Key Required)
+```bash
+export CLAUDE_API_KEY=your_key_here
+export YAZE_AI_PROVIDER=claude
+z3ed agent run --prompt "..."
+```
+
+## Documentation Structure
+
+```
+docs/z3ed/
+├── README.md                           # Overview + navigation
+├── E6-z3ed-cli-design.md               # Architecture & design
+├── E6-z3ed-implementation-plan.md      # Overall roadmap
+├── LLM-INTEGRATION-PLAN.md             # 📋 Detailed LLM guide (NEW)
+├── LLM-IMPLEMENTATION-CHECKLIST.md     # ✅ Step-by-step tasks (NEW)
+└── LLM-INTEGRATION-SUMMARY.md          # 📄 This file (NEW)
+
+scripts/
+└── quickstart_ollama.sh                # 🚀 Automated setup test (NEW)
+```
+
+## Key Architectural Decisions
+
+### 1. Service Interface Pattern
+All LLM providers implement the same `AIService` interface:
+
+```cpp
+class AIService {
+ public:
+  virtual absl::StatusOr<std::vector<std::string>> GetCommands(
+      const std::string& prompt) = 0;
+};
+```
+
+This allows easy swapping between Ollama, Gemini, Claude, or Mock.
+
+### 2. Environment-Based Selection
+Provider selection via environment variables (not compile-time):
+
+```bash
+export YAZE_AI_PROVIDER=ollama  # or gemini, claude, mock
+```
+
+This enables:
+- Easy testing with different providers
+- CI/CD with MockAIService
+- User choice without rebuilding
+
+### 3. Graceful Degradation
+If Ollama/Gemini/Claude unavailable, fall back to MockAIService with clear warnings:
+
+```
+⚠️  Ollama unavailable: Cannot connect to http://localhost:11434
+   Falling back to MockAIService
+   Set YAZE_AI_PROVIDER=ollama or install Ollama to enable LLM
+```
+
+### 4. System Prompt Engineering
+Comprehensive system prompts include:
+- Full command catalogue from `z3ed-resources.yaml`
+- Few-shot examples (proven prompt/command pairs)
+- Output format requirements (JSON array of strings)
+- Current ROM context (loaded file, editors open)
+
+This improves accuracy from ~60% to >90% for standard tasks.
+
+## Success Metrics
+
+### Phase 1 Complete When:
+- ✅ `z3ed agent run` works with Ollama end-to-end
+- ✅ Health checks report clear errors
+- ✅ Fallback to MockAIService is transparent
+- ✅ Test script passes on macOS
+
+### Full Integration Complete When:
+- ✅ All three providers (Ollama, Gemini, Claude) work
+- ✅ Command accuracy >90% on standard prompts
+- ✅ Documentation guides users through setup
+- ✅ At least one community member validates workflow
+
+## Known Limitations
+
+### Current Implementation
+- `MockAIService` returns hardcoded test commands
+- No real LLM integration yet
+- Limited to simple test cases
+
+### After LLM Integration
+- **Model hallucination**: LLMs may generate invalid commands
+  - Mitigation: Validation layer + resource catalogue
+- **API rate limits**: Remote providers (Gemini/Claude) have limits
+  - Mitigation: Response caching + local Ollama option
+- **Cost**: API calls cost money (Gemini ~$0.10/million tokens)
+  - Mitigation: Ollama is free + cache responses
+
+## FAQ
+
+### Why Ollama first?
+- **No API keys**: Works out of the box
+- **Privacy**: All processing local
+- **Speed**: No network latency
+- **Cost**: Zero dollars
+- **Testing**: No rate limits
+
+### Why not OpenAI?
+- Cost (GPT-4 is expensive)
+- Rate limits (strict for free tier)
+- Not local (privacy concerns for ROM hackers)
+- Ollama + Gemini cover both local and remote use cases
+
+### Can I use multiple providers?
+Yes! Set `YAZE_AI_PROVIDER` per command:
+
+```bash
+YAZE_AI_PROVIDER=ollama z3ed agent run --prompt "Quick test"
+YAZE_AI_PROVIDER=gemini z3ed agent run --prompt "Complex task"
+```
+
+### What if I don't want to use AI?
+The CLI still works without LLM integration:
+
+```bash
+# Direct command execution (no LLM)
+z3ed rom validate --rom zelda3.sfc
+z3ed palette export --group sprites --id soldier --to output.pal
+```
+
+AI is **optional** and additive.
+
+## Next Steps
+
+### For @scawful (Project Owner)
+1. **Review this plan**: Confirm priority shift from IT-10 to LLM integration
+2. **Decide on Phase 1**: Start Ollama implementation (~4-6 hours)
+3. **Allocate time**: Schedule implementation over next 1-2 weeks
+4. **Test setup**: Install Ollama and verify it works on your machine
+
+### For Contributors
+1. **Read the docs**: Start with [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md)
+2. **Pick a phase**: Phase 1 (Ollama) is the highest priority
+3. **Follow checklist**: Use [LLM-IMPLEMENTATION-CHECKLIST.md](LLM-IMPLEMENTATION-CHECKLIST.md)
+4. **Submit PR**: Include tests + documentation updates
+
+### For Users (Future)
+1. **Wait for release**: This is in development
+2. **Install Ollama**: Get ready for local LLM support
+3. **Follow setup guide**: Will be in `AI-SERVICE-SETUP.md` (coming soon)
+
+## Timeline
+
+**Week 1 (Oct 7-11, 2025)**: Phase 1 (Ollama)  
+**Week 2 (Oct 14-18, 2025)**: Phases 2-4 (Gemini, Claude, Prompting)  
+**Week 3 (Oct 21-25, 2025)**: Testing, docs, user validation
+
+**Estimated Total**: 12-15 hours of development time
+
+## Related Documents
+
+- **[LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md)** - Complete technical implementation guide
+- **[LLM-IMPLEMENTATION-CHECKLIST.md](LLM-IMPLEMENTATION-CHECKLIST.md)** - Step-by-step task list
+- **[E6-z3ed-cli-design.md](E6-z3ed-cli-design.md)** - Overall architecture
+- **[E6-z3ed-implementation-plan.md](E6-z3ed-implementation-plan.md)** - Project roadmap
+
+## Questions?
+
+Open an issue or discuss in the project's communication channel. Tag this as "LLM Integration" for visibility.
+
+---
+
+**Status**: Documentation Complete | Ready to Begin Implementation  
+**Next Action**: Start Phase 1 (Ollama Integration) using checklist
diff --git a/docs/z3ed/README.md b/docs/z3ed/README.md
index 04153444..503e71dd 100644
--- a/docs/z3ed/README.md
+++ b/docs/z3ed/README.md
@@ -12,7 +12,7 @@
 
 **🤖 Why This Matters**: These enhancements are **critical for AI agent autonomy**. Without them, AI agents can't verify their changes worked (no test polling), discover UI elements dynamically (hardcoded names), learn from demonstrations (no recording), or debug failures (no screenshots). The test harness evolution enables **fully autonomous agents** that can execute → verify → self-correct without human intervention.
 
-**📋 Implementation Status**: Core infrastructure complete (Phases 1-6, AW-01 to AW-04, IT-01 to IT-04). Currently in **Test Harness Enhancement Phase** (IT-05 to IT-09). See [IMPLEMENTATION_CONTINUATION.md](IMPLEMENTATION_CONTINUATION.md) for the detailed roadmap and LLM integration plans (Ollama, Gemini, Claude).
+**📋 Implementation Status**: Core infrastructure complete (Phases 1-6, AW-01 to AW-04, IT-01 to IT-09). Currently focusing on **LLM Integration** to enable practical AI-driven workflows. See [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md) for the detailed roadmap (Ollama, Gemini, Claude).
 
 This directory contains the primary documentation for the `z3ed` system.
 
@@ -81,6 +81,14 @@ See the **[Technical Reference](E6-z3ed-reference.md)** for a full command list.
 
 ## Recent Enhancements
 
+**LLM Integration Priority Shift (Oct 3, 2025)** 🤖
+- 📋 Deprioritized IT-10 (Collaborative Editing) in favor of practical LLM integration
+- 📄 Created comprehensive implementation plan for Ollama, Gemini, and Claude integration
+- ✅ New documentation: [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md), [LLM-IMPLEMENTATION-CHECKLIST.md](LLM-IMPLEMENTATION-CHECKLIST.md), [LLM-INTEGRATION-SUMMARY.md](LLM-INTEGRATION-SUMMARY.md)
+- 🚀 Ready to enable real AI-driven ROM modifications with natural language prompts
+- **Estimated effort**: 12-15 hours across 4 phases
+- **Why now**: All infrastructure complete (CLI, proposals, sandbox, GUI automation) - only LLM connection missing
+
 **Recent Progress (Oct 3, 2025)**
 - ✅ IT-09 CLI Test Suite Tooling Complete: run/validate/create commands + JUnit output
   - Full suite runner with group/tag filters, parametrization, retries, and CI-friendly exit codes
@@ -124,11 +132,12 @@ See **[E6-z3ed-cli-design.md § 9](E6-z3ed-cli-design.md#9-test-harness-evolutio
 **📖 Getting Started**:
 - **New to z3ed?** Start with this [README.md](README.md) then [E6-z3ed-cli-design.md](E6-z3ed-cli-design.md)
 - **Want to use z3ed?** See [QUICK_REFERENCE.md](QUICK_REFERENCE.md) for all commands
+- **Setting up AI agents?** See [LLM-INTEGRATION-PLAN.md](LLM-INTEGRATION-PLAN.md) for Ollama/Gemini/Claude setup
 
 **🔧 Implementation Guides**:
+- [LLM-IMPLEMENTATION-CHECKLIST.md](LLM-IMPLEMENTATION-CHECKLIST.md) - Step-by-step LLM integration tasks ⭐ START HERE
 - [IT-05-IMPLEMENTATION-GUIDE.md](IT-05-IMPLEMENTATION-GUIDE.md) - Test Introspection API (complete ✅)
-- [IT-08-IMPLEMENTATION-GUIDE.md](IT-08-IMPLEMENTATION-GUIDE.md) - Enhanced Error Reporting (in progress 🔄)
-- [IMPLEMENTATION_CONTINUATION.md](IMPLEMENTATION_CONTINUATION.md) - Detailed continuation plan for current phase
+- [IT-08-IMPLEMENTATION-GUIDE.md](IT-08-IMPLEMENTATION-GUIDE.md) - Enhanced Error Reporting (complete ✅)
 
 **📚 Reference**:
 - [E6-z3ed-reference.md](E6-z3ed-reference.md) - Technical reference and API docs
diff --git a/scripts/quickstart_ollama.sh b/scripts/quickstart_ollama.sh
new file mode 100755
index 00000000..270caf98
--- /dev/null
+++ b/scripts/quickstart_ollama.sh
@@ -0,0 +1,128 @@
+#!/bin/bash
+# Quick Start Script for Testing Ollama Integration with z3ed
+# Usage: ./scripts/quickstart_ollama.sh
+
+set -e
+
+echo "🚀 z3ed + Ollama Quick Start"
+echo "================================"
+echo ""
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Step 1: Check if Ollama is installed
+echo "📦 Step 1: Checking Ollama installation..."
+if ! command -v ollama &> /dev/null; then
+    echo -e "${RED}✗ Ollama not found${NC}"
+    echo ""
+    echo "Install Ollama with:"
+    echo "  macOS:  brew install ollama"
+    echo "  Linux:  curl -fsSL https://ollama.com/install.sh | sh"
+    echo ""
+    exit 1
+fi
+echo -e "${GREEN}✓ Ollama installed${NC}"
+echo ""
+
+# Step 2: Check if Ollama server is running
+echo "🔌 Step 2: Checking Ollama server..."
+if ! curl -s http://localhost:11434/api/tags > /dev/null 2>&1; then
+    echo -e "${YELLOW}⚠ Ollama server not running${NC}"
+    echo ""
+    echo "Starting Ollama server in background..."
+    ollama serve > /dev/null 2>&1 &
+    OLLAMA_PID=$!
+    echo "Waiting for server to start..."
+    sleep 3
+    
+    if ! curl -s http://localhost:11434/api/tags > /dev/null 2>&1; then
+        echo -e "${RED}✗ Failed to start Ollama server${NC}"
+        exit 1
+    fi
+    echo -e "${GREEN}✓ Ollama server started (PID: $OLLAMA_PID)${NC}"
+else
+    echo -e "${GREEN}✓ Ollama server running${NC}"
+fi
+echo ""
+
+# Step 3: Check if recommended model is available
+RECOMMENDED_MODEL="qwen2.5-coder:7b"
+echo "🤖 Step 3: Checking for model: $RECOMMENDED_MODEL..."
+if ! ollama list | grep -q "$RECOMMENDED_MODEL"; then
+    echo -e "${YELLOW}⚠ Model not found${NC}"
+    echo ""
+    read -p "Pull $RECOMMENDED_MODEL? (~4.7GB download) [y/N]: " -n 1 -r
+    echo ""
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        echo "Pulling model (this may take a few minutes)..."
+        ollama pull "$RECOMMENDED_MODEL"
+        echo -e "${GREEN}✓ Model pulled successfully${NC}"
+    else
+        echo -e "${RED}✗ Model required for testing${NC}"
+        exit 1
+    fi
+else
+    echo -e "${GREEN}✓ Model available${NC}"
+fi
+echo ""
+
+# Step 4: Check if z3ed is built
+echo "🔨 Step 4: Checking z3ed build..."
+if [ ! -f "./build/bin/z3ed" ]; then
+    echo -e "${YELLOW}⚠ z3ed not found in ./build/bin/${NC}"
+    echo ""
+    echo "Building z3ed..."
+    cmake --build build --target z3ed
+    if [ ! -f "./build/bin/z3ed" ]; then
+        echo -e "${RED}✗ Failed to build z3ed${NC}"
+        exit 1
+    fi
+fi
+echo -e "${GREEN}✓ z3ed ready${NC}"
+echo ""
+
+# Step 5: Test Ollama integration
+echo "🧪 Step 5: Testing z3ed + Ollama integration..."
+export YAZE_AI_PROVIDER=ollama
+export OLLAMA_MODEL="$RECOMMENDED_MODEL"
+
+echo ""
+echo "Running test command:"
+echo -e "${BLUE}z3ed agent plan --prompt \"Validate the ROM file\"${NC}"
+echo ""
+
+if ./build/bin/z3ed agent plan --prompt "Validate the ROM file"; then
+    echo ""
+    echo -e "${GREEN}✓ Integration test passed!${NC}"
+else
+    echo ""
+    echo -e "${RED}✗ Integration test failed${NC}"
+    echo "Check error messages above for details"
+    exit 1
+fi
+
+echo ""
+echo "================================"
+echo -e "${GREEN}🎉 Setup Complete!${NC}"
+echo ""
+echo "Next steps:"
+echo "  1. Try a full agent run:"
+echo "     export YAZE_AI_PROVIDER=ollama"
+echo "     z3ed agent run --prompt \"Export first palette\" --rom zelda3.sfc --sandbox"
+echo ""
+echo "  2. Review generated commands:"
+echo "     z3ed agent list"
+echo "     z3ed agent diff"
+echo ""
+echo "  3. Try different models:"
+echo "     ollama pull codellama:13b"
+echo "     export OLLAMA_MODEL=codellama:13b"
+echo ""
+echo "  4. Read the docs:"
+echo "     docs/z3ed/LLM-INTEGRATION-PLAN.md"
+echo ""