agent-rev 0.5.14 → 0.5.24

package/dist/core/engine.js

@@ -69,7 +69,7 @@ function rebuildCmd(cliName, model, flags) {
 }
 async function ask(prompt, rl, fi) {
     if (fi) {
-        fi.println(chalk.cyan(`  ${prompt}`));
+        fi.println(chalk.cyan(prompt));
         const answer = await fi.readLine();
         // Echo user response right-aligned (chat style, per line)
         const userLines = answer.trim().split('\n').filter(l => l.trim());
@@ -238,9 +238,11 @@ async function walkForKeyFiles(root) {
         'server.ts', 'server.js', 'server.py',
         'application.ts', 'application.js', 'application.py',
     ]);
-    const ENTRY_REGEX = /Application\.(java|kt)$/;
+    const ENTRY_REGEX = /Application\.[a-z]+$/i; // *Application.java, *Application.kt, etc.
     const CTRL_REGEX = /(controller|router|routes|handler|endpoint|resource)/i;
     const SCHEMA_REGEX = /(schema|\.entity|\.model|\.dto|models?\.|entities?\.)/i;
+    // Directories that conventionally hold data/domain classes (language-agnostic)
+    const DOMAIN_DIR_REGEX = /[\/\\](domain|entity|entities|model|models|dto|dtos|schema|schemas)[\/\\]/i;
     async function walk(dir, depth) {
         if (depth > 6)
             return;
@@ -276,7 +278,8 @@ async function walkForKeyFiles(root) {
             if (CTRL_REGEX.test(e.name) && result.controllers.length < 5) {
                 result.controllers.push(p);
             }
-            if (SCHEMA_REGEX.test(e.name) && result.schemas.length < 5) {
+            const isSchema = SCHEMA_REGEX.test(e.name) || DOMAIN_DIR_REGEX.test(p);
+            if (isSchema && result.schemas.length < 5) {
                 result.schemas.push(p);
             }
         }
@@ -326,17 +329,25 @@ export class AgentEngine {
         if (!this.fi)
             return noop;
         const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+        const dotFrames = ['·  ', '·· ', '···'];
         let i = 0;
+        let ti = 0;
         const t0 = Date.now();
         const fi = this.fi;
+        let streaming = false;
         fi.startActivity(`${frames[0]}  ${label}  0s`);
+        fi.setActivityLines([`  ${dotFrames[0]}  esperando respuesta...`]);
         const iv = setInterval(() => {
             const s = Math.floor((Date.now() - t0) / 1000);
+            ti++;
             fi.updateActivityHeader(`${frames[i++ % frames.length]}  ${label}  ${s}s`);
-        }, 100);
+            if (!streaming) {
+                fi.setActivityLines([`  ${dotFrames[ti % dotFrames.length]}  esperando respuesta...`]);
+            }
+        }, 300);
         return {
             stop() { clearInterval(iv); fi.stopActivity(); },
-            push(line) { fi.pushActivity(line); },
+            push(_chunk) { streaming = true; },
         };
     }
     /** Extract readable text lines from a qwen/CLI streaming chunk. */
@@ -406,7 +417,7 @@ INSTRUCCIONES:
                 const model = this.coordinatorCmd.match(/(?:-m|--model)\s+(\S+)/)?.[1] || 'coder-model';
                 const sp = this._startSpinner(`coordinador  ${model}`);
                 try {
-                    const result = await callQwenAPI(prompt, model, (c) => this._parseChunk(c).forEach(l => sp.push(l)));
+                    const result = await callQwenAPI(prompt, model, (c) => sp.push(c));
                     sp.stop();
                     return result;
                 }
@@ -617,26 +628,22 @@ INSTRUCCIONES:
         const ROLE_BINARIES = new Set(['agent-orch', 'agent-impl', 'agent-rev', 'agent-explorer']);
         const tryRoleBinaryCreds = async (cliName, model) => {
             const credsPath = path.join(os.homedir(), `.${cliName}`, 'oauth_creds.json');
-            if (!(await fileExists(credsPath))) {
-                log.warn(`${cliName} has no credentials — run: ${cliName} --login`);
-                return null;
+            const hasOAuthCreds = await fileExists(credsPath);
+            if (!hasOAuthCreds) {
+                // No role OAuth creds — try global API key config before giving up
+                const { loadApiKeyConfig } = await import('../utils/qwen-auth.js');
+                const apiKeyCfg = await loadApiKeyConfig();
+                if (!apiKeyCfg) {
+                    log.warn(`${cliName} has no credentials — run: agent-mp setup api-key  or  ${cliName} --login`);
+                    return null;
+                }
+                // Fall through: callQwenAPIFromCreds will use the API key config
             }
             const sp = this._startSpinner(`${cliName}  ${model}`);
-            let lineBuf = '';
-            const onChunk = (delta) => {
-                lineBuf += delta;
-                const lines = lineBuf.split('\n');
-                lineBuf = lines.pop() || '';
-                for (const l of lines) {
-                    if (l.trim())
-                        sp.push(l.trim());
-                }
-            };
+            const onChunk = (delta) => sp.push(delta);
             try {
                 log.info(`${cliName}: calling Qwen API with own credentials (${model})`);
                 const result = await callQwenAPIFromCreds(rolePrompt, model, credsPath, onChunk);
-                if (lineBuf.trim())
-                    sp.push(lineBuf.trim());
                 sp.stop();
                 return result;
             }
@@ -693,20 +700,9 @@ INSTRUCCIONES:
             const fb = this.config.fallback_global;
             log.warn(`Using global fallback: ${fb.cli} (${fb.model})`);
             const sp = this._startSpinner(`${fb.cli}  ${fb.model}  (fallback)`);
-            let lineBuf = '';
-            const onChunk = (delta) => {
-                lineBuf += delta;
-                const lines = lineBuf.split('\n');
-                lineBuf = lines.pop() || '';
-                for (const l of lines) {
-                    if (l.trim())
-                        sp.push(l.trim());
-                }
-            };
+            const onChunk = (delta) => sp.push(delta);
             try {
                 const globalResult = await callQwenAPI(rolePrompt, fb.model, onChunk);
-                if (lineBuf.trim())
-                    sp.push(lineBuf.trim());
                 sp.stop();
                 trackTokens(globalResult, fb.cli, fb.model);
                 return globalResult;
@@ -1155,7 +1151,7 @@ INSTRUCCIONES:
                     compSection.push(`### ENTRY POINT: ${rel}\n\`\`\`\n${content}\n\`\`\``);
                 }
             }
-            const ctrls = found.controllers.slice(0, 3);
+            const ctrls = found.controllers.slice(0, 5);
             for (const ctrl of ctrls) {
                 const content = await readFileSafe(ctrl, MAX_CTRL);
                 if (content) {
@@ -1163,7 +1159,7 @@ INSTRUCCIONES:
                     compSection.push(`### CONTROLLER/ROUTER: ${rel}\n\`\`\`\n${content}\n\`\`\``);
                 }
             }
-            const schemas = found.schemas.slice(0, 3);
+            const schemas = found.schemas.slice(0, 4);
             for (const sch of schemas) {
                 const content = await readFileSafe(sch, MAX_SCHEMA);
                 if (content) {
@@ -1190,8 +1186,30 @@ INSTRUCCIONES:
         // Ensure .agent/ structure exists
         const agentDir = path.join(this.projectDir, '.agent');
         const contextDir = path.join(agentDir, 'context');
+        const docsDir = path.join(agentDir, 'docs');
+        const rulesDir = path.join(agentDir, 'rules');
         await fs.mkdir(contextDir, { recursive: true });
-        await fs.mkdir(path.join(agentDir, 'rules'), { recursive: true });
+        await fs.mkdir(docsDir, { recursive: true });
+        await fs.mkdir(rulesDir, { recursive: true });
+        // Seed rules files if they don't exist yet (idempotent — never overwrites)
+        const proj = this.config.project;
+        const rulesSeeds = {
+            'workflow.md': `# Workflow Contract — ${proj}\n\n\`\`\`\n[ORCHESTRATOR] planifica → genera plan.json\n       ↓\n[IMPLEMENTOR] ejecuta el plan → modifica archivos\n       ↓\n[REVIEWER] valida → genera result.md\n\`\`\`\n\n## REGLA #1 — Separacion de roles\nCada CLI opera SOLO en su rol.\n\n## REGLA #2 — Orden estricto\nOrchestrator primero. Implementor no actua sin plan. Reviewer no actua sin implementacion.\n\n## REGLA #3 — Sin inventar\nCada rol trabaja con los archivos reales del proyecto.\n`,
+            'orchestrator.md': `# Rol: ORCHESTRATOR — ${proj}\n\n## Responsabilidad\nAnalizar el requerimiento, leer el contexto y generar un plan de tareas ejecutable.\n\n## Antes de planificar\n1. Leer .agent/context/architecture.md\n2. Leer .agent/rules/structure.md\n3. Leer .agent/rules/patterns.md\n\n## Al generar el plan\n- Pasos atomicos (1 paso = 1 cambio verificable)\n- Rutas de archivos REALES\n- Dependencias entre pasos si las hay\n\n## Prohibido\n- Modificar archivos de codigo directamente\n- Ejecutar comandos de build o test\n`,
+            'implementor.md': `# Rol: IMPLEMENTOR — ${proj}\n\n## Responsabilidad\nEjecutar el plan del Orchestrator. Modificar archivos de codigo siguiendo las instrucciones exactas.\n\n## Antes de implementar\n1. Leer .agent/tasks/{ID}/plan.json completo\n2. Leer .agent/rules/structure.md\n3. Leer .agent/rules/patterns.md\n\n## Al implementar\n- Seguir el plan paso a paso, en orden\n- No agregar cambios fuera del scope\n- Marcar cada paso como completado\n\n## Prohibido\n- Modificar el plan\n- Hacer refactors no solicitados\n`,
+            'reviewer.md': `# Rol: REVIEWER — ${proj}\n\n## Responsabilidad\nValidar que la implementacion cumple el plan y respeta las reglas del proyecto.\n\n## Checklist\n- [ ] Cada paso del plan fue implementado\n- [ ] Sin archivos modificados fuera del scope\n- [ ] Convenciones de patterns.md respetadas\n- [ ] Estructura de structure.md respetada\n- [ ] Sin codigo muerto ni imports sin usar\n\n## Al generar result.md\n- Indicar cada item: OK / FAIL / SKIP con razon\n- Si FAILs: describir qué falta y en qué archivo\n\n## Prohibido\n- Modificar archivos de codigo\n- Aprobar implementaciones incompletas\n`,
+            'structure.md': `# Estructura — ${proj}\n\n## Directorios aprobados\n- . (raiz del proyecto)\n\n## Prohibidos\n- node_modules/, dist/, .git/, build/, target/, __pycache__/, .venv/\n`,
+            'patterns.md': `# Patrones — ${proj}\n\n## Nombrado\n- Archivos: kebab-case\n- Clases: PascalCase\n- Variables/funciones: camelCase\n- Constantes: UPPER_SNAKE_CASE\n\n## Reglas generales\n- Sin console.log de debug en produccion\n- Un archivo = una responsabilidad principal\n`,
+        };
+        for (const [name, content] of Object.entries(rulesSeeds)) {
+            const fp = path.join(rulesDir, name);
+            try {
+                await fs.access(fp);
+            }
+            catch {
+                await writeFile(fp, content);
+            } // only create if missing
+        }
         // NOTE: cleanup of stray files moved to AFTER successful parse, to avoid
         // wiping previous docs when the explorer fails (e.g. tool-call hallucination).
         // Build a quick filesystem snapshot to give the explorer context
@@ -1273,11 +1291,28 @@ El engine YA leyo por vos los archivos clave de cada componente y te los pasa ar
    - Del MANIFEST: nombre, version, framework, dependencias clave con sus versiones, scripts, entry point
    - Del ENTRY POINT: puerto real, middlewares, modulos cargados
    - De los CONFIG/ENV: variables reales y su proposito
-   - De los CONTROLLER/ROUTER: endpoints REALES (metodo, ruta, parametros)
-   - De los SCHEMA/MODEL: shape real de los datos
+   - De los CONTROLLER/ROUTER: endpoints REALES (metodo, ruta, parametros, anotaciones como @GetMapping/@PostMapping/router.get)
+   - De los SCHEMA/MODEL/DOMAIN: shape real de los datos (campos, tipos, anotaciones @Column/@Entity)
 3. Identificar relaciones REALES entre componentes (URLs/hosts de otros servicios en .env, imports cross-component, conexiones a BBDD).
 4. Generar la documentacion en los 3 niveles, en formato markdown, dentro de los bloques === ... ===.
 
+REGLA CRITICA PARA MODULOS (NIVEL 2):
+- Los modulos SON LAS FEATURES DEL NEGOCIO, NO las capas tecnicas.
+- MAL: modulos llamados "web-api", "security", "data-access" — eso es hablar de capas, no de features
+- BIEN: modulos llamados "clients", "sales", "products", "auth", "orders" — eso es hablar de features reales
+- Para identificar los modulos, MIRA los CONTROLLER/ROUTER pre-leidos: el nombre del modulo = lo que maneja ese controller
+  * ClientController o clients.controller → modulo "clients"
+  * SaleController o sale.routes → modulo "sales"
+  * AuthController o auth.handler → modulo "auth"
+- "Archivos clave" en cada modulo DEBE listar los archivos FUENTE REALES que leiste, NO solo el manifest.
+  Ejemplo correcto:
+  | Archivo (ruta relativa al componente) | Rol |
+  | controller/ClientController.java | Endpoints REST /clients |
+  | domain/Client.java | Entidad mapeada a tabla CLIENTS |
+  | repository/ClientRepository.java | Acceso a base de datos |
+  | src/clients/clients.controller.ts | Endpoints /clients |
+  | src/clients/client.schema.ts | Modelo de datos Client |
+
 NO inventes datos. Si un componente no tiene una de esas piezas en los archivos leidos, simplemente omiti esa seccion en su documentacion.
 
 ================================================================
@@ -1292,190 +1327,254 @@ ESTRUCTURA DE LOS 3 NIVELES
 ================================================================
 
 ────────────────────────────────────────────────────────────────
-NIVEL 0 — architecture.md (raiz de .agent/context/)
-Indice global. Objetivo: 50-150 lineas. Concreto.
 ────────────────────────────────────────────────────────────────
-Secciones obligatorias:
+NIVEL 0 — architecture.md  (raiz de .agent/context/)
+Objetivo: 80-150 lineas. Panorama global real, no generico.
+────────────────────────────────────────────────────────────────
 
-# ${this.config.project} — Arquitectura Global (NIVEL 0)
+# [Nombre del proyecto] — Arquitectura Global (NIVEL 0)
 
-> Indice de servicios y relaciones. Lectura escalonada:
+> Lectura escalonada:
 >   NIVEL 0: este archivo
 >   NIVEL 1: .agent/context/[componente]/architecture.md
 >   NIVEL 2: .agent/context/[componente]/modules/[modulo].md
 
 ## 1. Overview funcional
-2-4 lineas en lenguaje simple: que es el sistema, para quien sirve, que problema resuelve.
+2-4 lineas. Que es el sistema, para quien sirve, que problema resuelve.
+Si hay multiples componentes con roles distintos, nombrarlos y contrastarlos en el overview:
+ej. "X es la API de ingesta (escritura, batch), Y es la API de gestion (CRUD, portal Nexus)."
 
 ## 2. Componentes del proyecto
-| Componente | Tipo | Stack + version | Puerto | Proposito (negocio) | Entry point |
-|------------|------|-----------------|--------|---------------------|-------------|
-(una fila por componente, con datos REALES)
+| Componente | Stack (version exacta) | Puerto | Rol principal | Consumers tipicos |
+|---|---|---|---|---|
+(datos REALES del manifest. "Consumers tipicos" = quien llama a este componente: frontend, proceso batch, sistema externo)
 
 ## 3. Relaciones entre componentes
-| Origen | Destino | Tipo (HTTP / Import / DB / Queue / CORS) | Proposito |
-|--------|---------|------------------------------------------|-----------|
-(una fila por cada relacion confirmada)
+| Origen | Destino | Tipo | Proposito |
+|---|---|---|---|
+(incluir URLs/hosts reales si aparecen en .env o config: ej. "http://57.151.96.13:8000/v1/validate")
 
 ## 4. Diagrama de arquitectura
-\`\`\`
-[Frontend Web] ──HTTP──> [API Auth :8081]
-       │                        │
-       │                        v
-       └──HTTP──> [API Core :8080] ──> [MongoDB]
+Usar box-drawing (┌─┐│└┘┬┴├┤) y flechas (→ ──> ▼ ▲). Mostrar puertos REALES.
+Incluir endpoints clave inline en los componentes cuando se conocen.
+\`\`\`text
+┌─────────────────────┐         ┌──────────────────────┐
+│ componente-a :8083  │         │ componente-b :8084    │
+│ POST /api/sales     │         │ GET /api/nexus/combos │
+│ POST /api/stock     │────────>│ PUT /api/nexus/...    │
+└──────────┬──────────┘         └──────────────────────┘
+           │                               │
+           ▼                               ▼
+    ┌──────────────┐              ┌──────────────┐
+    │  SQL Server  │              │  Auth Service│
+    │  :31434      │              │  :8000       │
+    └──────────────┘              └──────────────┘
 \`\`\`
 
-## 5. Flujos end-to-end principales (3-5)
-Mappings funcional → tecnico, paso a paso. Ejemplo:
-- **"Un usuario crea un pedido"**: WebApp → POST /orders (API Core) → valida JWT contra API Auth → guarda en MongoDB → devuelve 201 con el pedido.
+## 5. Flujos end-to-end principales
+Concretos, con componentes, endpoints y acciones reales. 2-5 flujos.
+- **"Nombre del flujo":** Actor → POST /endpoint (componente-a) → valida JWT con auth-service → escribe en SQL Server → responde 201.
 
-## 6. Prerequisitos para levantar el proyecto
-Versiones REALES leidas de los manifests (no rangos genericos).
+## 6. Prerequisitos para levantar
+Solo lo que es real: acceso de red a hosts externos, herramientas requeridas. Sin generalidades.
 
-## 7. Comandos globales de desarrollo
+## 7. Comandos de desarrollo
 | Comando | Descripcion | Directorio |
-
-## 8. Decisiones de arquitectura globales (opcional, solo si hay)
+|---|---|---|
+(comandos reales del Makefile, run.sh, package.json scripts, mvnw, etc.)
 
 ────────────────────────────────────────────────────────────────
 NIVEL 1 — [componente]/architecture.md
-Detalle del componente. Objetivo: 80-200 lineas. Crear UNO POR CADA componente NO trivial.
+Objetivo: 120-250 lineas. Un archivo por cada componente no trivial.
 ────────────────────────────────────────────────────────────────
-Secciones obligatorias:
 
 # [componente] — Arquitectura (NIVEL 1)
 
 ## Que hace
-2-3 lineas en lenguaje simple, sin tecnicismos.
+Parrafo 1: describe el rol del componente en lenguaje de negocio + quien lo consume.
+Parrafo 2 (si hay componentes hermanos): contrasta con ellos. ej. "A diferencia de X que solo escribe en bulk, esta API expone CRUD con paginacion y filtros para el portal."
 
 ## Casos de uso principales
-3-6 bullets en formato negocio:
-- "Permite al usuario X..."
-- "El sistema usa este servicio para Y..."
+Tabla con: Caso de uso | Actor (quien lo dispara) | Descripcion + endpoint si se conoce.
+| Caso de uso | Actor | Descripcion |
+|---|---|---|
+| Ingesta de ventas | Proceso batch BAT | POST /api/sales — upsert bulk de ventas finales |
+| Consulta de productos | Portal Nexus | GET /api/products?eanCode=XXX |
 
 ## Stack tecnico
 | Item | Valor |
-|------|-------|
-| Lenguaje | TypeScript 5.3 |
-| Framework | NestJS 11.0.1 |
-| ORM | Mongoose 9.3.3 |
-| Auth | Passport JWT |
-(datos reales del manifest)
+|---|---|
+| Lenguaje | Java 21 (Temurin LTS) |
+| Framework | Spring Boot 3.5.6 |
+| ORM | Spring Data JPA + Hibernate |
+| Seguridad | Spring Security 6 + JJWT |
+(versiones REALES del manifest. Si hay librerias clave como POI, MapStruct, HikariCP: incluirlas)
 
 ## Puerto y URLs
-- **Puerto:** 8085 (de PORT en .env)
-- **Swagger / docs:** http://localhost:8085/api/docs (si aplica)
-- **Health check:** GET /health (si existe)
-
-## Estructura interna (arbol real)
+| Recurso | URL |
+|---|---|
+| API base | http://localhost:8084 |
+| Swagger / docs | http://localhost:8084/swagger-ui/index.html |
+| Perfil activo | development (application-development.properties) |
+
+## Estructura de capas / paquetes
+Arbol con los archivos y directorios REALES que leiste. Usar → para anotar inline que hace cada clase o directorio.
+\`\`\`text
+paquete.raiz/
+├── controller/        → endpoints REST, delegan a service, responden ApiResponse<T>
+│   ├── ClientController     → CRUD /api/clients
+│   ├── SaleController       → POST /api/sales, /api/sales/interim-sales
+│   └── ExportController     → GET /api/export/combos (genera .xlsx)
+├── service/           → interfaces de logica de negocio
+│   └── impl/          → implementaciones (@Transactional aqui)
+├── repository/        → Spring Data JPA Repositories
+├── domain/            → Entidades JPA (@Entity)
+│   ├── Client, InterimClient  → clientes finales y en staging
+│   ├── Sale, InterimSale      → ventas finales y en staging
+│   └── compositekeys/         → @IdClass para PKs compuestas
+├── dto/               → contratos de API (Request/Response DTOs)
+├── mapper/            → MapStruct: Entity ↔ DTO
+├── security/          → filtros JWT, validacion, handler 401
+└── configuration/     → CORS, Swagger, SecurityConfig
 \`\`\`
-src/
-├── main.ts            # entry point, configura CORS y swagger
-├── auth/              # autenticacion JWT
-├── leads/             # gestion de leads
-└── ...
+(Adaptar a la estructura real del proyecto: puede ser src/, app/, pkg/, etc.)
+
+## Endpoints reales
+SOLO los que se leyeron en los CONTROLLER/ROUTER files. Incluir columna Auth si se conoce.
+| Metodo | Ruta | Auth | Funcion |
+|---|---|---|---|
+| GET | /api/clients | JWT | Lista clientes (paginado, filtrable) |
+| POST | /api/sales | JWT | Upsert bulk de ventas finales |
+| GET | /api/export/combos | JWT/Azure | Descarga Excel con combos |
+(querystring params relevantes en la ruta, ej. ?eanCode= , ?page=&size= )
+
+## Formato de respuesta (si hay wrapper estandar)
+Si el codigo muestra un wrapper comun para todas las respuestas, documentarlo:
+\`\`\`json
+{
+  "status": 200,
+  "message": "Operacion exitosa",
+  "data": [...],
+  "pagination": { "page": 1, "size": 15, "totalElements": 120, "totalPages": 8 }
+}
 \`\`\`
+Si no hay wrapper, omitir esta seccion.
 
 ## Modulos internos
-| Modulo | Proposito (negocio) | Doc tecnica |
-|--------|---------------------|-------------|
-| auth | Login y validacion de tokens | modules/auth.md |
-| leads | Listado y consulta de negocios | modules/leads.md |
-
-## Endpoints principales
-| Metodo | Ruta | Modulo | Que hace (lenguaje simple) |
-|--------|------|--------|----------------------------|
-| GET | /leads | leads | Lista negocios filtrables |
-| GET | /leads/:id | leads | Detalle de un negocio |
-(SOLO endpoints reales extraidos de los controllers)
-
-## Variables de entorno
-| Variable | Default | Proposito |
-|----------|---------|-----------|
-| PORT | 8085 | Puerto del servicio |
-| MONGODB_URI | mongodb://... | Conexion principal |
-
-## Integraciones con otros servicios / sistemas
-| Servicio externo | Tipo (HTTP/DB/Queue) | Proposito |
+| Modulo | Proposito | Doc tecnica |
+|---|---|---|
+| seguridad | Autenticacion JWT/Azure, roles, filtro HTTP | modules/security.md |
+| acceso-datos | JPA, Specifications, pool, entidades | modules/data-access.md |
+| api-web | Controladores, DTOs, validacion, exportacion | modules/web-api.md |
+(Agrupar por responsabilidad tecnica real, no inventar modulos)
+
+## Variables de configuracion clave
+| Propiedad / Variable | Valor actual | Proposito |
+|---|---|---|
+| server.port | 8084 | Puerto de la API |
+| spring.datasource.url | jdbc:sqlserver://... | Conexion SQL Server |
+| auth.url | http://57.151.96.13:8000/v1/validate | Servicio externo de validacion JWT |
+(Valores REALES del archivo de config/env leido. Si no se leyo el archivo, omitir la tabla)
 
 ## Como levantar
-- **Instalar deps:** \`npm install\`
-- **Servicios necesarios:** MongoDB corriendo, security-api accesible
-- **Comando para iniciar:** \`npm run start:dev\`
-
-## Comandos disponibles
-| Comando | Que hace |
+Comando principal primero. Luego paso a paso si existe.
+\`\`\`bash
+./run.sh        # compila y levanta todo en uno (si existe)
+\`\`\`
+O paso a paso:
+\`\`\`bash
+source ./scripts/env.sh
+npm install && npm run dev
+\`\`\`
 
-## Decisiones tecnicas relevantes
-(solo si hay decisiones notables; si no, omitir esta seccion)
+## Testing (si hay tests en el proyecto)
+Frameworks, comando para correr, cobertura minima si se menciona en el manifest o config.
+\`\`\`bash
+npm test               # todos los tests
+npm test -- --watch    # modo watch
+\`\`\`
 
 ────────────────────────────────────────────────────────────────
 NIVEL 2 — [componente]/modules/[modulo].md
-Detalle de un modulo interno. Objetivo: 40-120 lineas. Crear UNO POR cada modulo significativo.
+Objetivo: 50-120 lineas. Un archivo por modulo significativo.
 ────────────────────────────────────────────────────────────────
-Secciones obligatorias:
 
-# Modulo: [nombre] — [componente]
+# Modulo: [Nombre] — [componente]
 
 ## Funcion (lenguaje simple)
-1-2 lineas: "Permite al usuario gestionar X" / "El sistema usa este modulo para Y".
+1-2 lineas: "Protege todos los endpoints /api/**. Cada request debe llevar un token JWT valido."
 
 ## Funcion (tecnica)
-1-2 lineas: como esta implementado a alto nivel.
-
-## Flujos / casos de uso (1-3)
-Escenarios paso a paso. Ejemplo:
-- **Crear un pedido:** Cliente → POST /orders → middleware valida JWT → service.create() → guarda en DB → responde 201
-
-## Endpoints / interfaces publicas (si aplica)
-| Metodo | Ruta | Body | Respuesta |
-|--------|------|------|-----------|
-
-## Modelos / schemas relevantes
-\`\`\`typescript
-// shape REAL extraido del archivo de schema/model
-{
-  _id: ObjectId,
-  name: string,
-  createdAt: Date,
-  ...
-}
+1-2 lineas: como esta implementado. ej. "Filtro OncePerRequestFilter que extrae el JWT del header Authorization, lo valida contra el servicio externo auth.url, y si es valido establece el SecurityContext."
+
+## Flujo principal (diagrama ASCII)
+Para modulos de seguridad, acceso a datos, o cualquiera con logica de decision/secuencia:
+mostrar el flujo con ASCII art y nombres REALES de clases/metodos.
+\`\`\`text
+HTTP Request
+    │
+    ▼
+AuthFilter (OncePerRequestFilter)
+    │
+    ├── X-User-Source == "Azure"?
+    │       ▼ SI
+    │   AzureHeaderValidator → construye usuario virtual desde headers
+    │
+    └── NO
+        ▼
+    JwtValidator → POST http://auth-service/validate → carga usuario de BD
+    │
+    ▼
+SecurityContextHolder.setAuthentication(...)
+    │
+    ▼
+@PreAuthorize("hasAnyAuthority('ROLE_A','ROLE_B')") en el controller
 \`\`\`
 
-## Reglas de negocio
-- Validaciones: ...
-- Condiciones especiales: ...
-- Excepciones: ...
+## Entidades / modelos relevantes (si aplica)
+Para modulos de acceso a datos: tabla de entidades con su proposito y notas.
+| Entidad | Proposito | Notas |
+|---|---|---|
+| Client | Clientes finales | Clave compuesta: ClientId |
+| InterimClient | Clientes en staging | Tabla intermedia antes de procesar |
+
+## Reglas del modulo
+- Rutas protegidas: /api/** → autenticacion obligatoria
+- Rutas publicas: OPTIONS /**, /swagger-ui/**, /*
+- Sin sesion: STATELESS — sin cookies
+- ddl-auto=validate → el schema nunca se auto-modifica
 
 ## Archivos clave
+Rutas RELATIVAS al directorio raiz del componente (no rutas absolutas, no solo el manifest).
 | Archivo | Rol |
-|---------|-----|
-| src/leads/leads.controller.ts | Endpoints /leads |
-| src/leads/leads.service.ts | Logica de negocio |
+|---|---|
+| security/AuthFilter.java | Filtro principal — intercepta y valida cada request |
+| security/JwtValidator.java | Extrae username del JWT, verifica firma y expiracion |
+| configuration/SecurityConfig.java | Define SecurityFilterChain, rutas publicas/protegidas |
+| application-development.properties | auth.url, security.token.secret, security.token.expiration |
 
 ## Dependencias
-- **Internas (mismo componente):** auth, common
-- **Externas:** mongoose, class-validator
-- **Cross-component:** llama a security-api via HTTP para validar JWT
+- Librerias clave con version si se conoce: io.jsonwebtoken:jjwt:0.9.1, spring-boot-starter-security
+- Cross-component si corresponde: "llama a http://auth-service:8000/v1/validate para validar tokens"
 
 ================================================================
 CALIBRACION DE DETALLE
 ================================================================
-- NIVEL 0: 50-150 lineas (no menos, no mas)
-- NIVEL 1: 80-200 lineas por componente
-- NIVEL 2: 40-120 lineas por modulo
-- Si te queda corto → leiste pocos archivos, lee mas
-- Si te queda largo → estas repitiendo o agregando relleno, recorta
+- NIVEL 0: 80-150 lineas
+- NIVEL 1: 120-250 lineas por componente
+- NIVEL 2: 50-120 lineas por modulo
+- Si te queda corto → incluir mas endpoints reales, mas clases en el arbol, mas config values
+- Si te queda largo → estas repitiendo entre niveles o agregando relleno; recorta
 
 ================================================================
 QUE NO HACER
 ================================================================
 - NO usar "Inferido", "Probablemente", "(asumido)", "(quizas)", "parece"
 - NO repetir lo mismo entre niveles sin agregar valor (cada nivel zoomea mas)
-- NO dejar tablas vacias ni con placeholders tipo "..."
-- NO mezclar lenguaje tecnico puro: SIEMPRE empezar funcional, despues tecnico
-- NO documentar componentes triviales (scripts, docs, configs sueltas) con su propia carpeta — mencionalos en NIVEL 0 y listo
-- NO inventar endpoints, env vars, puertos o schemas que no leiste
+- NO dejar tablas vacias ni con placeholders tipo "..." o "ver manifest"
+- NO escribir overview que podria aplicar a cualquier proyecto (tiene que ser especifico de ESTE proyecto)
+- NO documentar componentes triviales (scripts sueltos, configs simples) con carpeta propia — mencionalos en NIVEL 0 y listo
+- NO inventar endpoints, env vars, puertos, hosts, clases o schemas que no leiste en los archivos reales
 
 ================================================================
 FORMATO DE SALIDA — OBLIGATORIO
@@ -1483,35 +1582,29 @@ FORMATO DE SALIDA — OBLIGATORIO
 Devolve UNICAMENTE bloques de archivos separados por marcadores ===. Nada de explicaciones extra fuera de los bloques.
 
 IMPORTANTE: TODAS las rutas son RELATIVAS al directorio del proyecto.
-Los archivos se escriben SIEMPRE dentro de .agent/context/
 
-Ejemplos de marcadores:
+Ejemplos de marcadores validos:
   === .agent/context/architecture.md ===
   === .agent/context/datamart-data-access-api/architecture.md ===
   === .agent/context/datamart-data-access-api/modules/auth.md ===
   === .agent/context/nexus-core-api/architecture.md ===
-  === .agent/context/nexus-core-api/modules/users.md ===
+  === .agent/context/nexus-core-api/modules/clients.md ===
 
 === .agent/context/architecture.md ===
-[contenido completo del NIVEL 0]
-
-=== .agent/context/nombre-componente-1/architecture.md ===
-[contenido completo del NIVEL 1 del componente 1]
-
-=== .agent/context/nombre-componente-1/modules/auth.md ===
-[contenido completo del NIVEL 2 del modulo auth]
+[contenido NIVEL 0]
 
-=== .agent/context/nombre-componente-1/modules/leads.md ===
-[contenido completo del NIVEL 2 del modulo leads]
+=== .agent/context/nombre-componente/architecture.md ===
+[contenido NIVEL 1]
 
-=== .agent/context/nombre-componente-2/architecture.md ===
-...
+=== .agent/context/nombre-componente/modules/auth.md ===
+[contenido NIVEL 2]
 
 REGLAS DE PATHS:
-- El archivo principal SIEMPRE es: === .agent/context/architecture.md ===
+- Arquitectura global: === .agent/context/architecture.md ===
 - Por componente: === .agent/context/[nombre-componente]/architecture.md ===
 - Por modulo interno: === .agent/context/[nombre-componente]/modules/[nombre-modulo].md ===
 - Documenta TODOS los componentes no triviales del DIRECTORIO_TRABAJO
+- NO escribir nada bajo .agent/docs/ — esa carpeta es de uso manual
 - Si existe documentacion previa, ACTUALIZALA preservando lo que sigue siendo valido y agregando lo nuevo`;
         const res = await this.runWithFallback('explorer', prompt, 'Exploracion');
         const text = extractCliText(res);
@@ -1541,8 +1634,8 @@ REGLAS DE PATHS:
             content = content.replace(/^```markdown\s*/i, '').replace(/^```\s*$/gm, '').trim();
             if (!content)
                 continue;
-            // Normalize: strip any .agent/context/ prefix from the marker
-            let relPath = fileName.replace(/^\.agent\/context\//i, '').replace(/^\/+/, '');
+            // All explorer output goes under .agent/context/ — docs/ is manual-only
+            const relPath = fileName.replace(/^\.agent\/context\//i, '').replace(/^\/+/, '');
             let targetPath = null;
             if (relPath === 'architecture.md' || relPath === 'ARCHITECTURE.md') {
                 targetPath = mainArchPath;