docs: add comprehensive component documentation and index

Co-authored-by: jcarvajalantigua <54653531+jcarvajalantigua@users.noreply.github.com>

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>