agent-rev 0.5.13 → 0.5.23

package/dist/core/engine.js

@@ -202,6 +202,110 @@ function extractJson(text) {
         throw new Error('No JSON found');
     return JSON.parse(c.slice(first, last + 1));
 }
+/** Read a file safely, truncating to maxChars. Returns null if missing or empty. */
+async function readFileSafe(p, maxChars) {
+    try {
+        const content = await fs.readFile(p, 'utf-8');
+        if (!content || !content.trim())
+            return null;
+        if (content.length > maxChars) {
+            return content.slice(0, maxChars) + `\n... [truncado, ${content.length - maxChars} caracteres mas]`;
+        }
+        return content;
+    }
+    catch {
+        return null;
+    }
+}
+const PREFETCH_SKIP_DIRS = new Set([
+    '.agent', 'node_modules', '.git', 'dist', 'build', 'target',
+    '__pycache__', '.venv', 'venv', '.idea', '.vscode', '.next',
+    'coverage', '.cache', 'out', 'bin', 'obj',
+]);
+/** Walk a component dir looking for entry point, controllers, routers, schemas, models. */
+async function walkForKeyFiles(root) {
+    const result = {
+        entry: null,
+        controllers: [],
+        schemas: [],
+    };
+    const SOURCE_EXT = /\.(ts|tsx|js|jsx|py|go|java|kt|rs|cs)$/;
+    const SKIP_FILE = /\.(test|spec|d)\.[a-z]+$/i;
+    const ENTRY_NAMES = new Set([
+        'main.ts', 'main.js', 'main.py', 'main.go', 'Main.java',
+        'index.ts', 'index.js', 'index.py',
+        'app.ts', 'app.js', 'app.py',
+        'server.ts', 'server.js', 'server.py',
+        'application.ts', 'application.js', 'application.py',
+    ]);
+    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;
+        if (result.controllers.length >= 5 && result.schemas.length >= 5 && result.entry)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.'))
+                continue;
+            if (PREFETCH_SKIP_DIRS.has(e.name))
+                continue;
+            const p = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(p, depth + 1);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            if (!SOURCE_EXT.test(e.name))
+                continue;
+            if (SKIP_FILE.test(e.name))
+                continue;
+            // entry point detection
+            if (!result.entry && (ENTRY_NAMES.has(e.name) || ENTRY_REGEX.test(e.name))) {
+                result.entry = p;
+            }
+            if (CTRL_REGEX.test(e.name) && result.controllers.length < 5) {
+                result.controllers.push(p);
+            }
+            const isSchema = SCHEMA_REGEX.test(e.name) || DOMAIN_DIR_REGEX.test(p);
+            if (isSchema && result.schemas.length < 5) {
+                result.schemas.push(p);
+            }
+        }
+    }
+    await walk(root, 0);
+    return result;
+}
+/** Detect if the LLM hallucinated tool calls instead of producing the document content. */
+function looksLikeHallucinatedToolCalls(text) {
+    if (!text)
+        return true;
+    // Common hallucination patterns when the LLM thinks it's calling tools
+    const TOOL_PATTERNS = [
+        /===\s*TOOL_CALL\s*:/i,
+        /^\s*<tool_call>/m,
+        /^\s*<function_call>/m,
+        /^\s*```tool_use/im,
+    ];
+    if (TOOL_PATTERNS.some(re => re.test(text)))
+        return true;
+    // If the text has NO valid file markers at all, it's also a failure case
+    const fileMarkerMatches = text.match(/===\s+[^\n=]+?\.md\s*===/g);
+    if (!fileMarkerMatches || fileMarkerMatches.length === 0)
+        return true;
+    return false;
+}
 export class AgentEngine {
     config;
     projectDir;
@@ -516,9 +620,16 @@ 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 = '';
@@ -969,6 +1080,114 @@ INSTRUCCIONES:
             }
         }
     }
+    /**
+     * Pre-read the actual file contents (manifests, env, entry points, controllers, schemas)
+     * for every component in the project, so the LLM does not need tool-use to inspect them.
+     * This is critical when the explorer runs against the Qwen API (no tools available)
+     * to avoid the LLM hallucinating tool calls instead of producing the real document.
+     */
+    async _prefetchProjectFiles() {
+        const MAX_MANIFEST = 5000;
+        const MAX_ENV = 2000;
+        const MAX_README = 3000;
+        const MAX_ENTRY = 3000;
+        const MAX_CTRL = 2500;
+        const MAX_SCHEMA = 1800;
+        let topEntries;
+        try {
+            topEntries = await fs.readdir(this.projectDir, { withFileTypes: true });
+        }
+        catch {
+            return '';
+        }
+        const sections = [];
+        // Top-level manifest / readme / docker (gives global context)
+        const TOP_GLOBAL_FILES = ['package.json', 'pom.xml', 'build.gradle', 'requirements.txt', 'go.mod', 'Cargo.toml', 'README.md', 'docker-compose.yml', 'docker-compose.yaml', 'Makefile'];
+        const topGlobal = [];
+        for (const fname of TOP_GLOBAL_FILES) {
+            const content = await readFileSafe(path.join(this.projectDir, fname), MAX_MANIFEST);
+            if (content)
+                topGlobal.push(`### ROOT: ${fname}\n\`\`\`\n${content}\n\`\`\``);
+        }
+        if (topGlobal.length > 0) {
+            sections.push(`## CONTEXTO GLOBAL DEL PROYECTO\n\n${topGlobal.join('\n\n')}`);
+        }
+        // Each top-level directory = candidate component
+        const components = topEntries
+            .filter(e => e.isDirectory() && !PREFETCH_SKIP_DIRS.has(e.name) && !e.name.startsWith('.'))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const comp of components) {
+            const compDir = path.join(this.projectDir, comp.name);
+            const compSection = [`## COMPONENTE: ${comp.name}`];
+            // Manifest
+            const MANIFESTS = ['package.json', 'requirements.txt', 'pyproject.toml', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'Cargo.toml', 'go.mod', 'composer.json', 'Gemfile'];
+            let manifestFound = false;
+            for (const m of MANIFESTS) {
+                const content = await readFileSafe(path.join(compDir, m), MAX_MANIFEST);
+                if (content) {
+                    compSection.push(`### MANIFEST: ${m}\n\`\`\`\n${content}\n\`\`\``);
+                    manifestFound = true;
+                    break;
+                }
+            }
+            // README
+            const readme = await readFileSafe(path.join(compDir, 'README.md'), MAX_README)
+                || await readFileSafe(path.join(compDir, 'readme.md'), MAX_README);
+            if (readme)
+                compSection.push(`### README\n${readme}`);
+            // Env / config files (try several conventional locations)
+            const ENV_FILES = ['.env', '.env.example', '.env.sample', '.env.local', '.env.dev', 'application.yml', 'application.yaml', 'application.properties', 'config.yaml', 'config.yml'];
+            const ENV_DIRS = [compDir, path.join(compDir, 'src', 'main', 'resources'), path.join(compDir, 'config'), path.join(compDir, 'src', 'config')];
+            const seenEnv = new Set();
+            let envCount = 0;
+            for (const dir of ENV_DIRS) {
+                for (const f of ENV_FILES) {
+                    if (envCount >= 3)
+                        break;
+                    const p = path.join(dir, f);
+                    if (seenEnv.has(p))
+                        continue;
+                    seenEnv.add(p);
+                    const content = await readFileSafe(p, MAX_ENV);
+                    if (content) {
+                        const rel = path.relative(compDir, p);
+                        compSection.push(`### CONFIG/ENV: ${rel}\n\`\`\`\n${content}\n\`\`\``);
+                        envCount++;
+                    }
+                }
+            }
+            // Walk source for entry, controllers, schemas
+            const found = await walkForKeyFiles(compDir);
+            if (found.entry) {
+                const content = await readFileSafe(found.entry, MAX_ENTRY);
+                if (content) {
+                    const rel = path.relative(compDir, found.entry);
+                    compSection.push(`### ENTRY POINT: ${rel}\n\`\`\`\n${content}\n\`\`\``);
+                }
+            }
+            const ctrls = found.controllers.slice(0, 5);
+            for (const ctrl of ctrls) {
+                const content = await readFileSafe(ctrl, MAX_CTRL);
+                if (content) {
+                    const rel = path.relative(compDir, ctrl);
+                    compSection.push(`### CONTROLLER/ROUTER: ${rel}\n\`\`\`\n${content}\n\`\`\``);
+                }
+            }
+            const schemas = found.schemas.slice(0, 4);
+            for (const sch of schemas) {
+                const content = await readFileSafe(sch, MAX_SCHEMA);
+                if (content) {
+                    const rel = path.relative(compDir, sch);
+                    compSection.push(`### SCHEMA/MODEL: ${rel}\n\`\`\`\n${content}\n\`\`\``);
+                }
+            }
+            // Only add the component if we read at least the manifest or one source file
+            if (manifestFound || found.entry || found.controllers.length > 0 || found.schemas.length > 0) {
+                sections.push(compSection.join('\n\n'));
+            }
+        }
+        return sections.join('\n\n---\n\n');
+    }
     async runExplorer(task) {
         if (!this.config.roles.explorer) {
             if (!this.config.fallback_global) {
@@ -981,10 +1200,32 @@ 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 });
-        // Clean up stray files before running
-        await this._cleanContextDir(contextDir);
+        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
         let fsSnapshot = '';
         try {
@@ -992,6 +1233,17 @@ INSTRUCCIONES:
             fsSnapshot = execSync(`find "${this.projectDir}" -maxdepth 3 -not -path '*/.agent/*' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*' -not -path '*/target/*' -not -path '*/build/*' -not -name '.git' | sort | head -300`, { encoding: 'utf-8', timeout: 10000 });
         }
         catch { /* ignore */ }
+        // Pre-read real file contents so the LLM has actual data instead of needing tools
+        const sp0 = this._startSpinner('explorer  pre-fetch  reading project files');
+        let prefetched = '';
+        try {
+            prefetched = await this._prefetchProjectFiles();
+            sp0.push(`${prefetched.split('## COMPONENTE:').length - 1} componente(s) leidos`);
+        }
+        catch (err) {
+            sp0.push(`prefetch error: ${err.message}`);
+        }
+        sp0.stop();
         // Read existing main architecture doc
         const mainArchPath = path.join(contextDir, 'architecture.md');
         let existingMainArch = '';
@@ -1024,6 +1276,8 @@ STACK: ${this.config.stack}
 ESTRUCTURA DE ARCHIVOS (excluye .agent, node_modules, .git, dist, __pycache__, .venv, target, build):
 ${fsSnapshot}
 
+${prefetched ? `================================================================\nARCHIVOS REALES LEIDOS DEL PROYECTO (esta es tu fuente de verdad)\n================================================================\n${prefetched}\n` : ''}
+
 ${existingMainArch ? `=== DOC EXISTENTE: architecture.md (principal) ===\n${existingMainArch.slice(0, 2000)}\n` : ''}
 ${existingComponentDocs ? `=== DOC EXISTENTE por componente ===\n${existingComponentDocs.slice(0, 3000)}\n` : ''}
 
@@ -1031,36 +1285,49 @@ ${existingComponentDocs ? `=== DOC EXISTENTE por componente ===\n${existingCompo
 OBJETIVO
 ================================================================
 Generar documentacion ESCALONADA en 3 niveles, util TANTO para personas funcionales (PM, negocio) como tecnicas (devs).
-Detallada pero NO excesiva. Concreta, con datos REALES leidos de los archivos. Cero especulaciones.
+Detallada pero NO excesiva. Concreta, con datos REALES extraidos de los archivos que estan mas arriba. Cero especulaciones.
 
 ================================================================
 REGLA DE ORO — PROHIBIDO INVENTAR
 ================================================================
 NO uses jamas: "Inferido", "Probablemente", "Posiblemente", "Asumido", "(supuesto)", "(quizas)", "parece ser".
-Si no podes verificar un dato leyendo un archivo concreto → OMITELO. Es mejor una doc corta y veraz que una larga llena de suposiciones.
-Cada puerto, version, endpoint, env var, schema o ruta que aparezca en la doc DEBE haber sido leido de un archivo real.
+Si un dato (puerto, version, endpoint, env var, schema, ruta) no aparece en los ARCHIVOS REALES de arriba → OMITILO.
+Es mejor una doc corta y veraz que una larga llena de suposiciones.
+NO devuelvas marcadores tipo "TOOL_CALL", "tool_use", "function_call" — vos NO tenes que llamar herramientas, tenes que devolver MARKDOWN.
 
 ================================================================
-WORKFLOW QUE TENES QUE EJECUTAR (usa tus tools de read_file/grep_search/list_directory)
+COMO TRABAJAR (lectura ya hecha por el engine)
 ================================================================
-1. Lista DIRECTORIO_TRABAJO. Identifica los componentes (apps/services/libs). Descarta lo trivial (solo configs/docs/scripts).
-2. Para CADA componente no trivial, LEE COMO MINIMO:
-   a. Manifest del proyecto: package.json | requirements.txt | pyproject.toml | pom.xml | build.gradle | Cargo.toml | go.mod
-      → de ahi sacas: nombre, version, framework, dependencias clave con sus versiones, scripts/tasks, entry point
-   b. Entry point real: src/main.ts | index.js | app.py | Application.java | cmd/main.go (segun stack)
-      → de ahi sacas: puerto, middlewares, modulos cargados, configuracion inicial
-   c. Archivo de variables de entorno: .env | .env.example | application.yml | config.* | settings.py
-      → de ahi sacas: variables reales con su proposito
-   d. Al menos 2-3 controladores/routers/handlers principales
-      → de ahi extraes endpoints REALES (metodo, ruta, parametros)
-   e. Al menos 2-3 modelos/schemas/entities principales
-      → de ahi extraes el shape de datos
-   f. README.md del componente si existe
-3. Mapea RELACIONES REALES entre componentes (no asumas):
-   - Buscando URLs/hosts de otros servicios en .env
-   - Buscando imports cross-component
-   - Buscando cadenas de conexion a BBDD/colas/cache
-4. Recien con esa informacion concreta, genera los archivos de documentacion.
+El engine YA leyo por vos los archivos clave de cada componente y te los pasa arriba en la seccion "ARCHIVOS REALES LEIDOS DEL PROYECTO". Tu tarea es:
+
+1. Identificar los componentes en la estructura de archivos.
+2. Para cada componente, extraer de sus archivos reales:
+   - 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, 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.
 
 ================================================================
 LENGUAJE DUAL (regla critica)
@@ -1074,190 +1341,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
@@ -1265,41 +1596,49 @@ 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]
+[contenido NIVEL 0]
 
-=== .agent/context/nombre-componente-1/modules/auth.md ===
-[contenido completo del NIVEL 2 del modulo auth]
+=== .agent/context/nombre-componente/architecture.md ===
+[contenido NIVEL 1]
 
-=== .agent/context/nombre-componente-1/modules/leads.md ===
-[contenido completo del NIVEL 2 del modulo leads]
-
-=== .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);
+        // Always overwrite the single last-run report so we have a debug trail
+        try {
+            await writeFile(path.join(contextDir, 'explorer-last.md'), `# Explorer Report\n\nTask: ${effectiveTask}\nDate: ${new Date().toISOString()}\n\n${text}\n`);
+        }
+        catch { /* don't fail if save fails */ }
+        // Detect tool-call hallucination or empty responses BEFORE touching anything
+        if (looksLikeHallucinatedToolCalls(text)) {
+            log.error('Explorer no devolvio bloques === *.md ===');
+            log.warn('Posible causa: el LLM intento llamar tools que no estan disponibles via API.');
+            log.warn(`Output guardado en: ${path.join(contextDir, 'explorer-last.md')}`);
+            log.warn('Documentacion previa preservada (no se modifico nada).');
+            return text;
+        }
         // Parse sections separated by === path/file.md === markers
         const sections = text.split(/===\s+(.+?\.md)\s*===/).slice(1);
-        let filesWritten = 0;
+        // First pass: collect all valid file writes WITHOUT touching disk yet (transactional)
+        const pendingWrites = [];
         for (let i = 0; i < sections.length; i += 2) {
             const fileName = sections[i].trim();
             let content = sections[i + 1] ? sections[i + 1].trim() : '';
@@ -1307,141 +1646,57 @@ REGLAS DE PATHS:
                 continue;
             // Clean up code fences if present
             content = content.replace(/^```markdown\s*/i, '').replace(/^```\s*$/gm, '').trim();
-            try {
-                let targetPath;
-                // Normalize: strip any .agent/context/ prefix from the marker
-                let relPath = fileName.replace(/^\.agent\/context\//i, '');
-                if (relPath === 'architecture.md' || relPath === 'ARCHITECTURE.md' || relPath === fileName) {
-                    // Main architecture doc
-                    if (relPath === 'architecture.md' || relPath === 'ARCHITECTURE.md') {
-                        targetPath = mainArchPath;
-                    }
-                    else {
-                        // Fallback for unrecognized paths: skip
-                        continue;
-                    }
+            if (!content)
+                continue;
+            // 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;
+            }
+            else {
+                const pathParts = relPath.split(/[\/\\]/).filter(Boolean);
+                if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
+                    targetPath = path.join(contextDir, pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
                 }
-                else {
-                    // Component doc: component/architecture.md or component/modules/mod.md
-                    const pathParts = relPath.split(/[\/\\]/).filter(Boolean);
-                    if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
-                        // component/modules/file.md
-                        targetPath = path.join(contextDir, pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
-                    }
-                    else if (pathParts.length >= 2) {
-                        // component/file.md
-                        targetPath = path.join(contextDir, pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
-                    }
-                    else {
-                        // Fallback
-                        continue;
-                    }
+                else if (pathParts.length >= 2) {
+                    targetPath = path.join(contextDir, pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
                 }
+            }
+            if (!targetPath)
+                continue;
+            pendingWrites.push({ targetPath, content, label: relPath });
+        }
+        if (pendingWrites.length === 0) {
+            log.error('Explorer devolvio texto pero ningun bloque === *.md === fue parseable.');
+            log.warn(`Output guardado en: ${path.join(contextDir, 'explorer-last.md')}`);
+            log.warn('Documentacion previa preservada (no se modifico nada).');
+            return text;
+        }
+        // Second pass: write everything to disk now that we know we have valid output
+        let filesWritten = 0;
+        for (const { targetPath, content, label } of pendingWrites) {
+            try {
                 await fs.mkdir(path.dirname(targetPath), { recursive: true });
                 await writeFile(targetPath, content);
                 filesWritten++;
             }
             catch (err) {
-                log.warn(`Failed to write ${fileName}: ${err.message}`);
+                log.warn(`Failed to write ${label}: ${err.message}`);
             }
         }
-        if (filesWritten > 0) {
-            log.ok(`${filesWritten} documentation file(s) written`);
-        }
-        // Overwrite the single last-run report (no timestamp accumulation)
+        log.ok(`${filesWritten} documentation file(s) written`);
+        // NOW it's safe to clean stray root-level .md files (after successful write).
         try {
-            await writeFile(path.join(contextDir, 'explorer-last.md'), `# Explorer Report\n\nTask: ${effectiveTask}\nDate: ${new Date().toISOString()}\n\n${text}\n`);
+            await this._cleanContextDir(contextDir);
         }
-        catch { /* don't fail if save fails */ }
+        catch { /* don't fail run if cleanup fails */ }
         return text;
     }
-    /** Called when the current binary IS the configured explorer CLI (prevents recursion).
-     *  Builds the full exploration prompt and calls Qwen API using own credentials. */
+    /** Legacy entry point — delegates to runExplorer.
+     *  Kept for backward compatibility with anything that may still call it. */
     async runExplorerDirect(task) {
-        const role = this.config.roles.explorer;
-        if (!role)
-            throw new Error('Explorer role not configured.');
-        const agentDir = path.join(this.projectDir, '.agent');
-        const contextDir = path.join(agentDir, 'context');
-        await fs.mkdir(contextDir, { recursive: true });
-        // Clean up stray files before running
-        await this._cleanContextDir(contextDir);
-        const archPath = path.join(contextDir, 'architecture.md');
-        let existingArch = '';
-        try {
-            existingArch = await readFile(archPath);
-        }
-        catch { /* new */ }
-        const effectiveTask = task || 'Explorar y documentar todas las aplicaciones y servicios del proyecto';
-        const context = await this.buildOrchestratorContext();
-        const prompt = this.buildRolePrompt('explorer', `TAREA DE EXPLORACION: ${effectiveTask}
-DIRECTORIO_TRABAJO: ${this.projectDir}
-PROYECTO: ${this.config.project}
-
-${existingArch ? `DOCUMENTACION EXISTENTE:\n${existingArch.slice(0, 3000)}\n` : 'Sin documentacion previa.\n'}
-CONTEXTO: ${context.slice(0, 2000)}
-
-OBJETIVO
-Generar documentacion ESCALONADA en 3 niveles (global / componente / modulo), util para perfiles funcionales y tecnicos. Detallada pero concreta. Cero suposiciones.
-
-REGLA DE ORO — PROHIBIDO ESPECULAR
-NO uses "Inferido", "Probablemente", "Asumido", "(quizas)", "parece". Si no podes verificar un dato leyendo un archivo, OMITELO. Cada puerto, version, endpoint, env var y schema debe haber sido leido de un archivo real.
-
-WORKFLOW (usa tus tools)
-1. Lista DIRECTORIO_TRABAJO y detecta los componentes no triviales.
-2. Para cada componente, LEE como minimo:
-   - Manifest (package.json | requirements.txt | pom.xml | build.gradle | go.mod | Cargo.toml)
-   - Entry point (main.ts | index.js | app.py | Application.java | cmd/main.go)
-   - .env / .env.example / application.yml / settings.py
-   - 2-3 controladores/routers principales (para endpoints reales)
-   - 2-3 schemas/models principales (para shapes reales)
-3. Mapea relaciones reales (URLs en .env, imports cross-component, conexiones a DB/colas).
-
-LENGUAJE DUAL
-Cada seccion abre con UNA linea simple (que entienda un PM). Despues, el detalle tecnico.
-- MAL: "El microservicio orquesta la persistencia mediante un repositorio."
-- BIEN: "Guarda la informacion del usuario. Internamente usa un repositorio que abstrae MongoDB."
-
-NIVEL 0 — ${archPath} (50-150 lineas)
-Secciones: Overview funcional · Tabla de componentes (con stack+version, puerto, proposito, entry point) · Tabla de relaciones (origen, destino, tipo, proposito) · Diagrama ASCII · 3-5 flujos end-to-end (mapping funcional → tecnico) · Prerequisitos · Comandos globales.
-
-NIVEL 1 — ${contextDir}/<componente>/architecture.md (80-200 lineas, uno por componente)
-Secciones: Que hace (simple) · Casos de uso (3-6 bullets en formato negocio) · Stack tecnico (tabla con versiones reales) · Puerto y URLs · Estructura interna (arbol real) · Tabla de modulos · Tabla de endpoints reales · Tabla de variables de entorno · Integraciones · Como levantar · Comandos.
-
-NIVEL 2 — ${contextDir}/<componente>/modules/<modulo>.md (40-120 lineas, uno por modulo significativo)
-Secciones: Funcion (simple) · Funcion (tecnica) · Flujos / casos de uso paso a paso · Endpoints / interfaces · Schemas reales en codigo · Reglas de negocio · Archivos clave · Dependencias internas/externas/cross-component.
-
-CALIBRACION
-- NIVEL 0: 50-150 lineas. NIVEL 1: 80-200 por componente. NIVEL 2: 40-120 por modulo.
-- Si te queda corto, leiste pocos archivos. Si te queda largo, recorta el relleno.
-- Componentes triviales (solo scripts/docs): mencionalos en NIVEL 0 y NO les crees subcarpeta.
-
-REGLAS DE ESCRITURA
-- Solo podes escribir archivos dentro de ${contextDir}/
-- NO crees archivos sueltos en la raiz de ${contextDir}/ (excepto architecture.md)
-- Por componente usa: ${contextDir}/<componente>/architecture.md
-- Por modulo usa: ${contextDir}/<componente>/modules/<modulo>.md
-- Si existe documentacion previa, ACTUALIZALA preservando lo valido`);
-        let result;
-        const sp = this._startSpinner(`agent-explorer  ${role.model}`);
-        try {
-            result = await callQwenAPI(prompt, role.model, (c) => this._parseChunk(c).forEach(l => sp.push(l)));
-            sp.stop();
-        }
-        catch (err) {
-            sp.stop();
-            if (err.message?.startsWith('QWEN_AUTH_EXPIRED')) {
-                console.log(chalk.red('\n  ✗ Sesión Qwen expirada.'));
-                console.log(chalk.yellow('  Ejecutá: agent-mp --login  (o agent-explorer --login)\n'));
-                return '';
-            }
-            throw err;
-        }
-        try {
-            await writeFile(path.join(contextDir, 'explorer-last.md'), `# Explorer Report\n\nTask: ${effectiveTask}\nDate: ${new Date().toISOString()}\n\n${result}\n`);
-        }
-        catch { /* ignore */ }
-        return result;
+        return this.runExplorer(task);
     }
     async runFullCycle(task) {
         // Header is now shown by the REPL before the first user message