agent-mp 0.5.38 → 0.5.40

package/dist/commands/repl.js

@@ -190,7 +190,7 @@ function detectInstalledClis() {
     }
     return installed;
 }
-function detectModels(cliName) {
+async function detectModels(cliName) {
     try {
         switch (cliName) {
             case 'claude': {
@@ -225,17 +225,61 @@ function detectModels(cliName) {
             case 'agent-impl':
             case 'agent-rev':
             case 'agent-explorer': {
+                const found = [];
+                const add = (m) => { if (m && !found.includes(m))
+                    found.push(m); };
+                // For each sub-agent home dir, read each provider's key file
+                // and live-fetch the available models from that provider's API.
                 for (const dir of [`.${cliName}`, '.agent-mp']) {
+                    const homeDir = path.join(os.homedir(), dir);
+                    // Qwen / OpenAI-compatible
                     try {
-                        const cfg = JSON.parse(fsSync.readFileSync(path.join(os.homedir(), dir, 'config.json'), 'utf-8'));
-                        if (cfg.availableModels?.length)
-                            return cfg.availableModels;
-                        if (cfg.coordinatorModel)
-                            return [cfg.coordinatorModel];
+                        const cfg = JSON.parse(fsSync.readFileSync(path.join(homeDir, 'api_key.json'), 'utf-8'));
+                        if (cfg?.api_key) {
+                            const remote = await fetchApiKeyModels(cfg);
+                            if (remote.length)
+                                remote.forEach(add);
+                            else
+                                add(cfg.model);
+                        }
+                    }
+                    catch { }
+                    // Gemini
+                    try {
+                        const cfg = JSON.parse(fsSync.readFileSync(path.join(homeDir, 'gemini_key.json'), 'utf-8'));
+                        if (cfg?.api_key) {
+                            const remote = await fetchGeminiModels(cfg);
+                            if (remote.length)
+                                remote.forEach(add);
+                            else
+                                add(cfg.model);
+                        }
                     }
                     catch { }
+                    // DeepSeek
+                    try {
+                        const cfg = JSON.parse(fsSync.readFileSync(path.join(homeDir, 'deepseek_key.json'), 'utf-8'));
+                        if (cfg?.api_key) {
+                            const remote = await fetchDeepSeekModels(cfg);
+                            if (remote.length)
+                                remote.forEach(add);
+                            else
+                                add(cfg.model);
+                        }
+                    }
+                    catch { }
+                    // Legacy fallback fields in config.json
+                    try {
+                        const cfg = JSON.parse(fsSync.readFileSync(path.join(homeDir, 'config.json'), 'utf-8'));
+                        if (Array.isArray(cfg.availableModels))
+                            cfg.availableModels.forEach(add);
+                        add(cfg.coordinatorModel);
+                    }
+                    catch { }
+                    if (found.length)
+                        break;
                 }
-                return ['coder-model'];
+                return found.length ? found : ['coder-model'];
             }
             default: return ['default'];
         }
@@ -411,7 +455,7 @@ async function cmdSetup(rl) {
         log.cliList(c.name, c.path);
     console.log(chalk.bold('\n  Multi-CLI Configuration'));
     const cliConfig = await loadCliConfig();
-    const roles = ['orchestrator', 'implementor', 'reviewer'];
+    const roles = ['orchestrator', 'implementor', 'reviewer', 'explorer'];
     for (const role of roles) {
         console.log(chalk.yellow(`\n  ${role.toUpperCase()}`));
         const cliName = await selectOption(rl, `CLI for ${role}:`, installed.map((c) => c.name));
@@ -419,22 +463,24 @@ async function cmdSetup(rl) {
             console.log(chalk.red(`  Unknown CLI: ${cliName}`));
             return;
         }
-        const models = detectModels(cliName);
+        const models = await detectModels(cliName);
         const model = await selectOption(rl, `Model for ${cliName}:`, models);
         cliConfig.roles[role] = { cli: cliName, model };
-        // Ask about fallback for this role
-        const fbAnswer = await ask(rl, `  Configure fallback for ${role}? (y/N): `);
-        if (fbAnswer.toLowerCase() === 'y') {
-            const otherClis = installed.filter((c) => c.name !== cliName);
-            if (otherClis.length === 0) {
-                console.log(chalk.dim('  No other CLIs available for fallback.'));
-            }
-            else {
-                const fbCliName = await selectOption(rl, `Fallback CLI for ${role}:`, otherClis.map((c) => c.name));
-                const fbModels = detectModels(fbCliName);
-                const fbModel = await selectOption(rl, `Fallback model for ${fbCliName}:`, fbModels);
-                cliConfig.roles[role].fallbackCli = fbCliName;
-                cliConfig.roles[role].fallbackModel = fbModel;
+        // Ask about fallback for this role (skip explorer — single CLI is enough)
+        if (role !== 'explorer') {
+            const fbAnswer = await ask(rl, `  Configure fallback for ${role}? (y/N): `);
+            if (fbAnswer.toLowerCase() === 'y') {
+                const otherClis = installed.filter((c) => c.name !== cliName);
+                if (otherClis.length === 0) {
+                    console.log(chalk.dim('  No other CLIs available for fallback.'));
+                }
+                else {
+                    const fbCliName = await selectOption(rl, `Fallback CLI for ${role}:`, otherClis.map((c) => c.name));
+                    const fbModels = await detectModels(fbCliName);
+                    const fbModel = await selectOption(rl, `Fallback model for ${fbCliName}:`, fbModels);
+                    cliConfig.roles[role].fallbackCli = fbCliName;
+                    cliConfig.roles[role].fallbackModel = fbModel;
+                }
             }
         }
     }
@@ -454,7 +500,7 @@ async function cmdSetup(rl) {
     const globalFbAnswer = await ask(rl, '  Configurar fallback global? (y/N): ');
     if (globalFbAnswer.toLowerCase() === 'y') {
         const fbCliName = await selectOption(rl, 'Fallback global CLI:', installed.map((c) => c.name));
-        const fbModels = detectModels(fbCliName);
+        const fbModels = await detectModels(fbCliName);
         const fbModel = await selectOption(rl, `Fallback global model for ${fbCliName}:`, fbModels);
         cliConfig.fallback_global = { cli: fbCliName, model: fbModel };
     }
@@ -483,6 +529,7 @@ async function cmdSetup(rl) {
             orchestrator: buildRoleWithFallback('orchestrator'),
             implementor: buildRoleWithFallback('implementor'),
             reviewer: buildRoleWithFallback('reviewer'),
+            ...(cliConfig.roles.explorer?.cli ? { explorer: { cli: cliConfig.roles.explorer.cli, model: cliConfig.roles.explorer.model, cmd: buildCmd(cliConfig.roles.explorer.cli, cliConfig.roles.explorer.model) } } : {}),
         },
         deliberation: cliConfig.deliberation.enabled ? {
             proposer: { cli: cliConfig.roles.proposer?.cli || '', model: cliConfig.roles.proposer?.model || '', cmd: buildCmd(cliConfig.roles.proposer?.cli || '', cliConfig.roles.proposer?.model || '') },
@@ -526,34 +573,36 @@ async function cmdConfigMulti(rl) {
     for (const c of installed)
         log.cliList(c.name, c.path);
     const cliConfig = await loadCliConfig();
-    const roles = ['orchestrator', 'implementor', 'reviewer'];
+    const roles = ['orchestrator', 'implementor', 'reviewer', 'explorer'];
     for (const role of roles) {
         const current = cliConfig.roles[role];
         const fbInfo = current?.fallbackCli ? ` | fb: ${current.fallbackCli}/${current.fallbackModel}` : '';
         console.log(chalk.yellow(`\n  ${role.toUpperCase()}${current ? ` [current: ${current.cli}/${current.model}${fbInfo}]` : ''}`));
         const cliName = await selectOption(rl, `CLI for ${role}:`, installed.map((c) => c.name));
-        const models = detectModels(cliName);
+        const models = await detectModels(cliName);
         const model = await selectOption(rl, `Model for ${cliName}:`, models);
         cliConfig.roles[role] = { cli: cliName, model };
-        // Ask about fallback for this role
-        const fbAnswer = await ask(rl, `  Configure fallback for ${role}? (y/N): `);
-        if (fbAnswer.toLowerCase() === 'y') {
-            const otherClis = installed.filter((c) => c.name !== cliName);
-            if (otherClis.length === 0) {
-                console.log(chalk.dim('  No other CLIs available for fallback.'));
+        // Ask about fallback for this role (skip explorer — single CLI is enough)
+        if (role !== 'explorer') {
+            const fbAnswer = await ask(rl, `  Configure fallback for ${role}? (y/N): `);
+            if (fbAnswer.toLowerCase() === 'y') {
+                const otherClis = installed.filter((c) => c.name !== cliName);
+                if (otherClis.length === 0) {
+                    console.log(chalk.dim('  No other CLIs available for fallback.'));
+                }
+                else {
+                    const fbCliName = await selectOption(rl, `Fallback CLI for ${role}:`, otherClis.map((c) => c.name));
+                    const fbModels = await detectModels(fbCliName);
+                    const fbModel = await selectOption(rl, `Fallback model for ${fbCliName}:`, fbModels);
+                    cliConfig.roles[role].fallbackCli = fbCliName;
+                    cliConfig.roles[role].fallbackModel = fbModel;
+                }
             }
             else {
-                const fbCliName = await selectOption(rl, `Fallback CLI for ${role}:`, otherClis.map((c) => c.name));
-                const fbModels = detectModels(fbCliName);
-                const fbModel = await selectOption(rl, `Fallback model for ${fbCliName}:`, fbModels);
-                cliConfig.roles[role].fallbackCli = fbCliName;
-                cliConfig.roles[role].fallbackModel = fbModel;
+                delete cliConfig.roles[role].fallbackCli;
+                delete cliConfig.roles[role].fallbackModel;
             }
         }
-        else {
-            delete cliConfig.roles[role].fallbackCli;
-            delete cliConfig.roles[role].fallbackModel;
-        }
     }
     // Global fallback
     const currentGlobalFb = cliConfig.fallback_global;
@@ -562,7 +611,7 @@ async function cmdConfigMulti(rl) {
     const globalFbAnswer = await ask(rl, '  Configurar fallback global? (y/N): ');
     if (globalFbAnswer.toLowerCase() === 'y') {
         const fbCliName = await selectOption(rl, 'Fallback global CLI:', installed.map((c) => c.name));
-        const fbModels = detectModels(fbCliName);
+        const fbModels = await detectModels(fbCliName);
         const fbModel = await selectOption(rl, `Fallback global model for ${fbCliName}:`, fbModels);
         cliConfig.fallback_global = { cli: fbCliName, model: fbModel };
     }
@@ -591,6 +640,7 @@ async function cmdConfigMulti(rl) {
             orchestrator: buildRoleWithFallback('orchestrator'),
             implementor: buildRoleWithFallback('implementor'),
             reviewer: buildRoleWithFallback('reviewer'),
+            ...(cliConfig.roles.explorer?.cli ? { explorer: { cli: cliConfig.roles.explorer.cli, model: cliConfig.roles.explorer.model, cmd: buildCmd(cliConfig.roles.explorer.cli, cliConfig.roles.explorer.model) } } : {}),
         },
         deliberation: cliConfig.deliberation?.enabled ? {
             proposer: { cli: cliConfig.roles.proposer?.cli || '', model: cliConfig.roles.proposer?.model || '', cmd: buildCmd(cliConfig.roles.proposer?.cli || '', cliConfig.roles.proposer?.model || '') },
@@ -616,7 +666,7 @@ async function cmdConfigOneRole(rl, role) {
     const current = cliConfig.roles[role];
     console.log(chalk.yellow(`\n  ${role.toUpperCase()}${current ? ` [current: ${current.cli}/${current.model}]` : ''}`));
     const cliName = await selectOption(rl, `CLI for ${role}:`, installed.map((c) => c.name));
-    const models = detectModels(cliName);
+    const models = await detectModels(cliName);
     const model = await selectOption(rl, `Model for ${cliName}:`, models);
     cliConfig.roles[role] = { cli: cliName, model };
     await saveCliConfig(cliConfig);
@@ -761,15 +811,15 @@ async function cmdModels(roleArg, fi, rl) {
         console.log(chalk.dim('  Fetching Qwen models...'));
         models = await fetchQwenModels();
         if (!models.length)
-            models = detectModels('qwen');
+            models = await detectModels('qwen');
     }
     else if (apiKeyCfg?.api_key) {
         models = await fetchApiKeyModels(apiKeyCfg);
         if (!models.length)
-            models = detectModels(activeProvider);
+            models = await detectModels(activeProvider);
     }
     else {
-        models = activeProvider ? detectModels(activeProvider) : [];
+        models = activeProvider ? await detectModels(activeProvider) : [];
     }
     if (!models.length) {
         resume();
@@ -1148,6 +1198,7 @@ export async function runRepl(resumeSession) {
                 orchestrator: `${config.roles.orchestrator.cli}/${config.roles.orchestrator.model}`,
                 implementor: `${config.roles.implementor.cli}/${config.roles.implementor.model}`,
                 reviewer: `${config.roles.reviewer.cli}/${config.roles.reviewer.model}`,
+                ...(config.roles.explorer?.cli ? { explorer: `${config.roles.explorer.cli}/${config.roles.explorer.model}` } : {}),
             };
         }
     }
@@ -1205,6 +1256,7 @@ export async function runRepl(resumeSession) {
                     orchestrator: `${config.roles.orchestrator.cli}/${config.roles.orchestrator.model}`,
                     implementor: `${config.roles.implementor.cli}/${config.roles.implementor.model}`,
                     reviewer: `${config.roles.reviewer.cli}/${config.roles.reviewer.model}`,
+                    ...(config.roles.explorer?.cli ? { explorer: `${config.roles.explorer.cli}/${config.roles.explorer.model}` } : {}),
                 };
             }
         }

package/dist/commands/setup.js

@@ -25,7 +25,7 @@ function detectInstalledClis() {
     }
     return installed;
 }
-function detectModels(cliName) {
+async function detectModels(cliName) {
     try {
         switch (cliName) {
             case 'claude': {
@@ -63,17 +63,58 @@ function detectModels(cliName) {
             case 'agent-impl':
             case 'agent-rev':
             case 'agent-explorer': {
+                const { fetchApiKeyModels } = await import('../utils/qwen-auth.js');
+                const { fetchGeminiModels } = await import('../utils/gemini.js');
+                const { fetchDeepSeekModels } = await import('../utils/deepseek.js');
+                const found = [];
+                const add = (m) => { if (m && !found.includes(m))
+                    found.push(m); };
                 for (const dir of [`.${cliName}`, '.agent-mp']) {
+                    const homeDir = path.join(os.homedir(), dir);
                     try {
-                        const cfg = JSON.parse(fsSync.readFileSync(path.join(os.homedir(), dir, 'config.json'), 'utf-8'));
-                        if (cfg.availableModels?.length)
-                            return cfg.availableModels;
-                        if (cfg.coordinatorModel)
-                            return [cfg.coordinatorModel];
+                        const cfg = JSON.parse(fsSync.readFileSync(path.join(homeDir, 'api_key.json'), 'utf-8'));
+                        if (cfg?.api_key) {
+                            const remote = await fetchApiKeyModels(cfg);
+                            if (remote.length)
+                                remote.forEach(add);
+                            else
+                                add(cfg.model);
+                        }
                     }
                     catch { }
+                    try {
+                        const cfg = JSON.parse(fsSync.readFileSync(path.join(homeDir, 'gemini_key.json'), 'utf-8'));
+                        if (cfg?.api_key) {
+                            const remote = await fetchGeminiModels(cfg);
+                            if (remote.length)
+                                remote.forEach(add);
+                            else
+                                add(cfg.model);
+                        }
+                    }
+                    catch { }
+                    try {
+                        const cfg = JSON.parse(fsSync.readFileSync(path.join(homeDir, 'deepseek_key.json'), 'utf-8'));
+                        if (cfg?.api_key) {
+                            const remote = await fetchDeepSeekModels(cfg);
+                            if (remote.length)
+                                remote.forEach(add);
+                            else
+                                add(cfg.model);
+                        }
+                    }
+                    catch { }
+                    try {
+                        const cfg = JSON.parse(fsSync.readFileSync(path.join(homeDir, 'config.json'), 'utf-8'));
+                        if (Array.isArray(cfg.availableModels))
+                            cfg.availableModels.forEach(add);
+                        add(cfg.coordinatorModel);
+                    }
+                    catch { }
+                    if (found.length)
+                        break;
                 }
-                return ['coder-model'];
+                return found.length ? found : ['coder-model'];
             }
             default:
                 return ['default'];
@@ -126,7 +167,7 @@ async function configureOneRole(rl, role, installed, cliConfig) {
         console.log(chalk.red(`  Unknown CLI: ${cliName}`));
         return false;
     }
-    const models = detectModels(cliName);
+    const models = await detectModels(cliName);
     const modelOptions = numberedSelect(`Models for ${cliName}:`, models);
     const modelChoice = await ask(rl, `  Model: `);
     cliConfig.roles[role] = {
@@ -244,7 +285,7 @@ export function setupCommand(program) {
                 rl.close();
                 return;
             }
-            const models = detectModels(cliName);
+            const models = await detectModels(cliName);
             const modelOptions = numberedSelect(`Models for ${cliName}:`, models);
             const modelChoice = await ask(rl, `  Model: `);
             const model = resolveChoice(modelChoice, modelOptions);
@@ -338,7 +379,7 @@ export function setupCommand(program) {
                 continue;
             }
             const cliName = resolveChoice(cliChoice, cliOptions);
-            const models = detectModels(cliName);
+            const models = await detectModels(cliName);
             const modelOptions = numberedSelect(`Models for ${cliName}:`, models);
             const modelChoice = await ask(rl, `  Model: `);
             cliConfig.roles[role] = { cli: cliName, model: resolveChoice(modelChoice, modelOptions) };

package/dist/core/engine.js

@@ -1667,358 +1667,212 @@ INSTRUCCIONES:
         }
         catch { /* ignore */ }
         const effectiveTask = task || 'Explorar y documentar todas las aplicaciones y servicios del proyecto';
-        const prompt = `TAREA DE EXPLORACION: ${effectiveTask}
+        const prompt = `TAREA: ${effectiveTask}
 DIRECTORIO_TRABAJO: ${this.projectDir}
 PROYECTO: ${this.config.project}
-STACK: ${this.config.stack}
 
-ESTRUCTURA DE ARCHIVOS (excluye .agent, node_modules, .git, dist, __pycache__, .venv, target, build):
+ESTRUCTURA DEL PROYECTO:
 ${fsSnapshot}
 
-${prefetched ? `================================================================\nARCHIVOS REALES LEIDOS DEL PROYECTO (esta es tu fuente de verdad)\n================================================================\n${prefetched}\n` : ''}
+${prefetched ? `==== ARCHIVOS REALES LEIDOS (tu unica fuente de verdad) ====\n${prefetched}\n` : ''}
+${existingMainArch ? `==== DOC EXISTENTE: architecture.md (raiz) — preservar y solo actualizar lo que cambio ====\n${existingMainArch.slice(0, 6000)}\n` : ''}
+${existingComponentDocs ? `==== DOC EXISTENTE por componente ====\n${existingComponentDocs.slice(0, 4000)}\n` : ''}
 
-${existingMainArch ? `=== DOC EXISTENTE: architecture.md (principal) ===\n${existingMainArch.slice(0, 2000)}\n` : ''}
-${existingComponentDocs ? `=== DOC EXISTENTE por componente ===\n${existingComponentDocs.slice(0, 3000)}\n` : ''}
+==================================================================
+TU TRABAJO — leelo entero antes de escribir
+==================================================================
 
-================================================================
-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 extraidos de los archivos que estan mas arriba. Cero especulaciones.
+1. IDENTIFICAR COMPONENTES
+   Un "componente" = cada CARPETA HIJA del DIRECTORIO_TRABAJO que tenga un manifest propio:
+     package.json, pom.xml, build.gradle(.kts), requirements.txt / pyproject.toml,
+     go.mod, Cargo.toml, composer.json, Gemfile, *.csproj, *.sln, mix.exs, Dockerfile.
+   Backend, frontend, worker, batch, mobile — todos cuentan. Si tiene manifest, es componente.
 
-================================================================
+2. PARA CADA COMPONENTE, GENERAR EXACTAMENTE UN ARCHIVO:
+     === .agent/context/<carpeta-del-componente>/architecture.md ===
+
+   El nombre de carpeta DEBE coincidir con el nombre real del directorio en el proyecto.
+   Si hay 3 carpetas/componentes en la raiz, hay que generar 3 archivos NIVEL 1.
+   No omitas ninguno. Frontends incluidos.
+
+3. ADEMAS, GENERAR EL DOC RAIZ:
+     === .agent/context/architecture.md ===  (NIVEL 0 — vista global)
+
+4. OPCIONAL — modulos por feature dentro de un componente:
+     === .agent/context/<componente>/modules/<feature>.md ===  (NIVEL 2)
+   Solo si el componente tiene features de negocio claras (clients, sales, auth, products...).
+   No crees modulos por capa tecnica (security, db, web). Si no hay features claras, omiti NIVEL 2.
+
+==================================================================
 REGLA DE ORO — PROHIBIDO INVENTAR
-================================================================
-NO uses jamas: "Inferido", "Probablemente", "Posiblemente", "Asumido", "(supuesto)", "(quizas)", "parece ser".
-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.
-
-================================================================
-COMO TRABAJAR (lectura ya hecha por el engine)
-================================================================
-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)
-================================================================
-Cada seccion abre con UNA linea en lenguaje simple (que entienda un PM/negocio), DESPUES viene el detalle tecnico.
-- MAL: "El microservicio orquesta la persistencia mediante un repositorio."
-- BIEN: "Guarda la informacion del usuario en la base. Internamente usa un repositorio que abstrae la conexion a MongoDB."
-
-================================================================
-ESTRUCTURA DE LOS 3 NIVELES
-================================================================
-
-────────────────────────────────────────────────────────────────
-────────────────────────────────────────────────────────────────
-NIVEL 0 — architecture.md  (raiz de .agent/context/)
-Objetivo: 80-150 lineas. Panorama global real, no generico.
-────────────────────────────────────────────────────────────────
-
-# [Nombre del proyecto] — Arquitectura Global (NIVEL 0)
+==================================================================
+- Si un dato (puerto, version, endpoint, env var, ruta, clase) no aparece en los ARCHIVOS REALES → OMITILO.
+- NO uses "inferido", "probablemente", "asumido", "(quizas)", "parece ser".
+- Mejor doc corta y veraz que larga llena de suposiciones.
+- NO devuelvas "tool_call", "function_call" ni invocaciones — devolves MARKDOWN, nada mas.
+
+==================================================================
+PLANTILLAS — usa lo que aplique al stack real, omite lo que no
+==================================================================
+
+────── NIVEL 0  (.agent/context/architecture.md, 80-180 lineas) ──────
+
+REGLA CRITICA PARA NIVEL 0 — UPDATE INCREMENTAL, NO REESCRIBIR:
+Si arriba aparece "DOC EXISTENTE: architecture.md (raiz)", USALA COMO BASE.
+- Mantene su estructura, sus secciones y su redaccion tal cual.
+- Cambia UNICAMENTE las celdas/lineas donde el dato real (puerto, version, endpoint, dependencia) cambio.
+- Si un componente seguia listado en la doc previa pero su carpeta YA NO EXISTE en el filesystem actual:
+    NO LO BORRES. Conservalo en su fila y agrega el sufijo " — (archivado, fuera del workspace actual)".
+    Si tiene seccion propia (flujos, relaciones), preservala igual y marca el componente como archivado.
+- Si hay un componente NUEVO (carpeta presente ahora que antes no estaba), agregalo como fila/seccion nueva.
+- No reescribas overview/diagrama/flujos a menos que el cambio real lo requiera.
+- Si NO hay doc previa, generala con la plantilla de abajo.
+
+# ${this.config.project} — Arquitectura Global
 
 > 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. 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 | 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 | Proposito |
+>   NIVEL 0: este archivo (vista global)
+>   NIVEL 1: .agent/context/<componente>/architecture.md
+>   NIVEL 2: .agent/context/<componente>/modules/<feature>.md
+
+## 1. Que es el sistema
+2-4 lineas. Para quien sirve, que problema resuelve. Si hay multiples componentes, contrastalos.
+
+## 2. Componentes
+| Componente | Estado | Tipo (api / web / worker / mobile) | Stack + version | Puerto | Rol |
+|---|---|---|---|---|---|
+(Estado: "activo" si la carpeta existe ahora; "archivado" si estaba en la doc previa pero ya no esta en el filesystem.)
+(Datos REALES del manifest. Componentes archivados conservan sus datos previos.)
+
+## 3. Como se conectan
+| Origen | Destino | Tipo (HTTP, DB, mensaje) | Detalle |
 |---|---|---|---|
-(incluir URLs/hosts reales si aparecen en .env o config: ej. "http://57.151.96.13:8000/v1/validate")
+(URLs/hosts reales de .env / config. Si una relacion involucra un componente archivado, mantenerla y marcarla con "(archivado)".)
 
-## 4. Diagrama de arquitectura
-Usar box-drawing (┌─┐│└┘┬┴├┤) y flechas (→ ──> ▼ ▲). Mostrar puertos REALES.
-Incluir endpoints clave inline en los componentes cuando se conocen.
+## 4. Diagrama
+Box-drawing y flechas. Mostrar puertos REALES y endpoints clave si 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       │
-    └──────────────┘              └──────────────┘
+┌──────────────┐   HTTP    ┌──────────────┐
+│ frontend :3000│──────────>│ api :8080   │
+└──────────────┘           └──────┬───────┘
+                                  │ JDBC
+                                  ▼
+                            ┌──────────┐
+                            │ DB :5432 │
+                            └──────────┘
 \`\`\`
 
-## 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.
+## 5. Flujos end-to-end (2-5)
+- **<nombre>:** Actor → endpoint/componente → valida X → escribe Y → responde Z.
 
-## 6. Prerequisitos para levantar
-Solo lo que es real: acceso de red a hosts externos, herramientas requeridas. Sin generalidades.
+## 6. Prerequisitos
+Lo concreto: acceso a hosts externos, herramientas requeridas, secrets esperados. Sin frases genericas.
 
-## 7. Comandos de desarrollo
+## 7. Comandos
 | Comando | Descripcion | Directorio |
 |---|---|---|
-(comandos reales del Makefile, run.sh, package.json scripts, mvnw, etc.)
+(scripts reales: package.json scripts, Makefile targets, run.sh, mvnw, gradlew, etc.)
 
-────────────────────────────────────────────────────────────────
-NIVEL 1 — [componente]/architecture.md
-Objetivo: 120-250 lineas. Un archivo por cada componente no trivial.
-────────────────────────────────────────────────────────────────
 
-# [componente] — Arquitectura (NIVEL 1)
+────── NIVEL 1  (.agent/context/<componente>/architecture.md, 100-220 lineas) ──────
+
+# <componente> — Arquitectura
 
 ## Que hace
-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."
+Parrafo 1: rol funcional + quien lo consume (en lenguaje de negocio).
+Parrafo 2 (si aplica): que lo diferencia de los otros componentes hermanos.
 
 ## Casos de uso principales
-Tabla con: Caso de uso | Actor (quien lo dispara) | Descripcion + endpoint si se conoce.
-| Caso de uso | Actor | Descripcion |
+| Caso de uso | Quien lo dispara | Detalle |
 |---|---|---|
-| 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
+## Stack
 | Item | Valor |
 |---|---|
-| 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)
+| Lenguaje | (real, version del manifest) |
+| Framework | (real) |
+| Librerias clave | (las relevantes con version) |
 
-## Puerto y URLs
+## URLs y puertos (si aplica)
 | Recurso | URL |
 |---|---|
-| API base | http://localhost:8084 |
-| Swagger / docs | http://localhost:8084/swagger-ui/index.html |
-| Perfil activo | development (application-development.properties) |
+| Base | http://localhost:<puerto-real> |
+| Docs / Swagger / Storybook | (si existe) |
 
-## Estructura de capas / paquetes
-Arbol con los archivos y directorios REALES que leiste. Usar → para anotar inline que hace cada clase o directorio.
+## Estructura
+Arbol con DIRECTORIOS y archivos REALES leidos, anotados con → que rol cumple cada uno.
 \`\`\`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
-\`\`\`
-(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 }
-}
+src/
+├── ...   → ...
 \`\`\`
-Si no hay wrapper, omitir esta seccion.
 
-## Modulos internos
-| 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)
+## Endpoints / Rutas / Pantallas
+- Backend (api): tabla con metodo, ruta, auth, proposito.
+- Frontend (web): tabla con ruta de pagina, proposito, datos que consume.
+- Worker / batch: tabla con job, trigger, proposito.
+Solo lo leido en archivos reales.
 
-## Variables de configuracion clave
-| Propiedad / Variable | Valor actual | Proposito |
+## Configuracion clave
+| Variable / Propiedad | Valor real | 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)
+(de .env / application*.properties / config files leidos)
 
 ## Como levantar
-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
+# comando real del manifest / scripts
 \`\`\`
 
-## 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
-\`\`\`
+## Tests (si los hay)
+Frameworks + comando para correr.
 
-────────────────────────────────────────────────────────────────
-NIVEL 2 — [componente]/modules/[modulo].md
-Objetivo: 50-120 lineas. Un archivo por modulo significativo.
-────────────────────────────────────────────────────────────────
 
-# Modulo: [Nombre] — [componente]
+────── NIVEL 2  (.agent/context/<componente>/modules/<feature>.md, 40-100 lineas) ──────
+Solo si el componente tiene features de negocio claras (no crees modulos por capa tecnica).
 
-## Funcion (lenguaje simple)
-1-2 lineas: "Protege todos los endpoints /api/**. Cada request debe llevar un token JWT valido."
+# <feature> — <componente>
 
-## Funcion (tecnica)
-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."
+## Que hace (negocio, 1-2 lineas)
 
-## 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
-\`\`\`
+## Como esta implementado (tecnico, 1-2 lineas)
 
-## Entidades / modelos relevantes (si aplica)
-Para modulos de acceso a datos: tabla de entidades con su proposito y notas.
+## Flujo principal
+Diagrama ASCII si hay logica de decision, con nombres REALES de clases/funciones.
+
+## Entidades / modelos (si aplica)
 | 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 |
+| Archivo (ruta relativa al componente) | Rol |
 |---|---|
-| 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
-- 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: 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 "..." 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
-================================================================
-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.
 
-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/clients.md ===
+==================================================================
+FORMATO DE SALIDA — OBLIGATORIO
+==================================================================
+Devolve UNICAMENTE bloques separados por marcadores ===. Sin texto extra fuera de los bloques.
+TODAS las rutas son RELATIVAS al directorio del proyecto.
 
 === .agent/context/architecture.md ===
-[contenido NIVEL 0]
+[NIVEL 0]
+
+=== .agent/context/<componente-A>/architecture.md ===
+[NIVEL 1 del componente A]
+
+=== .agent/context/<componente-B>/architecture.md ===
+[NIVEL 1 del componente B]
 
-=== .agent/context/nombre-componente/architecture.md ===
-[contenido NIVEL 1]
+(... un bloque NIVEL 1 por cada componente identificado en paso 1)
 
-=== .agent/context/nombre-componente/modules/auth.md ===
-[contenido NIVEL 2]
+=== .agent/context/<componente-A>/modules/<feature>.md ===
+[NIVEL 2 — opcional]
 
-REGLAS DE PATHS:
-- 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`;
+REGLAS FINALES:
+- Un archivo NIVEL 1 por cada carpeta-componente que EXISTE HOY en el filesystem (no saltes ninguna, incluye frontends).
+- NO regeneres NIVEL 1 de componentes archivados (carpetas que ya no existen): no los incluyas en tu output. La doc previa de esos componentes queda intacta en disco.
+- NIVEL 0: update incremental. Si la doc previa lista componentes archivados, conservalos marcados como tal — no los borres.
+- NO escribir bajo .agent/docs/.
+- Los nombres de carpeta en los marcadores DEBEN coincidir con los nombres reales del proyecto (los activos).`;
         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

package/dist/ui/theme.d.ts

@@ -40,6 +40,7 @@ export interface WelcomePanelOpts {
         orchestrator?: string;
         implementor?: string;
         reviewer?: string;
+        explorer?: string;
     };
 }
 export declare function renderWelcomePanel(opts: WelcomePanelOpts): string;

package/dist/ui/theme.js

@@ -90,7 +90,7 @@ export function renderWelcomePanel(opts) {
         "",
     ];
     if (opts.roles &&
-        (opts.roles.orchestrator || opts.roles.implementor || opts.roles.reviewer)) {
+        (opts.roles.orchestrator || opts.roles.implementor || opts.roles.reviewer || opts.roles.explorer)) {
         right.push(` ${accent("Current roles")}`);
         right.push(` ${rSep}`);
         if (opts.roles.orchestrator) {
@@ -102,6 +102,9 @@ export function renderWelcomePanel(opts) {
         if (opts.roles.reviewer) {
             right.push(` ${chalk.dim("Rev   ")}${chalk.rgb(0, 185, 180)(opts.roles.reviewer)}`);
         }
+        if (opts.roles.explorer) {
+            right.push(` ${chalk.dim("Expl  ")}${chalk.rgb(0, 185, 180)(opts.roles.explorer)}`);
+        }
         right.push("");
     }
     else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mp",
-  "version": "0.5.38",
+  "version": "0.5.40",
   "description": "Deterministic multi-agent CLI orchestrator — plan, code, review",
   "type": "module",
   "main": "./dist/index.js",