ozali 0.1.0 → 0.3.0

package/README.md

@@ -46,18 +46,38 @@ npx --ignore-scripts ozali@<versión> init
 git clone <repo> && node ozali/cli/bin/ozali.mjs init
 ```
 
+> **`dlx`/`npx` son efímeros:** ejecutan `init` pero **no dejan `ozali` en tu PATH**. Para usar
+> `ozali doctor`/`update`/`sync` después, instala globalmente (el propio `init` te lo recuerda):
+>
+> ```bash
+> pnpm add -g ozali@<versión>      # recomendado
+> npm install -g ozali@<versión>
+> ```
+
 ### Uso del CLI
 
 ```bash
-ozali init      # detecta agente, instala la skill, aísla el histórico, configura Engram
-ozali doctor    # health-check read-only (fuente de verdad, Engram, Strict TDD, runner…)
+ozali init      # detecta agente, instala la skill, aísla el histórico, instala+configura Engram
+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
 ```
 
-Flags útiles: `--yes` (no interactivo), `--dry-run` (init sin escribir), `--agent`, `--scope`,
-`--knowledge-repo`, `--import`/`--push` (sync). Modelo mental completo en
-[docs/intended-usage.md](docs/intended-usage.md).
+`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
+**ignora** los permisos de un proyecto hasta confiar en él, `init` ofrece marcar el workspace como
+confiable (`hasTrustDialogAccepted` en `~/.claude.json`); usa `--no-trust` para omitirlo.
+
+`init` también **instala Engram** y registra su MCP con `engram setup <agente>`: en modo
+interactivo te pregunta (default sí), y con `--yes` lo instala automáticamente. Usa brew en
+macOS/Linux, `go install` en Windows, con binario precompilado como fallback. Si prefieres no
+instalarlo, pasa `--no-engram` (arranca en modo `docs`). Opcionalmente habilita **Engram Cloud**
+(réplica de equipo opt-in) además del git-sync.
+
+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).
 
 ## Agentes soportados
 
@@ -68,6 +88,7 @@ Claude Code y opencode (perfiles de permisos para ambos en
 
 | Tema | Doc |
 |---|---|
+| Guía de uso (usuarios generales) | [docs/guia-de-uso.md](docs/guia-de-uso.md) |
 | Uso previsto (modelo mental) | [docs/intended-usage.md](docs/intended-usage.md) |
 | Seguridad del instalador (npx/pnpm) | [docs/security.md](docs/security.md) |
 | Histórico aislado y memoria de equipo | [docs/team-history.md](docs/team-history.md) |

package/cli/bin/ozali.mjs

@@ -24,8 +24,11 @@ ${c.bold("Opciones comunes:")}
   --agent <a>          (init) claude-code | opencode | both.
   --scope <s>          (init) project | global.
   --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.
   --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).
   -h, --help           Esta ayuda.    -v, --version   Versión.
 
 ${c.bold("Instalación segura:")}
@@ -42,6 +45,9 @@ function parseArgs(argv) {
     else if (a === "--dry-run") opts.dryRun = true;
     else if (a === "--import") opts.import = true;
     else if (a === "--push") opts.push = true;
+    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 === "--agent") opts.agent = argv[++i];
     else if (a === "--scope") opts.scope = argv[++i];
     else if (a === "--knowledge-repo") opts.knowledgeRepo = argv[++i];

package/cli/lib/commands.mjs

@@ -4,7 +4,8 @@ import path from "node:path";
 import {
   c, ok, warn, err, info, step,
   SKILL_SRC, exists, ensureDir, copyDir, readJSON, writeJSON,
-  ensureGitignore, tryExec, projectName, pkgVersion, DEFAULT_KNOWLEDGE,
+  ensureGitignore, tryExec, spawnCmd, which,
+  projectName, pkgVersion, DEFAULT_KNOWLEDGE, HOME,
 } from "./util.mjs";
 import { detectAll } from "./detect.mjs";
 import { ask, confirm, select } from "./prompt.mjs";
