ozali 0.7.0 → 0.8.0

package/README.md

@@ -80,7 +80,10 @@ referencian entre sí, corre **una vez** en esa raíz:
 ```bash
 ozali workspace           # escanea repos hijos, remedia los que faltan y escribe la config conjunta
 ozali workspace --dry-run # solo muestra el inventario y el plan, sin escribir
+ozali workspace --yes     # no interactivo: acepta defaults y todas las referencias detectadas
 ozali workspace --depth 2 # busca repos hasta 2 niveles (para raíces con subcarpetas de grupo)
+ozali workspace --doctor  # health-check de TODOS los repos miembros + resumen (solo CLI)
+ozali workspace --update  # actualiza skills/permisos/jarvis de TODOS los repos miembros (solo CLI)
 ```
 
 Qué hace, en orden: (1) **escanea** los repos hijos y reporta su estado —`✔ listo`, `⚠ sin calibrar`
@@ -93,6 +96,13 @@ contigo; y (4) escribe la config para **trabajar en conjunto**:
 - `<carpeta>.code-workspace` — workspace multi-root que abre todos los repos juntos.
 - Orquestador **`ozali-workspace-jarvis`** en `CLAUDE.md`/`AGENTS.md` de la raíz: coordina los repos
   según el manifiesto y delega la ejecución en el `cdk` de cada uno.
+- La skill **`ozali`** en la raíz (`.claude/skills/ozali/`) para **calibrar los miembros desde el
+  workspace** (modo target), sin abrir cada proyecto.
+
+**Operar todo desde la raíz:** `ozali workspace --doctor` y `--update` corren el health-check y la
+actualización sobre **todos** los repos miembros (solo CLI). Y para calibrar los `⚠ sin calibrar`,
+abre el agente en la raíz y pídele a `ozali-workspace-jarvis` que *"calibre los repos pendientes"*: los
+recorre uno por uno (con su GATE) sin que cambies de proyecto.
 
 Es **idempotente**: re-córrelo cuando agregues repos o cambien las referencias. Detalle completo en
 [`docs/workspaces.md`](docs/workspaces.md).
@@ -152,6 +162,7 @@ Claude Code y opencode (perfiles de permisos para ambos en
 |---|---|
 | 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) |
+| Compilado y uso local (repo clonado) | [docs/compilado-local.md](docs/compilado-local.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) |
 | Desplegar Engram Cloud (VPS) | [docs/deploy-cloud-vps.md](docs/deploy-cloud-vps.md) |

package/cli/bin/ozali.mjs

@@ -16,6 +16,7 @@ ${c.bold("Comandos:")}
             ozali-commit, aísla el histórico, configura Engram y el repo de conocimiento.
   workspace Multi-repo: escanea los repos de la carpeta raíz, remedia los que no tienen
             ozali init, guía la calibración y escribe la config para trabajar en conjunto.
+            Con --doctor / --update opera sobre TODOS los repos miembros desde la raíz.
   doctor    Health-check read-only del proyecto (fuente de verdad, Engram, versión de cdk, TDD…).
   update    Actualiza la instalación (skills ozali + ozali-commit + ozali-jarvis + permisos)
             al paquete y avisa si la skill cdk quedó desactualizada.
@@ -29,6 +30,8 @@ ${c.bold("Opciones comunes:")}
   --agent <a>          (init) claude-code | opencode | both.
   --scope <s>          (init) project | global.
   --depth <n>          (workspace) Niveles a escanear bajo la raíz (default 1).
+  --doctor             (workspace) Health-check de TODOS los repos miembros + resumen.
+  --update             (workspace) Actualiza (skills/permisos/jarvis) TODOS los repos miembros.
   --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.
@@ -73,6 +76,8 @@ function parseArgs(argv) {
     else if (a === "--agent") opts.agent = argv[++i];
     else if (a === "--scope") opts.scope = argv[++i];
     else if (a === "--depth") opts.depth = argv[++i];
+    else if (a === "--doctor") opts.wsDoctor = true;
+    else if (a === "--update") opts.wsUpdate = true;
     else if (a === "--knowledge-repo") opts.knowledgeRepo = argv[++i];
     else if (a === "-h" || a === "--help") opts.help = true;
     else if (a === "-v" || a === "--version") opts.version = true;

package/cli/lib/commands.mjs

@@ -5,7 +5,7 @@ import os from "node:os";
 import {
   c, ok, warn, err, info, step,
   SKILL_SRC, COMMIT_SKILL_SRC, TEMPLATES_SRC, exists, ensureDir, copyDir, readJSON, writeJSON,
-  ensureGitignore, tryExec, spawnCmd, which, engramAssetName,
+  ensureGitignore, tryExec, spawnCmd, which, engramAssetName, pickEngramAsset,
   projectName, pkgVersion, DEFAULT_KNOWLEDGE, HOME, openURL, gitInfo,
 } from "./util.mjs";
 import { detectAll, detectWorkspace, detectReferences } from "./detect.mjs";
@@ -305,19 +305,28 @@ function installEngram() {
   return false;
 }
 
-const ENGRAM_RELEASES_API = "https://api.github.com/repos/Gentleman-Programming/engram/releases/latest";
-const ENGRAM_RELEASES_DL = "https://github.com/Gentleman-Programming/engram/releases/download";
+// Lista de releases (NO /releases/latest: ese endpoint puede devolver un tag especial
+// sin binarios, p. ej. `pi-v*`). Recorremos la lista y elegimos el release estable.
+const ENGRAM_RELEASES_LIST = "https://api.github.com/repos/Gentleman-Programming/engram/releases?per_page=30";
 
-/** Última versión publicada de Engram (sin la "v" inicial), o null si no hay red. */
-function latestEngramVersion() {
-  let raw = null;
-  if (which("curl")) raw = tryExec("curl", ["-fsSL", ENGRAM_RELEASES_API]);
-  else if (which("wget")) raw = tryExec("wget", ["-qO-", ENGRAM_RELEASES_API]);
+/** GET de texto con curl (o wget). Devuelve el body o null si no hay red/herramienta. */
+function fetchText(url) {
+  if (which("curl")) return tryExec("curl", ["-fsSL", url]);
+  if (which("wget")) return tryExec("wget", ["-qO-", url]);
+  return null;
+}
+
+/**
+ * Resuelve { version, url } del binario precompilado de Engram para este SO/arch,
+ * consultando la lista de releases y quedándose con el release estable más reciente
+ * que contenga el asset. Devuelve null si no hay red/herramienta o no hay binario.
+ */
+function resolveEngramAsset(platform, arch) {
+  const raw = fetchText(ENGRAM_RELEASES_LIST);
   if (!raw) return null;
-  try {
-    const tag = JSON.parse(raw).tag_name;
-    return tag ? String(tag).replace(/^v/, "") : null;
-  } catch { return null; }
+  let releases;
+  try { releases = JSON.parse(raw); } catch { return null; }
+  return pickEngramAsset(releases, platform, arch);
 }
 
 /** Descarga url → dest con curl (o wget como fallback). Devuelve true si tuvo éxito. */
@@ -359,14 +368,13 @@ function installEngramFromTarball() {
     return false;
   }
 
-  const version = latestEngramVersion();
-  if (!version) {
-    warn("No pude resolver la última versión de Engram (¿sin red o sin curl/wget?).");
+  const resolved = resolveEngramAsset(plat, process.arch);
+  if (!resolved) {
+    warn("No pude resolver un binario precompilado de Engram para tu SO/arch (¿sin red, sin curl/wget, o release sin assets?).");
     return false;
   }
-
+  const { version, url } = resolved;
   const asset = engramAssetName(plat, process.arch, version);
-  const url = `${ENGRAM_RELEASES_DL}/v${version}/${asset}`;
   info(`Descargando binario precompilado de Engram ${c.bold("v" + version)} (${process.arch})…`);
 
   let tmpDir;
@@ -785,6 +793,10 @@ export async function workspace(cwd, opts = {}) {
   step("Repos detectados");
   printMembers(ws.members);
 
+  // Modos batch (Track 1): operan sobre los miembros del workspace ya existente y salen.
+  if (opts.wsDoctor) return workspaceDoctor(ws.members);
+  if (opts.wsUpdate) return workspaceUpdate(ws.members, opts);
+
   // Fase B — remediación de los que no tienen ozali init
   const missing = ws.members.filter((m) => m.status === "missing-init");
   if (missing.length && opts.dryRun) {
@@ -828,6 +840,7 @@ export async function workspace(cwd, opts = {}) {
   const agent = manifest.agent;
   if (agent === "claude-code" || agent === "both") {
     ensureWorkspaceJarvisClaudeCode(cwd);
+    ensureWorkspaceOzaliSkill(cwd); // Track 2: skill ozali en la raíz → calibrar miembros desde el workspace
     if (!opts.noTrust) await ensureClaudeWorkspaceTrust(cwd, opts);
   }
   if (agent === "opencode" || agent === "both") ensureWorkspaceJarvisOpencode(cwd);
@@ -841,11 +854,68 @@ export async function workspace(cwd, opts = {}) {
   step("Siguientes pasos");
   const wsFile = `${path.basename(cwd)}.code-workspace`;
   console.log(`  1. Abre el workspace en tu editor: ${c.bold(wsFile)} ${c.dim("(VSCode/Antigravity → Open Workspace).")}`);
-  if (needCal.length) console.log(`  2. Calibra los repos pendientes (${c.bold(needCal.map((m) => m.dir).join(", "))}) corriendo la skill ${c.bold("ozali")} en cada uno.`);
+  if (needCal.length) {
+    console.log(`  2. Calibra los pendientes (${c.bold(needCal.map((m) => m.dir).join(", "))}) ${c.dim("sin salir del workspace:")}`);
+    console.log(`     ${c.dim("abre el agente en la raíz y pide a")} ${c.bold("ozali-workspace-jarvis")} ${c.dim('que "calibre los repos pendientes"')}`);
+    console.log(`     ${c.dim("(usa la skill")} ${c.bold("ozali")} ${c.dim("en modo target, repo por repo con su GATE).")}`);
+  }
+  console.log(`  ${c.dim("• Salud de todos los repos:")}     ${c.bold("ozali workspace --doctor")}`);
+  console.log(`  ${c.dim("• Actualizar todos los repos:")}   ${c.bold("ozali workspace --update")}`);
   console.log(`  ${c.dim("Re-corre")} ${c.bold("ozali workspace")} ${c.dim("cuando agregues repos o cambien las referencias (es idempotente).")}`);
   return 0;
 }
 
+/** Track 1 — health-check de todos los miembros (doctor por repo) + resumen consolidado. */
+function workspaceDoctor(members) {
+  const results = [];
+  for (const m of members) {
+    console.log("");
+    console.log(c.bold(c.magenta(`── ${m.dir} ──`)));
+    if (m.status === "missing-init") {
+      warn(`Sin ozali init → córrelo (o re-corre ${c.bold("ozali workspace")}).`);
+      results.push({ dir: m.dir, ok: false, note: "sin init" });
+      continue;
+    }
+    const code = doctor(m.path);
+    results.push({ dir: m.dir, ok: code === 0, note: code === 0 ? "todo en orden" : "puntos a atender" });
+  }
+  step("Resumen del workspace");
+  const pad = Math.max(4, ...members.map((m) => m.dir.length));
+  for (const r of results) {
+    console.log(`  ${r.ok ? c.green("✔") : c.yellow("✖")} ${r.dir.padEnd(pad)}  ${c.dim(r.note)}`);
+  }
+  return results.every((r) => r.ok) ? 0 : 1;
+}
+
+/** Track 1 — update de todos los miembros ozali (skills/permisos/jarvis) + resumen. */
+function workspaceUpdate(members, opts) {
+  const results = [];
+  let failed = 0;
+  for (const m of members) {
+    console.log("");
+    console.log(c.bold(c.magenta(`── ${m.dir} ──`)));
+    if (m.status === "missing-init") {
+      warn("Sin ozali init → nada que actualizar (córrelo primero).");
+      results.push({ dir: m.dir, mark: c.yellow("—"), note: "sin init (saltado)" });
+      continue;
+    }
+    const code = update(m.path, opts);
+    if (code !== 0) failed++;
+    results.push({ dir: m.dir, mark: code === 0 ? c.green("✔") : c.yellow("✖"), note: code === 0 ? "actualizado" : "revisar" });
+  }
+  step("Resumen del workspace");
+  const pad = Math.max(4, ...members.map((m) => m.dir.length));
+  for (const r of results) console.log(`  ${r.mark} ${r.dir.padEnd(pad)}  ${c.dim(r.note)}`);
+  info(`La skill ${c.bold("cdk")} la regenera el agente. Re-corre ${c.bold("ozali workspace")} para refrescar estados.`);
+  return failed > 0 ? 1 : 0;
+}
+
+/** Track 2 — instala la skill `ozali` en la raíz para calibrar miembros desde el workspace. */
+function ensureWorkspaceOzaliSkill(root) {
+  copyDir(SKILL_SRC, path.join(root, ".claude", "skills", "ozali"));
+  ok(`Skill ${c.bold("ozali")} instalada en la raíz (${c.bold(".claude/skills/ozali")}) para calibrar miembros desde el workspace.`);
+}
+
 /** Primer .ozali/config.json entre los miembros ya inicializados (para heredar defaults). */
 function inheritedConfig(members) {
   for (const m of members) {

package/cli/lib/detect.mjs

@@ -1,7 +1,7 @@
 // detect.mjs — detección read-only del entorno del proyecto destino.
 import fs from "node:fs";
 import path from "node:path";
-import { exists, which, gitInfo, nodeMajor, HOME, readJSON, projectName, DEFAULT_KNOWLEDGE } from "./util.mjs";
+import { exists, which, gitInfo, tryExec, nodeMajor, HOME, readJSON, projectName, DEFAULT_KNOWLEDGE } from "./util.mjs";
 
 /** Variante de fuente de verdad: {found, doc, dir, variant} */
 export function detectSourceOfTruth(cwd) {
@@ -121,9 +121,21 @@ function isKnowledgeRepo(dir) {
   return d === k || d.startsWith(k + path.sep);
 }
 
+/**
+ * ¿`dir` es la RAÍZ de su propio repo git? No basta con estar dentro de un work tree
+ * (una subcarpeta de un repo también lo está): exigimos que el toplevel de git sea `dir`.
+ * Así, correr `ozali workspace` dentro de un repo NO trata sus subcarpetas como miembros.
+ */
+function isRepoRoot(dir) {
+  const top = tryExec("git", ["-C", dir, "rev-parse", "--show-toplevel"]);
+  if (!top) return false;
+  try { return fs.realpathSync(top) === fs.realpathSync(dir); } catch { return false; }
+}
+
 /**
  * Junta las rutas de repos git bajo `root` hasta `depth` niveles. Un directorio que
- * ES repo git se trata como hoja (no se desciende dentro). Salta ocultos/ignorados.
+ * ES la raíz de su propio repo git se trata como hoja (no se desciende dentro). Salta
+ * ocultos/ignorados.
  */
 function collectRepoDirs(root, depth, level = 1, acc = []) {
   let entries;
@@ -133,7 +145,7 @@ function collectRepoDirs(root, depth, level = 1, acc = []) {
     if (e.name.startsWith(".") || IGNORE_DIRS.has(e.name)) continue;
     const full = path.join(root, e.name);
     if (isKnowledgeRepo(full)) continue;
-    if (gitInfo(full).isRepo) { acc.push(full); continue; } // repo = hoja
+    if (isRepoRoot(full)) { acc.push(full); continue; } // repo propio = hoja
     if (level < depth) collectRepoDirs(full, depth, level + 1, acc);
   }
   return acc;

package/cli/lib/util.mjs

@@ -37,6 +37,29 @@ export function engramAssetName(platform, arch, version) {
   return `engram_${version}_${os}_${a}.${ext}`;
 }
 
+/**
+ * Elige el binario precompilado de Engram para un SO/arch dado a partir de la lista de
+ * releases (formato de la API de GitHub `/releases`). Se queda con el release ESTABLE
+ * más reciente cuyo tag sea semver `vX.Y.Z` y que **realmente contenga** el asset
+ * esperado, y devuelve su `browser_download_url` real. Ignora tags no-semver (p. ej.
+ * `pi-v*`, builds de Raspberry Pi que NO traen binarios) y draft/prerelease.
+ * Función pura (sin red). Devuelve { version, url } o null.
+ */
+export function pickEngramAsset(releases, platform, arch) {
+  if (!Array.isArray(releases)) return null;
+  for (const r of releases) {
+    if (!r || r.draft || r.prerelease) continue;
+    const m = /^v(\d+\.\d+\.\d+)$/.exec(r.tag_name || "");
+    if (!m) continue; // salta tags no-semver (pi-v*, etc.)
+    const version = m[1];
+    const name = engramAssetName(platform, arch, version);
+    if (!name) return null; // SO/arch sin binario publicado
+    const asset = Array.isArray(r.assets) ? r.assets.find((a) => a && a.name === name) : null;
+    if (asset && asset.browser_download_url) return { version, url: asset.browser_download_url };
+  }
+  return null;
+}
+
 // ---- colores (sin deps; respeta NO_COLOR y no-TTY) --------------------------
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));

package/cli/test/smoke.test.mjs

@@ -6,7 +6,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { engramAssetName } from "../lib/util.mjs";
+import { engramAssetName, pickEngramAsset } from "../lib/util.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const BIN = path.resolve(HERE, "..", "bin", "ozali.mjs");
@@ -257,6 +257,8 @@ test("workspace escribe manifiesto + .code-workspace + jarvis y es idempotente",
     assert.ok(fs.existsSync(wsFile), ".code-workspace escrito");
     assert.equal(JSON.parse(fs.readFileSync(wsFile, "utf8")).folders.length, 2, "multi-root con 2 folders");
     assert.match(fs.readFileSync(path.join(root, "CLAUDE.md"), "utf8"), /ozali-workspace-jarvis:start/, "bloque jarvis en CLAUDE.md");
+    // Track 2: la skill ozali queda instalada en la raíz para calibrar miembros desde el workspace
+    assert.ok(fs.existsSync(path.join(root, ".claude", "skills", "ozali", "SKILL.md")), "skill ozali en la raíz");
 
     // idempotencia: re-correr no duplica
     run(["workspace", "--yes", "--no-trust"], root);
@@ -268,6 +270,51 @@ test("workspace escribe manifiesto + .code-workspace + jarvis y es idempotente",
   }
 });
 
+test("workspace --doctor revisa cada miembro y saca resumen consolidado", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "ozali-ws-"));
+  try {
+    wsRepo(root, "api", { config: true, cdk: true, pkg: { name: "api", version: "1.0.0" } });
+    wsRepo(root, "web", { config: true, cdk: true, pkg: { name: "web" } });
+    const { stdout } = run(["workspace", "--doctor"], root, true); // exit 1 esperado (repos sin sot/engram)
+    assert.match(stdout, /health-check/i, "corre doctor por repo");
+    assert.match(stdout, /Resumen del workspace/, "imprime el resumen consolidado");
+    assert.match(stdout, /api/, "menciona el repo api en el resumen");
+    assert.match(stdout, /web/, "menciona el repo web en el resumen");
+    assert.ok(!fs.existsSync(path.join(root, "ozali-workspace.json")), "--doctor no escribe config");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("workspace --update actualiza cada miembro y salta los sin init", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "ozali-ws-"));
+  try {
+    wsRepo(root, "api", { config: true, cdk: true, pkg: { name: "api", version: "1.0.0" } });
+    wsRepo(root, "bare", { pkg: { name: "bare" } }); // missing-init → se salta
+    const { stdout } = run(["workspace", "--update", "--yes", "--no-jarvis"], root);
+    assert.match(stdout, /Resumen del workspace/, "imprime el resumen consolidado");
+    assert.match(stdout, /Sin ozali init/, "salta el repo sin init");
+    assert.ok(!fs.existsSync(path.join(root, "ozali-workspace.json")), "--update no escribe config");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("workspace no trata subcarpetas de un repo como miembros (solo repos propios)", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "ozali-ws-"));
+  try {
+    execFileSync("git", ["init", "-q"], { cwd: root }); // la raíz ES un repo git
+    fs.mkdirSync(path.join(root, "src"));                 // subcarpeta simple, NO repo propio
+    fs.writeFileSync(path.join(root, "src", "index.js"), "//\n");
+    wsRepo(root, "pkg", { config: true, cdk: true, pkg: { name: "pkg", version: "1.0.0" } }); // repo propio anidado
+    const { stdout } = run(["workspace", "--dry-run"], root);
+    assert.match(stdout, /\bpkg\b/, "incluye el repo propio anidado");
+    assert.doesNotMatch(stdout, /\bsrc\b/, "no incluye la subcarpeta que no es repo propio");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("init --dry-run no escribe nada", () => {
   const dir = tmpProject();
   try {
@@ -335,3 +382,31 @@ test("engramAssetName respeta la convención de release por SO/arch", () => {
   assert.equal(engramAssetName("linux", "ia32", "1.17.0"), null, "arch no soportada → null");
   assert.equal(engramAssetName("freebsd", "x64", "1.17.0"), null, "SO no soportado → null");
 });
+
+test("pickEngramAsset ignora tags no-semver sin binarios (pi-v*) y draft/prerelease", () => {
+  // Shape real de la API de GitHub: el 'latest' es pi-v0.1.9 (0 assets); los binarios
+  // viven en tags vX.Y.Z. Además metemos un prerelease más nuevo que debe saltarse.
+  const releases = [
+    { tag_name: "pi-v0.1.9", prerelease: false, draft: false, assets: [] },
+    { tag_name: "v2.0.0", prerelease: true, draft: false, assets: [
+      { name: "engram_2.0.0_linux_amd64.tar.gz", browser_download_url: "https://x/pre" },
+    ] },
+    { tag_name: "v1.17.0", prerelease: false, draft: false, assets: [
+      { name: "checksums.txt", browser_download_url: "https://x/sum" },
+      { name: "engram_1.17.0_linux_amd64.tar.gz", browser_download_url: "https://x/engram_1.17.0_linux_amd64.tar.gz" },
+      { name: "engram_1.17.0_darwin_arm64.tar.gz", browser_download_url: "https://x/darwin" },
+    ] },
+  ];
+  // Linux x64 → salta pi-v* (sin assets) y el prerelease → v1.17.0, con la URL REAL del asset.
+  assert.deepEqual(pickEngramAsset(releases, "linux", "x64"), {
+    version: "1.17.0",
+    url: "https://x/engram_1.17.0_linux_amd64.tar.gz",
+  });
+  // macOS arm64 → mismo release, su asset darwin_arm64.
+  assert.deepEqual(pickEngramAsset(releases, "darwin", "arm64"), { version: "1.17.0", url: "https://x/darwin" });
+  // Arch sin binario → null.
+  assert.equal(pickEngramAsset(releases, "linux", "ia32"), null);
+  // Sin releases utilizables → null.
+  assert.equal(pickEngramAsset([{ tag_name: "pi-v0.1.9", assets: [] }], "linux", "x64"), null);
+  assert.equal(pickEngramAsset(null, "linux", "x64"), null);
+});

package/docs/compilado-local.md

@@ -0,0 +1,182 @@
+# Compilado y uso local (para probar el repo clonado)
+
+← [README](../README.md)
+
+Guía para cuando **clonas este repositorio** y quieres compilarlo/empaquetarlo y **probarlo en local**
+antes de publicarlo o para desarrollar sobre él.
+
+> **Aclaración importante — no hay "compilación".** `ozali` es un CLI **Node de cero dependencias y
+> ESM puro** (solo usa módulos `node:*`). **No hay build step**, ni TypeScript que transpilar, ni
+> `dist/`. "Compilar" aquí significa una de dos cosas: (a) **correrlo tal cual** desde el fuente, o
+> (b) **empaquetar el artefacto distribuible** (`npm pack` → un `.tgz`, el "archivo base") para
+> instalarlo y probarlo como lo haría un usuario final.
+
+---
+
+## Requisitos
+
+- **Node ≥ 16** (`node --version`). Es lo único imprescindible.
+- **git** (el CLI lee identidad/estado del repo).
+- **pnpm** o **npm** (opcional; solo para `test`, `pack`, `link` o instalación global). No hay `npm
+  install` que correr: **el repo no tiene dependencias**.
+
+```bash
+git clone https://github.com/jimmybathrooms/ozali.git
+cd ozali
+```
+
+---
+
+## 1. Correr desde el fuente (sin instalar nada)
+
+Como no hay dependencias ni build, el CLI corre directo:
+
+```bash
+node cli/bin/ozali.mjs --version     # imprime la versión de package.json (p. ej. 0.8.0)
+node cli/bin/ozali.mjs --help        # lista de comandos
+node cli/bin/ozali.mjs doctor        # health-check en el cwd
+```
+
+Esta es la forma **más auditable**: ejecutas exactamente el código que ves, sin capa de instalación.
+
+---
+
+## 2. Correr la batería de pruebas
+
+```bash
+npm test        # (o: pnpm test)  → node --test cli/test/*.test.mjs
+```
+
+Debe salir todo en verde. Los tests son `node:test` puro (sin dependencias) y cubren init, doctor,
+update, workspace, seguridad del paquete y los helpers de release de Engram.
+
+---
+
+## 3. Empaquetar el "archivo base" (tarball distribuible)
+
+El artefacto que se publicaría en npm es un tarball `.tgz`. Se genera con:
+
+```bash
+npm pack                 # (o: pnpm pack)
+# → crea  ozali-<version>.tgz  en la raíz del repo (el cwd)
+```
+
+Para tu versión actual produce, por ejemplo, **`ozali-0.8.0.tgz`**. Es **idéntico** a lo que recibiría
+un usuario desde npm: incluye solo lo declarado en `package.json > files` (`cli/`, `skill/`,
+`skill-commit/`, `templates/`, `docs/`, `README.md`, `LICENSE`).
+
+Para **ver qué contiene sin generar el archivo**:
+
+```bash
+npm pack --dry-run       # lista archivos, tamaño y nombre del tarball, sin escribir nada
+```
+
+> El `.tgz` es un artefacto temporal: **no lo commitees**. Bórralo tras probar (o añádelo a
+> `.gitignore` como `ozali-*.tgz`).
+
+### Extraer / inspeccionar el tarball
+
+El tarball es un `.tar.gz` estándar. Para extraerlo y revisar el "archivo base" tal como quedaría
+instalado:
+
+```bash
+tar -xzf ozali-0.8.0.tgz      # crea una carpeta  package/  con el contenido publicable
+ls -R package                 # inspecciona la estructura
+tar -tzf ozali-0.8.0.tgz      # o solo LISTA el contenido, sin extraer
+```
+
+La carpeta `package/` es exactamente lo que npm coloca en `node_modules/ozali` al instalar.
+
+---
+
+## 4. Usarlo en local para pruebas
+
+Tres formas, de la más cómoda para desarrollar a la más fiel al usuario final:
+
+### a) `npm link` — bucle de desarrollo (refleja tus cambios al instante)
+
+```bash
+npm link                 # (o: pnpm link --global)
+# ahora 'ozali' está en tu PATH, apuntando al clon local
+ozali --version
+ozali doctor
+```
+
+Como es un symlink al repo, cualquier edición que hagas en `cli/` se ve de inmediato (no hace falta
+re-linkear). Para deshacer: `npm unlink -g ozali` (o `npm rm -g ozali`).
+
+### b) Instalar el tarball global — prueba el artefacto real
+
+Instala el `.tgz` como lo haría un usuario, para validar el paquete exacto que publicarías:
+
+```bash
+npm i -g ./ozali-0.8.0.tgz     # (o: pnpm add -g ./ozali-0.8.0.tgz)
+ozali --version
+```
+
+Para desinstalar: `npm rm -g ozali`.
+
+### c) Efímero, sin instalar en el PATH — como `npx`/`pnpm dlx`
+
+```bash
+npx ./ozali-0.8.0.tgz init        # corre init desde el tarball, sin dejar 'ozali' instalado
+pnpm dlx ./ozali-0.8.0.tgz init   # equivalente con pnpm
+```
+
+> **Nota de seguridad:** el flag `--ignore-scripts` que recomendamos para instalar desde npm es
+> irrelevante aquí, porque `ozali` **no tiene dependencias ni lifecycle scripts** (nada que ejecutar
+> en install). Detalle en [security.md](security.md).
+
+---
+
+## 5. Probar en un proyecto sandbox
+
+Crea un repo de juguete y corre el flujo real sin ensuciar nada:
+
+```bash
+mkdir /tmp/ozali-sandbox && cd /tmp/ozali-sandbox && git init
+
+# opción sin instalar: apunta al bin del clon
+node /ruta/al/clon/ozali/cli/bin/ozali.mjs init --dry-run          # muestra el plan, no escribe
+node /ruta/al/clon/ozali/cli/bin/ozali.mjs init --yes --no-engram  # init real, sin instalar Engram
+node /ruta/al/clon/ozali/cli/bin/ozali.mjs doctor                  # verifica el resultado
+```
+
+Para probar **workspaces multi-repo**, crea una carpeta con varios repos git dentro y corre:
+
+```bash
+node /ruta/al/clon/ozali/cli/bin/ozali.mjs workspace --dry-run     # inventario + plan, sin escribir
+node /ruta/al/clon/ozali/cli/bin/ozali.mjs workspace --doctor      # health-check de todos los miembros
+```
+
+(Si hiciste `npm link`, sustituye todo lo anterior por simplemente `ozali <comando>`.)
+
+---
+
+## 6. Verificar y limpiar
+
+```bash
+ozali --version                 # debe coincidir con la "version" de package.json
+npm rm -g ozali                 # desinstala el global (link o tarball)
+rm -f ozali-*.tgz               # borra el tarball de prueba
+rm -rf package/                 # borra la extracción del tarball, si la hiciste
+```
+
+---
+
+## Resumen
+
+| Quiero… | Comando |
+|---|---|
+| Correr sin instalar | `node cli/bin/ozali.mjs <cmd>` |
+| Correr los tests | `npm test` |
+| Empaquetar el distribuible | `npm pack` → `ozali-<version>.tgz` |
+| Ver el contenido del paquete | `npm pack --dry-run` |
+| Extraer el tarball | `tar -xzf ozali-<version>.tgz` → `package/` |
+| Desarrollar con `ozali` en PATH | `npm link` |
+| Probar el artefacto real | `npm i -g ./ozali-<version>.tgz` |
+| Probar efímero | `npx ./ozali-<version>.tgz init` |
+
+> ¿Buscas **publicar** una versión nueva (no solo probar)? Eso es otro flujo: bump de `version` en
+> `package.json` → commit → tag `vX.Y.Z` → push; el tag dispara la publicación a npm con provenance
+> vía GitHub Actions.

package/docs/guia-de-uso.md

@@ -81,6 +81,7 @@ Lleva el histórico y la memoria al repo de conocimiento del equipo. Tus compañ
 | Comando | Qué hace |
 |---|---|
 | `ozali init` | Prepara el proyecto (lo corres una vez por repo). |
+| `ozali workspace` | Configura varios repos de una carpeta para trabajar en conjunto (lo corres en la carpeta raíz). |
 | `ozali doctor` | Revisa que todo esté bien. Es solo lectura, no cambia nada. |
 | `ozali update` | Actualiza skill ozali + ozali-jarvis + permisos (y guía cómo regenerar cdk). |
 | `ozali sync` | Sube el histórico/memoria al repo de equipo. |
@@ -171,6 +172,51 @@ Atajos: `ozali audit --tui` abre un navegador interactivo de la memoria; `ozali
 busca un término; `ozali audit --general` fuerza el alcance general. Si no tienes Engram, audita el
 histórico local de `.ozali/docs/`.
 
+---
+
+## Trabajar con varios repos a la vez (`ozali workspace`)
+
+¿Tienes una carpeta que agrupa **varios repositorios que se hablan entre sí** (una API, su front, una
+librería compartida) y quieres que tu agente trabaje con todos juntos? Corre **una vez** en esa
+carpeta raíz:
+
+```bash
+ozali workspace             # escanea los repos hijos, prepara los que falten y arma la config conjunta
+ozali workspace --dry-run   # solo te muestra el inventario y el plan, sin escribir nada
+ozali workspace --yes       # sin preguntas: acepta los defaults y las referencias detectadas
+ozali workspace --depth 2   # busca repos hasta 2 niveles (si están en subcarpetas de grupo)
+```
+
+Qué hace, en orden:
+
+1. **Revisa** cada repo y te dice cómo está: `✔ listo`, `⚠ sin calibrar` (le falta correr la skill
+   `ozali`) o `✖ sin init` (nunca se preparó).
+2. **Prepara** los que están `✖ sin init` corriendo `ozali init` por ti, y te **guía** para calibrar
+   los que están `⚠ sin calibrar` (abrir ese repo y escribir *"diagnostica el proyecto"* — eso lo
+   hace tu agente, no el comando).
+3. **Detecta las referencias** entre repos (dependencias npm cruzadas, submódulos, `docker-compose`) y
+   te pide confirmarlas.
+4. **Escribe la configuración** para trabajar en conjunto:
+   - `ozali-workspace.json` — el mapa de repos, su estado y sus referencias (esto **sí** se commitea).
+   - `<carpeta>.code-workspace` — ábrelo en VSCode/Antigravity y verás todos los repos juntos.
+   - **ozali-workspace-jarvis** en el `CLAUDE.md`/`AGENTS.md` de la raíz: un orquestador que coordina
+     los repos según ese mapa y delega el trabajo de código en el `cdk` de cada uno.
+
+**Sin ir a cada proyecto:** desde la carpeta raíz puedes operar todos los repos de una vez:
+
+```bash
+ozali workspace --doctor    # revisa la salud de todos los repos y saca un resumen
+ozali workspace --update    # actualiza skills, permisos y jarvis de todos los repos
+```
+
+Y para **calibrar** (generar `cdk`) los que estén `⚠ sin calibrar`, ya **no** abres cada proyecto:
+abre tu agente en la carpeta raíz y pídele *"calibra los repos pendientes"* — el orquestador los
+recorre **uno por uno** (cada uno con su aprobación) sin que cambies de proyecto.
+
+Es **idempotente**: vuelve a correrlo cuando agregues un repo o cambien las referencias — no duplica
+nada. Cada repo conserva su autonomía (su propio jarvis, su `cdk` y su memoria); el workspace solo
+los **coordina**. Detalle completo en [workspaces.md](workspaces.md).
+
 ## Preguntas frecuentes
 
 **¿Tengo que usar Engram?**
@@ -185,6 +231,10 @@ Lo corriste con `dlx`/`npx`, que es temporal. Instálalo global: `pnpm add -g oz
 **¿Esto ensucia mi repositorio?**
 No. El histórico y la memoria se aíslan (`.ozali/`, `.engram/` van al `.gitignore`).
 
+**Tengo varios repos que dependen entre sí. ¿Los conecto?**
+Sí: abre la carpeta que los agrupa y corre `ozali workspace`. Prepara los que falten y arma una
+config para que tu agente trabaje con todos juntos. Ver [arriba](#trabajar-con-varios-repos-a-la-vez-ozali-workspace).
+
 **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

package/docs/workspaces.md

@@ -26,6 +26,18 @@ ozali workspace --no-trust   # no marca la raíz como confiable en Claude Code
 Un CLI **no puede auto-dispararse** con solo hacer `cd`; por eso es un comando explícito e
 **idempotente**: re-córrelo cuando agregues repos o cambien las referencias.
 
+### Operar todos los repos desde la raíz
+
+Para no entrar repo por repo, dos modos batch corren un comando sobre **todos los miembros**:
+
+```bash
+ozali workspace --doctor     # health-check de cada repo miembro + resumen consolidado
+ozali workspace --update     # actualiza skills/permisos/jarvis de cada repo + avisa de cdk desfasado
+```
+
+Ambos son **solo CLI** (no necesitan el agente) y saltan los repos `✖ sin init`. La **calibración**
+(generar `cdk`) sí la hace el agente, pero también **sin cambiar de proyecto** — ver abajo.
+
 ## Qué hace, paso a paso
 
 1. **Escaneo (read-only).** Enumera los repos git hijos y reporta el estado ozali de cada uno:
@@ -37,10 +49,11 @@ Un CLI **no puede auto-dispararse** con solo hacer `cd`; por eso es un comando e
    instala skills, aísla histórico, configura Engram). Hereda `agent`/`scope`/`knowledge-repo` de un
    repo ya inicializado para mantener el equipo consistente.
 
-3. **Guía de calibración.** El CLI **no calibra** (eso lo hace el agente). Para cada repo
-   `⚠ sin calibrar`, imprime la instrucción: abre ese repo en tu agente y corre la skill **`ozali`**
-   ("diagnostica el proyecto") para generar su `cdk`. El orquestador de workspace también queda
-   cableado para conducir esa calibración repo por repo.
+3. **Guía de calibración.** El CLI **no calibra** (eso lo hace el agente), pero ya **no** tienes que
+   abrir cada repo por separado: `ozali workspace` instala la skill **`ozali`** en la **raíz**, y el
+   orquestador `ozali-workspace-jarvis` la usa **en modo target** para calibrar cada repo
+   `⚠ sin calibrar` **desde el workspace**, repo por repo y con su propio 🛑 GATE. Abre el agente en la
+   raíz y pídele *"calibra los repos pendientes"*.
 
 4. **Referencias (auto-detección + confirmación).** Infiere aristas dirigidas `from → to`:
    - `npm-dep` — el `name` de un repo aparece en `dependencies`/`devDependencies`/`peerDependencies` de otro.
@@ -58,6 +71,7 @@ En la carpeta raíz:
 | `ozali-workspace.json` | Manifiesto: miembros (ruta, proyecto, estado, fuente de verdad), referencias, `knowledgeRepo`, cloud. Fuente de verdad del workspace. |
 | `<carpeta>.code-workspace` | Workspace **multi-root** de VSCode/Antigravity: abre todos los repos juntos. Merge idempotente si ya existe. |
 | `CLAUDE.md` / `AGENTS.md` (raíz) | Bloque marcado del orquestador **`ozali-workspace-jarvis`** + subagente / agente de opencode. |
+| `.claude/skills/ozali/` (raíz) | La skill **`ozali`** instalada en la raíz para **calibrar miembros en modo target** sin cambiar de proyecto (solo Claude Code). |
 
 Si la raíz es a su vez un repo git, se añade `.claude/`, `.engram/` y `.ozali/` a su `.gitignore`
 (los artefactos locales del agente no se commitean). `ozali-workspace.json` y `.code-workspace` **sí**
@@ -78,5 +92,5 @@ miembros). Su trabajo:
 ## Fuera de alcance (por ahora)
 
 - Auto-sugerencia al abrir la carpeta (tarea de editor/hook).
-- `ozali doctor`/`sync` agregados a nivel workspace.
+- `ozali sync` agregado a nivel workspace (`--doctor`/`--update` ya existen; falta `--sync`).
 - Detección de referencias más allá de npm/submódulos/compose (imports TS/py, `go.work`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ozali",
-  "version": "0.7.0",
+  "version": "0.8.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/SKILL.md

@@ -26,6 +26,28 @@ produce documentación, la calibración, el plan y los artefactos de la skill `c
 
 ---
 
+## Modo workspace — calibrar un repo miembro (target)
+
+Normalmente `ozali` opera sobre el **repo actual** (cwd). Pero cuando te invocan desde la **raíz de un
+workspace** (existe `ozali-workspace.json`) para calibrar un **repo miembro**, operas sobre un
+**target de subcarpeta** en vez del cwd. En ese caso:
+
+- **Todas las rutas son relativas al `<target>`**, no a la raíz: la fuente de verdad
+  (`<target>/AI.md` + `<target>/.ai/`, o su variante `IA.md` + `.ia/`), la skill que generas
+  (`<target>/.claude/skills/cdk/`), el histórico (`<target>/.ozali/docs/`) y
+  `<target>/.engram/config.json`.
+- **Identidad git del miembro:** usa `git -C <target> …` (no la raíz).
+- **Engram:** guarda con el `project_name` de `<target>/.engram/config.json` (equivale al
+  `members[].project` del manifiesto). **No mezcles** memoria entre repos.
+- **Un target por corrida**, secuencial, con su **propio 🛑 GATE**. No calibres varios a la vez sin
+  aprobación.
+- Al terminar, sugiere **re-correr `ozali workspace`** en la raíz para refrescar el estado del miembro
+  en el manifiesto (`needs-calibration` → `ready`).
+
+Si te invocan sin target (uso normal en un solo repo), ignora esta sección y sigue con el cwd.
+
+---
+
 ## Flujo general (7 fases)
 
 ```

package/templates/ozali-workspace-jarvis.md

@@ -13,29 +13,73 @@ ejecución disciplinada dentro de cada uno.
 > Cada repo miembro conserva su propia autonomía: su `ozali-jarvis`, su skill `cdk`, su fuente de
 > verdad (`.ai/`/`.ia/`) y su memoria Engram. Tú **no** los reemplazas: los **coordinas**.
 
+## El manifiesto (`ozali-workspace.json`) — tu única fuente de verdad
+
+Léelo en la raíz **antes de cualquier cosa**. Es lo que `ozali workspace` escribió; su esquema:
+
+- `members[]` — cada repo miembro:
+  - `path` — carpeta relativa a la raíz (el repo donde ejecutas).
+  - `project` — **nombre del proyecto en Engram** de ese repo. Úsalo para acotar la memoria (ver §1);
+    **no** dependas de `mem_current_project`, que detecta la raíz del workspace, no el miembro.
+  - `status` — `ready` / `needs-calibration` / `missing-init`. **Es una foto** del último
+    `ozali workspace`: puede haber quedado atrás (ver §2).
+  - `sot` — variante de fuente de verdad del repo (`ai`/`ia`/…) o `null` si no la tiene.
+- `references[]` — aristas dirigidas `{ from, to, kind }` entre miembros (`from` consume a `to`):
+  - `kind: "npm-dep"` — `from` declara a `to` en sus dependencias npm.
+  - `kind: "git-submodule"` — `to` está montado como submódulo dentro de `from`.
+  - `kind: "compose"` — un servicio de `from` construye desde `to` (`docker-compose`).
+- `knowledgeRepo` — repo de conocimiento **compartido** por el equipo (histórico + memoria sincronizada).
+- `cloud` — config de Engram Cloud (réplica de equipo) si está habilitada.
+- `agent` — agente objetivo (`claude-code` / `opencode` / `both`).
+
+**No inventes** miembros ni referencias: si algo no está en el manifiesto, no lo asumas.
+
 ## 1. Al iniciar (recall-first, a nivel workspace)
-- **Lee `ozali-workspace.json`** en la raíz: es la fuente de verdad de los **miembros**, su **estado**
-  (`ready` / `needs-calibration` / `missing-init`) y las **referencias** entre ellos (`from → to`).
-- Ubica la tarea: ¿qué repo(s) toca y a través de qué referencias impacta a otros?
-- Recupera contexto de memoria **de cada proyecto involucrado** (no de todos): confirma el proyecto de
-  cada repo con `mem_current_project` y usa `mem_search`/`mem_context` acotado a esos proyectos.
+- **Lee `ozali-workspace.json`** y ubica la tarea: ¿qué repo(s) toca y, vía qué `references`, impacta a
+  otros?
+- Recupera contexto de memoria **solo de los proyectos involucrados** (no de todos): para cada miembro
+  en juego usa su `members[].project` con `mem_search`/`mem_context` acotado a ese proyecto.
 - **Recuperación selectiva:** nunca vuelques toda la memoria; trae solo lo necesario por repo.
 
 ## 2. Antes de tocar código — verifica que el repo esté listo
-- Si un miembro está `missing-init`, dilo y sugiere `ozali init` en ese repo (o re-correr
-  `ozali workspace` en la raíz).
-- Si un miembro está `needs-calibration` (sin `cdk`), **condúcelo**: sugiere abrir ese repo y correr la
-  skill **`ozali`** ("diagnostica el proyecto") para generar su `cdk` antes de ejecutar cambios.
+- El `status` del manifiesto es una foto; **confírmalo contra la realidad** antes de confiar en él: un
+  repo está calibrado si existe `<path>/.claude/skills/cdk/SKILL.md`.
+- Si un miembro está `missing-init` (sin `.ozali/config.json`), dilo y sugiere `ozali init` en ese repo.
+- Si está `needs-calibration` (tiene init pero **falta `cdk`**), **condúcelo** desde aquí (ver sección
+  siguiente): ya **no** hace falta abrir cada repo por separado.
+- Si calibraste o inicializaste un repo desde aquí, el manifiesto quedó **desactualizado**: sugiere
+  re-correr `ozali workspace` en la raíz para refrescar estados y referencias.
+
+## Calibrar o preparar miembros desde la raíz (sin cambiar de proyecto)
+
+No abras cada repo por separado. Desde este workspace prepara y calibra en secuencia:
+
+- **`missing-init`** (sin `.ozali/config.json`): pide correr `ozali init <path>` en ese miembro, o
+  `ozali workspace` en la raíz (que lo inicializa por ti).
+- **`needs-calibration`** (falta `cdk`): invoca la skill **`ozali`** instalada en la raíz **en modo
+  target**, apuntando a `<path>` del miembro. Genera `AI.md`/`.ai/` y su `cdk` **dentro de esa
+  subcarpeta**, guardando en Engram con el `members[].project` de ese repo.
+- Hazlo **repo por repo, secuencialmente**, respetando el 🛑 **GATE** de cada uno: nunca calibres
+  varios sin aprobación.
+- Para **revisar** o **actualizar** todos de golpe (sin agente, solo CLI): `ozali workspace --doctor`
+  y `ozali workspace --update`.
+- Tras inicializar/calibrar, sugiere **re-correr `ozali workspace`** en la raíz para refrescar los
+  estados del manifiesto.
 
 ## 3. Para ejecutar cambios → delega en el repo correcto
 - Un cambio se ejecuta **dentro** del repo que le corresponde, usando **su** skill `cdk` (plan, GATE,
   TDD, docs por hito). Tú preparas el contexto cruzado; el `cdk` del repo ejecuta.
-- **Cambios que cruzan repos** (p. ej. un contrato de API que consume un front): secuencia el trabajo
-  siguiendo las `references` (primero el `to`/proveedor, luego el `from`/consumidor), y deja registrado
-  en la memoria de cada repo qué cambió y por qué, enlazando ambos lados.
+- **Cambios que cruzan repos:** secuencia según las `references`, **primero el `to` (proveedor), luego
+  el `from` (consumidor)**. Según el `kind`:
+  - `npm-dep` — publica/enlaza el paquete de `to` antes de que `from` consuma la nueva versión.
+  - `git-submodule` — actualiza `to`, luego mueve el puntero del submódulo en `from` y verifícalo.
+  - `compose` — reconstruye el servicio de `to` antes de levantar `from`.
+- Deja registrado en la memoria de **cada** repo qué cambió y por qué, enlazando ambos lados de la
+  referencia.
 
 ## 4. Al cerrar
-- Resume por repo tocado con `mem_session_summary` (solo el agente top-level).
+- Resume por repo tocado con `mem_session_summary` (solo el agente top-level), usando el `project` de
+  cada miembro.
 - Si el cambio afectó una referencia entre repos, anótalo en **ambos** proyectos para que el recall
   futuro lo encuentre desde cualquiera de los dos.