From 224d2f522ca5de68a8cce31c214f32d70cfa3ba3 Mon Sep 17 00:00:00 2001 From: ARCHITECT Date: Tue, 30 Dec 2025 18:20:01 +0000 Subject: [PATCH] Add comprehensive README for CAPTAIN CLAUDE system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document full infrastructure overview (Central, DECK, CORP, HST) - Add SSH access instructions and R2 storage documentation - Detail all available services and microservices - Include context-manager CLI commands and examples - Document operation rules and automatic cleanup procedures - Provide troubleshooting and contact information - Add examples for common use cases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 352 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e1bd91a --- /dev/null +++ b/README.md @@ -0,0 +1,352 @@ +# CAPTAIN CLAUDE - Sistema Multiagente TZZR + +Coordinador central del sistema TZZR (The Zero-Trust Resilient Resource Network). CAPTAIN CLAUDE gestiona la infraestructura distribuida, servicios centralizados y coordina agentes especializados en múltiples servidores. + +## Visión General + +CAPTAIN CLAUDE es un sistema multiagente que coordina la infraestructura TZZR: + +- **Servidor Central**: 69.62.126.110 (Gitea, PostgreSQL) +- **Servidores Remotos**: DECK, CORP, HST +- **Almacenamiento**: Cloudflare R2 (s3://architect/) +- **Coordinación**: Agentes especializados para tareas específicas + +## Infraestructura + +### Servidores + +| Servidor | IP | Función | +|----------|-----|---------| +| **Central** | 69.62.126.110 | Control central, Gitea, PostgreSQL | +| **DECK** | 72.62.1.113 | Servicios, Agentes (Clara, Alfred, Mason, Feldman) | +| **CORP** | 92.112.181.188 | ERP (Odoo), CMS (Directus), Agentes (Margaret, Jared) | +| **HST** | 72.62.2.84 | Directus, Gestión de imágenes | + +### Acceso SSH + +Todos los servidores remotos son accesibles via SSH usando la clave `~/.ssh/tzzr`: + +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 # DECK +ssh -i ~/.ssh/tzzr root@92.112.181.188 # CORP +ssh -i ~/.ssh/tzzr root@72.62.2.84 # HST +``` + +## Almacenamiento R2 + +Cloudflare R2 almacena documentos, configuraciones y backups: + +```bash +# Endpoint +https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com + +# Estructura +s3://architect/ +├── documentos adjuntos/ # Documentos para compartir +├── documentos adjuntos/architect/ # Reportes generados +├── system/ # Configs, backups internos +├── gpu-services/ # Servicios GRACE/PENNY/FACTORY +├── backups/ # Backups Gitea y sistema +└── auditorias/ # Logs de auditoría +``` + +### Comandos R2 + +```bash +# Listar contenido +aws s3 ls s3://architect/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com + +# Subir archivo para usuario +aws s3 cp archivo.md "s3://architect/documentos adjuntos/archivo.md" \ + --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com + +# Subir archivo interno +aws s3 cp archivo "s3://architect/system/archivo" \ + --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com +``` + +## Agentes Especializados + +CAPTAIN CLAUDE coordina múltiples agentes para diferentes tareas: + +### Agentes Disponibles + +- **Captain**: Coordinador principal, análisis de tareas, delegación +- **Coder**: Implementación de código, desarrollo de features +- **Reviewer**: Revisión de código, calidad, estándares +- **Researcher**: Investigación, análisis, documentación +- **Architect**: Diseño de sistemas, arquitectura, optimización + +### Ejecución de Agentes + +Los agentes pueden ejecutarse: +- **En paralelo**: Para tareas independientes +- **Secuencialmente**: Para tareas dependientes +- **Interactivamente**: Con feedback del usuario + +## Servicios en Cada Servidor + +### DECK (72.62.1.113) + +**Microservicios:** +- Clara (5051) - Log inmutable y auditoría +- Alfred (5052) - Automatización de workflows +- Mason (5053) - Enriquecimiento de datos +- Feldman (5054) - Validador Merkle + +**Aplicaciones:** +- Nextcloud (8084) - Almacenamiento en la nube +- Odoo (8069) - ERP +- Vaultwarden (8085) - Gestor de contraseñas +- Directus (8055) - CMS +- Mailcow (8180) - Servidor de correo + +**Infraestructura:** +- PostgreSQL (5432) - Base de datos con pgvector +- Redis (6379) - Cache en memoria + +### CORP (92.112.181.188) + +**Aplicaciones:** +- Odoo 17 (8069) - Sistema ERP empresarial +- Directus 11 (8055) - CMS y gestor de contenidos +- Nextcloud (8080) - Almacenamiento compartido +- Vaultwarden (8081) - Gestor de contraseñas + +**Microservicios:** +- Margaret (5051) - Orquestación y coordinación +- Jared (5052) - Procesamiento de datos +- Mason (5053) - Generación de reportes +- Feldman (5054) - Auditoría y logging + +**Infraestructura:** +- PostgreSQL (5432) - Base de datos + +### HST (72.62.2.84) + +- Directus +- Gestión de imágenes +- Servicios de almacenamiento + +## Context-Manager + +Sistema central para gestión de contexto persistente. Disponible en DECK. + +### Instalación + +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "context-manager --help" +``` + +### Comandos Principales + +```bash +# Ver ayuda +context-manager --help + +# Listar bloques de contexto +context-manager block list + +# Ver contenido de bloque +context-manager block view + +# Crear bloque +context-manager block add "nombre_bloque" \ + --tipo "project" \ + --contenido '{"estado": "en_progreso"}' + +# Eliminar bloque +context-manager block remove + +# Listar memoria compartida +context-manager memory list + +# Agregar a memoria +context-manager memory add "clave" "contenido" + +# Chat interactivo +context-manager chat +``` + +## Documentación + +Manuales disponibles para cada servidor: + +- **MANUAL_USUARIO_DECK.md**: Guía completa del servidor DECK + - Servicios, configuración, troubleshooting + - PostgreSQL y administración + - Guías rápidas de inicio + +- **MANUAL_USUARIO_CORP.md**: Guía completa del servidor CORP + - Odoo 17 y Directus 11 + - Administración y troubleshooting + - Procedimientos frecuentes + +- **MANUAL_USUARIO_HST.md**: Documentación del servidor HST + +Todos los manuales se encuentran en: +- Repositorio: `/home/architect/captain-claude/` +- R2: `s3://architect/system/skynet v8/` + +## Reglas de Operación + +### Principio Fundamental + +**No guardar documentos en servidor local.** + +- Los documentos y reportes generados van a R2, NO al filesystem local +- El servidor solo mantiene código, configuraciones y aplicaciones activas +- Limpieza automática después de generar archivos + +### Limpieza Automática + +Al finalizar cualquier tarea que genere archivos: + +1. Subir TODOS los archivos generados a R2 + ```bash + aws s3 cp archivo "s3://architect/destino/archivo" \ + --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com + ``` + +2. Verificar que están en R2 + ```bash + aws s3 ls s3://architect/destino/ \ + --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com + ``` + +3. Eliminar archivos locales + ```bash + rm -rf carpeta_local/ + ``` + +4. No esperar a que el usuario lo pida - ejecutar automáticamente + +### Destinos R2 por Tipo + +| Tipo | Destino R2 | +|------|-----------| +| Auditorías | `s3://architect/auditorias/` | +| Reportes para usuario | `s3://architect/documentos adjuntos/architect/` | +| Configs/backups internos | `s3://architect/system/` | +| Documentos de usuario | `s3://architect/documentos adjuntos/` | + +## Ejecución + +### Inicio + +```bash +# Ejecutar CAPTAIN CLAUDE +python captain_claude.py + +# O via script +./run.sh +``` + +### Variables de Entorno + +Se requieren: +- Acceso SSH a servidores remotos (clave `~/.ssh/tzzr`) +- Credenciales de R2 (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) +- APIs configuradas (Anthropic, OpenAI, etc.) + +### Logs y Monitoreo + +Los logs se almacenan en: +- Local: `captain_output/` +- R2: `s3://architect/auditorias/` + +## Casos de Uso + +### 1. Supervisar Estado de la Infraestructura + +```bash +python captain_claude.py --action health-check --all-servers +``` + +### 2. Generar Reportes + +```bash +python captain_claude.py --action report --type performance --output r2 +``` + +### 3. Administrar Servicios + +```bash +# Ver estado de servicio en DECK +ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps" + +# Reiniciar servicio +ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker restart clara-service" +``` + +### 4. Gestionar Contexto + +```bash +# Crear bloque de contexto para coordinación +context-manager block add "tarea_importante" \ + --tipo "coordination" \ + --contenido '{"agentes": ["coder", "reviewer"], "estado": "en_progreso"}' +``` + +## Contacto y Soporte + +### Coordinación + +- **Servidor Central**: Git en http://localhost:3000 +- **Bitácora**: Logs en R2 `s3://architect/auditorias/` +- **Documentación**: Manuales en R2 `s3://architect/system/skynet v8/` + +### Escalation + +1. Revisar logs relevantes +2. Consultar documentación +3. Crear ticket en Gitea +4. Contactar administrador del sistema + +## Información Técnica + +### Dependencias + +- Python 3.8+ +- SSH (conexión a servidores remotos) +- AWS CLI (acceso a R2) +- Docker (para servicios) +- PostgreSQL (base de datos) + +### Estructura del Proyecto + +``` +captain-claude/ +├── README.md # Este archivo +├── CAPTAIN_CLAUDE.md # Instrucciones de operación +├── captain_claude.py # Coordinador principal +├── captain # Script de ejecución +├── apps/ # Aplicaciones integradas +├── context-manager/ # Sistema de gestión de contexto +├── venv/ # Entorno virtual Python +└── captain_output/ # Salidas y logs +``` + +### Permisos y Seguridad + +- Clave SSH protegida: `~/.ssh/tzzr` +- Credenciales R2 en variables de entorno +- Logs auditados y almacenados en R2 +- Acceso restringido por rol + +## Versión y Actualización + +**Versión**: 1.0 +**Última actualización**: 2025-12-30 +**Sistema**: TZZR - Skynet v8 + +## Licencia + +Proyecto interno del sistema TZZR. + +--- + +Para más información, consultar: +- Gitea: http://69.62.126.110:3000 +- R2 System Docs: s3://architect/system/ +- Manuales: s3://architect/system/skynet v8/