@@ -47,14 +48,47 @@ export async function init(cwd, opts) {
   const knowledgeRepo = opts.knowledgeRepo || await ask("Ruta del repo de conocimiento (histórico aislado)", DEFAULT_KNOWLEDGE);
 
   // Engram
-  let memoryMode = "hybrid";
-  if (env.engram.available) {
+  let memoryMode = "docs";
+  if (opts.noEngram) {
+    info("--no-engram: arranco en modo " + c.bold("docs") + " (sin usar Engram).");
+  } else if (env.engram.available) {
+    memoryMode = "hybrid";
     ok(`Engram disponible (${env.engram.bin}). Modo de memoria: ${c.bold("hybrid")} (docs + Engram).`);
   } else {
-    memoryMode = "docs";
-    warn("Engram no está instalado. Arrancamos en modo " + c.bold("docs") + " (solo documentos legibles).");
-    info("Para activar memoria buscable/acumulativa instala Engram: " + c.cyan("https://github.com/Gentleman-Programming/engram"));
-    info("Tras instalarlo, vuelve a correr " + c.bold("ozali doctor") + " — el modo subirá a hybrid automáticamente.");
+    warn("Engram no está instalado.");
+    // --dry-run no instala; --yes usa el default (sí); interactivo pregunta.
+    if (opts.dryRun) info("(dry-run) Aquí instalaría y configuraría Engram.");
+    const installNow = opts.dryRun ? false
+      : (opts.yes ? true : await confirm("¿Instalo y configuro Engram ahora?", true));
+    if (installNow) {
+      if (opts.yes) info("Modo no interactivo: instalando Engram automáticamente…");
+      const installed = installEngram();
+      if (installed) {
+        if (agent === "claude-code" || agent === "both") {
+          info("Registrando MCP en Claude Code…");
+          spawnCmd("engram", ["setup", "claude-code"]);
+        }
+        if (agent === "opencode" || agent === "both") {
+          info("Registrando MCP en opencode…");
+          spawnCmd("engram", ["setup", "opencode"]);
+        }
+        memoryMode = "hybrid";
+        ok("Engram listo. Modo de memoria: " + c.bold("hybrid") + ".");
+        info("Reinicia tu agente para que cargue el servidor MCP de Engram.");
+      } else {
+        warn("Instalación no completada. Continúo en modo " + c.bold("docs") + ".");
+        printEngramManualInstructions(agent);
+      }
+    } else {
+      info("Modo " + c.bold("docs") + " activo. Cuando instales Engram, corre " + c.bold("ozali doctor") + " para activar hybrid.");
+      printEngramManualInstructions(agent);
+    }
+  }
+
+  // Engram Cloud (opt-in) — réplica de equipo además del git-sync. Solo si Engram quedó disponible.
+  let cloud = { enabled: false };
+  if (memoryMode === "hybrid" && !opts.dryRun) {
+    cloud = await maybeEnableEngramCloud(projectName(cwd), opts);
   }
 
   if (opts.dryRun) { warn("--dry-run: no escribo nada. Plan mostrado arriba."); return 0; }
@@ -67,7 +101,12 @@ export async function init(cwd, opts) {
   copyDir(SKILL_SRC, target);
   ok(`Skill instalada en ${c.bold(path.relative(cwd, target) || target)}.`);
 
-  // 2) opencode: perfil base de permisos (idempotente, merge mínimo)
+  // 2) perfiles base de permisos (idempotentes, merge mínimo) por agente
+  if (agent === "claude-code" || agent === "both") {
+    ensureClaudeCodeProfile(cwd, scope);
+    // Claude Code ignora los permisos de un .claude/settings.json de proyecto hasta confiar en él.
+    if (scope === "project" && !opts.noTrust) await ensureClaudeWorkspaceTrust(cwd, opts);
+  }
   if (agent === "opencode" || agent === "both") {
     ensureOpencodeProfile(cwd);
   }
@@ -92,7 +131,7 @@ export async function init(cwd, opts) {
 
   // 5) config local (gitignored)
   const config = {
-    version: pkgVersion(), agent, scope, knowledgeRepo, memoryMode,
+    version: pkgVersion(), agent, scope, knowledgeRepo, memoryMode, cloud,
     project: projectName(cwd), createdAt: new Date().toISOString(),
   };
   writeJSON(CONFIG_PATH(cwd), config);
@@ -100,6 +139,15 @@ export async function init(cwd, opts) {
 
   // --- siguientes pasos ---
   step("Siguientes pasos");
+  // Detect if ozali is NOT permanently in PATH (i.e., run via pnpm dlx / npx without global install).
+  if (!which("ozali")) {
+    const v = pkgVersion();
+    warn("ozali no está en tu PATH — fue ejecutado via dlx/npx sin instalación permanente.");
+    info(`Instala globalmente para usar ${c.bold("ozali doctor")}, ${c.bold("ozali sync")}, etc.:`);
+    console.log(`    ${c.bold(`pnpm add -g ozali@${v}`)}   ${c.dim("← recomendado")}`);
+    console.log(`    ${c.dim("o")}  ${c.bold(`npm install -g ozali@${v}`)}`);
+    console.log("");
+  }
   console.log(`  1. Abre tu agente en este proyecto.`);
   console.log(`  2. Escribe ${c.bold('"diagnostica el proyecto"')} o ${c.bold('"ozali"')} para arrancar el bootstrap (calibración + generación de la skill ${c.bold("cdk")}).`);
   console.log(`  3. Tras trabajar, corre ${c.bold("ozali sync")} para llevar el histórico al repo de conocimiento.`);
@@ -107,6 +155,165 @@ export async function init(cwd, opts) {
   return 0;
 }
 
+/**
+ * Instala Engram con la mejor ruta disponible para el SO actual.
+ * macOS/Linux: Homebrew (recomendado) o Go install como fallback.
+ * Windows: Go install (recomendado) o binario manual.
+ * Devuelve true si el binario quedó disponible en PATH.
+ */
+function installEngram() {
+  const plat = process.platform;
+
+  if (plat === "darwin" || plat === "linux") {
+    if (which("brew")) {
+      info("Instalando: " + c.bold("brew install gentleman-programming/tap/engram"));
+      spawnCmd("brew", ["install", "gentleman-programming/tap/engram"]);
+    } else if (which("go")) {
+      info("Homebrew no encontrado — instalando con Go:");
+      info("  " + c.bold("go install github.com/Gentleman-Programming/engram/cmd/engram@latest"));
+      spawnCmd("go", ["install", "github.com/Gentleman-Programming/engram/cmd/engram@latest"]);
+    } else {
+      warn("No se encontró Homebrew ni Go. Opciones de instalación:");
+      info("  a) Homebrew " + c.dim("(recomendado)") + ": " + c.cyan("https://brew.sh") + " → " + c.bold("brew install gentleman-programming/tap/engram"));
+      info("  b) Binario precompilado: " + c.cyan("https://github.com/Gentleman-Programming/engram/releases"));
+      return false;
+    }
+  } else if (plat === "win32") {
+    if (which("go")) {
+      info("Instalando: " + c.bold("go install github.com/Gentleman-Programming/engram/cmd/engram@latest"));
+      spawnCmd("go", ["install", "github.com/Gentleman-Programming/engram/cmd/engram@latest"]);
+    } else {
+      warn("Go no encontrado. Opciones de instalación en Windows:");
+      info("  a) Go 1.24+ " + c.dim("(recomendado)") + ": " + c.cyan("https://go.dev/dl/") + " → " + c.bold("go install github.com/Gentleman-Programming/engram/cmd/engram@latest"));
+      info("  b) Binario .zip: " + c.cyan("https://github.com/Gentleman-Programming/engram/releases"));
+      return false;
+    }
+  } else {
+    info("Guía de instalación completa: " + c.cyan("https://github.com/Gentleman-Programming/engram/blob/main/docs/INSTALLATION.md"));
+    return false;
+  }
+
+  const bin = which("engram");
+  if (bin) { ok("Engram instalado (" + bin + ")."); return true; }
+  warn("El binario engram no aparece en PATH tras la instalación.");
+  info("Puede que necesites reiniciar la terminal o ajustar tu PATH.");
+  return false;
+}
+
+/**
+ * Engram Cloud opt-in: réplica de equipo en tiempo real, adicional al git-sync.
+ * Configura el servidor y enrola el proyecto. Devuelve { enabled, server }.
+ */
+async function maybeEnableEngramCloud(project, opts) {
+  if (opts.yes) return { enabled: false };
+  const enable = await confirm("¿Habilitar Engram Cloud para el equipo? (réplica opt-in, requiere un servidor)", false);
+  if (!enable) {
+    info("Cloud omitido. El histórico de equipo viaja por git-sync (" + c.bold("ozali sync") + ").");
+    return { enabled: false };
+  }
+  const server = await ask("URL del servidor de Engram Cloud", "http://127.0.0.1:18080");
+  info(`Configurando Engram Cloud → ${server}`);
+  spawnCmd("engram", ["cloud", "config", "--server", server]);
+  info(`Enrolando el proyecto "${project}"…`);
+  if (spawnCmd("engram", ["cloud", "enroll", project]) === 0) {
+    ok("Engram Cloud habilitado. Replica con " + c.bold("ozali sync --cloud") + ".");
+    return { enabled: true, server };
+  }
+  warn("No se pudo enrolar el proyecto en Engram Cloud. Continúo solo con git-sync.");
+  return { enabled: false, server };
+}
+
+function printEngramManualInstructions(agent) {
+  const plat = process.platform;
+  info("Para activar memoria buscable/acumulativa (modo " + c.bold("hybrid") + "):");
+  if (plat === "darwin" || plat === "linux") {
+    info("  1. " + c.bold("brew install gentleman-programming/tap/engram") + "  " + c.dim("(o binario: github.com/Gentleman-Programming/engram/releases)"));
+  } else if (plat === "win32") {
+    info("  1. " + c.bold("go install github.com/Gentleman-Programming/engram/cmd/engram@latest") + "  " + c.dim("(requiere Go 1.24+)"));
+    info("     " + c.dim("o binario .zip: github.com/Gentleman-Programming/engram/releases"));
+  } else {
+    info("  1. " + c.cyan("https://github.com/Gentleman-Programming/engram/blob/main/docs/INSTALLATION.md"));
+  }
+  if (agent === "claude-code" || agent === "both") info("  2. " + c.bold("engram setup claude-code"));
+  if (agent === "opencode" || agent === "both") info("  2. " + c.bold("engram setup opencode"));
+  info("  3. Corre " + c.bold("ozali doctor") + " — el modo subirá a hybrid automáticamente.");
+}
+
+// Perfil base de permisos para Claude Code: lectura/comandos comunes libres,
+// destructivos denegados. Es un TEMPLATE — el usuario puede añadir más entradas y
+// re-correr init no las pisa (hace unión de listas).
+const CLAUDE_PERMS = {
+  allow: [
+    "WebFetch", "WebSearch",
+    "Bash(python *)", "Bash(python3 *)",
+    "Bash(node *)", "Bash(npm *)", "Bash(npx *)", "Bash(pnpm *)", "Bash(yarn *)",
+    "Bash(go *)", "Bash(mvn *)", "Bash(java *)",
+    "Bash(git status)", "Bash(git diff *)", "Bash(git log *)", "Bash(git add *)", "Bash(git commit *)",
+    "Bash(ozali *)", "Bash(engram *)",
+    "PowerShell(python *)", "PowerShell(node *)", "PowerShell(npm *)", "PowerShell(npx *)",
+    "PowerShell(mvn *)", "PowerShell(java *)",
+  ],
+  deny: [
+    "Bash(rm -rf *)", "Bash(git push *)",
+    "PowerShell(Remove-Item *)",
+  ],
+};
+
+function mergeUnique(existing, additions) {
+  const out = Array.isArray(existing) ? [...existing] : [];
+  const seen = new Set(out);
+  let added = 0;
+  for (const item of additions) if (!seen.has(item)) { out.push(item); seen.add(item); added++; }
+  return { out, added };
+}
+
+function ensureClaudeCodeProfile(cwd, scope) {
+  const settingsPath = scope === "global"
+    ? path.join(HOME, ".claude", "settings.json")
+    : path.join(cwd, ".claude", "settings.json");
+  const cfg = readJSON(settingsPath, {});
+  cfg.permissions = cfg.permissions || {};
+  const allowMerge = mergeUnique(cfg.permissions.allow, CLAUDE_PERMS.allow);
+  const denyMerge = mergeUnique(cfg.permissions.deny, CLAUDE_PERMS.deny);
+  cfg.permissions.allow = allowMerge.out;
+  cfg.permissions.deny = denyMerge.out;
+  writeJSON(settingsPath, cfg);
+  const rel = path.relative(cwd, settingsPath) || settingsPath;
+  if (allowMerge.added + denyMerge.added > 0) {
+    ok(`Perfil base de permisos de Claude Code en ${c.bold(rel)} (${allowMerge.added} allow / ${denyMerge.added} deny añadidos; tus reglas se conservan).`);
+  } else {
+    info(`Permisos de Claude Code ya cubiertos en ${c.bold(rel)} (sin cambios).`);
+  }
+}
+
+// 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) {
+  const p = path.join(HOME, ".claude.json");
+  if (!exists(p)) {
+    info("Claude Code aún no tiene ~/.claude.json; al abrirlo aquí, acepta el diálogo de confianza.");
+    return;
+  }
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { warn("No pude leer ~/.claude.json; acepta el diálogo de confianza de Claude Code manualmente."); return; }
+  cfg.projects = cfg.projects || {};
+  cfg.projects[cwd] = cfg.projects[cwd] || {};
+  if (cfg.projects[cwd].hasTrustDialogAccepted === true) {
+    info("Claude Code ya confía en este workspace.");
+    return;
+  }
+  const doTrust = opts.yes ? true
+    : await confirm("¿Marcar este proyecto como confiable en Claude Code? (necesario para que apliquen los permisos)", true);
+  if (!doTrust) {
+    info("Workspace no marcado como confiable: Claude Code ignorará los permisos hasta que aceptes su diálogo.");
+    return;
+  }
+  cfg.projects[cwd].hasTrustDialogAccepted = true;
+  fs.writeFileSync(p, JSON.stringify(cfg, null, 2)); // formato que usa Claude Code (indent 2, sin newline final)
+  ok("Workspace marcado como confiable en Claude Code (los permisos de .claude/settings.json ya aplican).");
+}
+
 function ensureOpencodeProfile(cwd) {
   const p = path.join(cwd, "opencode.json");
   const base = readJSON(p, {});
@@ -135,6 +342,9 @@ 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");
+  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)");
   add("Repo de conocimiento", !!(cfg && cfg.knowledgeRepo && exists(cfg.knowledgeRepo)), cfg ? cfg.knowledgeRepo : "sin configurar (ozali init)");
 
   // Strict TDD (de la fuente de verdad)
@@ -154,6 +364,23 @@ export function doctor(cwd) {
   console.log("");
   if (bad === 0) ok("Todo en orden. ozali está listo para trabajar.");
   else warn(`${bad} punto(s) a atender. Revisa los ✖ de arriba.`);
+
+  // Auto-upgrade: si Engram acaba de instalarse y el config aún dice "docs", subir a hybrid.
+  if (cfg && cfg.memoryMode === "docs" && env.engram.available) {
+    cfg.memoryMode = "hybrid";
+    writeJSON(CONFIG_PATH(cwd), cfg);
+    ok("Engram detectado → modo de memoria actualizado a " + c.bold("hybrid") + " en .ozali/config.json.");
+  }
+
+  // Estado de sync de Engram (informativo).
+  if (env.engram.available) {
+    const status = tryExec("engram", ["sync", "--status"], { cwd });
+    if (status) {
+      step("Estado de sync (Engram)");
+      for (const line of status.split(/\r?\n/)) console.log("  " + c.dim(line));
+    }
+  }
+
   return bad === 0 ? 0 : 1;
 }
 
@@ -192,13 +419,45 @@ export function sync(cwd, opts) {
   const docsLocal = path.join(cwd, ".ozali", "docs");
   const engramLocal = path.join(cwd, ".engram");
 
+  // Engram Cloud (opt-in): réplica bidireccional adicional al git-sync.
+  if (opts.cloud) {
+    if (cfg.cloud && cfg.cloud.enabled && tryExec("engram", ["--version"])) {
+      info(`Replicando con Engram Cloud (proyecto "${project}")…`);
+      if (spawnCmd("engram", ["sync", "--cloud", "--project", project], { cwd }) === 0) ok("Réplica con Engram Cloud completada.");
+      else warn("engram sync --cloud no terminó correctamente. Revisa el output de arriba.");
+    } else if (!(cfg.cloud && cfg.cloud.enabled)) {
+      warn("--cloud pedido, pero Engram Cloud no está habilitado. Corre " + c.bold("ozali init") + " para habilitarlo, o usa git-sync sin --cloud.");
+    } else {
+      warn("--cloud pedido, pero Engram no responde. Omito la réplica cloud.");
+    }
+  }
+
   if (opts.import) {
     // Repo de conocimiento → local
+    // 0) Traer lo más reciente del equipo (si el knowledge repo tiene remoto).
+    if (exists(path.join(kRepo, ".git")) && tryExec("git", ["remote", "get-url", "origin"], { cwd: kRepo })) {
+      info("Actualizando el repo de conocimiento (git pull)…");
+      if (spawnCmd("git", ["pull", "--ff-only"], { cwd: kRepo }) !== 0) {
+        warn("git pull no pudo completarse; importo lo que haya localmente.");
+      }
+    }
+    // 1) Docs
     const srcDocs = path.join(projDir, "docs");
     if (exists(srcDocs)) { copyDir(srcDocs, docsLocal); ok("Docs importados a .ozali/docs/."); }
+    else info("Aún no hay docs en el repo de conocimiento para este proyecto.");
+    // 2) Engram: copiar los chunks del repo de conocimiento → .engram/ ANTES de importar
+    //    (engram sync --import lee de .engram/ en el cwd; sin esta copia, un dev nuevo
+    //     no importaría nada).
     if (cfg.memoryMode === "hybrid" && tryExec("engram", ["--version"])) {
-      info("Ejecutando engram sync --import…");
-      tryExec("engram", ["sync", "--import"], { cwd });
+      const srcEngram = path.join(kRepo, "engram", project);
+      if (exists(srcEngram)) {
+        copyDir(srcEngram, engramLocal);
+        info("Chunks de Engram copiados a .engram/. Importando…");
+        if (spawnCmd("engram", ["sync", "--import"], { cwd }) === 0) ok("Memorias importadas a Engram local.");
+        else warn("engram sync --import no terminó correctamente. Revisa el output de arriba.");
+      } else {
+        info("Aún no hay export de Engram en el repo de conocimiento para este proyecto.");
+      }
     }
     info("Import completo. Revisa .ozali/docs/.");
     return 0;
@@ -208,8 +467,12 @@ export function sync(cwd, opts) {
   // 1) Engram export (si hybrid + disponible)
   if (cfg.memoryMode === "hybrid" && tryExec("engram", ["--version"])) {
     info("Exportando memorias con engram sync…");
-    tryExec("engram", ["sync"], { cwd });
-    if (exists(engramLocal)) { copyDir(engramLocal, path.join(kRepo, "engram", project)); ok("Export de Engram copiado al repo de conocimiento."); }
+    if (spawnCmd("engram", ["sync"], { cwd }) === 0) {
+      if (exists(engramLocal)) { copyDir(engramLocal, path.join(kRepo, "engram", project)); ok("Export de Engram copiado al repo de conocimiento."); }
+      else info("engram sync no generó .engram/ (sin memorias nuevas).");
+    } else {
+      warn("engram sync falló; sincronizo solo docs. Revisa el output de arriba.");
+    }
   } else if (cfg.memoryMode === "hybrid") {
     warn("Modo hybrid pero Engram no responde; sincronizo solo docs.");
   }

package/cli/lib/util.mjs

@@ -79,6 +79,24 @@ export function tryExec(cmd, args = [], opts = {}) {
   }
 }
 
+/** Ejecuta un comando con I/O visible en la terminal. Devuelve el exit code (0 = éxito). */
+export function spawnCmd(cmd, args = [], opts = {}) {
+  try {
+    execFileSync(cmd, args, { stdio: "inherit", ...opts });
+    return 0;
+  } catch (e) {
+    return e.status ?? 1;
+  }
+}
+
+/** Detecta el gestor de paquetes disponible (pnpm > bun > yarn > npm). */
+export function detectPkgManager() {
+  for (const pm of ["pnpm", "bun", "yarn", "npm"]) {
+    if (which(pm)) return pm;
+  }
+  return "npm";
+}
+
 export function which(bin) {
   const finder = process.platform === "win32" ? "where" : "which";
   return tryExec(finder, [bin]);

package/cli/test/smoke.test.mjs

@@ -57,12 +57,20 @@ test("doctor en proyecto vacío reporta pendientes (exit 1)", () => {
 test("init --yes instala la skill, aísla el histórico y escribe config", () => {
   const dir = tmpProject();
   try {
-    run(["init", "--yes", "--agent", "claude-code", "--scope", "project", "--knowledge-repo", path.join(dir, ".k")], dir);
+    run(["init", "--yes", "--no-engram", "--no-trust", "--agent", "claude-code", "--scope", "project", "--knowledge-repo", path.join(dir, ".k")], dir);
     assert.ok(fs.existsSync(path.join(dir, ".claude", "skills", "ozali", "SKILL.md")), "SKILL.md instalada");
     assert.ok(fs.existsSync(path.join(dir, ".ozali", "config.json")), "config escrita");
+    const cfg = JSON.parse(fs.readFileSync(path.join(dir, ".ozali", "config.json"), "utf8"));
+    assert.equal(cfg.memoryMode, "docs", "--no-engram deja modo docs");
     const gi = fs.readFileSync(path.join(dir, ".gitignore"), "utf8");
     assert.match(gi, /\.ozali\//);
     assert.match(gi, /\.engram\//);
+    // perfil base de permisos de Claude Code
+    const settingsPath = path.join(dir, ".claude", "settings.json");
+    assert.ok(fs.existsSync(settingsPath), "settings.json de Claude Code escrito");
+    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");
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -71,7 +79,7 @@ test("init --yes instala la skill, aísla el histórico y escribe config", () =>
 test("init --dry-run no escribe nada", () => {
   const dir = tmpProject();
   try {
-    run(["init", "--dry-run", "--yes"], dir);
+    run(["init", "--dry-run", "--yes", "--no-engram"], dir);
     assert.ok(!fs.existsSync(path.join(dir, ".ozali")), "no debe crear .ozali en dry-run");
     assert.ok(!fs.existsSync(path.join(dir, ".claude")), "no debe crear .claude en dry-run");
   } finally {

package/docs/guia-de-uso.md

@@ -0,0 +1,166 @@
+# Guía de uso — ozali
+
+← [README](../README.md) · ¿buscas el modelo mental? → [intended-usage.md](intended-usage.md)
+
+Guía rápida y sin tecnicismos para empezar a usar **ozali** en cualquier proyecto. Si nunca lo
+has usado, lee esto de principio a fin: son 5 minutos.
+
+---
+
+## ¿Qué es ozali, en simple?
+
+ozali le enseña a tu asistente de IA (Claude Code u opencode) **cómo trabajar en tu proyecto**:
+entiende tu código, propone un plan, pide tu aprobación antes de ejecutar, y **recuerda** lo que
+el equipo hizo antes. Tú sigues mandando; ozali pone el método y el orden.
+
+Piensa en tres piezas:
+
+| Pieza | Para qué sirve |
+|---|---|
+| **El comando `ozali`** | Lo corres en la terminal. Instala y mantiene todo. |
+| **La skill `ozali`** | Vive dentro de tu agente. Diagnostica el proyecto y prepara el trabajo. |
+| **Engram** *(opcional)* | La "memoria" del equipo: lo aprendido se guarda y se comparte. |
+
+---
+
+## Paso a paso (primera vez)
+
+### 1. Instala ozali
+
+```bash
+pnpm add -g ozali      # recomendado
+# o:  npm install -g ozali
+```
+
+> Puedes probarlo sin instalar con `pnpm dlx ozali init`, pero entonces el comando `ozali` **no
+> queda disponible** después. Para usar `doctor`, `sync`, etc. en el día a día, instálalo con `-g`.
+
+### 2. Entra a tu proyecto y arranca
+
+```bash
+cd mi-proyecto
+ozali init
+```
+
+El asistente te hará unas preguntas (qué agente usas, dónde guardar la memoria, si instalar
+Engram). Puedes aceptar los valores por defecto si dudas. Al terminar, deja listo:
+
+- la skill instalada en tu agente,
+- los permisos base para que el agente **no te pregunte por cada comando** (ver más abajo),
+- el aislamiento del histórico (no ensucia tu repo).
+
+### 3. Abre tu agente y diagnostica
+
+Abre Claude Code (u opencode) en el proyecto y escribe:
+
+```
+diagnostica el proyecto
+```
+
+ozali revisará tu código, preparará la documentación base y te mostrará un **plan**. Nada se
+ejecuta hasta que tú apruebes (eso es el 🛑 **GATE**).
+
+### 4. Trabaja normal
+
+Pídele cosas a tu agente como siempre: *"crea el endpoint de login"*, *"corrige este bug"*, etc.
+ozali se encarga de hacerlo con orden y de ir guardando el registro.
+
+### 5. Guarda y comparte (si trabajas en equipo)
+
+```bash
+ozali sync
+```
+
+Lleva el histórico y la memoria al repo de conocimiento del equipo. Tus compañeros lo traen con
+`ozali sync --import`.
+
+---
+
+## Los comandos (chuleta)
+
+| Comando | Qué hace |
+|---|---|
+| `ozali init` | Prepara el proyecto (lo corres una vez por repo). |
+| `ozali doctor` | Revisa que todo esté bien. Es solo lectura, no cambia nada. |
+| `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ó. |
+
+¿Algo no funciona? Corre **`ozali doctor`** primero: te dice qué falta y cómo arreglarlo.
+
+---
+
+## Sobre los permisos (menos interrupciones)
+
+Por defecto, los agentes piden confirmación **antes de cada comando**. Eso cansa. Durante `init`,
+ozali crea un archivo `.claude/settings.json` con una lista de permisos razonable: deja correr
+libremente cosas seguras (instalar dependencias, correr tests, leer archivos, `git status`…) y
+**bloquea las peligrosas** (`rm -rf`, `git push`).
+
+Es **un punto de partida, no una jaula**: puedes editar ese archivo y añadir lo que tu proyecto
+necesite. Si vuelves a correr `ozali init`, tus reglas **se conservan** (no se borran ni se
+duplican).
+
+> **Confianza del workspace (Claude Code):** por seguridad, Claude Code **ignora** los permisos de
+> un proyecto hasta que confías en él (verás un aviso *"this workspace has not been trusted"*).
+> `init` te ofrece marcarlo como confiable automáticamente; si prefieres hacerlo tú, abre Claude
+> Code en la carpeta y acepta el diálogo de confianza una vez. Con `--no-trust` ozali no lo toca.
+
+Ejemplo — permitir Docker además de lo de fábrica:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(docker *)"],
+    "deny": []
+  }
+}
+```
+
+---
+
+## Engram: la memoria del equipo (opcional)
+
+Durante `init`, ozali **instala Engram por ti**: en modo interactivo te pregunta (basta con aceptar),
+y en modo automático (`--yes`) lo instala solo. Lo baja con brew (macOS/Linux) o `go` (Windows), y si
+no puede, te deja las instrucciones. Con Engram, tu agente **recuerda** decisiones, bugs resueltos y
+convenciones — y los recupera en futuras sesiones.
+
+¿No quieres Engram ahora? Pasa `--no-engram` y ozali arranca en modo `docs` (la memoria se queda en
+documentos legibles). Cuando quieras activarlo, instálalo y corre `ozali doctor`: el modo sube a
+`hybrid` solo.
+
+Dos detalles si lo usas en equipo:
+
+- **Idioma:** guarda la memoria compartida **en español** (y búscala en español). El buscador no
+  mezcla idiomas: si guardas en español y buscas en inglés, no encuentra nada.
+- **Privado vs. compartido:** lo que marques como `scope: project` lo ve todo el equipo. Para notas
+  personales usa `scope: personal` (aunque hoy el sync comparte ambos — para algo realmente privado,
+  no lo pongas en el proyecto de equipo).
+
+Más detalle técnico en [engram-convention.md](../skill/references/engram-convention.md).
+
+---
+
+## Preguntas frecuentes
+
+**¿Tengo que usar Engram?**
+No. Es opcional. Sin él, ozali funciona en modo `docs`.
+
+**¿ozali toca mi código sin permiso?**
+No. Siempre hay un plan y un GATE de aprobación antes de ejecutar.
+
+**Escribí `ozali` y la terminal dice "command not found".**
+Lo corriste con `dlx`/`npx`, que es temporal. Instálalo global: `pnpm add -g ozali`.
+
+**¿Esto ensucia mi repositorio?**
+No. El histórico y la memoria se aíslan (`.ozali/`, `.engram/` van al `.gitignore`).
+
+**Veo "this workspace has not been trusted" y mis permisos no aplican.**
+Es el aviso de seguridad de Claude Code: ignora los permisos del proyecto hasta confiar en él.
+Deja que `init` lo marque como confiable, o abre Claude Code en la carpeta y acepta el diálogo una
+vez. Tras eso, el aviso desaparece y los permisos surten efecto.
+
+**¿Funciona en Windows?**
+Sí. Los permisos base incluyen variantes PowerShell, y Engram se instala con `go install` o un
+binario descargable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ozali",
-  "version": "0.1.0",
+  "version": "0.3.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": {

package/skill/references/engram-convention.md

@@ -33,6 +33,44 @@ Sin remoto, el nombre de carpeta. Mantén UN nombre por proyecto (evita drift `m
 
 ---
 
+## 1.5. Memoria de equipo (scope + idioma)
+
+La memoria de Engram es **compartida**: lo que un dev guarda en `scope: project` lo recuperan los
+agentes de sus compañeros tras `ozali sync` / `ozali sync --import`. Dos convenciones son
+**obligatorias** para que esa memoria compartida sirva como herramienta de equipo.
+
+### Scope: `project` vs `personal`
+
+| Guarda como `scope: project` | Guarda como `scope: personal` |
+|---|---|
+| Decisiones de arquitectura y trade-offs | Notas y aprendizajes personales |
+| Bugfixes que afectan a otros | Atajos de editor / dotfiles |
+| Convenciones, naming, *gotchas* del repo | Preferencias de estilo o workflow |
+| Contratos de API, quirks de despliegue | Enlaces para releer luego |
+| Contexto de onboarding | TODOs y recordatorios personales |
+
+> Regla rápida: **si el agente de un compañero debería encontrarlo, es `scope: project`.** Todos los
+> artefactos automáticos de `cdk` (§2) van en `scope: project`.
+
+> ⚠️ **El sync exporta AMBOS scopes.** Hoy `scope` filtra búsqueda, **no** transporte: al sincronizar
+> un proyecto se comparten también sus observaciones `personal`. Si necesitas notas verdaderamente
+> privadas, guárdalas bajo **otro nombre de proyecto** (p. ej. `tu-nombre-notas`) que no sincronices,
+> o no las pongas en Engram.
+
+### Idioma de la memoria compartida: **español**
+
+FTS5 (el buscador de Engram) **no es multilingüe**: una búsqueda en un idioma no matchea memorias
+guardadas en otro. Por eso este equipo fija una **lingua franca** para `scope: project`:
+
+- **`scope: project` → siempre en español.** Títulos, `topic_key` semánticos y contenido.
+- **`scope: personal` → cualquier idioma** (nadie más busca tu scope personal).
+
+> 🔑 **Regla de consistencia:** como elegimos español, **tanto al guardar como al buscar**
+> `scope: project` se usa español. Una `mem_search` en inglés sobre memoria guardada en español
+> **no devuelve nada** — la búsqueda se fragmenta y la memoria de equipo deja de funcionar.
+
+---
+
 ## 2. Naming determinista
 
 Todos los artefactos de `cdk` en Engram siguen: