ozali 0.3.0 → 0.4.0

package/README.md

@@ -61,8 +61,14 @@ ozali init      # detecta agente, instala la skill, aísla el histórico, instal
 ozali doctor    # health-check read-only (fuente de verdad, Engram, Cloud, Strict TDD, runner…)
 ozali update    # actualiza la skill instalada a la versión del paquete
 ozali sync      # lleva el histórico (docs + Engram) al repo de conocimiento de equipo
+ozali audit     # navega/audita la memoria de Engram del proyecto (o general)
 ```
 
+`ozali audit` recorre lo que el equipo ha acumulado en Engram: dentro de un repo propone auditar
+**ese proyecto** o **general** (todos los proyectos); fuera de un repo va directo a general. Usa
+`--tui` para el navegador interactivo, `--search "<texto>"` para buscar y `--general` para forzar el
+alcance. Sin Engram, audita el histórico local de `.ozali/docs/`.
+
 `init` también escribe un **perfil base de permisos** (`.claude/settings.json` para Claude Code,
 `opencode.json` para opencode) para reducir confirmaciones: deja libres comandos seguros y bloquea
 los destructivos. Es un template — tus reglas se conservan al re-correr `init`. Como Claude Code
@@ -75,9 +81,16 @@ macOS/Linux, `go install` en Windows, con binario precompilado como fallback. Si
 instalarlo, pasa `--no-engram` (arranca en modo `docs`). Opcionalmente habilita **Engram Cloud**
 (réplica de equipo opt-in) además del git-sync.
 
+`init` también crea **ozali-jarvis**, un **orquestador always-on**: persona en `CLAUDE.md`/`AGENTS.md`
++ subagente + hooks de recordatorio que hace que el agente, **en toda sesión y sin necesidad de
+`/cdk`**, recupere contexto de Engram, registre el trabajo del equipo (memoria en contexto) y delegue
+la ejecución disciplinada en `cdk`. Fija el proyecto en `.engram/config.json` para memoria
+determinista. Con Engram en línea, jarvis y `cdk` operan **recall-first** (reusan memoria en vez de
+releer) para gastar menos tokens/contexto. Omítelo con `--no-jarvis`.
+
 Flags útiles: `--yes` (no interactivo), `--dry-run` (init sin escribir), `--no-engram`, `--no-trust`,
-`--agent`, `--scope`, `--knowledge-repo`, `--import`/`--push`/`--cloud` (sync). Modelo mental completo
-en [docs/intended-usage.md](docs/intended-usage.md).
+`--no-jarvis`, `--agent`, `--scope`, `--knowledge-repo`, `--import`/`--push`/`--cloud` (sync). Modelo
+mental completo en [docs/intended-usage.md](docs/intended-usage.md).
 
 ## Agentes soportados
 

package/cli/bin/ozali.mjs

@@ -3,7 +3,7 @@
 // Seguridad: sin dependencias ni scripts de instalación. Ejecuta seguro con
 // `pnpm dlx ozali` o `npx --ignore-scripts ozali`. Ver docs/security.md.
 import { c, err, pkgVersion } from "../lib/util.mjs";
-import { init, doctor, update, sync } from "../lib/commands.mjs";
+import { init, doctor, update, sync, audit } from "../lib/commands.mjs";
 
 const HELP = `
 ${c.bold("ozali")} ${c.dim("v" + pkgVersion())} — bootstrap de IA por equipo (TDD/SDD + memoria Engram)
@@ -17,6 +17,7 @@ ${c.bold("Comandos:")}
   doctor    Health-check read-only del proyecto (fuente de verdad, Engram, TDD…).
   update    Actualiza la skill ozali instalada a la versión de este paquete.
   sync      Sincroniza el histórico (docs + Engram) con el repo de conocimiento.
+  audit     Navega/audita la memoria de Engram del proyecto (o general).
 
 ${c.bold("Opciones comunes:")}
   --yes, -y            No interactivo: usa defaults.
@@ -26,9 +27,13 @@ ${c.bold("Opciones comunes:")}
   --knowledge-repo <p> (init) Ruta del repo de conocimiento.
   --no-engram          (init) No usar Engram; arranca en modo docs.
   --no-trust           (init) No marcar el workspace como confiable en Claude Code.
+  --no-jarvis          (init) No crear el orquestador ozali-jarvis.
   --import             (sync) Importa del repo de conocimiento a local.
   --push               (sync) Hace push al remoto del repo de conocimiento.
   --cloud              (sync) Replica también a Engram Cloud (si está habilitado).
+  --general            (audit) Auditoría general (todos los proyectos en Engram).
+  --tui                (audit) Abre el navegador interactivo de Engram.
+  --search <q>         (audit) Busca <q> en la memoria.
   -h, --help           Esta ayuda.    -v, --version   Versión.
 
 ${c.bold("Instalación segura:")}
