class ChatAgent(
    Agent,
    RAGToolsMixin,         # Existing: document Q&A
    FileToolsMixin,        # Existing: file watching
    ShellToolsMixin,       # Existing: shell commands
    FileSearchToolsMixin,  # Existing: file search
    FileIOToolsMixin,      # NEW: read/write/edit files
    ProjectManagementMixin,# NEW: list_files, create_project
    ExternalToolsMixin,    # NEW: web search, doc search
    TestingMixin,          # NEW: execute Python, run tests
):

class ChatAgent(
    Agent,
    MCPClientMixin,        # NEW: MCP server connectivity
    RAGToolsMixin,
    FileToolsMixin,
    ShellToolsMixin,
    FileSearchToolsMixin,
    # ... other mixins
):

{
  "catalog": [
    {
      "name": "filesystem",
      "display_name": "File System",
      "description": "Secure file read/write/search with configurable access",
      "category": "system",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"],
      "requires_config": ["allowed_directories"],
      "tier": 1
    },
    {
      "name": "github",
      "display_name": "GitHub",
      "description": "Repos, PRs, issues, workflows",
      "category": "dev-tools",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": ""},
      "requires_config": ["GITHUB_TOKEN"],
      "tier": 1
    },
    {
      "name": "playwright",
      "display_name": "Browser (Playwright)",
      "description": "Web browsing and interaction via accessibility snapshots",
      "category": "browser",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"],
      "tier": 1
    }
  ]
}

Phase 1 (Quick Wins — Existing SDK Mixins)
  └── No external dependencies (reuse existing SDK)

Phase 1-MCP (MCP Server Integration)
  ├── MCPClientMixin (already exists in SDK)
  ├── Node.js/npx (for npm-based MCP servers)
  └── MCP server packages installed on demand

Phase 2 (Vision & Media)
  ├── Lemonade Server with VLM model loaded (Qwen3-VL-4B)
  ├── PIL/Pillow (already in deps)
  └── mss (new dep for cross-platform screenshots)

Phase 3 (Web & System)
  ├── httpx (already in deps)
  ├── beautifulsoup4 (new dep)
  ├── pyperclip (new dep)
  └── plyer (new dep for notifications)

Phase 4 (Computer Use)
  ├── Phase 1 (guardrails MUST be done first)
  ├── Phase 2 (VLM for screen understanding)
  ├── pyautogui (new dep)
  ├── pywinauto (Windows, new dep)
  ├── Playwright (optional, for browser automation)
  └── OR: Windows Desktop MCP servers (external, via MCP)

Phase 5 (Audio/Voice)
  ├── Whisper ASR model loaded in Lemonade
  ├── Kokoro TTS model loaded in Lemonade
  └── Browser MediaRecorder API support

BEFORE:  Phase 4g (week 8+) — build native Playwright integration
AFTER:   Phase 1-MCP (week 1) — enable Playwright MCP server
         Phase 4g (later) — build native integration only if MCP insufficient

