diff --git a/INTEGRATION-GUIDE.md b/INTEGRATION-GUIDE.md
new file mode 100644
index 0000000..b598e17
--- /dev/null
+++ b/INTEGRATION-GUIDE.md
@@ -0,0 +1,763 @@
+# Claude Code Integration Guide
+
+> Technical documentation of how 40+ agents, MCP tools, and frameworks were integrated into Claude Code
+
+## Table of Contents
+
+1. [Agent Integration Architecture](#agent-integration-architecture)
+2. [MCP Tools Integration](#mcp-tools-integration)
+3. [Ralph Framework Integration](#ralph-framework-integration)
+4. [Auto-Triggering System](#auto-triggering-system)
+5. [Multi-Model Support](#multi-model-support)
+6. [Benefits & Use Cases](#benefits--use-cases)
+
+---
+
+## Agent Integration Architecture
+
+### How Agents Work in Claude Code
+
+Claude Code uses a **file-based agent system** where each agent is defined as a Markdown file with structured metadata and instructions.
+
+#### Agent File Structure
+
+```bash
+~/.claude/agents/
+├── engineering/
+│   ├── frontend-developer.md
+│   ├── backend-architect.md
+│   ├── ai-engineer.md
+│   └── ...
+├── marketing/
+│   ├── tiktok-strategist.md
+│   ├── growth-hacker.md
+│   └── ...
+└── design/
+    ├── whimsy-injector.md
+    └── ...
+```
+
+#### Agent File Format
+
+Each agent file contains:
+
+```markdown
+---
+description: Specialized agent for frontend development with React, Vue, and Angular
+triggers:
+  - User asks for UI components
+  - Frontend code needs to be written
+  - Responsive design is mentioned
+---
+
+# Frontend Developer Agent
+
+You are a frontend development specialist...
+
+## Capabilities
+- React, Vue, Angular expertise
+- Responsive design
+- Performance optimization
+- Accessibility standards
+
+## Approach
+1. Analyze requirements
+2. Choose appropriate framework
+3. Implement with best practices
+4. Optimize for performance
+...
+```
+
+#### Integration Points
+
+**1. File-Based Discovery**
+- Claude Code scans `~/.claude/agents/` directory
+- Automatically discovers all `.md` files
+- Parses YAML frontmatter for metadata
+- Loads agent descriptions and triggers
+
+**2. Task Routing**
+```javascript
+// Claude Code internal routing (simplified)
+function selectAgent(userQuery, availableAgents) {
+    for (agent of availableAgents) {
+        if (matchesTriggers(userQuery, agent.triggers)) {
+            return agent;
+        }
+    }
+    return defaultAgent;
+}
+```
+
+**3. Context Injection**
+- Agent instructions are injected into system prompt
+- Agent-specific context is maintained
+- Previous interactions with same agent are remembered
+
+#### Our Integration Approach
+
+**Created 40+ Specialized Agent Files:**
+- Organized by category (engineering, marketing, product, etc.)
+- Each with specific triggers and capabilities
+- Optimized for 6-day development cycles
+- Coordinated with studio operations workflows
+
+**Example: frontend-developer.md**
+```markdown
+---
+description: React/Vue/Angular specialist with responsive design expertise
+triggers:
+  - react component
+  - frontend
+  - ui/ux
+  - responsive design
+  - web application
+---
+
+You are a Frontend Developer agent specializing in modern web frameworks...
+
+## Tech Stack
+- React 18+ with hooks
+- Vue 3 with composition API
+- Angular 15+
+- TypeScript
+- Tailwind CSS
+
+## Development Philosophy
+- Mobile-first responsive design
+- Accessibility-first (WCAG 2.1 AA)
+- Performance optimization
+- Component reusability
+...
+```
+
+---
+
+## MCP Tools Integration
+
+### What is MCP (Model Context Protocol)?
+
+MCP is an **open standard** for connecting AI models to external tools and data sources. Think of it as a "plugin system" for AI assistants.
+
+#### MCP Architecture
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│  Claude     │────▶│  MCP Server  │────▶│   Tool      │
+│  Code       │     │  (bridge)    │     │   (API)     │
+└─────────────┘     └──────────────┘     └─────────────┘
+      │                    │
+      ▼                    ▼
+┌─────────────┐     ┌──────────────┐
+│  Agent      │◀───│  Tool Output │
+│  Context    │     │  (result)    │
+└─────────────┘     └──────────────┘
+```
+
+#### Integration Method 1: NPM Packages
+
+**Vision Tools (@z_ai/mcp-server)**
+
+```bash
+# Install the MCP server
+npm install -g @z_ai/mcp-server
+```
+
+**Configuration (~/.claude/claude_desktop_config.json):**
+```json
+{
+  "mcpServers": {
+    "zai-vision": {
+      "command": "npx",
+      "args": ["@z_ai/mcp-server"]
+    }
+  }
+}
+```
+
+**How It Works:**
+1. Claude Code starts the MCP server on startup
+2. Server exposes tools via STDIO/JSON-RPC protocol
+3. When agent needs vision analysis, Claude sends request to MCP server
+4. Server processes and returns structured data
+5. Agent uses the data in its response
+
+**Available Vision Tools:**
+- `analyze_image` - General image understanding
+- `analyze_video` - Video content analysis
+- `ui_to_artifact` - Convert UI screenshots to code
+- `extract_text` - OCR text extraction
+- `diagnose_error` - Error screenshot diagnosis
+- `ui_diff_check` - Compare two UIs
+- `analyze_data_viz` - Extract insights from charts
+- `understand_diagram` - Understand technical diagrams
+
+#### Integration Method 2: Configuration-Based Tools
+
+**Web Search, Web Reader, GitHub Reader**
+
+These are configured via MCP server settings:
+
+```json
+{
+  "mcpServers": {
+    "web-search": {
+      "command": "npx",
+      "args": ["@z_ai/coding-helper"],
+      "env": {
+        "TOOL": "web-search-prime"
+      }
+    },
+    "web-reader": {
+      "command": "npx",
+      "args": ["@z_ai/coding-helper"],
+      "env": {
+        "TOOL": "web-reader"
+      }
+    },
+    "zread": {
+      "command": "npx",
+      "args": ["@z_ai/coding-helper"],
+      "env": {
+        "TOOL": "github-reader"
+      }
+    }
+  }
+}
+```
+
+#### Tool Invocation Flow
+
+```javascript
+// When an agent needs a tool
+
+// 1. Agent identifies need
+agent: "I need to search the web for latest React trends"
+
+// 2. Claude Code routes to MCP tool
+tool = mcpServers['web-search'].tools['web-search-prime']
+
+// 3. Execute tool
+result = await tool.execute({
+  query: "latest React trends 2025",
+  maxResults: 10
+})
+
+// 4. Return to agent
+agent.receive(result)
+```
+
+#### Our MCP Integration Benefits
+
+**Vision Capabilities:**
+- Designers can show screenshots and get code
+- Debugging with error screenshots
+- Analyze competitor UIs
+- Extract data from charts/dashboards
+
+**Web Capabilities:**
+- Real-time web search for current information
+- Read documentation from URLs
+- Analyze GitHub repositories without cloning
+
+---
+
+## Ralph Framework Integration
+
+### What is Ralph?
+
+**Ralph** is an AI assistant framework created by [iannuttall](https://github.com/iannuttall/ralph) that provides:
+- Multi-agent coordination patterns
+- Agent hierarchy and supervision
+- Shared context and memory
+- Task delegation workflows
+
+### How We Integrated Ralph Patterns
+
+#### 1. Agent Hierarchy
+
+Ralph uses a **supervisor-agent pattern** where some agents coordinate others:
+
+```markdown
+---
+supervisor: true
+subordinates:
+  - frontend-developer
+  - backend-architect
+  - ui-designer
+---
+
+# Studio Producer Agent
+
+You coordinate the development workflow...
+
+## Coordination Responsibilities
+- Assign tasks to specialized agents
+- Review outputs from subordinates
+- Ensure quality standards
+- Manage timeline and dependencies
+```
+
+**Implementation in Claude Code:**
+```bash
+~/.claude/agents/
+├── project-management/
+│   ├── studio-producer.md        # Supervisor
+│   └── ...
+├── engineering/
+│   ├── frontend-developer.md     # Subordinate
+│   └── backend-architect.md      # Subordinate
+└── design/
+    └── ui-designer.md            # Subordinate
+```
+
+#### 2. Shared Context System
+
+Ralph maintains **shared context** across agents:
+
+```markdown
+## Shared Context
+- Project timeline: 6-day sprint cycle
+- Current sprint goals: [loaded from shared memory]
+- Team capacity: [known from studio operations]
+- Technical constraints: [from architecture]
+```
+
+**Claude Code Implementation:**
+- Agents reference shared project files
+- Common documentation in `~/.claude/project-context.md`
+- Previous agent outputs available as context
+
+#### 3. Task Delegation
+
+**Studio Producer** demonstrates Ralph's delegation pattern:
+
+```
+User: "Build a new user authentication feature"
+
+Studio Producer:
+├─► Frontend Developer: "Build login form UI"
+├─► Backend Architect: "Design authentication API"
+├─► UI Designer: "Create auth flow mockups"
+├─► Test Writer/Fixer: "Write auth tests"
+└─► Assembles all outputs into cohesive feature
+```
+
+**Agent File (studio-producer.md):**
+```markdown
+## Delegation Pattern
+
+When receiving a feature request:
+1. Break down into component tasks
+2. Identify required specialist agents
+3. Delegate tasks with clear requirements
+4. Set dependencies and timeline
+5. Review and integrate outputs
+6. Ensure quality and consistency
+
+## Task Delegation Template
+```
+Frontend Developer, please build [component]:
+- Requirements: [spec]
+- Design: [reference]
+- Timeline: [6-day sprint]
+- Dependencies: [API endpoints needed]
+
+Backend Architect, please design [API]:
+- Endpoints: [list]
+- Auth requirements: [spec]
+- Database schema: [entities]
+```
+```
+
+#### 4. Agent Coordination
+
+**Experiment Tracker** uses Ralph's coordination patterns:
+
+```markdown
+## Cross-Agent Coordination
+
+When running an A/B test:
+1. Work with Product Manager to define hypothesis
+2. Coordinate with Engineering for implementation
+3. Partner with Analytics for measurement
+4. Use Feedback Synthesizer to analyze results
+5. Report findings with Studio Producer
+```
+
+### Ralph Integration Benefits
+
+**1. Multi-Agent Projects**
+- Complex features require multiple specialists
+- Coordinated workflows across agent types
+- Consistent output quality
+
+**2. Studio Operations**
+- Professional project management
+- Resource allocation
+- Timeline coordination
+- Quality assurance
+
+**3. Knowledge Sharing**
+- Agents learn from each other's outputs
+- Shared best practices
+- Consistent terminology
+
+**4. Scalability**
+- Easy to add new agents
+- Clear hierarchy and responsibilities
+- Modular agent system
+
+---
+
+## Auto-Triggering System
+
+### What Are Auto-Triggers?
+
+Auto-triggers **automatically invoke specific agents** based on events or conditions, without manual selection.
+
+### Implementation via Hooks
+
+**File: ~/.claude/hooks.json**
+
+```json
+{
+  "userPromptSubmitHook": "test-writer-fixer@agent",
+  "toolOutputHook": "whimsy-injector@agent",
+  "agentCompleteHook": "studio-coach@agent"
+}
+```
+
+#### Hook 1: test-writer-fixer
+
+**Trigger:** When code is modified or files change
+
+```bash
+# User modifies a Python file
+$ echo "def new_function():" > app.py
+
+# test-writer-fixer AUTOMATICALLY triggers
+```
+
+**Agent File:**
+```markdown
+---
+autoTrigger: true
+triggerEvents:
+  - fileModified
+  - codeChanged
+  - testFailed
+---
+
+# Test Writer/Fixer Agent
+
+You automatically trigger when code changes...
+
+## Auto-Trigger Behavior
+1. Detect changed files
+2. Identify what needs testing
+3. Write comprehensive tests
+4. Run tests
+5. Fix any failures
+6. Report coverage
+```
+
+**Benefits:**
+- Tests are always up-to-date
+- No manual test writing needed
+- Catches bugs immediately
+- Maintains test coverage
+
+#### Hook 2: whimsy-injector
+
+**Trigger:** When UI code is generated
+
+```javascript
+// Frontend developer agent generates button
+const button = <button>Click me</button>;
+
+// whimsy-injector AUTOMATICALLY enhances
+const enhancedButton = (
+  <button className="hover:scale-105 active:scale-95 transition-transform">
+    Click me
+    <SparkleOnHover />
+  </button>
+);
+```
+
+**Agent File:**
+```markdown
+---
+autoTrigger: true
+triggerEvents:
+  - uiGenerated
+  - componentCreated
+  - designImplemented
+---
+
+# Whimsy Injector Agent
+
+You add delightful micro-interactions to UI designs...
+
+## Enhancement Philosophy
+- Subtle, unexpected moments of joy
+- Never interfere with functionality
+- Performance-conscious
+- Accessible by default
+
+## Auto-Trigger Behavior
+1. Monitor for UI code generation
+2. Analyze component for enhancement opportunities
+3. Add delightful touches
+4. Ensure accessibility maintained
+5. Preserve performance
+```
+
+**Benefits:**
+- Every UI has personality
+- Consistent delight across projects
+- No manual prompting needed
+- Memorable user experiences
+
+### Hook System Architecture
+
+```
+┌─────────────────┐
+│   User Action   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     ┌──────────────────┐
+│  Event System   │────▶│  Hook Dispatcher │
+│  (file change)  │     └────────┬─────────┘
+└─────────────────┘              │
+                                 ▼
+                    ┌──────────────────────┐
+                    │  test-writer-fixer   │
+                    │  (auto-invoked)       │
+                    └──────────────────────┘
+                                 │
+                                 ▼
+                    ┌──────────────────────┐
+                    │  Tests written &     │
+                    │  code verified        │
+                    └──────────────────────┘
+```
+
+---
+
+## Multi-Model Support
+
+### Architecture
+
+Claude Code supports **multiple model providers** through a unified interface:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
+    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
+  }
+}
+```
+
+### Provider Switching
+
+**Option 1: Anthropic (Official)**
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "sk-ant-xxx",
+    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
+  }
+}
+```
+
+**Option 2: Z.AI / GLM Plan**
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "zai-key-xxx",
+    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
+    "API_TIMEOUT_MS": "3000000"
+  }
+}
+```
+
+### Integration Benefits
+
+**1. Cost Optimization**
+- Z.AI offers 90% cost savings
+- Same Claude API compatibility
+- No code changes needed
+
+**2. Redundancy**
+- Switch providers instantly
+- No lock-in
+- Development vs production separation
+
+**3. Model Selection**
+```json
+{
+  "env": {
+    "MODEL_DEFAULT": "claude-sonnet-4-20250514",
+    "MODEL_FAST": "claude-haiku-4-20250514",
+    "MODEL_EXPENSIVE": "claude-opus-4-20250514"
+  }
+}
+```
+
+---
+
+## Benefits & Use Cases
+
+### 1. Engineering Teams
+
+**Before Claude Code + Agents:**
+- Manual code writing
+- Separate test writing
+- Manual debugging
+- Slow iteration
+
+**After:**
+- Frontend/Backend agents write code
+- Test Writer/Fixer writes tests automatically
+- Error diagnosis from screenshots
+- 10x faster development
+
+### 2. Marketing Teams
+
+**Before:**
+- Manual content creation
+- Separate strategies per platform
+- No viral optimization
+- Slow content production
+
+**After:**
+- TikTok Strategist creates viral strategies
+- Content Creator repurposes across platforms
+- Growth Hacker designs experiments
+- 5x content output
+
+### 3. Product Teams
+
+**Before:**
+- Manual feedback analysis
+- Slow sprint planning
+- No trend analysis
+- Reactive product decisions
+
+**After:**
+- Feedback Synthesizer analyzes user feedback
+- Sprint Prioritizer plans 6-day sprints
+- Trend Researcher identifies opportunities
+- Data-driven decisions
+
+### 4. Studio Operations
+
+**Before:**
+- Manual project coordination
+- No resource optimization
+- Poor workflow management
+- Reactive operations
+
+**After (Ralph patterns):**
+- Studio Producer coordinates teams
+- Experiment Tracker runs A/B tests
+- Analytics Reporter provides insights
+- Proactive operations
+
+### 5. Design Teams
+
+**Before:**
+- Manual design implementation
+- No accessibility consideration
+- Inconsistent UI patterns
+- Slow design-to-code
+
+**After:**
+- UI Designer creates components
+- Whimsy Injector adds delight
+- Brand Guardian ensures consistency
+- Design-to-code in minutes
+
+---
+
+## Complete Integration Stack
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   Claude Code CLI                       │
+│  (Base platform - by Anthropic)                         │
+└───────────────────┬─────────────────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────┐
+│              Customization Suite Layer                  │
+├─────────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
+│  │   Agents     │  │  MCP Tools   │  │   Hooks      │ │
+│  │  (40+ files) │  │  (15 tools)  │  │ (auto-trig.) │ │
+│  └──────────────┘  └──────────────┘  └──────────────┘ │
+├─────────────────────────────────────────────────────────┤
+│              Ralph Coordination Layer                    │
+│  (Multi-agent patterns, task delegation, coordination)  │
+├─────────────────────────────────────────────────────────┤
+│              Multi-Model Support Layer                   │
+│         (Anthropic + Z.AI/GLM Plan switching)           │
+└─────────────────────────────────────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────┐
+│                   External Services                      │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
+│  │ Anthropic│  │  Z.AI    │  │  GitHub  │  │   Web   │ │
+│  │   API    │  │  GLM API │  │   API   │  │ Search  │ │
+│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Integration Insights
+
+### 1. Modularity
+- Each agent is independent
+- Easy to add/remove agents
+- No coupling between agents
+
+### 2. Extensibility
+- File-based system
+- Markdown format
+- No recompilation needed
+
+### 3. Coordination
+- Ralph patterns for complex workflows
+- Clear hierarchy
+- Shared context
+
+### 4. Automation
+- Hooks for auto-triggering
+- Event-driven
+- Passive activation
+
+### 5. Flexibility
+- Multi-model support
+- Provider switching
+- No lock-in
+
+---
+
+## Conclusion
+
+This integration combines:
+- **Claude Code** (base platform)
+- **40+ specialized agents** (domain expertise)
+- **15+ MCP tools** (external capabilities)
+- **Ralph patterns** (coordination)
+- **Auto-triggering** (automation)
+- **Multi-model support** (flexibility)
+
+The result is a **comprehensive AI development environment** that handles end-to-end software development, from planning to deployment, with specialized AI assistance at every step.
+
+**Built for developers who ship.** 🚀