Merge 67dd486207 into da71eaebd2

README-IMPROVED.md

@@ -0,0 +1,806 @@
+# 🤖 Jarvis — Personal AI Assistant
+
+<p align="center">
+  <strong>Your Personal AI Assistant Running on Your Own Devices</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/jeturing/Jarvis/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/jeturing/Jarvis/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
+  <a href="https://github.com/jeturing/Jarvis/releases"><img src="https://img.shields.io/github/v/release/jeturing/Jarvis?include_prereleases&style=for-the-badge" alt="GitHub release"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
+</p>
+
+## 📋 Tabla de Contenidos
+
+- [¿Qué es Jarvis?](#qué-es-jarvis)
+- [Características Principales](#características-principales)
+- [Arquitectura del Sistema](#arquitectura-del-sistema)
+- [Diagrama de Uso](#diagrama-de-uso)
+- [Instalación Rápida](#instalación-rápida)
+- [Configuración](#configuración)
+- [Uso Básico](#uso-básico)
+- [Canales Soportados](#canales-soportados)
+- [Documentación Completa](#documentación-completa)
+- [Desarrollo](#desarrollo)
+- [Contribuir](#contribuir)
+
+---
+
+## ¿Qué es Jarvis?
+
+**Jarvis** es un **asistente personal de IA** que se ejecuta en tus propios dispositivos. Es una plataforma local-first, auto-hospedada y diseñada para control de usuario único.
+
+### Beneficios Clave
+
+✅ **Privacidad Total** — Todo se ejecuta localmente, tus datos nunca salen de tu control  
+✅ **Multi-Canal** — Conecta con WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams y más  
+✅ **Multi-Plataforma** — Funciona en macOS, iOS, Android, Linux y Windows (WSL2)  
+✅ **Extensible** — Sistema robusto de plugins para añadir funcionalidad  
+✅ **Siempre Activo** — Daemon persistente vía systemd/launchd  
+✅ **Capacidades de Voz** — Voice Wake y Talk Mode en macOS/iOS/Android  
+✅ **Canvas Visual** — Espacio de trabajo visual controlado por el agente  
+
+---
+
+## Características Principales
+
+### 🔐 Seguridad y Privacidad
+- **Local-First**: Todos tus datos permanecen en tu dispositivo
+- **Sin Servidor Central**: No hay dependencia de servicios de terceros
+- **Emparejamiento Seguro**: Sistema de códigos para autorización DM
+- **Lista de Permitidos**: Control granular de quién puede interactuar
+
+### 💬 Multi-Canal
+- **Mensajería Unificada**: Una interfaz para todos tus canales de chat
+- **13+ Canales Integrados**: WhatsApp, Telegram, Discord, Slack, Signal, y más
+- **Enrutamiento Inteligente**: Mensajes dirigidos al agente correcto
+- **Respuestas Contextuales**: Mantiene contexto en conversaciones grupales
+
+### 🛠️ Herramientas Poderosas
+- **Browser Tool**: Automatización web con Playwright
+- **Canvas Tool**: Espacio de trabajo visual con A2UI
+- **Image Tool**: Análisis y generación de imágenes
+- **Bash Tool**: Ejecución de comandos del sistema
+- **Cron Tool**: Tareas programadas
+- **Memory Tool**: Almacenamiento y recuperación de contexto
+
+### 🤖 IA Avanzada
+- **Múltiples Modelos**: Claude, GPT, Gemini, Bedrock, Ollama (local)
+- **Failover Automático**: Rotación automática si un modelo falla
+- **Streaming de Herramientas**: Ejecución de herramientas en tiempo real
+- **Multi-Agente**: Agentes aislados por workspace/canal
+
+---
+
+## Arquitectura del Sistema
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Interfaces de Usuario                         │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────┐ │
+│  │  macOS   │  │   iOS    │  │ Android  │  │   CLI / Web UI  │ │
+│  │   App    │  │   App    │  │   App    │  │                 │ │
+│  └──────────┘  └──────────┘  └──────────┘  └─────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │ WebSocket / HTTP
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                      Gateway (Servidor)                          │
+│  • Gestión de sesiones y enrutamiento de mensajes               │
+│  • Catálogo de modelos IA y autenticación                       │
+│  • Trabajos programados (cron) y webhooks                       │
+│  • Herramienta de navegador compartida                          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                    Runtime de Agente (Pi Agent)                  │
+│  • Ejecución de modelos IA (Claude, GPT, etc.)                  │
+│  • Streaming de herramientas en tiempo real                     │
+│  • Gestión de contexto de sesión                                │
+│  • Failover automático de modelos                               │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                      Capa Multi-Canal                            │
+│  WhatsApp │ Telegram │ Signal │ Discord │ Slack │ iMessage      │
+│  Teams │ Matrix │ Zalo │ BlueBubbles │ LINE │ Voice Call        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                    Servicios Externos (IA)                       │
+│  Anthropic Claude │ OpenAI GPT │ Google Gemini │ AWS Bedrock    │
+│  Ollama (Local) │ Otros proveedores                             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+📖 **Profundizar**: Ver [ARCHITECTURE.md](docs/ARCHITECTURE.md) para detalles completos de arquitectura
+
+---
+
+## Diagrama de Uso
+
+### Flujo de Mensaje Completo
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. Usuario envía mensaje desde canal (WhatsApp, Telegram, etc.)│
+└───────────────────────┬─────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  2. Canal recibe mensaje y lo normaliza                         │
+│     • Extrae texto, medios, contexto de respuesta               │
+│     • Añade metadata del canal                                  │
+└───────────────────────┬─────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  3. Verificación de seguridad                                   │
+│     • Verifica lista de permitidos                              │
+│     • Valida emparejamiento para DMs                            │
+│     • Comprueba permisos de grupo                               │
+└───────────────────────┬─────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  4. Gateway enruta mensaje                                      │
+│     • Determina sesión apropiada                                │
+│     • Verifica modo de activación (mention/reply/always)        │
+│     • Encola o ejecuta inmediatamente                           │
+└───────────────────────┬─────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  5. Agente procesa mensaje                                      │
+│     • Carga contexto de sesión                                  │
+│     • Ejecuta modelo IA con herramientas                        │
+│     • Stream de llamadas y resultados de herramientas           │
+└───────────────────────┬─────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  6. Ejecución de herramientas (si es necesario)                 │
+│     • Browser (automatización web)                              │
+│     • Bash (ejecutar comandos)                                  │
+│     • Canvas (workspace visual)                                 │
+│     • Memory (recuperar contexto)                               │
+│     • Otras herramientas personalizadas                         │
+└───────────────────────┬─────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  7. Agente genera respuesta                                     │
+│     • Basada en resultados de herramientas                      │
+│     • Aplica modo de thinking (low/high/always)                 │
+│     • Formatea para canal destino                               │
+└───────────────────────┬─────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  8. Respuesta enviada de vuelta                                 │
+│     • Formatea para protocolo específico del canal              │
+│     • Fragmenta mensajes largos si es necesario                 │
+│     • Añade indicadores de escritura/reacciones                 │
+└───────────────────────┬─────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────────────┐
+│  9. Usuario recibe respuesta en su canal                        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+📖 **Profundizar**: Ver [Flujo de Datos](docs/ARCHITECTURE.md#data-flow) en documentación de arquitectura
+
+---
+
+## Instalación Rápida
+
+### Requisitos Previos
+
+- **Node.js ≥ 22.12.0**
+- **npm, pnpm o bun**
+- **macOS, Linux o Windows (WSL2)**
+
+### Instalación con npm
+
+```bash
+# Instalar globalmente
+npm install -g moltbot@latest
+
+# Ejecutar asistente de configuración
+moltbot onboard --install-daemon
+```
+
+### Instalación desde Código Fuente
+
+```bash
+# Clonar repositorio
+git clone https://github.com/jeturing/Jarvis.git
+cd Jarvis
+
+# Instalar dependencias
+pnpm install
+
+# Construir proyecto
+pnpm ui:build
+pnpm build
+
+# Ejecutar asistente de configuración
+pnpm moltbot onboard --install-daemon
+```
+
+### Instalación con Docker
+
+```bash
+# Usando Docker Compose
+docker-compose up -d
+```
+
+📖 **Profundizar**: Ver [Guía de Instalación Completa](docs/README-ES.md#configuración-y-despliegue)
+
+---
+
+## Configuración
+
+### Estructura de Configuración
+
+```
+~/.clawdbot/
+├── config/
+│   ├── .moltbot.yaml          # Configuración principal
+│   ├── models.json            # Perfiles de modelos IA
+│   └── skills/                # Configuraciones de skills
+├── credentials/
+│   ├── anthropic.json         # Tokens OAuth
+│   ├── openai.json
+│   └── channels/              # Credenciales de canales
+├── sessions/
+│   ├── main/                  # Datos de sesión principal
+│   └── groups/                # Sesiones de grupos
+└── logs/
+    ├── gateway.log            # Logs del gateway
+    └── agent.log              # Logs del agente
+```
+
+### Archivo de Configuración Principal
+
+Edita `~/.clawdbot/config/.moltbot.yaml`:
+
+```yaml
+# ========================================
+# Configuración del Gateway
+# ========================================
+gateway:
+  mode: local              # 'local' o 'remote'
+  port: 18789             # Puerto del servidor
+  bind: loopback          # 'loopback' o 'all'
+  verbose: true           # Logging detallado
+
+# ========================================
+# Configuración de Agentes
+# ========================================
+agents:
+  default:
+    model: claude-4.5-sonnet    # Modelo IA por defecto
+    thinking: high              # Nivel de thinking (low/high/always)
+    temperature: 0.7            # Temperatura del modelo
+    max_tokens: 8192            # Tokens máximos
+
+# ========================================
+# Configuración de Canales
+# ========================================
+channels:
+  # WhatsApp
+  whatsapp:
+    enabled: true
+    pairing: code              # Método de emparejamiento
+    allowlist:
+      - "+1234567890"          # Números permitidos
+  
+  # Telegram
+  telegram:
+    enabled: true
+    bot_token: "${TELEGRAM_BOT_TOKEN}"
+  
+  # Discord
+  discord:
+    enabled: true
+    bot_token: "${DISCORD_BOT_TOKEN}"
+  
+  # Signal
+  signal:
+    enabled: true
+    phone: "+1234567890"
+  
+  # Slack
+  slack:
+    enabled: true
+    bot_token: "${SLACK_BOT_TOKEN}"
+
+# ========================================
+# Configuración de Herramientas
+# ========================================
+tools:
+  browser:
+    enabled: true
+    headless: true             # Navegador sin interfaz
+    timeout: 30000             # Timeout en ms
+  
+  canvas:
+    enabled: true
+    port: 8080                 # Puerto Canvas
+  
+  bash:
+    enabled: true
+    timeout: 60000             # Timeout comandos
+  
+  memory:
+    enabled: true
+    max_size: 1000             # Entradas máximas
+
+# ========================================
+# Configuración de Sandbox (Opcional)
+# ========================================
+sandbox:
+  enabled: false
+  docker_image: "jarvis/sandbox"
+  
+# ========================================
+# Configuración de Plugins
+# ========================================
+plugins:
+  - name: matrix
+    enabled: true
+    config:
+      homeserver: "https://matrix.org"
+  
+  - name: voice-call
+    enabled: false
+    config:
+      provider: "twilio"
+
+# ========================================
+# Configuración de Skills
+# ========================================
+skills:
+  - workspace1
+  - workspace2
+```
+
+### Variables de Entorno
+
+Crea un archivo `.env` en la raíz del proyecto:
+
+```bash
+# ========================================
+# Tokens de API de IA
+# ========================================
+ANTHROPIC_API_KEY=sk-ant-api03-...
+OPENAI_API_KEY=sk-...
+
+# ========================================
+# Tokens de Canales
+# ========================================
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
+DISCORD_BOT_TOKEN=MTk4...
+SLACK_BOT_TOKEN=xoxb-...
+
+# ========================================
+# Configuración del Gateway
+# ========================================
+CLAWDBOT_GATEWAY_PORT=18789
+CLAWDBOT_GATEWAY_BIND=loopback
+
+# ========================================
+# Configuración de Modo
+# ========================================
+CLAWDBOT_PROFILE=production    # 'production' o 'dev'
+CLAWDBOT_SKIP_CHANNELS=0
+
+# ========================================
+# Configuración de Depuración
+# ========================================
+CLAWDBOT_DEBUG=0
+CLAWDBOT_VERBOSE=0
+```
+
+### Diagrama de Configuración
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                  Proceso de Configuración                   │
+└────────────────────────────────────────────────────────────┘
+
+1. INSTALACIÓN
+   │
+   ├─→ Instalar paquete npm/pnpm
+   │
+   └─→ Ejecutar: moltbot onboard --install-daemon
+
+2. CONFIGURACIÓN INTERACTIVA
+   │
+   ├─→ Seleccionar modelos IA (Claude, GPT, etc.)
+   │   └─→ Añadir tokens API o OAuth
+   │
+   ├─→ Configurar canales
+   │   ├─→ WhatsApp (emparejamiento QR)
+   │   ├─→ Telegram (bot token)
+   │   ├─→ Discord (bot token)
+   │   ├─→ Signal (phone number)
+   │   └─→ Otros canales
+   │
+   ├─→ Configurar herramientas
+   │   ├─→ Browser (Playwright)
+   │   ├─→ Canvas (A2UI)
+   │   ├─→ Bash (comandos)
+   │   └─→ Memory (almacenamiento)
+   │
+   └─→ Configurar seguridad
+       ├─→ Listas de permitidos
+       ├─→ Políticas de emparejamiento DM
+       └─→ Permisos de grupo
+
+3. VERIFICACIÓN
+   │
+   ├─→ Ejecutar: moltbot doctor
+   │   └─→ Verifica configuración y detecta problemas
+   │
+   └─→ Ejecutar: moltbot channels status
+       └─→ Verifica estado de canales
+
+4. INICIO DEL GATEWAY
+   │
+   ├─→ Modo Daemon: moltbot daemon start
+   │   └─→ Gateway se ejecuta en segundo plano
+   │
+   └─→ Modo Manual: moltbot gateway --port 18789
+       └─→ Gateway se ejecuta en primer plano
+
+5. EMPAREJAMIENTO DE CANALES
+   │
+   ├─→ WhatsApp: Escanear código QR
+   │
+   ├─→ Otros canales: Aprobar códigos de emparejamiento
+   │   └─→ Ejecutar: moltbot pairing approve <canal> <código>
+   │
+   └─→ Verificar conexiones
+       └─→ Ejecutar: moltbot channels status --probe
+
+6. ¡LISTO!
+   └─→ Enviar mensaje de prueba
+       └─→ Ejecutar: moltbot agent --message "Hola Jarvis"
+```
+
+📖 **Profundizar**: Ver [Guía de Configuración Completa](docs/README-ES.md#configuración-y-despliegue)
+
+---
+
+## Uso Básico
+
+### Iniciar el Gateway
+
+```bash
+# Modo daemon (recomendado)
+moltbot daemon install
+moltbot daemon start
+moltbot daemon status
+
+# Modo manual (desarrollo)
+moltbot gateway --port 18789 --verbose
+```
+
+### Enviar Mensajes
+
+```bash
+# Enviar mensaje a un contacto
+moltbot message send --to +1234567890 --message "Hola desde Jarvis"
+
+# Enviar mensaje a un grupo
+moltbot message send --to group_id --message "Hola grupo"
+```
+
+### Interactuar con el Agente
+
+```bash
+# Modo interactivo
+moltbot agent --message "¿Cuál es el clima hoy?"
+
+# Con modo de thinking alto
+moltbot agent --message "Analiza este documento" --thinking high
+
+# Ejecutar comando y devolver resultado al canal
+moltbot agent --message "Lista archivos en /home" --reply-back telegram
+```
+
+### Gestionar Canales
+
+```bash
+# Ver estado de todos los canales
+moltbot channels status
+
+# Ver estado con verificación de conexión
+moltbot channels status --probe
+
+# Ver estado de un canal específico
+moltbot channels status whatsapp
+
+# Reiniciar un canal
+moltbot channels restart telegram
+```
+
+### Gestionar Emparejamiento
+
+```bash
+# Listar solicitudes de emparejamiento pendientes
+moltbot pairing list
+
+# Aprobar un emparejamiento
+moltbot pairing approve telegram ABC123
+
+# Rechazar un emparejamiento
+moltbot pairing reject whatsapp XYZ789
+
+# Ver lista de permitidos
+moltbot pairing allowlist
+```
+
+### Gestionar Modelos
+
+```bash
+# Listar modelos disponibles
+moltbot models list
+
+# Ver configuración de modelos
+moltbot models config
+
+# Probar un modelo
+moltbot models test claude-4.5-sonnet
+
+# Cambiar modelo por defecto
+moltbot config set agents.default.model claude-4.5-sonnet
+```
+
+### Gestionar Skills
+
+```bash
+# Listar skills disponibles
+moltbot skills list
+
+# Instalar un skill
+moltbot skills install workspace1
+
+# Actualizar skills
+moltbot skills update
+
+# Ver configuración de skills
+moltbot skills config
+```
+
+### Diagnóstico
+
+```bash
+# Ejecutar diagnóstico completo
+moltbot doctor
+
+# Ver logs del gateway
+moltbot logs gateway
+
+# Ver logs del agente
+moltbot logs agent
+
+# Ver logs de un canal
+moltbot logs channel telegram
+```
+
+📖 **Profundizar**: Ver [Comandos CLI](docs/README-ES.md#cli)
+
+---
+
+## Canales Soportados
+
+### Canales Integrados
+
+| Canal | Biblioteca | Estado | Documentación |
+|-------|-----------|--------|---------------|
+| **WhatsApp** | @whiskeysockets/baileys | ✅ Estable | [Ver docs](docs/channels/) |
+| **Telegram** | grammy | ✅ Estable | [Ver docs](docs/channels/) |
+| **Signal** | signal-cli | ✅ Estable | [Ver docs](docs/channels/) |
+| **iMessage** | imsg | ✅ Estable | [Ver docs](docs/channels/) |
+| **Discord** | discord.js | ✅ Estable | [Ver docs](docs/channels/) |
+| **Slack** | @slack/bolt | ✅ Estable | [Ver docs](docs/channels/) |
+| **Google Chat** | Chat API | ✅ Estable | [Ver docs](docs/channels/) |
+
+### Canales de Extensión
+
+| Canal | Ubicación | Estado | Documentación |
+|-------|-----------|--------|---------------|
+| **BlueBubbles** | extensions/bluebubbles | ✅ Estable | [Ver docs](docs/channels/) |
+| **Microsoft Teams** | extensions/msteams | ✅ Estable | [Ver docs](docs/channels/) |
+| **Matrix** | extensions/matrix | ✅ Estable | [Ver docs](docs/channels/) |
+| **Zalo** | extensions/zalo | ✅ Estable | [Ver docs](docs/channels/) |
+| **Zalo Personal** | extensions/zalouser | ✅ Estable | [Ver docs](docs/channels/) |
+| **Twitch** | extensions/twitch | ✅ Estable | [Ver docs](docs/channels/) |
+| **Mattermost** | extensions/mattermost | ✅ Estable | [Ver docs](docs/channels/) |
+| **LINE** | extensions/line | ✅ Estable | [Ver docs](docs/channels/) |
+| **Voice Call** | extensions/voice-call | 🔶 Beta | [Ver docs](docs/channels/) |
+
+### Características de Canal
+
+- ✅ **Emparejamiento DM**: Lista de permitidos basada en código
+- ✅ **Enrutamiento de grupo**: Control de menciones
+- ✅ **Etiquetas de respuesta**: Respuestas basadas en hilos
+- ✅ **Fragmentación de mensajes**: Límites específicos por canal
+- ✅ **Reacciones**: Reconocimientos
+- ✅ **Indicadores de escritura**: Estado en tiempo real
+- ✅ **Redacción de medios**: Capacidades de privacidad
+
+📖 **Profundizar**: Ver [Documentación de Canales](docs/README-ES.md#canales-de-mensajería)
+
+---
+
+## Documentación Completa
+
+### 📚 Documentación Principal
+
+- **[README Español (Completo)](docs/README-ES.md)** - Documentación completa en español
+- **[Arquitectura](docs/ARCHITECTURE.md)** - Arquitectura técnica detallada del sistema
+- **[Componentes](docs/COMPONENTS.md)** - Descripción de componentes individuales (próximamente)
+- **[Desarrollo](docs/DEVELOPMENT.md)** - Guía para desarrolladores (próximamente)
+- **[Plugin Development](docs/PLUGIN-DEVELOPMENT.md)** - Crear plugins personalizados (próximamente)
+- **[API Reference](docs/API-REFERENCE.md)** - Referencia completa de API (próximamente)
+- **[Deployment](docs/DEPLOYMENT.md)** - Guías de despliegue (próximamente)
+
+### 🔧 Configuración y Administración
+
+- **Gateway**: Ver [docs/gateway/](docs/gateway/)
+- **Canales**: Ver [docs/channels/](docs/channels/)
+- **Seguridad**: Ver [docs/security/](docs/security/)
+- **CLI**: Ver [docs/cli/](docs/cli/)
+
+### 💡 Conceptos y Guías
+
+- **Modelos IA**: Ver [docs/concepts/](docs/concepts/)
+- **Sesiones**: Ver [docs/concepts/](docs/concepts/)
+- **Herramientas**: Ver [docs/tools/](docs/tools/)
+- **Plugins**: Ver [docs/plugins/](docs/plugins/)
+
+### 🚀 Inicio Rápido
+
+- **Getting Started**: Ver [docs/start/](docs/start/)
+- **Instalación**: Ver [docs/install/](docs/install/)
+- **Plataformas**: Ver [docs/platforms/](docs/platforms/)
+
+### 📖 Referencia
+
+- **Testing**: Ver [docs/testing.md](docs/testing.md)
+- **Environment**: Ver [docs/environment.md](docs/environment.md)
+- **Debugging**: Ver [docs/debugging.md](docs/debugging.md)
+
+---
+
+## Desarrollo
+
+### Configuración del Entorno de Desarrollo
+
+```bash
+# 1. Clonar repositorio
+git clone https://github.com/jeturing/Jarvis.git
+cd Jarvis
+
+# 2. Instalar dependencias
+pnpm install
+
+# 3. Construir UI
+pnpm ui:build
+
+# 4. Construir proyecto
+pnpm build
+
+# 5. Ejecutar en modo desarrollo
+pnpm gateway:watch  # Auto-recarga en cambios
+```
+
+### Scripts de Desarrollo
+
+```bash
+# Desarrollo
+pnpm dev                  # Ejecutar CLI en modo dev
+pnpm gateway:watch        # Gateway con auto-recarga
+pnpm gateway:dev          # Gateway dev sin canales
+pnpm tui:dev              # UI de terminal dev
+
+# Build
+pnpm build                # Compilar TypeScript
+pnpm ui:build             # Construir UI web
+pnpm canvas:a2ui:bundle   # Empaquetar Canvas A2UI
+
+# Testing
+pnpm test                 # Ejecutar todos los tests
+pnpm test:watch           # Tests en modo watch
+pnpm test:coverage        # Tests con cobertura
+pnpm test:e2e             # Tests end-to-end
+
+# Linting & Formatting
+pnpm lint                 # Lint TypeScript
+pnpm lint:fix             # Fix problemas de lint
+pnpm format               # Verificar formato
+pnpm format:fix           # Fix formato
+
+# Plataformas
+pnpm ios:build            # Construir app iOS
+pnpm android:run          # Ejecutar app Android
+pnpm mac:package          # Empaquetar app macOS
+```
+
+### Estructura del Proyecto
+
+```
+/
+├── src/                  # Código fuente TypeScript
+├── extensions/           # Plugins de canal y extensiones
+├── apps/                 # Aplicaciones nativas (macOS, iOS, Android)
+├── docs/                 # Documentación
+├── skills/               # Paquetes de skills de workspace
+├── scripts/              # Scripts de utilidad
+├── test/                 # Fixtures de test y helpers
+└── ui/                   # UI web (Control UI)
+```
+
+📖 **Profundizar**: Ver [Estructura Completa](docs/README-ES.md#estructura-de-directorios)
+
+---
+
+## Contribuir
+
+¡Las contribuciones son bienvenidas! Por favor lee [CONTRIBUTING.md](CONTRIBUTING.md) para detalles sobre nuestro código de conducta y el proceso para enviar pull requests.
+
+### Cómo Contribuir
+
+1. **Fork el repositorio**
+2. **Crea una rama** para tu feature (`git checkout -b feature/AmazingFeature`)
+3. **Commit tus cambios** (`git commit -m 'Add some AmazingFeature'`)
+4. **Push a la rama** (`git push origin feature/AmazingFeature`)
+5. **Abre un Pull Request**
+
+### Áreas de Contribución
+
+- 🐛 **Bug fixes**: Reporta o arregla bugs
+- ✨ **Nuevas características**: Propón o implementa nuevas features
+- 📝 **Documentación**: Mejora la documentación
+- 🔌 **Plugins**: Crea nuevos plugins de canal o herramientas
+- 🧪 **Tests**: Añade o mejora tests
+- 🌐 **Traducciones**: Traduce documentación a otros idiomas
+
+---
+
+## Licencia
+
+Este proyecto está licenciado bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para detalles.
+
+---
+
+## Soporte
+
+¿Necesitas ayuda? Aquí tienes algunas opciones:
+
+- 📖 **Documentación**: Revisa la [documentación completa](docs/README-ES.md)
+- 🐛 **Issues**: Reporta bugs en [GitHub Issues](https://github.com/jeturing/Jarvis/issues)
+- 💬 **Discusiones**: Únete a [GitHub Discussions](https://github.com/jeturing/Jarvis/discussions)
+- 📧 **Email**: Contacta al equipo de desarrollo
+
+---
+
+## Agradecimientos
+
+Gracias a todos los contribuidores que han ayudado a hacer este proyecto posible.
+
+---
+
+## Seguridad
+
+Para reportar vulnerabilidades de seguridad, por favor lee [SECURITY.md](SECURITY.md).
+
+---
+
+<p align="center">
+  <strong>Hecho con ❤️ por la comunidad</strong>
+</p>
+
+<p align="center">
+  <sub>Si encuentras útil este proyecto, considera darle una ⭐ en GitHub</sub>
+</p>

docs/ARCHITECTURE.md

@@ -0,0 +1,814 @@
+# Moltbot Architecture Documentation
+
+## Table of Contents
+1. [Overview](#overview)
+2. [High-Level Architecture](#high-level-architecture)
+3. [Core Components](#core-components)
+4. [Data Flow](#data-flow)
+5. [Message Routing](#message-routing)
+6. [Agent Execution Model](#agent-execution-model)
+7. [Plugin Architecture](#plugin-architecture)
+8. [Security Model](#security-model)
+9. [Storage & Persistence](#storage--persistence)
+10. [Network Architecture](#network-architecture)
+
+---
+
+## Overview
+
+Moltbot is designed as a **local-first, extensible AI assistant platform** with a microkernel-inspired architecture. The system consists of a central Gateway (control plane) and modular components (channels, tools, plugins) that communicate through well-defined interfaces.
+
+### Design Principles
+
+1. **Local-First**: Everything runs on user's devices; no central server dependency
+2. **Privacy-Focused**: User data never leaves their control
+3. **Extensible**: Plugin system for adding channels, tools, and functionality
+4. **Multi-Platform**: Works on macOS, iOS, Android, Linux, Windows (WSL2)
+5. **Resilient**: Graceful degradation; continues working when components fail
+6. **Developer-Friendly**: Clear APIs, TypeScript types, comprehensive testing
+
+---
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      User Interfaces                             │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────┐ │
+│  │  macOS   │  │   iOS    │  │ Android  │  │   CLI / Web UI  │ │
+│  │   App    │  │   App    │  │   App    │  │                 │ │
+│  └──────────┘  └──────────┘  └──────────┘  └─────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ↓ WebSocket / HTTP
+┌─────────────────────────────────────────────────────────────────┐
+│                         Gateway Server                           │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │              WebSocket Control Plane                        ││
+│  │  • Session Management                                       ││
+│  │  • Message Routing                                          ││
+│  │  • Model Catalog                                            ││
+│  │  • Discovery Service (mDNS)                                 ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                              │                                   │
+│  ┌──────────────┬───────────┴───────────┬──────────────────┐  │
+│  │              │                        │                  │  │
+│  ▼              ▼                        ▼                  ▼  │
+│ ┌──────┐  ┌──────────┐  ┌───────────┐  ┌─────────────────┐   │
+│ │ Chat │  │  Model   │  │  Browser  │  │  Cron Scheduler │   │
+│ │Registry│ │ Catalog │  │   Tool    │  │                 │   │
+│ └──────┘  └──────────┘  └───────────┘  └─────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                      Agent Runtime Layer                         │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │              Pi Agent (RPC Mode)                            ││
+│  │  • Tool Streaming                                           ││
+│  │  • Block Streaming                                          ││
+│  │  • Model Failover                                           ││
+│  │  • Auth Profile Rotation                                    ││
+│  │  • Session Context Management                               ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                              │                                   │
+│  ┌──────────────┬───────────┴───────────┬──────────────────┐  │
+│  │              │                        │                  │  │
+│  ▼              ▼                        ▼                  ▼  │
+│ ┌──────┐  ┌──────────┐  ┌───────────┐  ┌─────────────────┐   │
+│ │ Tool │  │ Session  │  │   Memory  │  │   Sandbox       │   │
+│ │Registry│ │ Manager │  │   Store   │  │  (Optional)     │   │
+│ └──────┘  └──────────┘  └───────────┘  └─────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                    Channel Layer (Multi-Protocol)                │
+│  ┌──────────┬──────────┬──────────┬──────────┬──────────────┐  │
+│  │ WhatsApp │ Telegram │  Signal  │ Discord  │    Slack     │  │
+│  └──────────┴──────────┴──────────┴──────────┴──────────────┘  │
+│  ┌──────────┬──────────┬──────────┬──────────┬──────────────┐  │
+│  │ iMessage │   Teams  │  Matrix  │   Zalo   │  BlueBubbles │  │
+│  └──────────┴──────────┴──────────┴──────────┴──────────────┘  │
+│  ┌──────────┬──────────┬──────────┬──────────┬──────────────┐  │
+│  │  Twitch  │Mattermost│   LINE   │   Nostr  │  Voice Call  │  │
+│  └──────────┴──────────┴──────────┴──────────┴──────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                      External Services                           │
+│  ┌──────────┬──────────┬──────────┬──────────┬──────────────┐  │
+│  │ Anthropic│  OpenAI  │   AWS    │  Ollama  │    Google    │  │
+│  │  Claude  │   GPT    │ Bedrock  │  (Local) │  Gemini      │  │
+│  └──────────┴──────────┴──────────┴──────────┴──────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Core Components
+
+### 1. Gateway Server
+
+**Responsibility**: Central control plane for all communication and orchestration.
+
+**Key Modules**:
+- `server.ts` - Main WebSocket server
+- `chat-registry.ts` - Active chat session registry
+- `model-catalog.ts` - Available AI models catalog
+- `browser-tool.ts` - Shared browser automation tool
+- `discovery.ts` - mDNS service discovery
+
+**APIs**:
+```typescript
+interface GatewayServer {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  registerChat(chat: ChatSession): void;
+  unregisterChat(chatId: string): void;
+  routeMessage(message: InboundMessage): Promise<void>;
+  getModelCatalog(): ModelCatalog;
+  getBrowserTool(): BrowserTool;
+}
+```
+
+**Communication**:
+- WebSocket (ws://) for real-time bidirectional communication
+- HTTP REST API for management operations
+- mDNS for local network discovery
+
+### 2. Agent Runtime
+
+**Responsibility**: Execute AI models and manage agent sessions.
+
+**Key Modules**:
+- `pi-embedded-runner.ts` - Pi Agent executor
+- `session-manager.ts` - Session lifecycle management
+- `tool-registry.ts` - Available tools catalog
+- `model-auth.ts` - Model authentication and failover
+
+**Execution Flow**:
+```typescript
+interface AgentRuntime {
+  createSession(config: SessionConfig): AgentSession;
+  executeMessage(session: AgentSession, message: string): AsyncGenerator<AgentEvent>;
+  executeTools(session: AgentSession, tools: ToolCall[]): Promise<ToolResult[]>;
+  streamResponse(session: AgentSession): AsyncGenerator<ResponseChunk>;
+}
+```
+
+**Session Management**:
+- **Main Session**: Primary agent for user interactions
+- **Group Sessions**: Isolated agents for group chats
+- **Sub-Sessions**: Spawned agents for specific tasks
+- **Queue Modes**: Serial (one at a time) vs Concurrent (parallel)
+
+### 3. Channel Layer
+
+**Responsibility**: Handle messaging protocol specifics and normalize messages.
+
+**Channel Interface**:
+```typescript
+interface Channel {
+  name: string;
+  type: ChannelType;
+  
+  // Lifecycle
+  init(config: ChannelConfig): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  
+  // Messaging
+  send(message: OutboundMessage): Promise<void>;
+  receive(handler: MessageHandler): void;
+  
+  // Status
+  getStatus(): ChannelStatus;
+  getConnections(): Connection[];
+}
+```
+
+**Message Normalization**:
+```typescript
+interface NormalizedMessage {
+  id: string;
+  channel: string;
+  from: string;
+  to: string;
+  text: string;
+  media?: MediaAttachment[];
+  replyTo?: string;
+  timestamp: number;
+  metadata: Record<string, unknown>;
+}
+```
+
+**Channel Types**:
+- **Built-in**: WhatsApp, Telegram, Signal, Discord, Slack, iMessage
+- **Extensions**: Teams, Matrix, Zalo, BlueBubbles, Twitch, etc.
+
+### 4. Tool System
+
+**Responsibility**: Provide capabilities to agents beyond text generation.
+
+**Tool Interface**:
+```typescript
+interface Tool {
+  name: string;
+  description: string;
+  schema: JSONSchema;
+  
+  execute(params: unknown, context: ToolContext): Promise<ToolResult>;
+}
+```
+
+**Built-in Tools**:
+- **Browser Tool**: Web automation, screenshots, form filling
+- **Canvas Tool**: Visual workspace with A2UI
+- **Image Tool**: Image analysis and generation
+- **Message Tool**: Send messages across channels
+- **Session Tool**: Spawn sub-agents
+- **Bash Tool**: Execute shell commands
+- **Web Tool**: Fetch URLs, web search, readability
+- **Memory Tool**: Store and retrieve context
+- **Cron Tool**: Schedule tasks
+
+**Tool Execution Pipeline**:
+```
+User Message → Agent → Tool Call → Tool Execute → Tool Result → Agent → Response
+```
+
+### 5. Plugin System
+
+**Responsibility**: Enable extensibility through modular plugins.
+
+**Plugin Types**:
+1. **Channel Plugins**: Add new messaging integrations
+2. **Tool Plugins**: Add custom agent tools
+3. **Auth Plugins**: Add OAuth handlers
+4. **Memory Plugins**: Add storage backends
+5. **Hook Plugins**: Add global event handlers
+
+**Plugin Lifecycle**:
+```typescript
+interface Plugin {
+  manifest: PluginManifest;
+  
+  // Lifecycle
+  init(services: PluginServices): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  
+  // Hooks
+  hooks?: Record<string, HookHandler>;
+}
+```
+
+**Plugin Discovery**:
+- Auto-detect from `extensions/` directory
+- Auto-detect from `node_modules/@moltbot/` packages
+- Validate manifest and config schema
+- Load and initialize plugins
+
+---
+
+## Data Flow
+
+### Inbound Message Flow
+
+```
+External Channel (WhatsApp, Telegram, etc.)
+         ↓
+  Channel Handler
+         ↓
+  Message Normalization
+         ↓
+  Allowlist Check
+         ↓
+  Gateway Router
+         ↓
+  Session Selection
+         ↓
+  Agent Execution
+         ↓
+  Tool Streaming
+         ↓
+  Response Generation
+         ↓
+  Channel Formatting
+         ↓
+  Outbound Message
+         ↓
+External Channel
+```
+
+### Detailed Flow Steps
+
+1. **Channel Receives Message**
+   - Raw message from external protocol
+   - Protocol-specific handling (e.g., Baileys for WhatsApp)
+
+2. **Message Normalization**
+   - Convert to `NormalizedMessage` format
+   - Extract text, media, reply context
+   - Add metadata
+
+3. **Allowlist Check**
+   - Verify sender is allowed
+   - Check pairing status for DMs
+   - Validate group membership
+
+4. **Gateway Routing**
+   - Determine target session
+   - Check activation mode (mention, reply, always-on)
+   - Queue or execute immediately
+
+5. **Agent Execution**
+   - Load session context
+   - Execute model with tools
+   - Stream tool calls and responses
+
+6. **Tool Execution**
+   - Execute tools as needed
+   - Stream tool results back to agent
+   - Handle tool errors gracefully
+
+7. **Response Generation**
+   - Agent generates response
+   - Apply thinking mode (low/high/always)
+   - Format for target channel
+
+8. **Channel Formatting**
+   - Convert to channel-specific format
+   - Chunk long messages if needed
+   - Add reactions/typing indicators
+
+9. **Outbound Message**
+   - Send via channel handler
+   - Track delivery status
+   - Handle errors and retries
+
+---
+
+## Message Routing
+
+### Routing Rules
+
+```typescript
+interface RoutingConfig {
+  // Main session routing
+  mainSession: {
+    activationMode: 'always' | 'mention' | 'reply' | 'dm-only';
+    replyBack: boolean;
+    allowedChannels: string[];
+  };
+  
+  // Group session routing
+  groupSessions: {
+    enabled: boolean;
+    isolateByGroup: boolean;
+    activationMode: 'mention' | 'reply';
+  };
+  
+  // Cross-channel routing
+  crossChannel: {
+    enabled: boolean;
+    routes: ChannelRoute[];
+  };
+}
+```
+
+### Activation Modes
+
+1. **Always-On**: Every message triggers agent
+2. **Mention**: Only messages mentioning bot trigger agent
+3. **Reply**: Only replies to bot messages trigger agent
+4. **DM-Only**: Only direct messages trigger agent
+
+### Session Isolation
+
+- **Main Session**: Primary agent for user
+- **Group Session**: Separate agent per group chat
+- **Workspace Session**: Separate agent per workspace
+
+---
+
+## Agent Execution Model
+
+### Session Context
+
+```typescript
+interface SessionContext {
+  sessionId: string;
+  chatId: string;
+  channel: string;
+  
+  // Context window
+  messages: Message[];
+  maxTokens: number;
+  
+  // Configuration
+  model: string;
+  temperature: number;
+  thinkingMode: 'low' | 'high' | 'always';
+  
+  // Tools
+  availableTools: Tool[];
+  toolResults: ToolResult[];
+  
+  // Memory
+  memory: MemoryStore;
+  skills: Skill[];
+}
+```
+
+### Execution Pipeline
+
+```
+Message → Load Context → Execute Model → Stream Tools → Generate Response → Save Context
+```
+
+### Tool Streaming
+
+```typescript
+interface ToolStreamEvent {
+  type: 'tool_call' | 'tool_result' | 'text_chunk' | 'thinking';
+  data: unknown;
+}
+
+async function* streamAgentExecution(
+  session: SessionContext,
+  message: string
+): AsyncGenerator<ToolStreamEvent> {
+  // Stream tool calls and results in real-time
+  yield* piAgent.execute(session, message);
+}
+```
+
+### Model Failover
+
+```typescript
+interface ModelFailoverConfig {
+  primary: ModelConfig;
+  fallbacks: ModelConfig[];
+  retryAttempts: number;
+  retryDelay: number;
+}
+
+async function executeWithFailover(
+  config: ModelFailoverConfig,
+  request: ModelRequest
+): Promise<ModelResponse> {
+  // Try primary model
+  try {
+    return await execute(config.primary, request);
+  } catch (error) {
+    // Try fallback models
+    for (const fallback of config.fallbacks) {
+      try {
+        return await execute(fallback, request);
+      } catch (fallbackError) {
+        continue;
+      }
+    }
+    throw error;
+  }
+}
+```
+
+---
+
+## Plugin Architecture
+
+### Plugin System Design
+
+```
+┌──────────────────────────────────────┐
+│       Plugin Discovery               │
+│  • extensions/                       │
+│  • node_modules/@moltbot/            │
+└──────────────────────────────────────┘
+                │
+                ↓
+┌──────────────────────────────────────┐
+│       Plugin Loader                  │
+│  • Validate manifest                 │
+│  • Load config schema                │
+│  • Initialize plugin                 │
+└──────────────────────────────────────┘
+                │
+                ↓
+┌──────────────────────────────────────┐
+│       Plugin Runtime                 │
+│  • Register hooks                    │
+│  • Inject services                   │
+│  • Execute plugin logic              │
+└──────────────────────────────────────┘
+```
+
+### Plugin Manifest
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "type": "channel",
+  "exports": {
+    ".": "./dist/index.js",
+    "./config-schema": "./dist/config-schema.js"
+  },
+  "hooks": ["channel", "message:received", "message:sent"],
+  "permissions": ["network", "fs", "env"],
+  "dependencies": {
+    "some-lib": "^1.0.0"
+  }
+}
+```
+
+### Plugin Services
+
+```typescript
+interface PluginServices {
+  gateway: GatewayClient;
+  config: ConfigProvider;
+  logger: Logger;
+  http: HttpClient;
+  storage: StorageProvider;
+}
+```
+
+### Plugin Hooks
+
+```typescript
+interface PluginHooks {
+  'plugin:init': (plugin: Plugin) => Promise<void>;
+  'plugin:start': (plugin: Plugin) => Promise<void>;
+  'plugin:stop': (plugin: Plugin) => Promise<void>;
+  
+  'message:received': (message: NormalizedMessage) => Promise<void>;
+  'message:sent': (message: NormalizedMessage) => Promise<void>;
+  
+  'agent:before': (session: SessionContext) => Promise<void>;
+  'agent:after': (session: SessionContext, response: string) => Promise<void>;
+  
+  'tool:before': (tool: Tool, params: unknown) => Promise<void>;
+  'tool:after': (tool: Tool, result: ToolResult) => Promise<void>;
+}
+```
+
+---
+
+## Security Model
+
+### Authentication
+
+1. **Pairing System**
+   - Code-based pairing for DMs
+   - One-time pairing codes
+   - Allowlist management
+
+2. **Channel Authentication**
+   - OAuth tokens (Discord, Slack, etc.)
+   - Bot tokens (Telegram)
+   - Session persistence (WhatsApp, Signal)
+
+3. **Model Authentication**
+   - API keys (Anthropic, OpenAI)
+   - OAuth (Google, AWS)
+   - Profile rotation on failure
+
+### Authorization
+
+1. **Allowlists**
+   - Per-channel allowlists
+   - Phone numbers for WhatsApp
+   - User IDs for Telegram
+   - Handle-based for Discord
+
+2. **Group Policies**
+   - Mention-only mode
+   - Reply-only mode
+   - Admin-only commands
+
+3. **Tool Permissions**
+   - Per-tool enable/disable
+   - Execution timeouts
+   - Resource limits
+
+### Privacy
+
+1. **Local-First**
+   - All data stored locally
+   - No external server dependency
+   - User controls all data
+
+2. **Session Isolation**
+   - Separate sessions per chat
+   - No cross-session data leaks
+   - Clear session boundaries
+
+3. **Media Handling**
+   - Temporary storage with lifecycle
+   - Automatic cleanup
+   - Optional media redaction
+
+---
+
+## Storage & Persistence
+
+### File System Layout
+
+```
+~/.clawdbot/
+├── config/
+│   ├── .moltbot.yaml          # Main config
+│   ├── models.json            # Model profiles
+│   └── skills/                # Skill configs
+├── credentials/
+│   ├── anthropic.json         # OAuth tokens
+│   ├── openai.json
+│   └── channels/              # Channel credentials
+├── sessions/
+│   ├── main/                  # Main session data
+│   ├── groups/                # Group sessions
+│   └── agents/                # Agent-specific data
+├── media/
+│   ├── audio/                 # Audio files
+│   ├── images/                # Image files
+│   └── videos/                # Video files
+├── memory/
+│   ├── vectors/               # Vector embeddings
+│   └── cache/                 # Cached data
+└── logs/
+    ├── gateway.log            # Gateway logs
+    ├── agent.log              # Agent logs
+    └── channels/              # Per-channel logs
+```
+
+### Session Storage
+
+```typescript
+interface SessionStore {
+  // Session CRUD
+  create(session: SessionContext): Promise<void>;
+  read(sessionId: string): Promise<SessionContext>;
+  update(session: SessionContext): Promise<void>;
+  delete(sessionId: string): Promise<void>;
+  
+  // Message history
+  addMessage(sessionId: string, message: Message): Promise<void>;
+  getMessages(sessionId: string, limit: number): Promise<Message[]>;
+  
+  // Context management
+  getContext(sessionId: string): Promise<SessionContext>;
+  saveContext(sessionId: string, context: SessionContext): Promise<void>;
+}
+```
+
+### Memory Store
+
+```typescript
+interface MemoryStore {
+  // Vector storage
+  addEmbedding(key: string, embedding: number[]): Promise<void>;
+  searchEmbeddings(query: number[], k: number): Promise<SearchResult[]>;
+  
+  // Key-value storage
+  set(key: string, value: unknown): Promise<void>;
+  get(key: string): Promise<unknown>;
+  delete(key: string): Promise<void>;
+  
+  // Context retrieval
+  recall(query: string): Promise<MemoryResult[]>;
+}
+```
+
+---
+
+## Network Architecture
+
+### Local Mode
+
+```
+┌───────────────────────┐
+│   User Device         │
+│  ┌─────────────────┐  │
+│  │  Gateway Server │  │
+│  │  (localhost)    │  │
+│  └─────────────────┘  │
+│          ↓            │
+│  ┌─────────────────┐  │
+│  │  Agent Runtime  │  │
+│  └─────────────────┘  │
+│          ↓            │
+│  ┌─────────────────┐  │
+│  │    Channels     │  │
+│  └─────────────────┘  │
+└───────────────────────┘
+         ↓
+  External Services
+  (Anthropic, OpenAI)
+```
+
+### Remote Gateway Mode
+
+```
+┌───────────────────────┐        ┌───────────────────────┐
+│   Client Device       │        │   Remote Server       │
+│  ┌─────────────────┐  │   WS   │  ┌─────────────────┐  │
+│  │  Gateway Client │──┼────────┼──│  Gateway Server │  │
+│  │  (Control UI)   │  │        │  │  (Headless)     │  │
+│  └─────────────────┘  │        │  └─────────────────┘  │
+└───────────────────────┘        │          ↓            │
+                                 │  ┌─────────────────┐  │
+                                 │  │  Agent Runtime  │  │
+                                 │  └─────────────────┘  │
+                                 │          ↓            │
+                                 │  ┌─────────────────┐  │
+                                 │  │    Channels     │  │
+                                 │  └─────────────────┘  │
+                                 └───────────────────────┘
+                                          ↓
+                                   External Services
+```
+
+### Service Discovery
+
+```typescript
+interface DiscoveryService {
+  // mDNS advertisement
+  advertise(service: ServiceInfo): Promise<void>;
+  stopAdvertise(): Promise<void>;
+  
+  // Discovery
+  discover(serviceType: string): Promise<ServiceInfo[]>;
+  watch(serviceType: string, handler: ServiceHandler): void;
+}
+```
+
+---
+
+## Scalability Considerations
+
+### Vertical Scaling
+- Single-user design (no multi-tenancy)
+- Resource limits per tool
+- Session cleanup policies
+- Media file size limits
+
+### Horizontal Scaling
+- Not applicable (personal assistant)
+- Remote Gateway for headless servers
+- Multiple client devices connecting to single gateway
+
+### Performance Optimizations
+- Message chunking for large responses
+- Lazy loading of plugins
+- Caching of model responses
+- Connection pooling for channels
+- Parallel tool execution (where safe)
+
+---
+
+## Reliability & Fault Tolerance
+
+### Error Handling
+- Graceful degradation when components fail
+- Model failover on API errors
+- Channel reconnection on disconnect
+- Tool timeout handling
+
+### Monitoring
+- Gateway status endpoint
+- Channel connection status
+- Agent execution metrics
+- Tool execution tracing
+
+### Logging
+- Structured logging with tslog
+- Per-component log levels
+- Configurable log output (file, console)
+- Log rotation and retention
+
+---
+
+## Future Architecture Considerations
+
+### Planned Enhancements
+- Distributed tracing
+- Performance profiling
+- Advanced memory systems (RAG, embeddings)
+- Multi-agent coordination
+- Enhanced sandbox isolation
+
+### Extensibility Points
+- Custom model providers
+- Custom channel protocols
+- Custom tool implementations
+- Custom memory backends
+- Custom authentication providers
+
+---
+
+**End of Architecture Documentation**

docs/COMPONENTS.md

@@ -0,0 +1,883 @@
+# Components Documentation
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Gateway Components](#gateway-components)
+3. [Agent Runtime Components](#agent-runtime-components)
+4. [Channel Components](#channel-components)
+5. [Tool Components](#tool-components)
+6. [Plugin System Components](#plugin-system-components)
+7. [Configuration Components](#configuration-components)
+8. [Storage Components](#storage-components)
+9. [Utility Components](#utility-components)
+
+---
+
+## Overview
+
+This document provides detailed information about each component in the Jarvis system. Components are organized by layer and functionality.
+
+---
+
+## Gateway Components
+
+### Server (`src/gateway/server.ts`)
+
+**Purpose**: Main WebSocket server that handles all client connections and orchestration.
+
+**Responsibilities**:
+- Accept WebSocket connections from clients
+- Route messages to appropriate handlers
+- Manage active chat sessions
+- Coordinate tool execution
+- Handle cron jobs and webhooks
+
+**Key APIs**:
+```typescript
+class GatewayServer {
+  constructor(config: GatewayConfig);
+  
+  async start(): Promise<void>;
+  async stop(): Promise<void>;
+  
+  registerChat(chat: ChatSession): void;
+  unregisterChat(chatId: string): void;
+  
+  async routeMessage(message: InboundMessage): Promise<void>;
+  
+  getModelCatalog(): ModelCatalog;
+  getBrowserTool(): BrowserTool;
+  getDiscoveryService(): DiscoveryService;
+}
+```
+
+**Configuration**:
+```yaml
+gateway:
+  mode: local        # 'local' or 'remote'
+  port: 18789
+  bind: loopback     # 'loopback' or 'all'
+  verbose: true
+```
+
+---
+
+### Chat Registry (`src/gateway/chat-registry.ts`)
+
+**Purpose**: Maintains registry of all active chat sessions.
+
+**Responsibilities**:
+- Register new chat sessions
+- Track active sessions
+- Clean up inactive sessions
+- Provide session lookup
+
+**Key APIs**:
+```typescript
+class ChatRegistry {
+  register(chat: ChatSession): void;
+  unregister(chatId: string): void;
+  
+  get(chatId: string): ChatSession | undefined;
+  getAll(): ChatSession[];
+  
+  findByChannel(channel: string): ChatSession[];
+  findByUser(userId: string): ChatSession[];
+  
+  cleanup(): void;
+}
+```
+
+**Data Structure**:
+```typescript
+interface ChatSession {
+  id: string;
+  channel: string;
+  userId: string;
+  groupId?: string;
+  
+  agent: AgentSession;
+  context: SessionContext;
+  
+  createdAt: number;
+  lastActivityAt: number;
+  
+  metadata: Record<string, unknown>;
+}
+```
+
+---
+
+### Model Catalog (`src/gateway/model-catalog.ts`)
+
+**Purpose**: Maintains catalog of available AI models and their configurations.
+
+**Responsibilities**:
+- List available models
+- Provide model configurations
+- Handle model authentication
+- Track model usage and costs
+
+**Key APIs**:
+```typescript
+class ModelCatalog {
+  getAvailableModels(): ModelInfo[];
+  getModel(modelId: string): ModelInfo | undefined;
+  
+  getAuthProfile(modelId: string): AuthProfile;
+  setAuthProfile(modelId: string, profile: AuthProfile): void;
+  
+  getUsageStats(modelId: string): UsageStats;
+}
+```
+
+**Model Info Structure**:
+```typescript
+interface ModelInfo {
+  id: string;
+  name: string;
+  provider: 'anthropic' | 'openai' | 'google' | 'bedrock' | 'ollama';
+  
+  capabilities: {
+    vision: boolean;
+    tools: boolean;
+    streaming: boolean;
+  };
+  
+  limits: {
+    maxTokens: number;
+    contextWindow: number;
+    rateLimit: RateLimit;
+  };
+  
+  pricing: {
+    inputCostPer1k: number;
+    outputCostPer1k: number;
+  };
+}
+```
+
+---
+
+### Browser Tool (`src/gateway/browser-tool.ts`)
+
+**Purpose**: Shared browser automation tool using Playwright.
+
+**Responsibilities**:
+- Launch and manage browser instances
+- Execute browser automation tasks
+- Capture screenshots and PDFs
+- Handle browser profiles and cookies
+
+**Key APIs**:
+```typescript
+class BrowserTool {
+  async launch(options: LaunchOptions): Promise<BrowserInstance>;
+  async close(instanceId: string): Promise<void>;
+  
+  async navigate(instanceId: string, url: string): Promise<void>;
+  async screenshot(instanceId: string, options: ScreenshotOptions): Promise<Buffer>;
+  async pdf(instanceId: string, options: PDFOptions): Promise<Buffer>;
+  
+  async click(instanceId: string, selector: string): Promise<void>;
+  async type(instanceId: string, selector: string, text: string): Promise<void>;
+  async fill(instanceId: string, selector: string, value: string): Promise<void>;
+  
+  async evaluate(instanceId: string, script: string): Promise<unknown>;
+  async snapshot(instanceId: string): Promise<PageSnapshot>;
+}
+```
+
+**Configuration**:
+```yaml
+tools:
+  browser:
+    enabled: true
+    headless: true
+    timeout: 30000
+    viewport:
+      width: 1280
+      height: 720
+    profiles:
+      - name: default
+        cookies: []
+        localStorage: {}
+```
+
+---
+
+### Discovery Service (`src/gateway/discovery.ts`)
+
+**Purpose**: Service discovery using mDNS for local network.
+
+**Responsibilities**:
+- Advertise gateway service
+- Discover other gateways
+- Handle service announcements
+
+**Key APIs**:
+```typescript
+class DiscoveryService {
+  async advertise(service: ServiceInfo): Promise<void>;
+  async stopAdvertise(): Promise<void>;
+  
+  async discover(serviceType: string): Promise<ServiceInfo[]>;
+  watch(serviceType: string, handler: ServiceHandler): void;
+}
+```
+
+---
+
+## Agent Runtime Components
+
+### Pi Agent Runner (`src/agents/pi-embedded-runner.ts`)
+
+**Purpose**: Execute AI models in RPC mode with tool streaming.
+
+**Responsibilities**:
+- Execute model requests
+- Stream tool calls and results
+- Handle model authentication
+- Manage failover on errors
+
+**Key APIs**:
+```typescript
+class PiAgentRunner {
+  constructor(config: AgentConfig);
+  
+  async* execute(
+    session: SessionContext,
+    message: string
+  ): AsyncGenerator<AgentEvent>;
+  
+  async executeTools(
+    session: SessionContext,
+    tools: ToolCall[]
+  ): Promise<ToolResult[]>;
+  
+  async streamResponse(
+    session: SessionContext
+  ): AsyncGenerator<ResponseChunk>;
+}
+```
+
+**Event Types**:
+```typescript
+type AgentEvent = 
+  | { type: 'tool_call', data: ToolCall }
+  | { type: 'tool_result', data: ToolResult }
+  | { type: 'text_chunk', data: string }
+  | { type: 'thinking', data: string }
+  | { type: 'error', data: Error };
+```
+
+---
+
+### Session Manager (`src/agents/session-manager.ts`)
+
+**Purpose**: Manage agent session lifecycle and context.
+
+**Responsibilities**:
+- Create and destroy sessions
+- Load and save session context
+- Manage message history
+- Handle session isolation
+
+**Key APIs**:
+```typescript
+class SessionManager {
+  createSession(config: SessionConfig): AgentSession;
+  destroySession(sessionId: string): void;
+  
+  getSession(sessionId: string): AgentSession | undefined;
+  getAllSessions(): AgentSession[];
+  
+  async loadContext(sessionId: string): Promise<SessionContext>;
+  async saveContext(sessionId: string, context: SessionContext): Promise<void>;
+  
+  async addMessage(sessionId: string, message: Message): Promise<void>;
+  async getMessages(sessionId: string, limit: number): Promise<Message[]>;
+}
+```
+
+**Session Context**:
+```typescript
+interface SessionContext {
+  sessionId: string;
+  chatId: string;
+  channel: string;
+  
+  messages: Message[];
+  maxTokens: number;
+  
+  model: string;
+  temperature: number;
+  thinkingMode: 'low' | 'high' | 'always';
+  
+  availableTools: Tool[];
+  toolResults: ToolResult[];
+  
+  memory: MemoryStore;
+  skills: Skill[];
+  
+  metadata: Record<string, unknown>;
+}
+```
+
+---
+
+### Tool Registry (`src/agents/tool-registry.ts`)
+
+**Purpose**: Registry of available tools for agents.
+
+**Responsibilities**:
+- Register tools
+- Validate tool schemas
+- Execute tool calls
+- Track tool usage
+
+**Key APIs**:
+```typescript
+class ToolRegistry {
+  register(tool: Tool): void;
+  unregister(toolName: string): void;
+  
+  get(toolName: string): Tool | undefined;
+  getAll(): Tool[];
+  
+  async execute(
+    toolName: string,
+    params: unknown,
+    context: ToolContext
+  ): Promise<ToolResult>;
+  
+  validateParams(toolName: string, params: unknown): boolean;
+}
+```
+
+**Tool Interface**:
+```typescript
+interface Tool {
+  name: string;
+  description: string;
+  schema: JSONSchema;
+  
+  execute(params: unknown, context: ToolContext): Promise<ToolResult>;
+}
+```
+
+---
+
+### Model Auth (`src/agents/model-auth.ts`)
+
+**Purpose**: Handle model authentication and token management.
+
+**Responsibilities**:
+- Store API keys and OAuth tokens
+- Refresh expired tokens
+- Rotate auth profiles on failure
+- Secure credential storage
+
+**Key APIs**:
+```typescript
+class ModelAuth {
+  async getAuthProfile(modelId: string): Promise<AuthProfile>;
+  async setAuthProfile(modelId: string, profile: AuthProfile): Promise<void>;
+  
+  async refreshToken(modelId: string): Promise<void>;
+  async rotateProfile(modelId: string): Promise<void>;
+  
+  async validateCredentials(modelId: string): Promise<boolean>;
+}
+```
+
+**Auth Profile**:
+```typescript
+interface AuthProfile {
+  type: 'api_key' | 'oauth';
+  
+  // For API keys
+  apiKey?: string;
+  
+  // For OAuth
+  accessToken?: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  
+  metadata: Record<string, unknown>;
+}
+```
+
+---
+
+## Channel Components
+
+### Base Channel Interface (`src/channels/base.ts`)
+
+**Purpose**: Common interface for all channel implementations.
+
+**Responsibilities**:
+- Define channel lifecycle
+- Normalize messages
+- Handle errors gracefully
+
+**Interface**:
+```typescript
+interface Channel {
+  name: string;
+  type: ChannelType;
+  
+  // Lifecycle
+  init(config: ChannelConfig): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  
+  // Messaging
+  send(message: OutboundMessage): Promise<void>;
+  receive(handler: MessageHandler): void;
+  
+  // Status
+  getStatus(): ChannelStatus;
+  getConnections(): Connection[];
+}
+```
+
+---
+
+### WhatsApp Channel (`src/whatsapp/`)
+
+**Purpose**: WhatsApp integration using Baileys library.
+
+**Key Files**:
+- `bot.ts` - Main bot implementation
+- `send.ts` - Message sending
+- `markdown.ts` - Markdown to WhatsApp formatting
+- `qr.ts` - QR code pairing
+
+**Configuration**:
+```yaml
+channels:
+  whatsapp:
+    enabled: true
+    pairing: code
+    allowlist:
+      - "+1234567890"
+    session: main
+```
+
+---
+
+### Telegram Channel (`src/telegram/`)
+
+**Purpose**: Telegram integration using grammY library.
+
+**Key Files**:
+- `bot.ts` - Main bot implementation
+- `handlers.ts` - Message handlers
+- `markdown.ts` - Markdown to Telegram formatting
+- `keyboard.ts` - Inline keyboard support
+
+**Configuration**:
+```yaml
+channels:
+  telegram:
+    enabled: true
+    bot_token: "${TELEGRAM_BOT_TOKEN}"
+    allowlist:
+      - "username1"
+      - "username2"
+```
+
+---
+
+### Signal Channel (`src/signal/`)
+
+**Purpose**: Signal integration using signal-cli.
+
+**Key Files**:
+- `bot.ts` - Main bot implementation
+- `cli.ts` - signal-cli wrapper
+- `send.ts` - Message sending
+
+**Configuration**:
+```yaml
+channels:
+  signal:
+    enabled: true
+    phone: "+1234567890"
+    allowlist:
+      - "+0987654321"
+```
+
+---
+
+### Discord Channel (`src/discord/`)
+
+**Purpose**: Discord integration using discord.js.
+
+**Key Files**:
+- `bot.ts` - Main bot implementation
+- `handlers.ts` - Event handlers
+- `markdown.ts` - Markdown to Discord formatting
+- `embeds.ts` - Rich embed support
+
+**Configuration**:
+```yaml
+channels:
+  discord:
+    enabled: true
+    bot_token: "${DISCORD_BOT_TOKEN}"
+    dm:
+      policy: pairing
+      allowFrom: []
+    guilds:
+      - guild_id: "123456789"
+        channels: ["general", "bot-commands"]
+```
+
+---
+
+### Slack Channel (`src/slack/`)
+
+**Purpose**: Slack integration using Bolt framework.
+
+**Key Files**:
+- `bot.ts` - Main bot implementation
+- `handlers.ts` - Event handlers
+- `blocks.ts` - Block Kit formatting
+
+**Configuration**:
+```yaml
+channels:
+  slack:
+    enabled: true
+    bot_token: "${SLACK_BOT_TOKEN}"
+    signing_secret: "${SLACK_SIGNING_SECRET}"
+    dm:
+      policy: pairing
+```
+
+---
+
+## Tool Components
+
+### Browser Tool (`src/browser/`)
+
+**Purpose**: Web automation using Playwright.
+
+**Key Files**:
+- `browser-tool.ts` - Main tool implementation
+- `playwright-bridge.ts` - Playwright wrapper
+- `snapshot.ts` - Page snapshot generation
+- `profiles.ts` - Browser profile management
+
+**Tool Schema**:
+```typescript
+{
+  name: "browser",
+  description: "Automate web browsing",
+  schema: {
+    action: "navigate" | "click" | "type" | "screenshot",
+    url?: string,
+    selector?: string,
+    text?: string
+  }
+}
+```
+
+---
+
+### Canvas Tool (`src/canvas-host/`)
+
+**Purpose**: Visual workspace with A2UI framework.
+
+**Key Files**:
+- `index.ts` - Main canvas implementation
+- `a2ui/` - A2UI framework bundles
+- `renderer.ts` - DOM rendering
+- `websocket.ts` - Real-time updates
+
+**Tool Schema**:
+```typescript
+{
+  name: "canvas",
+  description: "Create visual workspace",
+  schema: {
+    action: "create" | "update" | "render",
+    content?: string,
+    layout?: string
+  }
+}
+```
+
+---
+
+### Bash Tool (`src/process/`)
+
+**Purpose**: Execute shell commands safely.
+
+**Key Files**:
+- `exec.ts` - Command execution
+- `spawn-utils.ts` - Process spawning utilities
+- `command-queue.ts` - Command queuing
+
+**Tool Schema**:
+```typescript
+{
+  name: "bash",
+  description: "Execute shell commands",
+  schema: {
+    command: string,
+    timeout?: number,
+    cwd?: string,
+    env?: Record<string, string>
+  }
+}
+```
+
+---
+
+### Memory Tool (`src/memory/`)
+
+**Purpose**: Store and retrieve contextual information.
+
+**Key Files**:
+- `index.ts` - Main memory implementation
+- `vector-store.ts` - Vector embeddings
+- `cache.ts` - Caching layer
+
+**Tool Schema**:
+```typescript
+{
+  name: "memory",
+  description: "Store and recall information",
+  schema: {
+    action: "store" | "recall" | "search",
+    key?: string,
+    value?: unknown,
+    query?: string
+  }
+}
+```
+
+---
+
+## Plugin System Components
+
+### Plugin Discovery (`src/plugins/discovery.ts`)
+
+**Purpose**: Auto-detect and validate plugins.
+
+**Responsibilities**:
+- Scan plugin directories
+- Validate manifests
+- Check dependencies
+
+**Key APIs**:
+```typescript
+class PluginDiscovery {
+  async discoverPlugins(): Promise<PluginManifest[]>;
+  async validateManifest(manifest: PluginManifest): Promise<boolean>;
+  async checkDependencies(manifest: PluginManifest): Promise<boolean>;
+}
+```
+
+---
+
+### Plugin Loader (`src/plugins/loader.ts`)
+
+**Purpose**: Load and initialize plugins.
+
+**Responsibilities**:
+- Load plugin modules
+- Initialize plugins
+- Register hooks
+- Inject services
+
+**Key APIs**:
+```typescript
+class PluginLoader {
+  async load(manifest: PluginManifest): Promise<Plugin>;
+  async init(plugin: Plugin): Promise<void>;
+  async start(plugin: Plugin): Promise<void>;
+  async stop(plugin: Plugin): Promise<void>;
+  
+  registerHooks(plugin: Plugin): void;
+  injectServices(plugin: Plugin, services: PluginServices): void;
+}
+```
+
+---
+
+### Plugin Services (`src/plugins/services.ts`)
+
+**Purpose**: Provide services to plugins.
+
+**Services**:
+```typescript
+interface PluginServices {
+  gateway: GatewayClient;
+  config: ConfigProvider;
+  logger: Logger;
+  http: HttpClient;
+  storage: StorageProvider;
+}
+```
+
+---
+
+## Configuration Components
+
+### Config Loader (`src/config/index.ts`)
+
+**Purpose**: Load and validate configuration.
+
+**Responsibilities**:
+- Load YAML configuration
+- Validate with Zod schemas
+- Merge environment variables
+- Handle migrations
+
+**Key APIs**:
+```typescript
+class ConfigLoader {
+  async load(path: string): Promise<Config>;
+  async validate(config: unknown): Promise<Config>;
+  async save(path: string, config: Config): Promise<void>;
+  
+  merge(configs: Partial<Config>[]): Config;
+  migrate(oldConfig: unknown): Config;
+}
+```
+
+---
+
+### Config Schema (`src/config/schema.ts`)
+
+**Purpose**: Zod schemas for configuration validation.
+
+**Schemas**:
+```typescript
+const ConfigSchema = z.object({
+  gateway: GatewayConfigSchema,
+  agents: AgentsConfigSchema,
+  channels: ChannelsConfigSchema,
+  tools: ToolsConfigSchema,
+  sandbox: SandboxConfigSchema,
+  plugins: PluginsConfigSchema,
+  skills: SkillsConfigSchema,
+});
+```
+
+---
+
+### Path Manager (`src/config/paths.ts`)
+
+**Purpose**: Manage system paths.
+
+**Paths**:
+```typescript
+class PathManager {
+  getConfigDir(): string;
+  getCredentialsDir(): string;
+  getSessionsDir(): string;
+  getMediaDir(): string;
+  getMemoryDir(): string;
+  getLogsDir(): string;
+  
+  resolve(relativePath: string): string;
+}
+```
+
+---
+
+## Storage Components
+
+### Session Store (`src/sessions/`)
+
+**Purpose**: Persist session data.
+
+**Key APIs**:
+```typescript
+class SessionStore {
+  async create(session: SessionContext): Promise<void>;
+  async read(sessionId: string): Promise<SessionContext>;
+  async update(session: SessionContext): Promise<void>;
+  async delete(sessionId: string): Promise<void>;
+  
+  async addMessage(sessionId: string, message: Message): Promise<void>;
+  async getMessages(sessionId: string, limit: number): Promise<Message[]>;
+}
+```
+
+---
+
+### Memory Store (`src/memory/`)
+
+**Purpose**: Vector storage for contextual memory.
+
+**Key APIs**:
+```typescript
+class MemoryStore {
+  async addEmbedding(key: string, embedding: number[]): Promise<void>;
+  async searchEmbeddings(query: number[], k: number): Promise<SearchResult[]>;
+  
+  async set(key: string, value: unknown): Promise<void>;
+  async get(key: string): Promise<unknown>;
+  async delete(key: string): Promise<void>;
+  
+  async recall(query: string): Promise<MemoryResult[]>;
+}
+```
+
+---
+
+## Utility Components
+
+### Logger (`src/logger.ts`)
+
+**Purpose**: Structured logging with tslog.
+
+**Key APIs**:
+```typescript
+class Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  
+  child(name: string): Logger;
+}
+```
+
+---
+
+### Terminal Utils (`src/terminal/`)
+
+**Purpose**: Terminal UI utilities.
+
+**Key Files**:
+- `palette.ts` - Color palette
+- `table.ts` - Table formatting
+- `progress.ts` - Progress bars
+
+---
+
+### Markdown Utils (`src/markdown/`)
+
+**Purpose**: Markdown parsing and rendering.
+
+**Key APIs**:
+```typescript
+class MarkdownUtils {
+  parse(markdown: string): MarkdownNode[];
+  render(nodes: MarkdownNode[]): string;
+  
+  toHTML(markdown: string): string;
+  toPlainText(markdown: string): string;
+}
+```
+
+---
+
+**End of Components Documentation**

docs/INDEX.md

@@ -0,0 +1,356 @@
+# Índice de Documentación de Jarvis
+
+## 📚 Documentación Completa del Proyecto
+
+Este directorio contiene toda la documentación del proyecto Jarvis, un asistente personal de IA que se ejecuta en tus propios dispositivos.
+
+---
+
+## 🚀 Documentos Principales
+
+### [README-ES.md](README-ES.md)
+**Documentación completa en español**
+
+Incluye:
+- Visión general del proyecto
+- ¿Qué es Jarvis?
+- Arquitectura del sistema
+- Componentes principales
+- Canales de mensajería soportados
+- Tecnologías utilizadas
+- Sistema de plugins
+- Configuración y despliegue
+- Desarrollo
+- Estructura de directorios
+
+📖 **Recomendado como punto de partida** para entender todo el proyecto.
+
+---
+
+### [ARCHITECTURE.md](ARCHITECTURE.md)
+**Documentación técnica de arquitectura**
+
+Incluye:
+- Arquitectura de alto nivel
+- Componentes del sistema
+- Flujo de datos
+- Enrutamiento de mensajes
+- Modelo de ejecución de agentes
+- Arquitectura de plugins
+- Modelo de seguridad
+- Almacenamiento y persistencia
+- Arquitectura de red
+
+📖 **Recomendado para desarrolladores** que necesitan entender la arquitectura técnica.
+
+---
+
+### [COMPONENTS.md](COMPONENTS.md)
+**Documentación de componentes individuales**
+
+Incluye:
+- Componentes del Gateway
+- Componentes del Runtime de Agente
+- Componentes de Canales
+- Componentes de Herramientas
+- Componentes del Sistema de Plugins
+- Componentes de Configuración
+- Componentes de Almacenamiento
+- Componentes de Utilidades
+
+📖 **Recomendado para desarrolladores** que trabajan en componentes específicos.
+
+---
+
+## 📖 Documentación por Categoría
+
+### 🎯 Inicio Rápido
+
+| Documento | Descripción |
+|-----------|-------------|
+| [start/](start/) | Guías de inicio rápido y tutoriales |
+| [install/](install/) | Guías de instalación paso a paso |
+| [Getting Started](start/) | Guía para principiantes |
+
+### ⚙️ Configuración
+
+| Documento | Descripción |
+|-----------|-------------|
+| [README-ES.md#configuración-y-despliegue](README-ES.md#configuración-y-despliegue) | Guía completa de configuración |
+| [gateway/](gateway/) | Configuración del Gateway |
+| [environment.md](environment.md) | Variables de entorno |
+
+### 💬 Canales
+
+| Documento | Descripción |
+|-----------|-------------|
+| [channels/](channels/) | Documentación de todos los canales |
+| [README-ES.md#canales-de-mensajería](README-ES.md#canales-de-mensajería) | Lista de canales soportados |
+
+### 🔐 Seguridad
+
+| Documento | Descripción |
+|-----------|-------------|
+| [security/](security/) | Guías de seguridad |
+| [ARCHITECTURE.md#security-model](ARCHITECTURE.md#security-model) | Modelo de seguridad |
+
+### 🛠️ Desarrollo
+
+| Documento | Descripción |
+|-----------|-------------|
+| [README-ES.md#desarrollo](README-ES.md#desarrollo) | Guía de desarrollo |
+| [testing.md](testing.md) | Guías de testing |
+| [debugging.md](debugging.md) | Guías de depuración |
+
+### 🔌 Plugins
+
+| Documento | Descripción |
+|-----------|-------------|
+| [plugins/](plugins/) | Documentación de plugins |
+| [ARCHITECTURE.md#plugin-architecture](ARCHITECTURE.md#plugin-architecture) | Arquitectura de plugins |
+
+### 🤖 Conceptos de IA
+
+| Documento | Descripción |
+|-----------|-------------|
+| [concepts/](concepts/) | Conceptos fundamentales |
+| [README-ES.md#tecnologías-utilizadas](README-ES.md#tecnologías-utilizadas) | Modelos IA soportados |
+
+### 🖥️ Plataformas
+
+| Documento | Descripción |
+|-----------|-------------|
+| [platforms/](platforms/) | Guías específicas de plataforma |
+| macOS | Documentación de macOS |
+| iOS | Documentación de iOS |
+| Android | Documentación de Android |
+
+### 📚 Referencia
+
+| Documento | Descripción |
+|-----------|-------------|
+| [reference/](reference/) | Documentación de referencia |
+| [cli/](cli/) | Referencia de comandos CLI |
+| [tools/](tools/) | Referencia de herramientas |
+
+---
+
+## 🗺️ Mapa de Navegación
+
+### Para Nuevos Usuarios
+
+1. **Empezar aquí**: [README-ES.md](README-ES.md) - Visión general completa
+2. **Instalar**: [install/](install/) - Guías de instalación
+3. **Configurar**: [README-ES.md#configuración-y-despliegue](README-ES.md#configuración-y-despliegue)
+4. **Usar**: [start/](start/) - Guías de uso básico
+
+### Para Desarrolladores
+
+1. **Arquitectura**: [ARCHITECTURE.md](ARCHITECTURE.md) - Entender el sistema
+2. **Componentes**: [COMPONENTS.md](COMPONENTS.md) - Componentes individuales
+3. **Desarrollo**: [README-ES.md#desarrollo](README-ES.md#desarrollo) - Setup de desarrollo
+4. **Testing**: [testing.md](testing.md) - Guías de testing
+
+### Para Crear Plugins
+
+1. **Sistema de Plugins**: [ARCHITECTURE.md#plugin-architecture](ARCHITECTURE.md#plugin-architecture)
+2. **Ejemplos**: [extensions/](../extensions/) - Plugins existentes
+3. **Plugin SDK**: Ver código en `src/plugin-sdk/`
+
+---
+
+## 📝 Estructura de Documentación
+
+```
+docs/
+├── README-ES.md              # 📖 Documentación completa en español
+├── ARCHITECTURE.md           # 🏗️ Arquitectura técnica
+├── COMPONENTS.md             # 🔧 Componentes individuales
+├── INDEX.md                  # 📋 Este archivo (índice)
+│
+├── start/                    # 🚀 Inicio rápido
+│   ├── getting-started.md
+│   └── wizard.md
+│
+├── install/                  # 📦 Instalación
+│   ├── docker.md
+│   └── updating.md
+│
+├── channels/                 # 💬 Canales
+│   ├── whatsapp.md
+│   ├── telegram.md
+│   ├── discord.md
+│   └── ...
+│
+├── gateway/                  # 🌐 Gateway
+│   ├── configuration.md
+│   ├── security.md
+│   └── doctor.md
+│
+├── concepts/                 # 💡 Conceptos
+│   ├── models.md
+│   ├── session.md
+│   ├── groups.md
+│   └── agent.md
+│
+├── cli/                      # 💻 CLI
+│   └── commands.md
+│
+├── tools/                    # 🛠️ Herramientas
+│   ├── browser.md
+│   ├── canvas.md
+│   └── skills.md
+│
+├── plugins/                  # 🔌 Plugins
+│   └── development.md
+│
+├── security/                 # 🔐 Seguridad
+│   └── best-practices.md
+│
+├── platforms/                # 🖥️ Plataformas
+│   ├── macos/
+│   ├── ios/
+│   ├── android/
+│   └── linux/
+│
+├── reference/                # 📚 Referencia
+│   └── RELEASING.md
+│
+├── automation/               # 🤖 Automatización
+├── debug/                    # 🐛 Depuración
+├── diagnostics/              # 🔍 Diagnósticos
+├── nodes/                    # 📡 Nodos
+├── providers/                # 🏢 Proveedores
+├── web/                      # 🌐 Web UI
+│
+├── assets/                   # 🎨 Assets
+├── images/                   # 🖼️ Imágenes
+└── _layouts/                 # 📄 Layouts
+```
+
+---
+
+## 🔍 Búsqueda por Tema
+
+### Instalación y Configuración
+- [Instalación](install/)
+- [Configuración](README-ES.md#configuración-y-despliegue)
+- [Variables de entorno](environment.md)
+- [Docker](install/docker.md)
+
+### Canales de Mensajería
+- [Todos los canales](channels/)
+- [WhatsApp](channels/whatsapp.md)
+- [Telegram](channels/telegram.md)
+- [Discord](channels/discord.md)
+- [Signal](channels/signal.md)
+- [Slack](channels/slack.md)
+
+### Desarrollo
+- [Setup de desarrollo](README-ES.md#desarrollo)
+- [Arquitectura](ARCHITECTURE.md)
+- [Componentes](COMPONENTS.md)
+- [Testing](testing.md)
+- [Debugging](debugging.md)
+
+### Plugins y Extensiones
+- [Sistema de plugins](ARCHITECTURE.md#plugin-architecture)
+- [Desarrollo de plugins](plugins/)
+- [Plugins existentes](../extensions/)
+
+### Herramientas
+- [Browser Tool](tools/browser.md)
+- [Canvas Tool](tools/canvas.md)
+- [Skills](tools/skills.md)
+
+### Seguridad
+- [Modelo de seguridad](ARCHITECTURE.md#security-model)
+- [Mejores prácticas](security/best-practices.md)
+- [Gateway security](gateway/security.md)
+
+### Plataformas
+- [macOS](platforms/macos/)
+- [iOS](platforms/ios/)
+- [Android](platforms/android/)
+- [Linux](platforms/linux/)
+
+---
+
+## 📊 Diagramas
+
+Los documentos incluyen varios diagramas ASCII para visualizar:
+
+- **Arquitectura del Sistema**: [ARCHITECTURE.md](ARCHITECTURE.md#high-level-architecture)
+- **Flujo de Datos**: [ARCHITECTURE.md](ARCHITECTURE.md#data-flow)
+- **Flujo de Mensajes**: [README-ES.md](README-ES.md#arquitectura-del-sistema)
+- **Diagrama de Uso**: Ver README mejorado en raíz del proyecto
+- **Diagrama de Configuración**: Ver README mejorado en raíz del proyecto
+
+---
+
+## 🔗 Enlaces Útiles
+
+### Repositorio
+- **Código fuente**: https://github.com/jeturing/Jarvis
+- **Issues**: https://github.com/jeturing/Jarvis/issues
+- **Pull Requests**: https://github.com/jeturing/Jarvis/pulls
+- **Discussions**: https://github.com/jeturing/Jarvis/discussions
+
+### Comunidad
+- **Discord**: (Añadir enlace si existe)
+- **Foro**: (Añadir enlace si existe)
+
+### Recursos Externos
+- **Anthropic Claude**: https://www.anthropic.com/
+- **OpenAI GPT**: https://openai.com/
+- **Playwright**: https://playwright.dev/
+- **grammY (Telegram)**: https://grammy.dev/
+
+---
+
+## 🤝 Contribuir a la Documentación
+
+¿Encontraste un error o quieres mejorar la documentación?
+
+1. **Reporta issues**: [GitHub Issues](https://github.com/jeturing/Jarvis/issues)
+2. **Envía PRs**: Sigue las guías en [CONTRIBUTING.md](../CONTRIBUTING.md)
+3. **Discute mejoras**: [GitHub Discussions](https://github.com/jeturing/Jarvis/discussions)
+
+### Guías para Contribuir
+
+- Mantén un tono claro y profesional
+- Incluye ejemplos de código cuando sea posible
+- Añade diagramas ASCII para conceptos complejos
+- Actualiza el índice cuando añadas nuevos documentos
+- Verifica que todos los enlaces funcionen
+
+---
+
+## 📄 Licencia
+
+La documentación está licenciada bajo la misma licencia MIT que el proyecto principal. Ver [LICENSE](../LICENSE).
+
+---
+
+## ⚡ Actualizaciones Recientes
+
+- **2024-01**: Creación de documentación completa en español
+- **2024-01**: Añadida documentación de arquitectura técnica
+- **2024-01**: Añadida documentación de componentes
+- **2024-01**: Creado índice de navegación
+
+---
+
+## 📧 Contacto
+
+¿Necesitas más ayuda?
+
+- **Email**: (Añadir email de contacto)
+- **Discord**: (Añadir enlace de Discord)
+- **Twitter**: (Añadir handle de Twitter)
+
+---
+
+<p align="center">
+  <strong>¡Feliz aprendizaje y desarrollo con Jarvis! 🤖</strong>
+</p>

docs/README-ES.md

@@ -0,0 +1,979 @@
+# 🦞 Moltbot - Documentación Completa del Proyecto
+
+## Índice
+1. [Visión General](#visión-general)
+2. [¿Qué es Moltbot?](#qué-es-moltbot)
+3. [Arquitectura del Sistema](#arquitectura-del-sistema)
+4. [Componentes Principales](#componentes-principales)
+5. [Canales de Mensajería](#canales-de-mensajería)
+6. [Tecnologías Utilizadas](#tecnologías-utilizadas)
+7. [Sistema de Plugins](#sistema-de-plugins)
+8. [Configuración y Despliegue](#configuración-y-despliegue)
+9. [Desarrollo](#desarrollo)
+10. [Estructura de Directorios](#estructura-de-directorios)
+
+---
+
+## Visión General
+
+**Moltbot** (también conocido como Jarvis o Clawdbot) es un **asistente personal de IA** que se ejecuta en tus propios dispositivos. Es una plataforma local-first, auto-hospedada y diseñada para control de usuario único.
+
+### Características Principales
+
+✅ **Multi-canal**: Conecta con WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, Matrix, Zalo y más  
+✅ **Capacidades de voz**: Wake Voice, Talk Mode (entrada/salida de voz en macOS/iOS/Android)  
+✅ **Canvas en vivo**: Espacio de trabajo visual controlado por agente con framework A2UI  
+✅ **Herramientas de primera clase**: Browser, Canvas, Cron, Sessions, acciones de Discord/Slack  
+✅ **Enrutamiento multi-agente**: Aisla agentes por espacio de trabajo/canal  
+✅ **Asistente de configuración**: `moltbot onboard` para configuración fácil  
+✅ **Daemon siempre activo**: vía systemd/launchd  
+✅ **Soporte Gateway remoto**: para servidores Linux sin interfaz gráfica  
+✅ **Privacidad**: Se ejecuta localmente, sin dependencia de servidor
+
+---
+
+## ¿Qué es Moltbot?
+
+Moltbot es un asistente de IA personal que:
+
+### Propósito Principal
+- Asistente de IA personal siempre activo usando modelos Claude/OpenAI
+- Gateway de mensajería multi-canal (bandeja de entrada unificada entre plataformas)
+- Funciona en macOS, iOS, Android, Linux, Windows (WSL2)
+- Enfocado en privacidad: se ejecuta localmente, sin dependencia de servidor
+
+### Casos de Uso
+1. **Asistente Personal**: Responde preguntas, ejecuta tareas, gestiona calendarios
+2. **Centro de Mensajería Unificado**: Una interfaz para todos tus canales de chat
+3. **Automatización**: Ejecuta scripts, gestiona tareas programadas (cron)
+4. **Navegación Web**: Automatización de navegador con Playwright
+5. **Procesamiento de Medios**: Transcripción de audio, análisis de imágenes, procesamiento de video
+6. **Desarrollo**: Asistente de código, revisión de código, depuración
+
+### Ventajas Únicas
+- **Control Total**: Tú posees tus datos y configuración
+- **Sin Servidor Central**: No hay dependencia de servicios de terceros
+- **Extensible**: Sistema de plugins robusto para añadir funcionalidad
+- **Multi-Plataforma**: Funciona en todos los sistemas operativos principales
+- **Seguro**: Autenticación local, políticas de lista de permitidos
+
+---
+
+## Arquitectura del Sistema
+
+```
+┌────────────────────────────────────────────────────┐
+│  Gateway (Servidor WebSocket)                      │
+│  - Plano de control para sesiones/canales          │
+│  - Registro de chat y enrutamiento de mensajes     │
+│  - Catálogo de modelos y perfiles de autenticación │
+│  - Trabajos cron, webhooks, herramienta de navegador│
+└────────────────────────────────────────────────────┘
+                     ↓
+┌────────────────────────────────────────────────────┐
+│  Runtime de Agente (Pi Agent)                      │
+│  - Modo RPC embedding                              │
+│  - Streaming de herramientas y bloques             │
+│  - Failover de modelos/rotación de auth            │
+│  - Ventana de contexto de sesión                   │
+│  - Entorno sandbox (Docker opcional)               │
+└────────────────────────────────────────────────────┘
+                     ↓
+┌────────────────────────────────────────────────────┐
+│  Capa Multi-Canal                                  │
+│  - Manejadores de canal base                       │
+│  - Análisis de mensajes entrantes                  │
+│  - Enrutamiento y formato salientes                │
+│  - Políticas de lista de permitidos/emparejamiento DM│
+│  - Enrutamiento de menciones en grupo              │
+└────────────────────────────────────────────────────┘
+                     ↓
+┌────────────────────────────────────────────────────┐
+│  Sistema de Herramientas                           │
+│  - Browser (automatización web)                    │
+│  - Canvas (espacio de trabajo visual)              │
+│  - Image (analizar/generar)                        │
+│  - Message (enviar entre canales)                  │
+│  - Session (generar sub-agentes)                   │
+│  - Bash (ejecutar comandos)                        │
+│  - Web (fetch, search, readability)                │
+│  - Memory (recordar contexto)                      │
+│  - Cron (programar tareas)                         │
+│  - Acciones Discord/Slack/WhatsApp                 │
+└────────────────────────────────────────────────────┘
+```
+
+### Flujo de Mensajes
+
+1. **Entrada**: Mensaje recibido desde canal (WhatsApp, Telegram, etc.)
+2. **Enrutamiento**: Gateway determina sesión y agente apropiado
+3. **Procesamiento**: Agente procesa mensaje con herramientas disponibles
+4. **Ejecución**: Herramientas se ejecutan (browser, bash, memory, etc.)
+5. **Respuesta**: Agente genera respuesta basada en resultados
+6. **Salida**: Mensaje enviado de vuelta al canal original o cruzado
+
+---
+
+## Componentes Principales
+
+### 1. Gateway (`src/gateway/`)
+
+El **Gateway** es el corazón del sistema. Es un servidor WebSocket que:
+
+- **Gestiona todas las sesiones** de chat activas
+- **Enruta mensajes** entre canales y agentes
+- **Mantiene catálogo de modelos** (Claude, GPT, Bedrock)
+- **Ejecuta trabajos cron** y webhooks
+- **Proporciona herramienta de navegador** compartida
+- **Maneja descubrimiento** de servicios (mDNS)
+
+**Archivos clave:**
+- `server.ts` - Servidor principal WebSocket
+- `chat-registry.ts` - Registro de chats activos
+- `model-catalog.ts` - Catálogo de modelos AI
+- `browser-tool.ts` - Integración de Playwright
+
+### 2. Runtime de Agente (`src/agents/`)
+
+El **Runtime de Agente** ejecuta modelos de IA y gestiona interacciones:
+
+- **Integración Pi Agent** (`pi-embedded-runner.ts`) - Ejecuta Claude/GPT en modo RPC
+- **Gestión de sesiones** (`session-*.ts`) - Aisla contextos de chat
+- **Streaming de herramientas** - Streaming en tiempo real de uso de herramientas
+- **Failover de modelos** - Rotación automática si un modelo falla
+- **Manejo de perfiles de auth** - OAuth y claves API
+
+**Archivos clave:**
+- `pi-embedded-runner.ts` - Ejecutor principal de agente
+- `session-manager.ts` - Gestor de sesiones de chat
+- `tool-registry.ts` - Registro de herramientas disponibles
+- `model-auth.ts` - Autenticación de modelos
+
+### 3. Canales (`src/channels/`, `extensions/`)
+
+**Canales integrados** (en `src/`):
+- `whatsapp/` - WhatsApp (biblioteca Baileys)
+- `telegram/` - Telegram (grammY)
+- `signal/` - Signal (signal-cli)
+- `imessage/` - iMessage (imsg)
+- `discord/` - Discord (discord.js)
+- `slack/` - Slack (Bolt)
+
+**Canales de extensión** (en `extensions/`):
+- `msteams/` - Microsoft Teams
+- `matrix/` - Matrix con soporte E2E
+- `zalo/`, `zalouser/` - Mensajería vietnamita
+- `bluebubbles/` - Relay iMessage
+- Y más de 20 extensiones de canal
+
+**Características:**
+- Emparejamiento DM (lista de permitidos basada en código)
+- Enrutamiento de grupo/canal con control de menciones
+- Etiquetas de respuesta para respuestas basadas en hilos
+- Fragmentación de mensajes por canal
+- Reconocimientos de reacción
+- Indicadores de escritura
+
+### 4. Sistema de Plugins (`src/plugins/`)
+
+El **sistema de plugins** permite extensibilidad:
+
+**Tipos de plugins:**
+- **Plugins de canal** - Nuevas integraciones de mensajería
+- **Plugins de auth** - Manejadores OAuth
+- **Plugins de herramientas** - Herramientas personalizadas de agente
+- **Plugins de memoria** - Backends de almacenamiento personalizados
+- **Plugins de hooks** - Manejadores de eventos globales
+
+**Archivos clave:**
+- `discovery.ts` - Auto-detecta plugins
+- `loader.ts` - Carga plugins validados
+- `manifest.ts` - Validación de esquema de manifiesto
+- `services.ts` - Proveedores de inyección de servicios
+
+### 5. Herramienta de Navegador (`src/browser/`)
+
+La **herramienta de navegador** proporciona automatización web:
+
+- **Automatización Chromium** vía Playwright
+- **Snapshots conscientes de IA** de páginas
+- **Rellenado de formularios e interacción**
+- **Generación de screenshots y PDF**
+- **Perfiles personalizados** con cookies/almacenamiento
+- **Puente CDP** para depuración DevTools
+
+**Archivos clave:**
+- `browser-tool.ts` - API principal de herramienta
+- `playwright-bridge.ts` - Puente Playwright
+- `snapshot.ts` - Generación de snapshots de página
+
+### 6. Pipeline de Medios (`src/media/`)
+
+El **pipeline de medios** maneja procesamiento de medios:
+
+- Procesamiento de imagen/audio/video
+- Hooks de transcripción
+- Almacén de archivos con límites de tamaño
+- Detección de tipo MIME
+- Gestión de ciclo de vida temporal
+
+**Archivos clave:**
+- `index.ts` - API principal de medios
+- `transcription.ts` - Hooks de transcripción de audio
+- `file-store.ts` - Almacenamiento persistente de archivos
+
+### 7. Canvas Host (`src/canvas-host/`)
+
+El **Canvas Host** proporciona un espacio de trabajo visual:
+
+- Framework A2UI para renderizado
+- Actualización de estado en tiempo real
+- Serialización de DOM
+- Integración WebSocket
+
+**Archivos clave:**
+- `index.ts` - API principal de Canvas
+- `a2ui/` - Paquetes de framework A2UI
+
+### 8. CLI (`src/cli/`)
+
+La **CLI** proporciona interfaz de línea de comandos:
+
+**Comandos principales:**
+- `gateway` - Iniciar servidor gateway
+- `agent` - Ejecutar agente AI
+- `onboard` - Asistente de configuración
+- `models` - Gestionar modelos AI
+- `channels` - Gestionar canales
+- `cron` - Gestionar trabajos programados
+- `daemon` - Gestionar servicio daemon
+- `plugins` - Gestionar plugins
+- `skills` - Gestionar skills
+
+**Archivos clave:**
+- `index.ts` - Entry point de CLI
+- `commands/` - Implementaciones de comandos
+
+### 9. Configuración (`src/config/`)
+
+El **sistema de configuración** gestiona ajustes:
+
+- Carga de configuración YAML
+- Validación de esquema Zod
+- Almacenamiento de sesión
+- Gestión de rutas
+- Migraciones de configuración
+
+**Archivos clave:**
+- `index.ts` - Cargador principal de configuración
+- `schema.ts` - Esquema de validación Zod
+- `paths.ts` - Resolución de rutas de sistema
+
+---
+
+## Canales de Mensajería
+
+### Canales Integrados
+
+| Canal | Biblioteca | Estado |
+|-------|-----------|--------|
+| **WhatsApp** | @whiskeysockets/baileys | ✅ Estable |
+| **Telegram** | grammy | ✅ Estable |
+| **Signal** | signal-cli | ✅ Estable |
+| **iMessage** | imsg | ✅ Estable |
+| **Discord** | discord.js | ✅ Estable |
+| **Slack** | @slack/bolt | ✅ Estable |
+| **Google Chat** | Chat API | ✅ Estable |
+
+### Canales de Extensión
+
+| Canal | Ubicación | Estado |
+|-------|-----------|--------|
+| **BlueBubbles** | extensions/bluebubbles | ✅ Estable |
+| **Microsoft Teams** | extensions/msteams | ✅ Estable |
+| **Matrix** | extensions/matrix | ✅ Estable |
+| **Zalo** | extensions/zalo | ✅ Estable |
+| **Zalo Personal** | extensions/zalouser | ✅ Estable |
+| **Twitch** | extensions/twitch | ✅ Estable |
+| **Mattermost** | extensions/mattermost | ✅ Estable |
+| **Nextcloud Talk** | extensions/nextcloud-talk | ✅ Estable |
+| **Tlon** | extensions/tlon | ✅ Estable |
+| **Nostr** | extensions/nostr | ✅ Estable |
+| **LINE** | extensions/line | ✅ Estable |
+| **Voice Call** | extensions/voice-call | ✅ Beta |
+
+### Características de Canal
+
+- **Emparejamiento DM**: Lista de permitidos basada en código
+- **Enrutamiento de grupo**: Control de menciones
+- **Etiquetas de respuesta**: Respuestas basadas en hilos
+- **Fragmentación de mensajes**: Límites específicos por canal
+- **Reacciones**: Reconocimientos
+- **Indicadores de escritura**: Estado en tiempo real
+- **Redacción de medios**: Capacidades de privacidad
+
+---
+
+## Tecnologías Utilizadas
+
+### Stack Backend
+
+| Tecnología | Versión | Propósito |
+|------------|---------|-----------|
+| **TypeScript** | 5.9+ | Lenguaje principal |
+| **Node.js** | ≥22.12.0 | Runtime |
+| **Hono** | 4.11.4 | Framework HTTP |
+| **Express** | 5.2 | Servidor WebSocket (legacy) |
+| **ws** | 8.19 | Biblioteca WebSocket |
+| **Zod** | 4.3 | Validación de esquema |
+
+### Integración AI/Modelo
+
+| Tecnología | Propósito |
+|------------|-----------|
+| **@mariozechner/pi-agent-core** | Agente Pi de Anthropic |
+| **@mariozechner/pi-tui** | UI de terminal para agente |
+| **Anthropic SDK** | API Claude |
+| **OpenAI SDK** | API ChatGPT |
+| **AWS Bedrock SDK** | Modelos AWS |
+| **Ollama SDK** | Soporte LLM local |
+
+### Mensajería & Comunicación
+
+| Biblioteca | Canal |
+|-----------|-------|
+| **@whiskeysockets/baileys** | WhatsApp |
+| **grammy** | Telegram |
+| **@slack/bolt** | Slack |
+| **discord.js** | Discord |
+| **@line/bot-sdk** | LINE |
+| **signal-cli** | Signal |
+| **imsg** | iMessage |
+
+### Automatización de Navegador
+
+| Tecnología | Propósito |
+|------------|-----------|
+| **Playwright Core** | 1.58 - Automatización web |
+| **chromium-bidi** | 13.0 - Protocolo DevTools Chrome |
+| **Sharp** | 0.34 - Procesamiento de imágenes |
+| **pdfjs-dist** | Manipulación de PDF |
+
+### Base de Datos & Almacenamiento
+
+| Tecnología | Propósito |
+|------------|-----------|
+| **SQLite-vec** | Almacenamiento vectorial para memoria |
+| **LanceDB** | Búsqueda vectorial (extensión) |
+| **Sistema de archivos** | Persistencia de sesión/configuración |
+| **proper-lockfile** | Control de acceso concurrente |
+
+### CLI & DevOps
+
+| Tecnología | Propósito |
+|------------|-----------|
+| **Commander.js** | Análisis de argumentos CLI |
+| **@clack/prompts** | Prompts CLI interactivos |
+| **Chalk** | Colores de terminal |
+| **dotenv** | Configuración de entorno |
+| **YAML** | Soporte de formato de configuración |
+
+### Herramientas de Desarrollo
+
+| Tecnología | Propósito |
+|------------|-----------|
+| **TypeScript** | Verificación de tipos estricta |
+| **Vitest** | Ejecutor de tests |
+| **oxlint** | Linting (OxC) |
+| **oxfmt** | Formateo |
+| **tsx** | Ejecución TS |
+| **Playwright Core** | Testing E2E |
+| **Wireit** | Orquestación de tareas de build |
+
+---
+
+## Sistema de Plugins
+
+### Arquitectura de Plugins
+
+```
+┌─────────────────────────────────────────────┐
+│  Descubrimiento de Plugins                  │
+│  - Auto-detecta desde extensions/           │
+│  - Auto-detecta desde node_modules/@moltbot/│
+│  - Validación de manifiesto                 │
+└─────────────────────────────────────────────┘
+              ↓
+┌─────────────────────────────────────────────┐
+│  Cargador de Plugins                        │
+│  - Validación de esquema de configuración   │
+│  - Inicialización de runtime                │
+│  - Registro de hooks                        │
+└─────────────────────────────────────────────┘
+              ↓
+┌─────────────────────────────────────────────┐
+│  Proveedores de Servicios                   │
+│  - Acceso a cliente Gateway                 │
+│  - Proveedor de configuración               │
+│  - Inyección de logger                      │
+│  - Utilidades de cliente HTTP               │
+└─────────────────────────────────────────────┘
+```
+
+### Tipos de Plugins
+
+#### 1. Plugins de Canal
+Añaden nuevos canales de mensajería:
+```typescript
+export function createChannelPlugin(): ChannelPlugin {
+  return {
+    name: 'my-channel',
+    type: 'channel',
+    init: async (config) => {
+      // Inicializar canal
+    },
+    send: async (message) => {
+      // Enviar mensaje
+    },
+    receive: async (handler) => {
+      // Recibir mensajes
+    }
+  }
+}
+```
+
+#### 2. Plugins de Herramientas
+Añaden herramientas personalizadas para agentes:
+```typescript
+export function createToolPlugin(): ToolPlugin {
+  return {
+    name: 'my-tool',
+    type: 'tool',
+    schema: z.object({
+      input: z.string()
+    }),
+    execute: async (params) => {
+      // Ejecutar herramienta
+      return { result: 'done' }
+    }
+  }
+}
+```
+
+#### 3. Plugins de Auth
+Añaden manejadores OAuth personalizados:
+```typescript
+export function createAuthPlugin(): AuthPlugin {
+  return {
+    name: 'my-auth',
+    type: 'auth',
+    authorize: async (credentials) => {
+      // Manejar OAuth
+      return { token: 'access_token' }
+    }
+  }
+}
+```
+
+#### 4. Plugins de Memoria
+Añaden backends de almacenamiento personalizados:
+```typescript
+export function createMemoryPlugin(): MemoryPlugin {
+  return {
+    name: 'my-memory',
+    type: 'memory',
+    store: async (key, value) => {
+      // Almacenar valor
+    },
+    retrieve: async (key) => {
+      // Recuperar valor
+    }
+  }
+}
+```
+
+#### 5. Plugins de Hooks
+Añaden manejadores de eventos globales:
+```typescript
+export function createHookPlugin(): HookPlugin {
+  return {
+    name: 'my-hook',
+    type: 'hook',
+    hooks: {
+      'message:received': async (message) => {
+        // Manejar mensaje recibido
+      },
+      'message:sent': async (message) => {
+        // Manejar mensaje enviado
+      }
+    }
+  }
+}
+```
+
+### Esquema de Manifiesto de Plugin
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.0.0",
+  "description": "Plugin description",
+  "exports": {
+    ".": "./dist/index.js",
+    "./config-schema": "./dist/config-schema.js"
+  },
+  "hooks": ["channel", "tool"],
+  "permissions": ["network", "fs"],
+  "dependencies": {
+    "some-lib": "^1.0.0"
+  }
+}
+```
+
+### Ciclo de Vida de Plugin
+
+1. **Descubrimiento** - Auto-detecta plugins desde directorios conocidos
+2. **Validación** - Valida manifiesto y esquema de configuración
+3. **Carga** - Carga módulo de plugin
+4. **Inicialización** - Ejecuta función init de plugin
+5. **Registro** - Registra hooks y herramientas
+6. **Ejecución** - Plugin maneja eventos y llamadas
+7. **Apagado** - Limpieza durante apagado de gateway
+
+---
+
+## Configuración y Despliegue
+
+### Archivo de Configuración Principal
+
+El archivo `.moltbot.yaml` (o `.clawdbot.yaml`) controla toda la configuración:
+
+```yaml
+# Configuración de Gateway
+gateway:
+  mode: local  # o 'remote'
+  port: 18789
+  bind: loopback  # o 'all'
+  verbose: true
+
+# Configuración de Agentes
+agents:
+  default:
+    model: claude-4.5-sonnet
+    thinking: high
+    temperature: 0.7
+    max_tokens: 8192
+
+# Configuración de Canales
+channels:
+  whatsapp:
+    enabled: true
+    pairing: code
+    allowlist:
+      - "+1234567890"
+  
+  telegram:
+    enabled: true
+    bot_token: "${TELEGRAM_BOT_TOKEN}"
+  
+  discord:
+    enabled: true
+    bot_token: "${DISCORD_BOT_TOKEN}"
+
+# Configuración de Herramientas
+tools:
+  browser:
+    enabled: true
+    headless: true
+    timeout: 30000
+  
+  canvas:
+    enabled: true
+    port: 8080
+
+# Configuración de Sandbox
+sandbox:
+  enabled: false
+  docker_image: "moltbot/sandbox"
+  
+# Configuración de Plugins
+plugins:
+  - name: matrix
+    enabled: true
+    config:
+      homeserver: "https://matrix.org"
+
+# Configuración de Skills
+skills:
+  - workspace1
+  - workspace2
+```
+
+### Variables de Entorno
+
+Archivo `.env`:
+```bash
+# Tokens de API
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
+DISCORD_BOT_TOKEN=MTk4...
+
+# Configuración de Gateway
+CLAWDBOT_GATEWAY_PORT=18789
+CLAWDBOT_GATEWAY_BIND=loopback
+
+# Configuración de Modo
+CLAWDBOT_PROFILE=production  # o 'dev'
+CLAWDBOT_SKIP_CHANNELS=0
+
+# Configuración de Depuración
+CLAWDBOT_DEBUG=0
+CLAWDBOT_VERBOSE=0
+```
+
+### Instalación
+
+#### Instalación rápida (npm)
+```bash
+npm install -g moltbot@latest
+moltbot onboard --install-daemon
+```
+
+#### Desde fuente (desarrollo)
+```bash
+git clone https://github.com/moltbot/moltbot.git
+cd moltbot
+pnpm install
+pnpm ui:build
+pnpm build
+pnpm moltbot onboard --install-daemon
+```
+
+#### Docker
+```bash
+docker-compose up -d
+```
+
+### Despliegue como Daemon
+
+#### macOS (launchd)
+```bash
+moltbot daemon install
+moltbot daemon start
+moltbot daemon status
+```
+
+#### Linux (systemd)
+```bash
+moltbot daemon install
+systemctl --user start moltbot-gateway
+systemctl --user status moltbot-gateway
+```
+
+#### Windows (WSL2)
+```bash
+# En WSL2
+moltbot daemon install
+moltbot daemon start
+```
+
+### Gateway Remoto
+
+Para servidores sin interfaz gráfica:
+
+```yaml
+# En servidor remoto
+gateway:
+  mode: remote
+  bind: all
+  port: 18789
+
+# En cliente local
+agents:
+  gateway_url: "ws://your-server:18789"
+```
+
+---
+
+## Desarrollo
+
+### Configuración de Entorno de Desarrollo
+
+```bash
+# 1. Clonar repositorio
+git clone https://github.com/moltbot/moltbot.git
+cd moltbot
+
+# 2. Instalar dependencias
+pnpm install
+
+# 3. Construir UI
+pnpm ui:build
+
+# 4. Construir proyecto
+pnpm build
+
+# 5. Ejecutar en modo desarrollo
+pnpm gateway:watch  # Auto-recarga en cambios
+```
+
+### Scripts de Desarrollo
+
+```bash
+# Desarrollo
+pnpm dev                  # Ejecutar CLI en modo dev
+pnpm gateway:watch        # Gateway con auto-recarga
+pnpm gateway:dev          # Gateway dev sin canales
+pnpm tui:dev              # UI de terminal dev
+
+# Build
+pnpm build                # Compilar TypeScript
+pnpm ui:build             # Construir UI web
+pnpm canvas:a2ui:bundle   # Empaquetar Canvas A2UI
+
+# Testing
+pnpm test                 # Ejecutar todos los tests
+pnpm test:watch           # Tests en modo watch
+pnpm test:coverage        # Tests con cobertura
+pnpm test:e2e             # Tests end-to-end
+pnpm test:live            # Tests con APIs reales
+
+# Linting & Formatting
+pnpm lint                 # Lint TypeScript
+pnpm lint:fix             # Fix problemas de lint
+pnpm format               # Verificar formato
+pnpm format:fix           # Fix formato
+
+# Plataformas
+pnpm ios:build            # Construir app iOS
+pnpm ios:run              # Ejecutar app iOS
+pnpm android:assemble     # Ensamblar app Android
+pnpm android:run          # Ejecutar app Android
+pnpm mac:package          # Empaquetar app macOS
+```
+
+### Estructura de Testing
+
+```
+test/
+├── unit/           # Tests unitarios
+├── e2e/            # Tests end-to-end
+├── integration/    # Tests de integración
+└── fixtures/       # Datos de prueba
+```
+
+**Configuraciones de Vitest:**
+- `vitest.config.ts` - Configuración principal
+- `vitest.unit.config.ts` - Tests unitarios
+- `vitest.e2e.config.ts` - Tests E2E
+- `vitest.live.config.ts` - Tests con APIs reales
+- `vitest.extensions.config.ts` - Tests de extensiones
+- `vitest.gateway.config.ts` - Tests de gateway
+
+### Requisitos de Cobertura de Tests
+
+- **Líneas**: 70%
+- **Funciones**: 70%
+- **Ramas**: 70%
+- **Declaraciones**: 70%
+
+### Estándares de Código
+
+- **TypeScript estricto**: Verificación de tipos completa
+- **ESLint**: Linting con oxlint
+- **Prettier**: Formateo con oxfmt
+- **Pre-commit hooks**: Ejecuta lint + format antes de commit
+- **Límite de LOC**: ~700 líneas por archivo (guía)
+
+---
+
+## Estructura de Directorios
+
+```
+/
+├── src/                      # Código fuente TypeScript
+│   ├── agents/              # Runtime de agente y gestión de sesiones
+│   ├── gateway/             # Servidor gateway y registro de chat
+│   ├── channels/            # Infraestructura base de canales
+│   ├── cli/                 # Comandos de interfaz de línea de comandos
+│   ├── browser/             # Herramienta de automatización de navegador
+│   ├── canvas-host/         # Host de Canvas y framework A2UI
+│   ├── media/               # Pipeline de procesamiento de medios
+│   ├── plugins/             # Sistema de plugins y cargador
+│   ├── config/              # Sistema de configuración
+│   ├── whatsapp/            # Integración WhatsApp
+│   ├── telegram/            # Integración Telegram
+│   ├── signal/              # Integración Signal
+│   ├── discord/             # Integración Discord
+│   ├── slack/               # Integración Slack
+│   ├── imessage/            # Integración iMessage
+│   ├── routing/             # Enrutamiento de mensajes
+│   ├── security/            # Auth y políticas de seguridad
+│   ├── memory/              # Gestión de memoria/contexto
+│   ├── tts/                 # Integración text-to-speech
+│   ├── wizard/              # Flujo de asistente de onboarding CLI
+│   ├── web/                 # Frontend WebChat y Control UI
+│   ├── utils/               # Utilidades compartidas
+│   └── ...
+│
+├── extensions/              # Plugins de canal y extensiones
+│   ├── bluebubbles/        # Plugin BlueBubbles
+│   ├── matrix/             # Plugin Matrix
+│   ├── msteams/            # Plugin Microsoft Teams
+│   ├── zalo/               # Plugin Zalo
+│   ├── zalouser/           # Plugin Zalo Personal
+│   ├── voice-call/         # Plugin Voice Call
+│   └── ...
+│
+├── apps/                    # Aplicaciones nativas
+│   ├── macos/              # App macOS (SwiftUI)
+│   ├── ios/                # App iOS (SwiftUI)
+│   └── android/            # App Android (Kotlin)
+│
+├── docs/                    # Documentación
+│   ├── start/              # Guías de inicio
+│   ├── install/            # Guías de instalación
+│   ├── channels/           # Documentación de canales
+│   ├── concepts/           # Documentación de conceptos
+│   ├── cli/                # Documentación de CLI
+│   ├── gateway/            # Documentación de gateway
+│   ├── platforms/          # Guías específicas de plataforma
+│   ├── providers/          # Documentación de proveedores
+│   ├── reference/          # Documentación de referencia
+│   └── ...
+│
+├── skills/                  # Paquetes de skills de workspace
+│   └── workspace1/         # Ejemplo de workspace
+│
+├── packages/                # Paquetes monorepo
+│   └── ...
+│
+├── scripts/                 # Scripts de utilidad
+│   ├── build-*.ts          # Scripts de build
+│   ├── test-*.sh           # Scripts de test
+│   ├── package-*.sh        # Scripts de empaquetado
+│   └── ...
+│
+├── test/                    # Fixtures de test y helpers
+│   ├── fixtures/           # Datos de prueba
+│   └── helpers/            # Utilidades de test
+│
+├── ui/                      # UI web (Control UI)
+│   └── ...
+│
+├── vendor/                  # Dependencias vendorizadas
+│   └── ...
+│
+├── .github/                 # Workflows de GitHub Actions
+│   ├── workflows/          # Definiciones de workflow CI/CD
+│   └── labeler.yml         # Configuración de auto-etiquetado
+│
+├── dist/                    # Salida compilada (generada)
+│   └── ...
+│
+├── package.json             # Configuración de paquete npm
+├── pnpm-workspace.yaml      # Configuración de workspace pnpm
+├── tsconfig.json            # Configuración de TypeScript
+├── vitest.config.ts         # Configuración de Vitest
+├── docker-compose.yml       # Configuración de Docker Compose
+├── Dockerfile               # Dockerfile principal
+├── README.md                # README principal (inglés)
+├── CHANGELOG.md             # Registro de cambios
+├── LICENSE                  # Licencia MIT
+└── ...
+```
+
+### Directorios Clave
+
+#### `/src/`
+Código fuente principal de TypeScript. Organizado por dominio:
+- **Agentes & Runtime**: `agents/`, `memory/`, `sessions/`
+- **Comunicación**: `gateway/`, `channels/`, `routing/`
+- **Canales Integrados**: `whatsapp/`, `telegram/`, `discord/`, etc.
+- **Herramientas**: `browser/`, `canvas-host/`, `media/`, `tts/`
+- **Sistema**: `cli/`, `config/`, `plugins/`, `daemon/`
+- **Seguridad**: `security/`, `pairing/`
+- **UI**: `web/`, `wizard/`, `tui/`
+
+#### `/extensions/`
+Plugins de extensión (20+ canales). Cada extensión es un paquete npm auto-contenido:
+- Tiene su propio `package.json`
+- Define `plugin.manifest.json`
+- Implementa hooks de plugin
+- Puede tener dependencias propias
+
+#### `/apps/`
+Aplicaciones nativas para múltiples plataformas:
+- **macOS**: App SwiftUI con integración de menubar
+- **iOS**: App SwiftUI con soporte de voz
+- **Android**: App Kotlin con soporte de voz
+
+#### `/docs/`
+Documentación completa (Mintlify):
+- Guías de inicio rápido
+- Tutoriales de instalación
+- Documentación de conceptos
+- Referencia de API
+- Guías específicas de plataforma
+- Documentación de desarrollo de plugins
+
+#### `/skills/`
+Skills de workspace. Cada workspace puede tener:
+- Prompts personalizados
+- Herramientas bash personalizadas
+- Integraciones personalizadas
+- Configuración específica de workspace
+
+#### `/scripts/`
+Scripts de utilidad para:
+- Construcción y empaquetado
+- Testing (unit, E2E, Docker)
+- Generación de código (protocol, Swift)
+- Gestión de releases
+- Automatización de desarrollo
+
+#### `/test/`
+Fixtures de test y helpers:
+- Datos de prueba
+- Mocks y stubs
+- Utilidades de test
+- Configuraciones de test
+
+---
+
+## Recursos Adicionales
+
+### Documentación Oficial
+- **Sitio Web**: https://molt.bot
+- **Documentación**: https://docs.molt.bot
+- **Comenzar**: https://docs.molt.bot/start/getting-started
+- **FAQ**: https://docs.molt.bot/start/faq
+- **Showcase**: https://docs.molt.bot/start/showcase
+
+### Comunidad
+- **Discord**: https://discord.gg/clawd
+- **GitHub**: https://github.com/moltbot/moltbot
+- **Releases**: https://github.com/moltbot/moltbot/releases
+
+### Guías de Desarrollo
+- **Desarrollo de Plugins**: Ver `PLUGIN-DEVELOPMENT.md`
+- **Referencia de API**: Ver `API-REFERENCE.md`
+- **Guía de Arquitectura**: Ver `ARCHITECTURE.md`
+- **Guía de Despliegue**: Ver `DEPLOYMENT.md`
+
+---
+
+## Licencia
+
+MIT License - Ver [LICENSE](../LICENSE) para detalles.
+
+---
+
+## Contribuir
+
+¡Las contribuciones son bienvenidas! Ver [CONTRIBUTING.md](../CONTRIBUTING.md) para guías.
+
+---
+
+**¡Feliz hacking con Moltbot! 🦞**