From 8add0e08c46f1508d61051767a5e68389977857c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= <joao.goncalves@itguys.com.br>
Date: Wed, 7 Jan 2026 21:17:00 -0300
Subject: [PATCH] docs: Add comprehensive developer documentation

- DEVELOPER_GUIDE.md: Architecture, how to add agents/crews/tools
- AGENT_CATALOG.md: All 26 agents with roles and crew assignments
- API_REFERENCE.md: Code reference for all modules and tools
- TROUBLESHOOTING.md: Common issues and solutions
- AI_AGENT_PROTOCOL.md: Mandatory protocol for AI agents
---
 docs/AGENT_CATALOG.md     | 235 ++++++++++++++++++++++++
 docs/AI_AGENT_PROTOCOL.md | 221 ++++++++++++++++++++++
 docs/API_REFERENCE.md     | 224 +++++++++++++++++++++++
 docs/DEVELOPER_GUIDE.md   | 373 ++++++++++++++++++++++++++++++++++++++
 docs/TROUBLESHOOTING.md   | 246 +++++++++++++++++++++++++
 5 files changed, 1299 insertions(+)
 create mode 100644 docs/AGENT_CATALOG.md
 create mode 100644 docs/AI_AGENT_PROTOCOL.md
 create mode 100644 docs/API_REFERENCE.md
 create mode 100644 docs/DEVELOPER_GUIDE.md
 create mode 100644 docs/TROUBLESHOOTING.md