Week 1: Guardrails framework (#438) + read-only mixins (ProjectManagementMixin)
Week 2: FileIOToolsMixin + ExternalToolsMixin (with guardrails active)
Week 3: CLIToolsMixin + TestingMixin (with guardrails active)

class FileIOToolsMixin:
    """...
    NOTE: This mixin expects the agent to also have ValidationAndParsingMixin
    for _validate_python_syntax() and _parse_python_code() methods.
    """

# In read_file, for .py files:
if hasattr(self, '_validate_python_syntax'):
    validation = self._validate_python_syntax(content)
    result["is_valid"] = validation["is_valid"]
else:
    result["file_type"] = "python"  # still tag it, just skip validation

def register_external_tools(self):
    if shutil.which("npx"):
        # register search_documentation
    if os.environ.get("PERPLEXITY_API_KEY"):
        # register search_web

Phase 1 actual: 3-4 weeks (not 1-2)
Phase 1-MCP actual: 2-3 weeks (not concurrent with Phase 1)
Phase 2 actual: 3-4 weeks (VLM model loading is non-trivial)

User: "Check my email for anything urgent"
Agent: I don't have email access yet. I found these MCP servers that can help:
       1. Gmail MCP (gmail-mcp-server) — Gmail access
       2. Outlook MCP (outlook-mcp-server) — Outlook/Microsoft 365
       3. Nylas MCP (nylas-mcp-server) — Multi-provider (Gmail + Outlook + more)
       Would you like me to install one?
User: "Install Gmail MCP"
Agent: [installs via npx, prompts for OAuth/credentials, connects]
       Gmail MCP is now connected. You have 3 urgent emails...

{
  "capabilities": {
    "email": ["gmail-mcp-server", "outlook-mcp-server", "nylas-mcp-server"],
    "calendar": ["google-calendar-mcp", "outlook-calendar-mcp"],
    "browser": ["@anthropic/mcp-playwright"],
    "web_search": ["@anthropic/mcp-brave-search"],
    "music": ["spotify-mcp-server"],
    "notes": ["obsidian-mcp-server"],
    "tasks": ["todoist-mcp-server"],
    "code": ["@modelcontextprotocol/server-github", "@modelcontextprotocol/server-git"],
    "files": ["@modelcontextprotocol/server-filesystem"],
    "database": ["@modelcontextprotocol/server-postgres"]
  }
}

# Deploy GAIA Application

## Description
Steps to deploy the GAIA application to production.

## Prerequisites
- Docker installed
- Access to container registry
- `.env.production` file configured

## Steps
1. Run tests: `pytest tests/ -x`
2. Build Docker image: `docker build -t gaia:latest .`
3. Push to registry: `docker push registry.example.com/gaia:latest`
4. Deploy: `kubectl apply -f k8s/deployment.yaml`

## Learned
- Always run tests before building (learned 2026-03-01)
- Use `--no-cache` flag if dependencies changed (learned 2026-03-05)

IMMEDIATE (This branch — kalin/agent-ui)
  ├── ✅ Windows shell compatibility fix (done)
  ├── ✅ Sidebar minimize + resize (done)
  └── ✅ Milestone + issues created (#438-#442)

WEEK 1-2: Foundation + MCP Framework
  ├── Add MCPClientMixin to ChatAgent
  ├── MCP Server Manager UI panel in Settings
  ├── Curated MCP server catalog (Tier 1: Playwright, Brave, Fetch, Filesystem, Git)
  ├── Refactor FileIOToolsMixin for graceful degradation (§10.1)
  ├── Conditional tool registration for ExternalToolsMixin (§10.3)
  └── Capability-to-MCP mapper (curated catalog — §13.1)

WEEK 3-4: Wire Existing Mixins + MCP Tier 1
  ├── Add FileIOToolsMixin to ChatAgent (file read/write/edit)
  ├── Add ProjectManagementMixin (list_files)
  ├── Add ExternalToolsMixin (web search, conditional)
  ├── Enable Playwright MCP (browser control)
  ├── Enable Brave Search MCP (web search, free)
  ├── Enable Fetch MCP (URL content extraction)
  └── Agent capabilities discovery API (#440)

WEEK 5-6: MCP Tier 2 + Productivity
  ├── MCP Tier 2 servers: Gmail, Outlook, Calendar, Spotify, Obsidian
  ├── MCP install prompt UI ("Install MCP server?" card)
  ├── Skills UI panel in Settings (view/manage SKILL.md files)
  ├── Tool argument streaming (#441)
  └── Per-session MCP server enable/disable

WEEK 3-5: Guardrails + Safety (PARALLEL with Milestone A)
  ├── Tool execution guardrails framework (#438) ← MUST BE FIRST
  │   ├── OutputHandler.confirm_tool_execution() API
  │   ├── SSE handler → frontend confirmation modal
  │   ├── threading.Event blocking pattern
  │   ├── Allow-list with localStorage persistence
  │   └── Risk classification (read/write/execute/destructive)
  ├── Cooperative execution cancellation (#439)
  └── Cross-platform shell compatibility (#442)

WEEK 5-7: Vision & Media
  ├── ScreenshotToolsMixin — cross-platform (PIL.ImageGrab, mss)
  ├── Wire VLMToolsMixin into ChatAgent (image analysis)
  ├── Image display in Agent UI (base64/file URL)
  ├── Screenshot → VLM → describe workflow
  └── Wire SDToolsMixin (image generation, optional)

WEEK 7-9: SDK Architecture
  ├── Tool categories + lazy loading (§10.2)
  ├── Tool description compression for prompts
  ├── MCP auto-discovery (search npm/GitHub for servers) — §13.1
  ├── SKILL.md support (load, save, search, format) — §13.2
  └── Skill-RAG integration (auto-index skills directory)

WEEK 9-12: Computer Use (CUA)
  ├── Windows Desktop MCP integration
  ├── Mouse/keyboard control (pyautogui) with mandatory guardrails
  ├── Window management (pywinauto/wmctrl)
  ├── VLM-based screen element detection
  └── CUA demo workflows (open apps, fill forms)

LATER: Audio/Voice
  ├── Voice input (Whisper ASR in Agent UI)
  ├── Voice output (Kokoro TTS in Agent UI)
  └── Continuous voice conversation mode

Milestone A (UI/Wiring)          Milestone B (SDK)
═══════════════════════          ═════════════════
Week 1: MCPClientMixin
Week 2: MCP Server UI            Week 3: Guardrails (#438) ← blocks write tools
Week 3: FileIOToolsMixin ───────────────→ needs guardrails for write ops
Week 4: Playwright MCP            Week 4: Cancellation (#439)
Week 5: Email/Calendar MCP        Week 5: ScreenshotToolsMixin
Week 6: Skills UI ────────────────Week 6: SKILL.md SDK support
                                  Week 7: Tool categories
                                  Week 8: MCP auto-discovery
                                  Week 9-12: Computer Use