@@ -48,6 +53,10 @@ function parseArgs(argv) {
     else if (a === "--cloud") opts.cloud = true;
     else if (a === "--no-engram") opts.noEngram = true;
     else if (a === "--no-trust") opts.noTrust = true;
+    else if (a === "--no-jarvis") opts.noJarvis = true;
+    else if (a === "--general") opts.general = true;
+    else if (a === "--tui") opts.tui = true;
+    else if (a === "--search") opts.search = argv[++i];
     else if (a === "--agent") opts.agent = argv[++i];
     else if (a === "--scope") opts.scope = argv[++i];
     else if (a === "--knowledge-repo") opts.knowledgeRepo = argv[++i];
@@ -71,6 +80,7 @@ async function main() {
     case "doctor": return doctor(cwd);
     case "update": return update(cwd);
     case "sync": return sync(cwd, opts);
+    case "audit": return await audit(cwd, opts);
     default:
       err(`comando desconocido "${cmd}". Usa ${c.bold("ozali --help")}.`);
       return 1;

package/cli/lib/commands.mjs

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import {
   c, ok, warn, err, info, step,
-  SKILL_SRC, exists, ensureDir, copyDir, readJSON, writeJSON,
+  SKILL_SRC, TEMPLATES_SRC, exists, ensureDir, copyDir, readJSON, writeJSON,
   ensureGitignore, tryExec, spawnCmd, which,
   projectName, pkgVersion, DEFAULT_KNOWLEDGE, HOME,
 } from "./util.mjs";
@@ -111,6 +111,16 @@ export async function init(cwd, opts) {
     ensureOpencodeProfile(cwd);
   }
 
+  // 2.5) ozali-jarvis: orquestador always-on (memoria Engram + puente a cdk).
+  if (!opts.noJarvis) {
+    const proj = projectName(cwd);
+    // Fija el proyecto para escrituras deterministas de memoria (se deriva igual por cada miembro).
+    writeJSON(path.join(cwd, ".engram", "config.json"), { project_name: proj });
+    ok(`Proyecto de memoria fijado en ${c.bold(".engram/config.json")} (${proj}).`);
+    if (agent === "claude-code" || agent === "both") ensureJarvisClaudeCode(cwd);
+    if (agent === "opencode" || agent === "both") ensureJarvisOpencode(cwd);
+  }
+
   // 3) gitignore del histórico aislado
   if (env.git.isRepo) {
     const { added } = ensureGitignore(cwd, [".ozali/", ".engram/"]);
@@ -286,6 +296,102 @@ function ensureClaudeCodeProfile(cwd, scope) {
   }
 }
 
+// ----------------------------------------------------------------- ozali-jarvis
+const JARVIS_BEGIN = "<!-- ozali-jarvis:start -->";
+const JARVIS_END = "<!-- ozali-jarvis:end -->";
+
+/** Cuerpo del bloque jarvis para CLAUDE.md / AGENTS.md (sin el frontmatter del template). */
+function jarvisPersonaBody() {
+  const tpl = fs.readFileSync(path.join(TEMPLATES_SRC, "ozali-jarvis.md"), "utf8");
+  // Quita el frontmatter YAML (--- ... ---) y deja el cuerpo markdown.
+  return tpl.replace(/^---[\s\S]*?---\s*/, "").trim();
+}
+
+/** Inserta/actualiza un bloque marcado en un archivo markdown (idempotente). */
+function upsertMarkedBlock(file, body) {
+  const block = `${JARVIS_BEGIN}\n${body}\n${JARVIS_END}`;
+  let txt = exists(file) ? fs.readFileSync(file, "utf8") : "";
+  const re = new RegExp(`${JARVIS_BEGIN}[\\s\\S]*?${JARVIS_END}`);
+  let changed;
+  if (re.test(txt)) {
+    const next = txt.replace(re, block);
+    changed = next !== txt; txt = next;
+  } else {
+    txt = (txt.trim() ? txt.replace(/\s*$/, "") + "\n\n" : "") + block + "\n";
+    changed = true;
+  }
+  fs.writeFileSync(file, txt);
+  return changed;
+}
+
+function ensureJarvisClaudeCode(cwd) {
+  // 1) persona en CLAUDE.md (always-on)
+  const claudeMd = path.join(cwd, "CLAUDE.md");
+  const ch = upsertMarkedBlock(claudeMd, jarvisPersonaBody());
+  ok(`ozali-jarvis ${ch ? "escrito" : "ya presente"} en ${c.bold("CLAUDE.md")} (orquestador por defecto).`);
+  // 2) subagente
+  const agentFile = path.join(cwd, ".claude", "agents", "ozali-jarvis.md");
+  ensureDir(path.dirname(agentFile));
+  fs.copyFileSync(path.join(TEMPLATES_SRC, "ozali-jarvis.md"), agentFile);
+  ok(`Subagente ${c.bold(".claude/agents/ozali-jarvis.md")} instalado.`);
+  // 3) hooks de recordatorio (idempotentes)
+  ensureJarvisHooks(cwd);
+}
+
+function ensureJarvisHooks(cwd) {
+  const p = path.join(cwd, ".claude", "settings.json");
+  const cfg = readJSON(p, {});
+  cfg.hooks = cfg.hooks || {};
+  const reminder = (msg) => ({ hooks: [{ type: "command", command: `echo '[ozali-jarvis] ${msg}'` }] });
+  const want = {
+    SessionStart: reminder("recall-first: confirma proyecto (mem_current_project) y recupera contexto de Engram (mem_context) antes de actuar."),
+    PreCompact: reminder("antes de compactar: persiste el state recuperable en Engram (engram-convention §4)."),
+    SessionEnd: reminder("cierre: registra lo trabajado en Engram (scope project, español) y haz mem_session_summary."),
+  };
+  let added = 0;
+  for (const [evt, val] of Object.entries(want)) {
+    const arr = cfg.hooks[evt] || (cfg.hooks[evt] = []);
+    // idempotencia: no duplicar el recordatorio ozali-jarvis para ese evento
+    const has = JSON.stringify(arr).includes("[ozali-jarvis]");
+    if (!has) { arr.push(val); added++; }
+  }
+  writeJSON(p, cfg);
+  if (added) ok(`Hooks de recordatorio de ozali-jarvis añadidos a ${c.bold(".claude/settings.json")} (${added}).`);
+  else info("Hooks de ozali-jarvis ya presentes en Claude Code.");
+}
+
+function ensureJarvisOpencode(cwd) {
+  // 1) persona en AGENTS.md
+  const agentsMd = path.join(cwd, "AGENTS.md");
+  const ch = upsertMarkedBlock(agentsMd, jarvisPersonaBody());
+  ok(`ozali-jarvis ${ch ? "escrito" : "ya presente"} en ${c.bold("AGENTS.md")} (orquestador por defecto).`);
+  // 2) agente en opencode.json
+  const p = path.join(cwd, "opencode.json");
+  const cfg = readJSON(p, {});
+  cfg.$schema = cfg.$schema || "https://opencode.ai/config.json";
+  cfg.agent = cfg.agent || {};
+  if (!cfg.agent["ozali-jarvis"]) {
+    cfg.agent["ozali-jarvis"] = {
+      mode: "primary",
+      description: "Orquestador del proyecto: memoria Engram + puente a la skill cdk.",
+      prompt: "{file:./AGENTS.md}",
+    };
+    writeJSON(p, cfg);
+    ok(`Agente ${c.bold("ozali-jarvis")} (primary) añadido a ${c.bold("opencode.json")}.`);
+  } else {
+    info("Agente ozali-jarvis ya presente en opencode.json.");
+  }
+  // 3) plugin de recordatorio
+  const plugin = path.join(cwd, ".opencode", "plugins", "ozali-jarvis.js");
+  if (!exists(plugin)) {
+    ensureDir(path.dirname(plugin));
+    fs.copyFileSync(path.join(TEMPLATES_SRC, "ozali-jarvis-plugin.js"), plugin);
+    ok(`Plugin ${c.bold(".opencode/plugins/ozali-jarvis.js")} instalado.`);
+  } else {
+    info("Plugin de ozali-jarvis ya presente en opencode.");
+  }
+}
+
 // Marca el proyecto como confiable en Claude Code (~/.claude.json). Sin esto, Claude Code
 // ignora los permisos de un .claude/settings.json de proyecto ("workspace not trusted").
 async function ensureClaudeWorkspaceTrust(cwd, opts) {
@@ -342,6 +448,13 @@ export function doctor(cwd) {
   add("Fuente de verdad", env.sot.found, env.sot.found ? `${env.sot.doc} + ${env.sot.dir}/` : "ausente (corre la skill 'ozali')");
   add("Skill ozali instalada", env.skill.installed, env.skill.installed ? env.skill.paths.map((p) => path.relative(cwd, p) || p).join(", ") : "no instalada (ozali init)");
   add("Engram", env.engram.available, env.engram.available ? env.engram.bin : "no instalado → modo docs");
+  if (env.engram.available) {
+    const online = tryExec("engram", ["doctor"], { cwd }) !== null;
+    add("Engram en línea", online, online ? "engram doctor OK" : "engram doctor no responde");
+  }
+  const jarvis = detectJarvis(cwd);
+  // jarvis es opt-in (--no-jarvis): informativo, no cuenta como fallo.
+  add("ozali-jarvis", true, jarvis.present ? `configurado (${jarvis.where.join(", ")})` : "no configurado (--no-jarvis)");
   const cloudOn = !!(cfg && cfg.cloud && cfg.cloud.enabled);
   // Cloud es opt-in: "off" es un estado válido (no cuenta como fallo).
   add("Engram Cloud", true, cloudOn ? `enrolado → ${cfg.cloud.server || "server por defecto"}` : "off (opt-in, git-sync activo)");
@@ -381,9 +494,31 @@ export function doctor(cwd) {
     }
   }
 
+  // Tendencia de uso de tokens (la escribe cdk en cada hito; informativo).
+  const metrics = readJSON(path.join(cwd, ".ozali", "metrics", "token-metrics.json"));
+  if (metrics && Array.isArray(metrics.hits) && metrics.hits.length) {
+    step("Tendencia de tokens (últimos hitos)");
+    for (const h of metrics.hits.slice(-3)) {
+      const saved = h.savedByRecall ? ` ${c.green("(ahorro recall: " + h.savedByRecall + ")")}` : "";
+      console.log(`  ${c.dim(h.hito || "?")}: total ${h.total ?? "N/A"}${saved}`);
+    }
+  }
+
   return bad === 0 ? 0 : 1;
 }
 
+/** Detecta si ozali-jarvis está configurado en el proyecto y dónde. */
+function detectJarvis(cwd) {
+  const where = [];
+  const hasBlock = (f) => exists(f) && fs.readFileSync(f, "utf8").includes(JARVIS_BEGIN);
+  if (hasBlock(path.join(cwd, "CLAUDE.md"))) where.push("CLAUDE.md");
+  if (hasBlock(path.join(cwd, "AGENTS.md"))) where.push("AGENTS.md");
+  if (exists(path.join(cwd, ".claude", "agents", "ozali-jarvis.md"))) where.push("subagente");
+  const oc = readJSON(path.join(cwd, "opencode.json"));
+  if (oc && oc.agent && oc.agent["ozali-jarvis"]) where.push("opencode");
+  return { present: where.length > 0, where };
+}
+
 function readStrictTdd(cwd, sot) {
   const f = path.join(cwd, sot.dir, "context", "tech-stack.md");
   if (!exists(f)) return { found: false };
@@ -496,3 +631,77 @@ export function sync(cwd, opts) {
   }
   return 0;
 }
+
+// ============================================================ audit ===========
+// Navega/audita la memoria de Engram: del proyecto actual o general (todos los
+// proyectos). Sin contexto de proyecto en la ruta → general. Sin Engram → audita
+// el histórico local de documentos.
+export async function audit(cwd, opts) {
+  step("ozali audit — auditoría de memoria (Engram)");
+  const env = detectAll(cwd);
+  const cfg = readJSON(CONFIG_PATH(cwd));
+  const engramCfg = readJSON(path.join(cwd, ".engram", "config.json"));
+  const project = (engramCfg && engramCfg.project_name) || (cfg && cfg.project) || projectName(cwd);
+  const hasProjectContext = env.git.isRepo || !!cfg || !!engramCfg;
+
+  // Resolver alcance: --general fuerza general; sin contexto → general; en repo se propone elegir.
+  let scope = (opts.general || !hasProjectContext) ? "general" : "project";
+  if (!hasProjectContext) info("Sin contexto de proyecto en esta ruta → auditoría " + c.bold("general") + ".");
+  else if (scope === "project" && !opts.general && !opts.yes) {
+    scope = await select("¿Qué auditoría quieres?", [
+      { value: "project", label: `Proyecto (${c.bold(project)})` },
+      { value: "general", label: "General (todos los proyectos en Engram)" },
+    ], 0);
+  }
+
+  // Sin Engram → auditar el histórico local de documentos.
+  if (!env.engram.available) {
+    warn("Engram no está instalado → auditoría desde documentos locales.");
+    return auditFromDocs(cwd, project);
+  }
+
+  // Navegador interactivo.
+  if (opts.tui) {
+    info("Abriendo el navegador interactivo de Engram (engram tui)…");
+    return spawnCmd("engram", ["tui"], { cwd });
+  }
+
+  if (scope === "general") {
+    step("Proyectos en Engram");
+    spawnCmd("engram", ["projects", "list"], { cwd });
+    step("Estadísticas (global)");
+    spawnCmd("engram", ["stats"], { cwd });
+    step("Contexto reciente");
+    spawnCmd("engram", ["context"], { cwd });
+  } else {
+    step(`Contexto reciente — ${project}`);
+    spawnCmd("engram", ["context", project], { cwd });
+    step("Estadísticas (global)");
+    spawnCmd("engram", ["stats"], { cwd });
+  }
+  if (opts.search) {
+    step(`Búsqueda: "${opts.search}"`);
+    spawnCmd("engram", ["search", opts.search], { cwd });
+  }
+  info("Navegación interactiva: " + c.bold("ozali audit --tui") + "  ·  búsqueda: " + c.bold('ozali audit --search "<texto>"'));
+  return 0;
+}
+
+function auditFromDocs(cwd, project) {
+  const docsDir = path.join(cwd, ".ozali", "docs", "cdk");
+  if (exists(docsDir)) {
+    step(`Hitos documentados localmente — ${project}`);
+    const hitos = fs.readdirSync(docsDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    if (hitos.length) for (const e of hitos) console.log("  • " + e.name);
+    else info("Aún no hay hitos en .ozali/docs/cdk/.");
+  } else {
+    info("No hay histórico local en .ozali/docs/cdk/ todavía.");
+  }
+  const metrics = readJSON(path.join(cwd, ".ozali", "metrics", "token-metrics.json"));
+  if (metrics && Array.isArray(metrics.hits) && metrics.hits.length) {
+    step("Uso de tokens (últimos hitos)");
+    for (const h of metrics.hits.slice(-5)) console.log(`  ${c.dim(h.hito || "?")}: total ${h.total ?? "N/A"}`);
+  }
+  info("Instala Engram para auditoría buscable/acumulativa (" + c.bold("ozali doctor") + ").");
+  return 0;
+}

package/cli/lib/util.mjs

@@ -10,6 +10,7 @@ import { execFileSync } from "node:child_process";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const PKG_ROOT = path.resolve(HERE, "..", "..");
 export const SKILL_SRC = path.join(PKG_ROOT, "skill");
+export const TEMPLATES_SRC = path.join(PKG_ROOT, "templates");
 
 export function pkgVersion() {
   try {

package/cli/test/smoke.test.mjs

@@ -33,9 +33,20 @@ test("--version imprime la versión del package.json", () => {
   assert.equal(stdout.trim(), pkg.version);
 });
 
-test("--help menciona los 4 comandos", () => {
+test("--help menciona los comandos", () => {
   const { stdout } = run(["--help"]);
-  for (const cmd of ["init", "doctor", "update", "sync"]) assert.match(stdout, new RegExp(cmd));
+  for (const cmd of ["init", "doctor", "update", "sync", "audit"]) assert.match(stdout, new RegExp(cmd));
+});
+
+test("audit imprime cabecera y no rompe (general)", () => {
+  const dir = tmpProject();
+  try {
+    // Sin Engram → fallback a docs; con Engram → comandos read-only. Ambos exit 0.
+    const { stdout } = run(["audit", "--general", "--yes"], dir);
+    assert.match(stdout, /auditoría de memoria/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
 });
 
 test("comando desconocido sale con código 1", () => {
@@ -71,6 +82,37 @@ test("init --yes instala la skill, aísla el histórico y escribe config", () =>
     const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
     assert.ok(Array.isArray(settings.permissions.allow) && settings.permissions.allow.length > 0, "allow no vacío");
     assert.ok(settings.permissions.deny.includes("Bash(rm -rf *)"), "deny bloquea rm -rf");
+    // ozali-jarvis (Claude Code)
+    assert.match(fs.readFileSync(path.join(dir, "CLAUDE.md"), "utf8"), /ozali-jarvis:start/, "bloque jarvis en CLAUDE.md");
+    assert.ok(fs.existsSync(path.join(dir, ".claude", "agents", "ozali-jarvis.md")), "subagente jarvis");
+    assert.ok(settings.hooks && settings.hooks.SessionStart, "hooks de recordatorio jarvis");
+    const eng = JSON.parse(fs.readFileSync(path.join(dir, ".engram", "config.json"), "utf8"));
+    assert.ok(eng.project_name, ".engram/config.json con project_name");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("init --no-jarvis no crea el orquestador", () => {
+  const dir = tmpProject();
+  try {
+    run(["init", "--yes", "--no-engram", "--no-trust", "--no-jarvis", "--agent", "claude-code", "--scope", "project", "--knowledge-repo", path.join(dir, ".k")], dir);
+    assert.ok(!fs.existsSync(path.join(dir, "CLAUDE.md")), "sin CLAUDE.md");
+    assert.ok(!fs.existsSync(path.join(dir, ".claude", "agents", "ozali-jarvis.md")), "sin subagente jarvis");
+    assert.ok(!fs.existsSync(path.join(dir, ".engram", "config.json")), "sin .engram/config.json");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("init opencode crea jarvis (AGENTS.md + agente + plugin)", () => {
+  const dir = tmpProject();
+  try {
+    run(["init", "--yes", "--no-engram", "--no-trust", "--agent", "opencode", "--scope", "project", "--knowledge-repo", path.join(dir, ".k")], dir);
+    assert.match(fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /ozali-jarvis:start/, "bloque jarvis en AGENTS.md");
+    const oc = JSON.parse(fs.readFileSync(path.join(dir, "opencode.json"), "utf8"));
+    assert.equal(oc.agent["ozali-jarvis"].mode, "primary", "agente jarvis primary en opencode.json");
+    assert.ok(fs.existsSync(path.join(dir, ".opencode", "plugins", "ozali-jarvis.js")), "plugin jarvis opencode");
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }

package/docs/guia-de-uso.md

@@ -85,6 +85,7 @@ Lleva el histórico y la memoria al repo de conocimiento del equipo. Tus compañ
 | `ozali update` | Actualiza la skill a la última versión. |
 | `ozali sync` | Sube el histórico/memoria al repo de equipo. |
 | `ozali sync --import` | Baja lo que el equipo ya guardó. |
+| `ozali audit` | Navega/audita la memoria de Engram (qué se ha hecho). |
 
 ¿Algo no funciona? Corre **`ozali doctor`** primero: te dice qué falta y cómo arreglarlo.
 
@@ -119,6 +120,23 @@ Ejemplo — permitir Docker además de lo de fábrica:
 
 ---
 
+## ozali-jarvis: el orquestador (no necesitas /cdk)
+
+`init` crea **ozali-jarvis**, el "cerebro" por defecto de tu proyecto. A partir de ahí, **en cada
+sesión y sin escribir `/cdk`**, tu agente:
+
+- **recuerda** lo que el equipo trabajó antes (recupera contexto de Engram al iniciar),
+- **registra** lo que van haciendo (decisiones, acciones, aprendizajes) para que quede acumulado,
+- y cuando toca **escribir código con disciplina**, delega en la skill `cdk` (plan, aprobación, TDD).
+
+Sigues pudiendo invocar `/cdk` cuando quieras; jarvis simplemente lo usa como referencia y mantiene
+todo en contexto. ¿No lo quieres? `init --no-jarvis`.
+
+### Menos tokens, más contexto
+Con Engram en línea, jarvis y `cdk` trabajan **recall-first**: antes de releer archivos o re-analizar,
+reutilizan el análisis/resumen que ya está en memoria (si el código no cambió). Eso gasta **menos
+tokens** y mantiene el contexto enfocado. Puedes ver la tendencia de consumo con `ozali doctor`.
+
 ## Engram: la memoria del equipo (opcional)
 
 Durante `init`, ozali **instala Engram por ti**: en modo interactivo te pregunta (basta con aceptar),
@@ -142,6 +160,17 @@ Más detalle técnico en [engram-convention.md](../skill/references/engram-conve
 
 ---
 
+## Auditar lo que se ha hecho (`ozali audit`)
+
+¿Quieres ver qué ha registrado el equipo? `ozali audit`:
+
+- **Dentro de un repo:** te propone auditar **ese proyecto** o **todos** (general).
+- **Fuera de un repo** (una ruta cualquiera): va directo a la auditoría **general**.
+
+Atajos: `ozali audit --tui` abre un navegador interactivo de la memoria; `ozali audit --search "rfc"`
+busca un término; `ozali audit --general` fuerza el alcance general. Si no tienes Engram, audita el
+histórico local de `.ozali/docs/`.
+
 ## Preguntas frecuentes
 
 **¿Tengo que usar Engram?**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ozali",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Bootstrap interactivo de IA por equipo: calibra el proyecto, genera la skill de ejecución (cdk) con TDD/SDD, y mantiene memoria de equipo (Engram) con histórico aislado.",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
   "files": [
     "cli/",
     "skill/",
+    "templates/",
     "docs/",
     "README.md",
     "LICENSE"

package/skill/SKILL.md

@@ -308,12 +308,25 @@ recuperable, acumulativo). Así la herramienta **aprende de lo que el equipo va
 completo (naming, llamadas inline, degradación) en
 [`references/engram-convention.md`](references/engram-convention.md).
 
+> **Orquestador por defecto (`ozali-jarvis`):** `ozali init` crea el agente **ozali-jarvis**
+> (persona en CLAUDE.md/AGENTS.md + subagente + hooks) que opera **memoria-aware en toda sesión, sin
+> necesidad de `/cdk`**: recupera contexto de Engram al iniciar, registra el trabajo del equipo
+> conforme avanza, y **delega la ejecución disciplinada en `cdk`**. `cdk` y jarvis comparten el mismo
+> contrato de memoria (esta convención).
+
 **Mínimos que `cdk` debe cablear** (resumen; el detalle y los `mem_*` exactos están en la convención):
 
-- **Al iniciar un hito** → `mem_save_prompt` (captura el prompt real una vez) + `mem_search` de
-  `cdk/{hito}/state`, `cdk/_project/testing-capabilities` y `cdk/{hito}/*` → `mem_get_observation`
-  de lo relevante. Si hay `state` con pendientes, **reanuda**; con `testing-capabilities` resuelve
-  el modo TDD.
+- **Al iniciar un hito** → handshake "Engram en línea" (`mem_current_project` + `mem_context`) +
+  `mem_save_prompt` (captura el prompt real una vez) + `mem_search` de `cdk/{hito}/state`,
+  `cdk/_project/testing-capabilities`, `cdk/_project/token-metrics` y `cdk/{hito}/*` →
+  `mem_get_observation` **selectivo** de lo relevante. Si hay `state` con pendientes, **reanuda**; con
+  `testing-capabilities` resuelve el modo TDD.
+- **Recall-first (ahorro de tokens/contexto)** → antes de releer/re-analizar, reusar el
+  `analisis`/`resumen-tecnico` previo si su `ultimo_commit` sigue vigente (guard de staleness); si el
+  código cambió, re-analizar solo el delta. Recuperación selectiva y restauración tras compactación
+  desde `state`+`bitacora`. Ver convención §7.
+- **Telemetría** → espejar `uso-tokens` a `cdk/{hito}/uso-tokens`, agregar en
+  `cdk/_project/token-metrics` y escribir `.ozali/metrics/token-metrics.json` (lo lee `ozali doctor`).
 - **Al aprobar el GATE** → `mem_save` de `cdk/{hito}/plan-aprobado` **una sola vez** (inmutable).
 - **Durante el ciclo** → `mem_update` (upsert) de `cdk/{hito}/bitacora` y `cdk/{hito}/state` tras
   cada transición de fase (el archivo `05` sigue siendo append-only como fuente de verdad).

package/skill/references/agents-blueprint.md

@@ -55,13 +55,15 @@ Para cada subagente, `cdk` debe generar un `.claude/agents/<rol>.md` con frontma
 ### 3. project-analyzer
 - **Misión:** entender el código existente y el impacto del cambio. *No se planea lo que
   no se ha entendido: primero el terreno, después el plano.*
-- **Responsabilidades:** **primero, SIEMPRE**, ejecuta el harness
-  `node .claude/skills/cdk/verify-structure.mjs --grep <palabra-clave>` — su salida es la
-  **base factual** del análisis (estructura real, clases clave, discrepancias doc↔código,
-  candidatos a **reutilización antes de crear**). Luego mapea dependencias, identifica
-  **hitos de importancia** y riesgos, superficies afectadas y contratos en riesgo. Marca
-  los riesgos **🔴 BLOQUEANTES** que detienen el flujo hasta resolverse. Es el autor del
-  **Documento 1 (análisis)**.
+- **Responsabilidades:** **recall antes de recomputar** — primero `mem_search` del `analisis`/
+  `resumen-tecnico` previo del área; si existe con `ultimo_commit` vigente, **reúsalo** (vía
+  `mem_get_observation` selectivo) en vez de releer archivos grandes; si el código cambió, analiza
+  **solo el delta** (convención §7). Ejecuta **siempre** el harness
+  `node .claude/skills/cdk/verify-structure.mjs --grep <palabra-clave>` (estructural, barato) como
+  **base factual** (estructura real, clases clave, discrepancias doc↔código, candidatos a
+  **reutilización antes de crear**). Luego mapea dependencias, identifica **hitos de importancia** y
+  riesgos, superficies afectadas y contratos en riesgo. Marca los riesgos **🔴 BLOQUEANTES** que
+  detienen el flujo hasta resolverse. Es el autor del **Documento 1 (análisis)**.
 - **Entrada:** tarea. **Salida:** informe de impacto + hitos (+ preguntas abiertas al usuario).
 - **Herramientas:** solo lectura (Read, Grep, Glob) + ejecución del harness (Bash/PowerShell
   acotado a `node verify-structure.mjs`).
@@ -70,7 +72,10 @@ Para cada subagente, `cdk` debe generar un `.claude/agents/<rol>.md` con frontma
 - **Misión:** enrutar el trabajo entre subagentes e integrar resultados.
 - **Responsabilidades:** decide qué subagente actúa y en qué orden; gestiona iteraciones
   executioners ⇄ tester; consolida la salida final. **Alimenta al `project-documenter`** con
-  los eventos del ciclo (dudas, decisiones, desvíos) para la bitácora `05`.
+  los eventos del ciclo (dudas, decisiones, desvíos) para la bitácora `05`. **Hace cumplir el
+  recall-first** (convención §7): recuperación selectiva (no volcar toda la memoria), restauración
+  desde `state`+`bitacora` tras compactación, y consulta `cdk/_project/token-metrics` al iniciar para
+  ajustar la agresividad del recall.
 - **Modo `--auto`:** si el hito se invocó con `--auto`, recorre el hito de punta a punta
   **sin prompts** —incluida la **lectura de rutas no contempladas** durante el análisis y la
   ejecución post-GATE— con el **único alto en el 🛑 GATE del plan**. Si algo cae **fuera de
@@ -117,6 +122,8 @@ Para cada subagente, `cdk` debe generar un `.claude/agents/<rol>.md` con frontma
   - `03-resumen-tecnico.md`, `04-resumen-usuario.md` y `06-uso-tokens.md` se escriben **al
     cierre**. El `06` solo rellena métricas si el proveedor es **Claude/Anthropic** (fuente
     `/cost`); con otro proveedor deja la estructura + nombre del proveedor y métricas `N/A`.
+    Además **espeja** `06` a Engram (`cdk/{hito}/uso-tokens`), actualiza el agregado
+    `cdk/_project/token-metrics` y escribe `.ozali/metrics/token-metrics.json` (lo lee `ozali doctor`).
 - **Herramientas:** escritura de documentación (Read, Write).
 
 ### 8. tester

package/skill/references/doc-templates.md

@@ -291,6 +291,13 @@ usuario, en:
 | Total de tiempo de sesión   | <n / N/A> |
 | Costo estimado              | <$ / N/A> |
 
+## Ahorro por recall (Engram)
+| Métrica | Valor |
+| :-- | :-- |
+| ¿Se reusó memoria? (recall-first) | sí / no |
+| Artefactos reusados | <p. ej. cdk/<hito>/analisis @ <commit>> |
+| Relectura evitada (estimada) | <n tokens / N/A> |
+
 ## Notas
 - <observaciones sobre el consumo del hito; deja vacío o "N/A" si no puedes encontrar información del proveedor>
 ```
@@ -299,3 +306,23 @@ usuario, en:
 > derivar ni inventar cifras de otro sistema: solo registra el nombre del proveedor y deja
 > el resto en `N/A`. El objetivo es **mantener la estructura presente** para no perder la
 > trazabilidad del hito.
+
+### Espejo en Engram + agregado (telemetría)
+
+Al cerrar, además del doc, `cdk` **espeja** las métricas a Engram y mantiene un agregado por
+proyecto (ver [`engram-convention.md`](engram-convention.md) §7):
+
+- `cdk/{hito}/uso-tokens` — métricas del hito (mismo contenido que el doc).
+- `cdk/_project/token-metrics` — agregado de los últimos hitos (para ajustar el recall-first).
+- `.ozali/metrics/token-metrics.json` — copia **local** que lee `ozali doctor` para la tendencia:
+
+```json
+{
+  "hits": [
+    { "hito": "<slug>", "input": 0, "output": 0, "total": 0, "savedByRecall": 0, "at": "<ISO-8601>" }
+  ]
+}
+```
+
+> `savedByRecall` = estimación de tokens de relectura evitados por reusar memoria. Con proveedor sin
+> métricas, deja `0`/`N/A` pero mantén la estructura.

package/skill/references/engram-convention.md

@@ -222,3 +222,50 @@ Internamente (Fase C lo implementa):
 
 > Trazabilidad: cada doc lleva `ultimo_commit`/`Commit:` del repo principal en su encabezado, así
 > el histórico aislado siempre apunta al código exacto que documenta.
+
+---
+
+## 7. Rendimiento: recall-first + telemetría de tokens
+
+El objetivo de esta sección es **gastar menos tokens y contexto** reutilizando lo que el equipo ya
+guardó en Engram, en vez de recomputarlo. Aplica tanto al uso **ambiental** (orquestador
+`ozali-jarvis`, sin `/cdk`) como por **hito** (`cdk`).
+
+### 7.1 Handshake "Engram en línea"
+Al iniciar sesión/hito: `mem_current_project` (confirma que coincide con `.engram/config.json`) +
+`mem_context`. Si responde → **modo recall-first activo**. Si no responde → degrada a `docs` (§1);
+la ausencia de Engram nunca bloquea.
+
+### 7.2 Recall-first con guard de staleness
+**Antes** de releer archivos o re-analizar, `mem_search` del `analisis` / `plan-aprobado` /
+`resumen-tecnico` del área. Cada artefacto lleva `ultimo_commit` (§6):
+
+- Si el **SHA actual coincide** (o los archivos del área no cambiaron) → **reusar** el resumen
+  conciso vía `mem_get_observation`, **sin releer el código**. Ahorra tokens de entrada.
+- Si **cambió** → re-analizar **solo el delta** (los archivos tocados desde `ultimo_commit`), no todo.
+
+> El harness `verify-structure.mjs` (estructural, barato) puede seguir corriendo; lo que se evita es
+> **releer archivos grandes** que ya tienen un resumen vigente en memoria.
+
+### 7.3 Recuperación selectiva
+`mem_search` devuelve **previews truncados**. Haz `mem_get_observation` **solo** de los pocos
+artefactos que realmente necesitas. **Nunca** vuelques toda la memoria al contexto.
+
+### 7.4 Restauración tras compactación
+Tras una compactación (o reabrir sesión), reconstruye desde `state` (§4) + `bitacora` —ambos
+concisos— en vez de re-derivar todo el contexto releyendo conversación y archivos.
+
+### 7.5 Guardar conciso para recall barato
+Guarda resúmenes **estructurados y deduplicados** (no volcados crudos). Mientras más conciso el
+artefacto, menos cuesta recuperarlo después.
+
+### 7.6 Telemetría de tokens (medir → mejorar)
+- Espeja el uso de tokens del hito a `cdk/{hito}/uso-tokens` y mantén un agregado por proyecto en
+  `cdk/_project/token-metrics`.
+- También escribe un resumen **local** en `.ozali/metrics/token-metrics.json` (últimos N hitos:
+  `{ hito, input, output, total, savedByRecall, at }`) para que `ozali doctor` muestre la tendencia
+  sin consultar el MCP.
+- **Al iniciar**, recupera `cdk/_project/token-metrics`: si hitos similares fueron pesados, sé más
+  agresivo con recall-first (resume antes, evita relecturas grandes).
+
+> `savedByRecall` = estimación de relectura evitada por reusar memoria (ver plantilla `06-uso-tokens`).

package/templates/ozali-jarvis-plugin.js

@@ -0,0 +1,27 @@
+// ozali-jarvis-plugin — recordatorios de memoria (Engram) para opencode.
+// Generado por `ozali init`. NO es la fuente de verdad del comportamiento:
+// la persona ozali-jarvis vive en AGENTS.md + el agente de opencode.json.
+// Este plugin solo refuerza, en eventos de sesión, el ciclo recall → capturar → resumir.
+// Marca de idempotencia: ozali-jarvis (no reescribir si ya existe esta marca).
+
+/** @type {import("@opencode-ai/plugin").Plugin} */
+export const OzaliJarvis = async () => {
+  const note = (m) => { try { console.log(`[ozali-jarvis] ${m}`); } catch { /* noop */ } };
+  return {
+    event: async ({ event }) => {
+      switch (event && event.type) {
+        case "session.created":
+          note("recall-first: confirma proyecto (mem_current_project) y recupera contexto de Engram (mem_context) antes de actuar.");
+          break;
+        case "experimental.session.compacting":
+          note("antes de compactar: persiste el `state` recuperable en Engram (ver engram-convention §4).");
+          break;
+        case "session.idle":
+          note("cierre: registra lo trabajado en Engram (scope: project, español) y haz mem_session_summary.");
+          break;
+        default:
+          break;
+      }
+    },
+  };
+};

package/templates/ozali-jarvis.md

@@ -0,0 +1,45 @@
+---
+name: ozali-jarvis
+description: Orquestador principal del proyecto. Memoria-aware por defecto (Engram) y puente hacia la skill cdk. Úsalo/actúa como jarvis para CUALQUIER trabajo en el repo — recupera contexto del equipo antes de actuar, registra decisiones y aprendizajes conforme avanzas (aunque no se invoque /cdk), y delega la ejecución disciplinada de código en cdk.
+---
+
+# ozali-jarvis — orquestador del proyecto
+
+Eres **ozali-jarvis**, el orquestador por defecto de este repositorio. Tu trabajo es mantener al
+equipo **en contexto** usando la memoria de Engram y delegar la ejecución de código a la skill
+`cdk`. Operas así en **toda** sesión, sin necesidad de que el usuario escriba `/cdk`.
+
+> Engram ya inyecta su **Memory Protocol** en la superficie de instrucciones (vía `engram setup`).
+> Esta persona lo **complementa**: no dupliques sus reglas; añade la orquestación y el wiring a `cdk`.
+
+## 1. Al iniciar (recall-first)
+- Confirma el proyecto con `mem_current_project` (debe coincidir con `.engram/config.json`).
+- Recupera contexto reciente del equipo: `mem_context` + `mem_search` de lo relacionado a la tarea.
+- **Recuperación selectiva:** `mem_search` devuelve previews truncados; haz `mem_get_observation`
+  **solo** de lo que necesitas. Nunca vuelques toda la memoria al contexto.
+- **No recomputes lo ya sabido:** si existe un `analisis`/`resumen-tecnico`/`plan-aprobado` del área
+  con `ultimo_commit` vigente, reúsalo en vez de releer el código (ver
+  `references/engram-convention.md` §7, *recall-first con guard de staleness*).
+
+## 2. Durante el trabajo (captura ambiental, en español, scope: project)
+- Registra en Engram las **decisiones, acciones y aprendizajes** del equipo conforme ocurren —
+  **aunque no se haya invocado `/cdk`**. Así el trabajo queda acumulado y buscable.
+- Guarda **conciso y estructurado** (no volcados crudos) para que el recall futuro cueste menos.
+- Idioma y scope según `references/engram-convention.md` §1.5: memoria compartida en **español**,
+  `scope: project`; lo puramente personal va en `scope: personal`.
+
+## 3. Para ejecutar cambios de código → delega en `cdk`
+- Cuando el trabajo implique escribir/modificar código con disciplina (plan, GATE, TDD, docs por
+  hito), **usa la skill `cdk`**. jarvis prepara el contexto; `cdk` ejecuta.
+- Si `cdk` aún no existe en el proyecto, sugiere generarla corriendo la skill **`ozali`**
+  ("diagnostica el proyecto").
+
+## 4. Al cerrar
+- Cierra la sesión con `mem_session_summary` (solo el agente top-level, nunca un subagente) — qué se
+  logró, decisiones clave y pendientes.
+- Antes de una compactación de contexto, persiste el `state` recuperable (ver convención §4).
+
+## Reglas duras
+- La memoria **nunca bloquea**: si Engram no responde, sigue en modo `docs` y anótalo.
+- **Persistir antes de responder** cuando guardes en Engram dentro de un subagente.
+- No inventes contenido de memoria; si no hay contexto, no fabriques.