diff --git a/docs/AGENT_CATALOG.md b/docs/AGENT_CATALOG.md
new file mode 100644
index 0000000..4f64840
--- /dev/null
+++ b/docs/AGENT_CATALOG.md
@@ -0,0 +1,235 @@
+# 🤖 Agent Catalog
+
+Complete list of all 26 AI agents available in the Antigravity Brain system.
+
+---
+
+## 🛠️ Infrastructure Agents
+
+### Arthur Mendes
+- **File:** `persona-arthur-mendes.md`
+- **Role:** Senior SRE & Monitoring Architect
+- **Specialty:** Zabbix templates, YAML validation, UUID fixing
+- **Tools:** ZabbixValidatorTool, UUIDFixerTool
+- **Crews:** Infra Engineering (Zabbix)
+
+### Gus Fring
+- **File:** `persona-gus-fring.md`
+- **Role:** Operations Director
+- **Specialty:** Stability, quality assurance, no half-measures
+- **Tools:** None (Reviewer)
+- **Crews:** Infra Engineering (Zabbix), Infra Support
+
+### Tony Stark
+- **File:** `persona-tony-stark.md`
+- **Role:** Automation Engineer
+- **Specialty:** DevOps automation, infrastructure as code
+- **Tools:** AutoCommitTool, ScaffoldMakerTool
+- **Crews:** Infra Support
+
+### Linus Torvalds
+- **File:** `persona-linus-torvalds.md`
+- **Role:** Performance Architect
+- **Specialty:** System optimization, code efficiency
+- **Tools:** FileStatsTool
+- **Crews:** Code Audit
+
+---
+
+## 🔐 Security Agents
+
+### Elliot Alderson
+- **File:** `persona-elliot-alderson.md`
+- **Role:** Offensive Security Specialist
+- **Specialty:** Penetration testing, vulnerability discovery
+- **Tools:** QASnapshotTool, RouteScannerTool
+- **Crews:** Security Audit
+
+### Devil (The Adversary)
+- **File:** `persona-devil.md`
+- **Role:** QA & Exploit Tester
+- **Specialty:** Finding edge cases, breaking things
+- **Tools:** QASnapshotTool, VisualProofTool
+- **Crews:** Security Audit
+
+### The Architect
+- **File:** `persona-the-architect.md`
+- **Role:** System Auditor & Designer
+- **Specialty:** Architecture review, technical debt analysis
+- **Tools:** ProjectMapTool, TodoTrackerTool, SpawnAgentTool
+- **Crews:** Code Audit, HR & Evolution
+
+---
+
+## 💼 Business Agents
+
+### Harvey Specter
+- **File:** `persona-harvey-specter.md`
+- **Role:** Legal & Compliance Lead
+- **Specialty:** LGPD/GDPR compliance, risk assessment
+- **Tools:** None (Reviewer)
+- **Crews:** Business Strategy
+
+### Kevin O'Leary
+- **File:** `persona-kevin-oleary.md`
+- **Role:** ROI Analyst
+- **Specialty:** Cost-benefit analysis, investment decisions
+- **Tools:** None (Reviewer)
+- **Crews:** Business Strategy
+
+### Marie Kondo
+- **File:** `persona-marie-kondo.md`
+- **Role:** Process Optimizer
+- **Specialty:** Cleanup, simplification, "does it spark joy?"
+- **Tools:** TodoTrackerTool
+- **Crews:** Business Strategy
+
+---
+
+## 💰 Sales Agents (The Hunters)
+
+### Ari Gold
+- **File:** `persona-ari-gold.md`
+- **Role:** Closer & Negotiator
+- **Specialty:** Deal closing, upselling, aggressive tactics
+- **Tools:** None
+- **Crews:** Sales Growth
+
+### Chris Gardner
+- **File:** `persona-chris-gardner.md`
+- **Role:** Prospector
+- **Specialty:** Lead generation, resilience, cold outreach
+- **Tools:** None
+- **Crews:** Sales Growth
+
+### Don Draper
+- **File:** `persona-don-draper.md`
+- **Role:** Pitch Master
+- **Specialty:** Storytelling, presentations, emotional appeal
+- **Tools:** None
+- **Crews:** Sales Growth
+
+### Jerry Maguire
+- **File:** `persona-jerry-maguire.md`
+- **Role:** Relationship Manager
+- **Specialty:** Client retention, personal connections
+- **Tools:** None
+- **Crews:** Sales Growth
+
+---
+
+## 🌱 Customer Success Agents (The Farmers)
+
+### Jim Halpert
+- **File:** `persona-jim-halpert.md`
+- **Role:** Support Specialist
+- **Specialty:** Low-friction resolution, casual approach
+- **Tools:** None
+- **Crews:** Customer Success
+
+### Leslie Knope
+- **File:** `persona-leslie-knope.md`
+- **Role:** Onboarding Specialist
+- **Specialty:** Documentation, processes, binders
+- **Tools:** None
+- **Crews:** Customer Success
+
+### Ted Lasso
+- **File:** `persona-ted-lasso.md`
+- **Role:** Retention Coach
+- **Specialty:** Morale boosting, belief, loyalty
+- **Tools:** None
+- **Crews:** Customer Success
+
+---
+
+## 🚨 Crisis Agents (The Fixers)
+
+### Olivia Pope
+- **File:** `persona-olivia-pope.md`
+- **Role:** Crisis Manager
+- **Specialty:** PR control, narrative management
+- **Tools:** None
+- **Crews:** Corporate Defense
+
+### Saul Goodman
+- **File:** `persona-saul-goodman.md`
+- **Role:** Legal Fixer
+- **Specialty:** Loopholes, creative solutions, damage control
+- **Tools:** None
+- **Crews:** Corporate Defense
+
+### Tyrion Lannister
+- **File:** `persona-tyrion-lannister.md`
+- **Role:** Strategic Advisor
+- **Specialty:** Long-term strategy, political maneuvering
+- **Tools:** None
+- **Crews:** Corporate Defense
+
+---
+
+## 🎨 Creative & Technical Agents
+
+### Steve Jobs
+- **File:** `persona-steve-jobs.md`
+- **Role:** Product Designer
+- **Specialty:** UX excellence, design thinking
+- **Tools:** None
+- **Crews:** Creative
+
+### Hannibal Lecter
+- **File:** `persona-hannibal-lecter.md`
+- **Role:** User Psychology Analyst
+- **Specialty:** Behavioral analysis, user motivation
+- **Tools:** None
+- **Crews:** Creative
+
+### Gordon Ramsay
+- **File:** `persona-gordon-ramsay.md`
+- **Role:** Code Reviewer
+- **Specialty:** Strict standards, brutal honesty
+- **Tools:** CodeFormatterTool
+- **Crews:** Code Audit, Zabbix Engineering
+
+### Walter White
+- **File:** `persona-walter-white.md`
+- **Role:** Architecture Purist
+- **Specialty:** Clean architecture, no compromises
+- **Tools:** None
+- **Crews:** Code Audit
+
+### The Gremlin
+- **File:** `persona-gremlin.md`
+- **Role:** Chaos Engineer
+- **Specialty:** Stress testing, breaking things intentionally
+- **Tools:** None
+- **Crews:** Security Audit
+
+### Sherlock Holmes
+- **File:** `persona-sherlock-holmes.md`
+- **Role:** Data Investigator
+- **Specialty:** Logic, deduction, pattern recognition
+- **Tools:** CodeSearchTool, LearnPolicyTool
+- **Crews:** HR & Evolution
+
+---
+
+## 📊 Agent Summary by Crew
+
+| Crew | Agents |
+|------|--------|
+| **Infra Engineering (Zabbix)** | Arthur Mendes, Gus Fring |
+| **Infra Support** | Gus Fring, Tony Stark, Elliot Alderson |
+| **Security Audit** | Elliot Alderson, Devil |
+| **Code Audit** | The Architect, Linus Torvalds, Gordon Ramsay |
+| **Business Strategy** | Harvey Specter, Kevin O'Leary, Marie Kondo |
+| **Sales Growth** | Ari Gold, Chris Gardner, Don Draper, Jerry Maguire |
+| **Customer Success** | Jim Halpert, Leslie Knope, Ted Lasso |
+| **Corporate Defense** | Olivia Pope, Saul Goodman, Tyrion Lannister |
+| **HR & Evolution** | The Architect, Sherlock Holmes |
+
+---
+
+## 🆕 How to Create New Agents
+
+See [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md#adding-new-agents)
diff --git a/docs/AI_AGENT_PROTOCOL.md b/docs/AI_AGENT_PROTOCOL.md
new file mode 100644
index 0000000..6d83d66
--- /dev/null
+++ b/docs/AI_AGENT_PROTOCOL.md
@@ -0,0 +1,221 @@
+# 🤖 AI Agent Protocol
+
+**READ THIS BEFORE WORKING ON THE CODEBASE**
+
+This document defines the mandatory protocols for AI agents working on the Antigravity Brain project.
+
+---
+
+## 🎯 Prime Directives
+
+1. **READ KNOWLEDGE FIRST** - Before writing ANY code, read relevant `src/knowledge/standards/*.md`
+2. **NEVER HARDCODE SECRETS** - Use `Config` class and environment variables
+3. **TOOLS MUST NOT RAISE** - Always return error strings, never raise exceptions
+4. **TEST BEFORE COMMIT** - Verify changes with `docker-compose restart app`
+
+---
+
+## 📖 Required Reading by Task Type
+
+| Task | Must Read First |
+|------|-----------------|
+| Python tools | `python_tool_standards.md` |
+| Docker changes | `docker_standards.md` |
+| New agents | `DEVELOPER_GUIDE.md#adding-new-agents` |
+| Database | `database_standards.md` |
+| Security | `security_standards.md` |
+| Git operations | `git_standards.md` |
+| UI changes | `ui_ux_standards.md` |
+
+---
+
+## ✅ Code Change Checklist
+
+Before making any change:
+
+- [ ] Read relevant standards file
+- [ ] Check if pattern already exists in codebase
+- [ ] Plan change with minimal impact
+- [ ] Add error handling
+- [ ] Test locally
+
+After making change:
+
+- [ ] Restart container: `docker-compose restart app`
+- [ ] Check logs for errors: `docker logs antigravity_brain --tail 50`
+- [ ] Verify functionality works
+- [ ] Commit with proper message format
+
+---
+
+## 📝 Commit Message Format
+
+```
+<type>: <short description>
+
+<optional body>
+```
+
+Types:
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `refactor:` Code cleanup
+- `test:` Tests
+- `chore:` Maintenance
+
+Example:
+```
+feat: Add new DevOps agent persona
+
+- Created persona-devops-dan.md
+- Added to Infrastructure crew
+- Assigned Docker tools
+```
+
+---
+
+## 🔧 Tool Development Protocol
+
+```python
+class MyTool(BaseTool):
+    name: str = "Descriptive Name"  # Agent reads this
+    description: str = (
+        "DETAILED description of when to use this tool. "
+        "Include example inputs and expected outputs."
+    )
+    args_schema: type = MyToolInput  # Pydantic model with Field descriptions
+
+    def _run(self, **kwargs) -> str:
+        try:
+            # Your logic
+            return "Success: ..."
+        except SpecificError as e:
+            return f"Error: Specific handling for {e}"
+        except Exception as e:
+            return f"Error: Unexpected - {str(e)[:100]}"
+```
+
+**NEVER:**
+- Use `input()` for user interaction
+- Raise exceptions
+- Return raw JSON (use narrative text)
+- Use `Any` type hints
+
+---
+
+## 🤖 Agent Development Protocol
+
+### Persona Files
+
+1. Use YAML frontmatter for metadata
+2. Include `**Role:**` and `**Goal:**` fields
+3. Write backstory in character voice
+4. Define clear protocols/procedures
+
+### Tool Assignment
+
+- Only assign tools the agent actually needs
+- Consider `model_tier`: tools requiring reasoning → `smart`
+- Memory tools are auto-assigned to all agents
+
+---
+
+## 📁 File Placement Rules
+
+| Content Type | Location |
+|--------------|----------|
+| Agent personas | `src/agents/personas/persona-*.md` |
+| Tools | `src/tools/*.py` |
+| Knowledge standards | `src/knowledge/standards/*.md` |
+| Dynamic knowledge | `src/knowledge/dynamic/*/*.md` |
+| Crew definitions | `src/crews/definitions.py` |
+| Configuration | `src/config.py` |
+
+---
+
+## ⚠️ Common Mistakes to Avoid
+
+### 1. Variable Names in Standards
+
+❌ BAD:
+```python
+return f"Error: File '{path}' not found"  # {path} interpreted as template
+```
+
+✅ GOOD:
+```python
+return f"Error: File 'PATH_VAR' not found"  # Escaped
+```
+
+### 2. Missing Rate Limiting
+
+❌ BAD:
+```python
+while True:
+    api.call()  # Burns quota instantly
+```
+
+✅ GOOD:
+```python
+for attempt in range(MAX_RETRIES):
+    result = api.call()
+    if success: break
+    time.sleep(DELAY * (2 ** attempt))
+```
+
+### 3. Hardcoded Configuration
+
+❌ BAD:
+```python
+model = "gpt-4"
+api_key = "sk-xxx"
+```
+
+✅ GOOD:
+```python
+config = Config.get_llm_config(mode="smart")
+```
+
+---
+
+## 🧪 Testing Protocol
+
+1. **Local test:**
+   ```bash
+   docker-compose restart app
+   docker logs antigravity_brain --tail 50
+   ```
+
+2. **Verify no errors:**
+   ```bash
+   docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"
+   ```
+
+3. **Interactive test:**
+   - Open http://localhost:8000
+   - Send test message
+   - Verify correct crew routing
+   - Check agent response
+
+---
+
+## 🚀 Deployment Protocol
+
+1. **Commit changes:**
+   ```bash
+   git add .
+   git commit -m "feat: Description"
+   git push
+   ```
+
+2. **On production server:**
+   ```bash
+   git pull
+   docker-compose build --no-cache app
+   docker-compose up -d
+   ```
+
+---
+
+**Remember:** Quality over speed. Read the standards. Test your changes.
diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md
new file mode 100644
index 0000000..043954d
--- /dev/null
+++ b/docs/API_REFERENCE.md
@@ -0,0 +1,224 @@
+# 🔧 API & Code Reference
+
+Technical reference for the Antigravity Brain codebase.
+
+---
+
+## 📦 Core Modules
+
+### src/config.py
+
+Central configuration hub.
+
+```python
+from src.config import Config
+
+# Get LLM configuration
+llm_config = Config.get_llm_config(mode="smart")  # or "fast"
+# Returns: {"model": "gemini/...", "temperature": 0.7, "api_key": "..."}
+
+# Get Memory configuration
+mem_config = Config.get_mem0_config()
+# Returns: {"llm": {...}, "embedder": {...}, "vector_store": {...}}
+
+# Get Telegram token
+token = Config.get_telegram_token()
+```
+
+---
+
+### src/agents/factory.py
+
+Agent creation from persona files.
+
+```python
+from src.agents.factory import AgentFactory
+
+# Create agent with default tools
+agent = AgentFactory.create_agent("arthur-mendes", model_tier="smart")
+
+# Create agent with specific tools
+from src.tools.zabbix import ZabbixValidatorTool
+agent = AgentFactory.create_agent(
+    "arthur-mendes",
+    specific_tools=[ZabbixValidatorTool()],
+    model_tier="smart"
+)
+
+# List available personas
+personas = AgentFactory.list_available_personas()
+# Returns: ["persona-arthur-mendes", "persona-gus-fring", ...]
+
+# Load corporate knowledge
+knowledge = AgentFactory.load_knowledge_base()
+# Returns concatenated string of all standards/*.md files
+```
+
+---
+
+### src/crews/definitions.py
+
+Crew assembly and management.
+
+```python
+from src.crews.definitions import CrewDefinitions
+
+# Get available crews
+crews = CrewDefinitions.get_available_crews()
+# Returns: ["Infra Engineering (Zabbix)", "Security Audit", ...]
+
+# Assemble a crew
+crew = CrewDefinitions.assemble_crew(
+    crew_name="Infra Engineering (Zabbix)",
+    inputs={"topic": "Validate this template"}
+)
+
+# Execute crew
+result = crew.kickoff(inputs={"topic": "Your task here"})
+```
+
+---
+
+### src/router.py
+
+Smart request routing using LLM.
+
+```python
+from src.router import SmartRouter
+
+# Route a user request to appropriate crew
+crew_name = SmartRouter.route("Check server health")
+# Returns: "Infra Engineering (Zabbix)"
+
+crew_name = SmartRouter.route("Create a new agent")
+# Returns: "HR & Evolution"
+```
+
+---
+
+### src/memory/wrapper.py
+
+Memory tools with rate limiting.
+
+```python
+from src.memory.wrapper import SearchMemoryTool, SaveMemoryTool, MemoryWrapper
+
+# Get memory client
+client = MemoryWrapper.get_client()
+
+# Use as tools (typically assigned to agents)
+search_tool = SearchMemoryTool()
+result = search_tool._run(query="What do we know about Zabbix?")
+
+save_tool = SaveMemoryTool()
+result = save_tool._run(fact="The server runs on port 8000")
+```
+
+---
+
+## 🔧 Available Tools
+
+### Memory Tools (src/memory/wrapper.py)
+
+| Tool | Input | Output |
+|------|-------|--------|
+| `SearchMemoryTool` | `query: str` | Found memories or "No relevant information" |
+| `SaveMemoryTool` | `fact: str` | "Successfully saved" or error |
+
+### Evolution Tools (src/tools/evolution.py)
+
+| Tool | Input | Output |
+|------|-------|--------|
+| `SpawnAgentTool` | `filename, name, role, goal, backstory, llm_preference` | Path to created file |
+| `LearnPolicyTool` | `title, content, category` | Path to saved policy |
+
+### Zabbix Tools (src/tools/zabbix.py)
+
+| Tool | Input | Output |
+|------|-------|--------|
+| `ZabbixValidatorTool` | `file_path: str` | Validation report |
+| `UUIDFixerTool` | `file_path: str` | Fixed file path |
+
+---
+
+## 🎭 Persona File Format
+
+```yaml
+---
+description: Short description
+llm_config:
+  provider: default  # openai, gemini, ollama, default
+---
+
+# 👤 Persona: Name
+
+**Role:** Job title
+**Goal:** Primary objective
+
+## 🧠 Backstory
+
+Personality and background text...
+```
+
+### Parsed Fields
+
+| Field | Source | Fallback |
+|-------|--------|----------|
+| `name` | First `# Heading` | "Unknown Agent" |
+| `role` | `**Role:**` line | "Support Agent" |
+| `goal` | `**Goal:**` or `**Especialidade:**` | "Execute tasks related to {role}" |
+| `backstory` | Entire body content | - |
+| `llm_config` | YAML frontmatter | `{}` |
+
+---
+
+## 🌐 Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `LLM_PROVIDER` | Yes | `openai` | gemini, openai, anthropic, ollama |
+| `LLM_MODEL_FAST` | Yes | `gpt-3.5-turbo` | Model for quick tasks |
+| `LLM_MODEL_SMART` | Yes | `gpt-4o` | Model for complex reasoning |
+| `GEMINI_API_KEY` | If gemini | - | Google AI API key |
+| `OPENAI_API_KEY` | If openai | - | OpenAI API key |
+| `ANTHROPIC_API_KEY` | If anthropic | - | Anthropic API key |
+| `OLLAMA_BASE_URL` | If ollama | `http://localhost:11434` | Ollama server URL |
+| `MEMORY_PROVIDER` | No | `mem0` | qdrant (local) or mem0 (cloud) |
+| `MEMORY_EMBEDDING_PROVIDER` | No | `openai` | local, openai, gemini |
+| `QDRANT_HOST` | If qdrant | `localhost` | Qdrant host |
+| `QDRANT_PORT` | If qdrant | `6333` | Qdrant port |
+| `MEMORY_PROJECT_ID` | No | `default_project` | Memory namespace |
+
+---
+
+## 🔄 Rate Limiting Constants
+
+In `src/memory/wrapper.py`:
+
+```python
+MAX_RETRIES = 3              # Max retry attempts on 429
+RETRY_DELAY_SECONDS = 2.0    # Initial delay (doubles each retry)
+MAX_CALLS_PER_MINUTE = 50    # Conservative API limit
+```
+
+---
+
+## 🐳 Docker Services
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| `app` | 8000 | Chainlit web UI |
+| `qdrant` | 6333 | Vector database |
+| `telegram_listener` | - | Telegram bot (optional) |
+
+---
+
+## 📝 Logging
+
+```python
+import logging
+logger = logging.getLogger("AntigravityMemory")  # Memory module
+logger = logging.getLogger("AntigravityConfig")   # Config module
+```
+
+Logs appear in Docker: `docker logs antigravity_brain -f`
diff --git a/docs/DEVELOPER_GUIDE.md b/docs/DEVELOPER_GUIDE.md
new file mode 100644
index 0000000..bd09b29
--- /dev/null
+++ b/docs/DEVELOPER_GUIDE.md
@@ -0,0 +1,373 @@
+# 📖 Antigravity Brain - Developer Documentation
+
+Complete guide for developers and AI agents working on this project.
+
+## 📑 Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Adding New Agents](#adding-new-agents)
+3. [Adding New Crews](#adding-new-crews)
+4. [Adding New Tools](#adding-new-tools)
+5. [Configuration Reference](#configuration-reference)
+6. [Memory System](#memory-system)
+7. [AI Agent Guidelines](#ai-agent-guidelines)
+
+---
+
+## 🏗️ Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Chainlit Web UI                          │
+│                      (src/app.py:8000)                          │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Smart Router                                │
+│                    (src/router.py)                               │
+│         Classifies user intent → Routes to Crew                  │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+│ Infra Crew  │   │ Security    │   │ HR/Evolution│
+│             │   │ Crew        │   │ Crew        │
+└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
+       │                 │                 │
+       ▼                 ▼                 ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Agent Factory                               │
+│                  (src/agents/factory.py)                         │
+│      Loads Persona → Injects Knowledge → Creates Agent          │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+│   Persona   │   │  Knowledge  │   │   Tools     │
+│    (.md)    │   │ Standards   │   │  (Python)   │
+└─────────────┘   └─────────────┘   └─────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Shared Memory (Mem0)                          │
+│                   (src/memory/wrapper.py)                        │
+│              Qdrant Vector DB + HuggingFace Embeddings           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/app.py` | Chainlit entry point, handles chat |
+| `src/router.py` | Routes requests to appropriate crew |
+| `src/config.py` | LLM & Memory configuration |
+| `src/agents/factory.py` | Creates agents from persona files |
+| `src/crews/definitions.py` | Defines crew compositions |
+| `src/memory/wrapper.py` | Mem0 integration with rate limiting |
+
+---
+
+## 🤖 Adding New Agents
+
+### Step 1: Create Persona File
+
+Create `src/agents/personas/persona-<name>.md`:
+
+```markdown
+---
+description: Short description of the agent
+llm_config:
+  provider: default  # or: openai, gemini, ollama
+---
+
+# 👤 Persona: Agent Name
+
+**Role:** The agent's job title
+**Goal:** What the agent aims to achieve
+
+## 🧠 Backstory
+
+Detailed personality and background. This becomes the agent's
+system prompt. Write in character.
+
+## 📋 Protocol
+
+1. Step one of how this agent works
+2. Step two...
+```
+
+### Step 2: Register in Factory (Optional)
+
+If agent needs special tools, update `src/crews/definitions.py`:
+
+```python
+from src.agents.factory import AgentFactory
+from src.tools.your_tool import YourTool
+
+agent = AgentFactory.create_agent(
+    "your-agent-name",  # matches filename
+    specific_tools=[YourTool()],
+    model_tier="smart"  # or "fast"
+)
+```
+
+### Naming Convention
+
+- Filename: `persona-<lowercase-hyphenated>.md`
+- Example: `persona-bob-builder.md`
+
+---
+
+## 👥 Adding New Crews
+
+### Step 1: Define Crew in definitions.py
+
+Edit `src/crews/definitions.py`:
+
+```python
+elif crew_name == "Your New Crew":
+    # Create agents
+    agent1 = AgentFactory.create_agent("agent-one", model_tier="smart")
+    agent2 = AgentFactory.create_agent("agent-two", model_tier="fast")
+    
+    # Define tasks
+    task1 = Task(
+        description=f"Do something with: '{inputs.get('topic')}'",
+        expected_output="Expected result description",
+        agent=agent1
+    )
+    
+    task2 = Task(
+        description="Review the previous work",
+        expected_output="Approval or feedback",
+        agent=agent2
+    )
+    
+    # Return crew
+    return Crew(
+        agents=[agent1, agent2],
+        tasks=[task1, task2],
+        process=Process.sequential,
+        verbose=True
+    )
+```
+
+### Step 2: Register in Router
+
+Edit `src/router.py` prompt:
+
+```python
+prompt = f"""
+AVAILABLE CREWS:
+...
+6. 'Your New Crew': Description of when to use this crew.
+"""
+```
+
+### Step 3: Add to Crew List
+
+In `src/crews/definitions.py`:
+
+```python
+@staticmethod
+def get_available_crews():
+    return [
+        ...
+        "Your New Crew",
+    ]
+```
+
+---
+
+## 🔧 Adding New Tools
+
+### Step 1: Create Tool File
+
+Create `src/tools/your_tools.py`:
+
+```python
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+class YourToolInput(BaseModel):
+    """Input schema - MUST have docstring and Field descriptions."""
+    param1: str = Field(..., description="What this parameter is for")
+    param2: int = Field(default=10, description="Optional with default")
+
+class YourTool(BaseTool):
+    name: str = "Your Tool Name"
+    description: str = (
+        "Detailed description of what this tool does. "
+        "The agent reads this to decide when to use it."
+    )
+    args_schema: type = YourToolInput
+
+    def _run(self, param1: str, param2: int = 10) -> str:
+        try:
+            # Your logic here
+            result = do_something(param1, param2)
+            return f"Success: {result}"
+        except Exception as e:
+            # NEVER raise, always return error string
+            return f"Error: {str(e)}"
+```
+
+### Tool Guidelines
+
+1. **Always catch exceptions** - Return error strings, never raise
+2. **Descriptive docstrings** - Agents use these to understand usage
+3. **Type hints required** - All parameters need types
+4. **Return strings** - Narrative results, not raw JSON
+
+---
+
+## ⚙️ Configuration Reference
+
+### .env Variables
+
+```env
+# LLM Provider: gemini, openai, anthropic, ollama
+LLM_PROVIDER=gemini
+
+# Model names (used for both agents and memory)
+LLM_MODEL_FAST=gemini-2.5-flash-lite-preview-06-17
+LLM_MODEL_SMART=gemini-2.5-flash-lite-preview-06-17
+
+# API Keys (only the one matching your provider)
+GEMINI_API_KEY=your-key
+OPENAI_API_KEY=your-key
+ANTHROPIC_API_KEY=your-key
+
+# Memory Configuration
+MEMORY_PROVIDER=qdrant          # qdrant (local) or mem0 (cloud)
+MEMORY_EMBEDDING_PROVIDER=local # local, openai, or gemini
+QDRANT_HOST=qdrant              # Docker service name
+QDRANT_PORT=6333
+MEMORY_PROJECT_ID=your_project  # Namespace for memories
+```
+
+### Model Tiers
+
+- **smart**: Used for complex reasoning (strategy, architecture)
+- **fast**: Used for quick tasks (classification, simple responses)
+
+---
+
+## 🧠 Memory System
+
+### How It Works
+
+1. All agents have access to `SearchMemoryTool` and `SaveMemoryTool`
+2. Memories are stored in Qdrant vector database
+3. Mem0 uses LLM to extract facts and embeddings to search
+
+### Rate Limiting
+
+The memory system has built-in protection:
+- Max 50 calls/minute
+- 3 retries with exponential backoff
+- Graceful degradation (continues without memory if unavailable)
+
+### Memory Scope
+
+All memories are scoped to `MEMORY_PROJECT_ID`. Change this to isolate different projects.
+
+---
+
+## 🤖 AI Agent Guidelines
+
+### For AI Agents Working on This Codebase
+
+> **READ BEFORE MAKING CHANGES**
+
+1. **Load Knowledge First**
+   - Read `src/knowledge/standards/*.md` before writing code
+   - These are THE LAW for code style and patterns
+
+2. **Never Hardcode**
+   - Use `Config.get_llm_config()` for LLM settings
+   - Use `Config.get_mem0_config()` for memory settings
+   - Use environment variables for secrets
+
+3. **Error Handling**
+   - Tools must NEVER raise exceptions
+   - Always return descriptive error strings
+   - Use rate limiting for external APIs
+
+4. **Adding Agents**
+   - Create persona file first
+   - Test agent loads: `AgentFactory.create_agent("name")`
+   - Add to crew only after persona works
+
+5. **Testing Changes**
+   ```bash
+   docker-compose restart app
+   docker logs antigravity_brain --tail 50
+   ```
+
+6. **Commit Convention**
+   ```
+   feat: Add new feature
+   fix: Bug fix
+   docs: Documentation
+   refactor: Code cleanup
+   ```
+
+---
+
+## 📁 Directory Reference
+
+```
+src/
+├── agents/
+│   ├── factory.py          # Agent creation logic
+│   └── personas/           # Agent personality files
+│       ├── persona-arthur-mendes.md
+│       ├── persona-gus-fring.md
+│       └── ... (26 agents)
+├── crews/
+│   └── definitions.py      # Crew compositions
+├── knowledge/
+│   └── standards/          # Corporate knowledge base
+│       ├── docker_standards.md
+│       ├── python_tool_standards.md
+│       └── ... (16 standards)
+├── memory/
+│   └── wrapper.py          # Mem0 + rate limiting
+├── tools/
+│   ├── base.py             # File system tools
+│   ├── evolution.py        # SpawnAgent, LearnPolicy
+│   └── zabbix.py           # Zabbix validation tools
+├── app.py                  # Chainlit entry
+├── config.py               # Configuration hub
+└── router.py               # Smart routing
+```
+
+---
+
+## 🚀 Quick Commands
+
+```bash
+# Start application
+docker-compose up -d
+
+# View logs
+docker logs antigravity_brain -f
+
+# Restart after changes
+docker-compose restart app
+
+# Rebuild container
+docker-compose build --no-cache app
+
+# Access Qdrant dashboard
+open http://localhost:6333/dashboard
+```
+
+---
+
+Built with ❤️ by ITGuys | Last Updated: 2026-01-07
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
new file mode 100644
index 0000000..14b638a
--- /dev/null
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,246 @@
+# 🔥 Troubleshooting Guide
+
+Common issues and solutions for the Antigravity Brain system.
+
+---
+
+## 🚨 API Errors
+
+### Error: 429 RESOURCE_EXHAUSTED (Quota Exceeded)
+
+**Symptoms:**
+- Agents stuck in retry loop
+- "You exceeded your current quota" in logs
+
+**Causes:**
+- API rate limit hit (especially with Gemini 2.0-flash-exp: only 10 RPM!)
+- Memory tools calling API too fast
+
+**Solutions:**
+
+1. **Switch to higher-quota model:**
+   ```env
+   LLM_MODEL_FAST=gemini-2.5-flash-lite-preview-06-17  # 4000 RPM
+   ```
+
+2. **Wait for quota reset** (typically 1 minute)
+
+3. **Check current quota:**
+   - Gemini: https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas
+   - OpenAI: https://platform.openai.com/usage
+
+---
+
+### Error: OPENAI_API_KEY must be set
+
+**Symptoms:**
+- Memory tools fail with "api_key client option must be set"
+
+**Cause:**
+- Mem0's LLM configuration missing
+
+**Solution:**
+- Ensure `src/config.py` has LLM config in `get_mem0_config()`
+- Check that `LLM_PROVIDER` in `.env` matches a supported provider
+
+---
+
+### Error: Template variable 'X' not found
+
+**Symptoms:**
+- Agent crashes when loading knowledge
+
+**Cause:**
+- `{variable}` syntax in markdown files interpreted as CrewAI template
+
+**Solution:**
+- Escape braces in code examples: use `PATH_VAR` instead of `{path}`
+- Check `src/knowledge/standards/*.md` for unescaped `{}`
+
+---
+
+## 🐳 Docker Issues
+
+### Container keeps restarting
+
+**Check logs:**
+```bash
+docker logs antigravity_brain --tail 100
+```
+
+**Common causes:**
+- Missing `.env` file
+- Invalid API key
+- Python import errors
+
+---
+
+### Qdrant connection refused
+
+**Symptoms:**
+- "Connection refused" to port 6333
+
+**Solutions:**
+
+1. **Check Qdrant is running:**
+   ```bash
+   docker ps | findstr qdrant
+   ```
+
+2. **Check host configuration:**
+   ```env
+   QDRANT_HOST=qdrant  # Docker service name, NOT localhost
+   ```
+
+3. **Restart Qdrant:**
+   ```bash
+   docker-compose restart qdrant
+   ```
+
+---
+
+### Changes not reflected
+
+**Problem:** Code changes don't appear after saving
+
+**Solution:**
+```bash
+docker-compose restart app
+```
+
+Or for full rebuild:
+```bash
+docker-compose build --no-cache app
+docker-compose up -d
+```
+
+---
+
+## 🤖 Agent Issues
+
+### Agent not found
+
+**Error:** `No persona found matching 'agent-name'`
+
+**Solutions:**
+
+1. **Check filename matches:**
+   ```
+   src/agents/personas/persona-<exact-name>.md
+   ```
+
+2. **Use correct search pattern:**
+   ```python
+   # This searches for *agent-name* in filename
+   AgentFactory.create_agent("agent-name")
+   ```
+
+---
+
+### Agent loads but doesn't respond
+
+**Possible causes:**
+
+1. **LLM API error** - Check logs for 429/401
+2. **Empty backstory** - Ensure persona has content
+3. **Tool errors** - Check if tools are raising exceptions
+
+**Debug:**
+```bash
+docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"
+```
+
+---
+
+### Agent using wrong model
+
+**Check:** Ensure `model_tier` is set correctly:
+```python
+agent = AgentFactory.create_agent("name", model_tier="smart")  # Uses LLM_MODEL_SMART
+agent = AgentFactory.create_agent("name", model_tier="fast")   # Uses LLM_MODEL_FAST
+```
+
+---
+
+## 🧠 Memory Issues
+
+### Memory not saving
+
+**Check Qdrant dashboard:**
+```
+http://localhost:6333/dashboard
+```
+
+**Verify collection exists:** Should see `itguys_antigravity_v1` (or your `MEMORY_PROJECT_ID`)
+
+---
+
+### Memory search returns nothing
+
+**Possible causes:**
+
+1. **Embedding mismatch** - Don't change `MEMORY_EMBEDDING_PROVIDER` after data exists
+2. **Wrong project ID** - Check `MEMORY_PROJECT_ID` matches
+3. **Qdrant empty** - No memories saved yet
+
+---
+
+## 🌐 Web UI Issues
+
+### Chainlit not loading
+
+**Check port:**
+```bash
+netstat -an | findstr 8000
+```
+
+**Check container:**
+```bash
+docker logs antigravity_brain | findstr -i "error"
+```
+
+---
+
+### "Could not reach server" toast
+
+**Cause:** Usually LLM API timeout or error
+
+**Solution:** Check API key and quota
+
+---
+
+## 📋 Quick Diagnostic Commands
+
+```bash
+# Check all containers
+docker ps
+
+# View real-time logs
+docker logs antigravity_brain -f
+
+# Check for errors only
+docker logs antigravity_brain 2>&1 | findstr "ERROR Error error Exception"
+
+# Restart everything
+docker-compose down && docker-compose up -d
+
+# Full rebuild
+docker-compose build --no-cache && docker-compose up -d
+
+# Check Qdrant health
+curl http://localhost:6333/health
+
+# Test Gemini API
+curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite-preview-06-17:generateContent?key=YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}'
+```
+
+---
+
+## 🆘 Getting Help
+
+1. **Check logs first** - 90% of issues are in Docker logs
+2. **Verify .env** - Most config issues are environment variables
+3. **Test API separately** - Ensure your API key works outside the app
+4. **Check quotas** - Rate limits are the #1 cause of failures