@cleocode/cleo 2026.4.17 → 2026.4.19

package/dist/cli/index.js

@@ -11114,13 +11114,54 @@ function reconcileJournal(nativeDb, migrationsFolder, existenceTable, logSubsyst
       }
     }
   }
+  if (tableExists(nativeDb, "__drizzle_migrations") && tableExists(nativeDb, existenceTable)) {
+    const localMigrations = readMigrationFiles({ migrationsFolder });
+    const journalEntries = nativeDb.prepare('SELECT hash FROM "__drizzle_migrations"').all();
+    const journaledHashes = new Set(journalEntries.map((e) => e.hash));
+    for (const migration of localMigrations) {
+      if (journaledHashes.has(migration.hash)) continue;
+      const alterColumnRegex = /ALTER\s+TABLE\s+[`"]?(\w+)[`"]?\s+ADD\s+COLUMN\s+[`"]?(\w+)[`"]?/gi;
+      const alterMatches = [];
+      const sqlStatements = Array.isArray(migration.sql) ? migration.sql : [migration.sql ?? ""];
+      const fullSql = sqlStatements.join("\n");
+      for (const m2 of fullSql.matchAll(alterColumnRegex)) {
+        alterMatches.push({ table: m2[1], column: m2[2] });
+      }
+      if (alterMatches.length === 0) continue;
+      const allColumnsExist = alterMatches.every(({ table, column }) => {
+        if (!tableExists(nativeDb, table)) return false;
+        const cols = nativeDb.prepare(`PRAGMA table_info(${table})`).all();
+        return cols.some((c) => c.name === column);
+      });
+      if (allColumnsExist) {
+        const log11 = getLogger(logSubsystem);
+        log11.warn(
+          { migration: migration.name, columns: alterMatches },
+          `Detected partially-applied migration ${migration.name} \u2014 columns exist but journal entry missing. Auto-reconciling.`
+        );
+        nativeDb.exec(
+          `INSERT INTO "__drizzle_migrations" ("hash", "created_at") VALUES ('${migration.hash}', ${migration.folderMillis})`
+        );
+      }
+    }
+  }
+}
+function isDuplicateColumnError(err) {
+  if (!(err instanceof Error)) return false;
+  return /duplicate column name/i.test(err.message);
 }
-function migrateWithRetry(db, migrationsFolder) {
+function migrateWithRetry(db, migrationsFolder, nativeDb, existenceTable, logSubsystem) {
+  let duplicateColumnReconciled = false;
   for (let attempt = 1; attempt <= MAX_MIGRATION_RETRIES; attempt++) {
     try {
       migrate(db, { migrationsFolder });
       return;
     } catch (err) {
+      if (isDuplicateColumnError(err) && !duplicateColumnReconciled && nativeDb !== void 0 && existenceTable !== void 0 && logSubsystem !== void 0) {
+        duplicateColumnReconciled = true;
+        reconcileJournal(nativeDb, migrationsFolder, existenceTable, logSubsystem);
+        continue;
+      }
       if (!isSqliteBusy(err) || attempt === MAX_MIGRATION_RETRIES) {
         throw err;
       }
@@ -13478,7 +13519,7 @@ function runMigrations(nativeDb, db) {
   }
   reconcileJournal(nativeDb, migrationsFolder, "tasks", "sqlite");
   ensureColumns(nativeDb, "sessions", REQUIRED_SESSION_COLUMNS, "sqlite");
-  migrateWithRetry(db, migrationsFolder);
+  migrateWithRetry(db, migrationsFolder, nativeDb, "tasks", "sqlite");
   ensureColumns(nativeDb, "tasks", REQUIRED_TASK_COLUMNS, "sqlite");
 }
 function closeDb() {
@@ -13604,7 +13645,7 @@ function runBrainMigrations(nativeDb, db) {
     createSafetyBackup(_dbPath2);
   }
   reconcileJournal(nativeDb, migrationsFolder, "brain_decisions", "brain");
-  migrateWithRetry(db, migrationsFolder);
+  migrateWithRetry(db, migrationsFolder, nativeDb, "brain_decisions", "brain");
 }
 function loadBrainVecExtension(nativeDb) {
   try {
@@ -34416,9 +34457,15 @@ async function addTask(options, cwd, accessor) {
     if (lifecycleMode === "strict") {
       throw new CleoError(
         6 /* VALIDATION_ERROR */,
-        'Tasks must have a parent (epic or task) in strict mode. Use --parent <epicId> or set lifecycle.mode to "advisory".',
+        'Tasks must have a parent (epic or task) in strict mode. Use --parent <epicId>, --type epic for a root-level epic, or set lifecycle.mode to "advisory".',
         {
-          fix: 'cleo add "Task title" --parent T### --acceptance "AC1|AC2|AC3"'
+          fix: 'cleo add "Task title" --parent T### --acceptance "AC1|AC2|AC3"',
+          alternatives: [
+            {
+              action: "Create as epic",
+              command: 'cleo add "Epic title" --type epic --priority high'
+            }
+          ]
         }
       );
     }
@@ -74007,6 +74054,57 @@ async function initProject(opts = {}) {
       ".cleo/ was found in root .gitignore and has been removed. CLEO uses .cleo/.gitignore for selective tracking."
     );
   }
+  try {
+    const cantDir = join105(cleoDir, "cant");
+    const cantAgentsDir = join105(cantDir, "agents");
+    const hasCantFiles = existsSync106(cantDir) && readdirSync36(cantDir, { recursive: true }).some(
+      (f2) => typeof f2 === "string" && f2.endsWith(".cant")
+    );
+    if (!hasCantFiles) {
+      let starterBundleSrc = null;
+      try {
+        const { createRequire: createRequire13 } = await import("node:module");
+        const req = createRequire13(import.meta.url);
+        const cleoOsPkgMain = req.resolve("@cleocode/cleo-os/package.json");
+        const cleoOsPkgRoot = dirname21(cleoOsPkgMain);
+        const candidate = join105(cleoOsPkgRoot, "starter-bundle");
+        if (existsSync106(candidate)) {
+          starterBundleSrc = candidate;
+        }
+      } catch {
+      }
+      if (!starterBundleSrc) {
+        const packageRoot = getPackageRoot();
+        const fallbacks = [
+          join105(packageRoot, "..", "cleo-os", "starter-bundle"),
+          join105(packageRoot, "..", "..", "packages", "cleo-os", "starter-bundle")
+        ];
+        starterBundleSrc = fallbacks.find((p2) => existsSync106(p2)) ?? null;
+      }
+      if (starterBundleSrc) {
+        await mkdir16(cantDir, { recursive: true });
+        await mkdir16(cantAgentsDir, { recursive: true });
+        const teamSrc = join105(starterBundleSrc, "team.cant");
+        const teamDst = join105(cantDir, "team.cant");
+        if (existsSync106(teamSrc) && !existsSync106(teamDst)) {
+          await copyFile4(teamSrc, teamDst);
+        }
+        const agentsSrc = join105(starterBundleSrc, "agents");
+        if (existsSync106(agentsSrc)) {
+          const agentFiles = readdirSync36(agentsSrc).filter((f2) => f2.endsWith(".cant"));
+          for (const agentFile of agentFiles) {
+            const dst = join105(cantAgentsDir, agentFile);
+            if (!existsSync106(dst)) {
+              await copyFile4(join105(agentsSrc, agentFile), dst);
+            }
+          }
+        }
+        created.push("starter-bundle: team + agent .cant files deployed to .cleo/cant/");
+      }
+    }
+  } catch (err) {
+    warnings.push(`Starter bundle deploy: ${err instanceof Error ? err.message : String(err)}`);
+  }
   if (opts.installSeedAgents) {
     try {
       const seedDir = await resolveSeedAgentsDir();
@@ -100331,7 +100429,7 @@ var init_normalizer = __esm({
 });
 
 // packages/cleo/src/cli/renderers/colors.ts
-function ansi(code) {
+function ansi2(code) {
   return colorsEnabled ? code : "";
 }
 function statusSymbol(status) {
@@ -100424,15 +100522,15 @@ var init_colors = __esm({
       if (lang === "C" || lang === "POSIX") return false;
       return lang.includes("UTF") || process.platform === "darwin";
     })();
-    BOLD = ansi("\x1B[1m");
-    DIM = ansi("\x1B[2m");
-    NC = ansi("\x1B[0m");
-    RED = ansi("\x1B[0;31m");
-    GREEN = ansi("\x1B[0;32m");
-    YELLOW = ansi("\x1B[1;33m");
-    BLUE = ansi("\x1B[0;34m");
-    MAGENTA = ansi("\x1B[0;35m");
-    CYAN = ansi("\x1B[0;36m");
+    BOLD = ansi2("\x1B[1m");
+    DIM = ansi2("\x1B[2m");
+    NC = ansi2("\x1B[0m");
+    RED = ansi2("\x1B[0;31m");
+    GREEN = ansi2("\x1B[0;32m");
+    YELLOW = ansi2("\x1B[1;33m");
+    BLUE = ansi2("\x1B[0;34m");
+    MAGENTA = ansi2("\x1B[0;35m");
+    CYAN = ansi2("\x1B[0;36m");
     BOX = unicodeEnabled ? {
       tl: "\u256D",
       tr: "\u256E",
@@ -111593,6 +111691,12 @@ async function orchestrateClassify(request, context, projectRoot) {
     };
   }
 }
+function evictFanoutManifest() {
+  while (fanoutManifestStore.size > FANOUT_MANIFEST_MAX_SIZE) {
+    const oldest = fanoutManifestStore.keys().next().value;
+    if (oldest !== void 0) fanoutManifestStore.delete(oldest);
+  }
+}
 async function orchestrateFanout(items, projectRoot) {
   const manifestEntryId = `fanout-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   try {
@@ -111637,6 +111741,7 @@ async function orchestrateFanout(items, projectRoot) {
       results,
       completedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
+    evictFanoutManifest();
     return {
       success: true,
       data: {
@@ -111738,7 +111843,7 @@ async function orchestrateAnalyzeParallelSafety(taskIds, projectRoot) {
     };
   }
 }
-var OrchestrateHandler, fanoutManifestStore;
+var OrchestrateHandler, FANOUT_MANIFEST_MAX_SIZE, fanoutManifestStore;
 var init_orchestrate2 = __esm({
   "packages/cleo/src/dispatch/domains/orchestrate.ts"() {
     "use strict";
@@ -112222,6 +112327,7 @@ var init_orchestrate2 = __esm({
         };
       }
     };
+    FANOUT_MANIFEST_MAX_SIZE = 64;
     fanoutManifestStore = /* @__PURE__ */ new Map();
   }
 });
@@ -116140,11 +116246,11 @@ var CLIError = class extends Error {
 function parseRawArgs(args = [], opts = {}) {
   const booleans = new Set(opts.boolean || []);
   const strings = new Set(opts.string || []);
-  const aliasMap = opts.alias || {};
+  const aliasMap2 = opts.alias || {};
   const defaults = opts.default || {};
   const aliasToMain = /* @__PURE__ */ new Map();
   const mainToAliases = /* @__PURE__ */ new Map();
-  for (const [key, value] of Object.entries(aliasMap)) {
+  for (const [key, value] of Object.entries(aliasMap2)) {
     const targets = value;
     for (const target of targets) {
       aliasToMain.set(key, target);
@@ -116165,8 +116271,8 @@ function parseRawArgs(args = [], opts = {}) {
   const allOptions = /* @__PURE__ */ new Set([
     ...booleans,
     ...strings,
-    ...Object.keys(aliasMap),
-    ...Object.values(aliasMap).flat(),
+    ...Object.keys(aliasMap2),
+    ...Object.values(aliasMap2).flat(),
     ...Object.keys(defaults)
   ]);
   for (const name2 of allOptions) if (!options[name2]) options[name2] = {
@@ -116582,6 +116688,237 @@ function camelToKebab2(str) {
 init_field_context();
 init_format_context();
 
+// packages/cleo/src/cli/help-renderer.ts
+var noColor2 = (() => {
+  const env = globalThis.process?.env ?? {};
+  return env.NO_COLOR === "1" || env.TERM === "dumb" || env.TEST || env.CI;
+})();
+var ansi = (code, reset = 39) => (t) => noColor2 ? t : `\x1B[${code}m${t}\x1B[${reset}m`;
+var bold2 = ansi(1, 22);
+var cyan2 = ansi(36);
+var gray2 = ansi(90);
+var underline2 = ansi(4, 24);
+var IMPLICIT_ALIASES = {
+  tags: "labels"
+};
+var NATIVE_COMMAND_DESCS = {
+  version: "Display CLEO version",
+  code: "Code analysis via tree-sitter AST"
+};
+var COMMAND_GROUPS = [
+  {
+    name: "Task Management",
+    commands: [
+      "add",
+      "show",
+      "find",
+      "list",
+      "update",
+      "complete",
+      "delete",
+      "start",
+      "stop",
+      "current",
+      "next",
+      "exists",
+      "bug"
+    ]
+  },
+  {
+    name: "Task Organization",
+    commands: [
+      "archive",
+      "labels",
+      "promote",
+      "relates",
+      "reorder",
+      "reparent",
+      "deps",
+      "tree",
+      "blockers"
+    ]
+  },
+  {
+    name: "Sessions & Planning",
+    commands: ["session", "briefing", "dash", "plan", "safestop", "context"]
+  },
+  {
+    name: "Phases & Lifecycle",
+    commands: ["phase", "phases", "lifecycle", "release", "roadmap"]
+  },
+  {
+    name: "Memory & Notes",
+    commands: ["memory", "brain", "observe", "refresh-memory", "sticky", "reason"]
+  },
+  {
+    name: "Analysis & Stats",
+    commands: ["analyze", "stats", "history", "archive-stats"]
+  },
+  {
+    name: "Validation & Compliance",
+    commands: [
+      "check",
+      "validate",
+      "verify",
+      "testing",
+      "compliance",
+      "implementation",
+      "specification",
+      "consensus",
+      "contribution",
+      "decomposition",
+      "backfill"
+    ]
+  },
+  {
+    name: "Code & Documentation",
+    commands: ["code", "docs", "detect-drift", "map"]
+  },
+  {
+    name: "Research & Orchestration",
+    commands: ["research", "orchestrate"]
+  },
+  {
+    name: "Import / Export",
+    commands: ["export", "import", "export-tasks", "import-tasks", "snapshot", "inject"]
+  },
+  {
+    name: "Collaboration",
+    commands: ["nexus", "remote", "push", "pull", "checkpoint"]
+  },
+  {
+    name: "Agents",
+    commands: ["agent", "grade"]
+  },
+  {
+    name: "System & Admin",
+    commands: [
+      "version",
+      "init",
+      "config",
+      "env",
+      "admin",
+      "doctor",
+      "upgrade",
+      "self-update",
+      "commands",
+      "ops",
+      "schema",
+      "log",
+      "sequence",
+      "adr",
+      "cant",
+      "token",
+      "otel",
+      "migrate",
+      "detect",
+      "generate-changelog",
+      "issue",
+      "skills",
+      "web",
+      "backup",
+      "restore"
+    ]
+  }
+];
+function buildAliasMap(shims) {
+  const map2 = /* @__PURE__ */ new Map();
+  for (const shim of shims) {
+    for (const alias of shim._aliases) {
+      map2.set(alias, shim._name);
+    }
+  }
+  for (const [alias, primary] of Object.entries(IMPLICIT_ALIASES)) {
+    map2.set(alias, primary);
+  }
+  return map2;
+}
+function getShortDescription(desc7) {
+  if (!desc7) return "";
+  const match = desc7.match(/^Description:\s*(.+)/);
+  if (match) return match[1].trim();
+  const firstLine = desc7.split("\n").find((l) => l.trim().length > 0);
+  return firstLine?.trim() ?? desc7.trim();
+}
+function renderGroupedHelp(version2, shims, aliasMap2) {
+  const descMap = /* @__PURE__ */ new Map();
+  for (const shim of shims) {
+    descMap.set(shim._name, getShortDescription(shim._description));
+  }
+  for (const [name2, desc7] of Object.entries(NATIVE_COMMAND_DESCS)) {
+    if (!descMap.has(name2)) {
+      descMap.set(name2, desc7);
+    }
+  }
+  const cmdAliases = /* @__PURE__ */ new Map();
+  for (const [alias, primary] of aliasMap2) {
+    const existing = cmdAliases.get(primary) ?? [];
+    existing.push(alias);
+    cmdAliases.set(primary, existing);
+  }
+  let maxCmdWidth = 0;
+  const allGroupedCmds = COMMAND_GROUPS.flatMap((g2) => g2.commands);
+  const allCmds = [.../* @__PURE__ */ new Set([...allGroupedCmds, ...shims.map((s3) => s3._name), "version"])];
+  for (const cmd of allCmds) {
+    if (!descMap.has(cmd) || aliasMap2.has(cmd)) continue;
+    const aliases = cmdAliases.get(cmd);
+    const display = aliases && aliases.length > 0 ? `${cmd} (${aliases.join(", ")})` : cmd;
+    if (display.length > maxCmdWidth) maxCmdWidth = display.length;
+  }
+  const lines = [];
+  lines.push(gray2(`CLEO V2 - Task management for AI coding agents (cleo v${version2})`));
+  lines.push("");
+  lines.push(`${underline2(bold2("USAGE"))} ${cyan2("cleo <command> [OPTIONS]")}`);
+  lines.push("");
+  const rendered = /* @__PURE__ */ new Set();
+  for (const group of COMMAND_GROUPS) {
+    const groupLines = [];
+    for (const cmd of group.commands) {
+      if (!descMap.has(cmd)) continue;
+      rendered.add(cmd);
+      const aliases = cmdAliases.get(cmd);
+      const display = aliases && aliases.length > 0 ? `${cmd} (${aliases.join(", ")})` : cmd;
+      const desc7 = descMap.get(cmd) ?? "";
+      groupLines.push(`  ${cyan2(display.padEnd(maxCmdWidth + 2))}${desc7}`);
+    }
+    if (groupLines.length > 0) {
+      lines.push(underline2(bold2(group.name.toUpperCase())));
+      lines.push(...groupLines);
+      lines.push("");
+    }
+  }
+  const ungrouped = [];
+  for (const shim of shims) {
+    if (!rendered.has(shim._name) && !aliasMap2.has(shim._name)) {
+      ungrouped.push(shim._name);
+    }
+  }
+  if (ungrouped.length > 0) {
+    lines.push(underline2(bold2("OTHER")));
+    for (const cmd of ungrouped) {
+      const aliases = cmdAliases.get(cmd);
+      const display = aliases && aliases.length > 0 ? `${cmd} (${aliases.join(", ")})` : cmd;
+      const desc7 = descMap.get(cmd) ?? "";
+      lines.push(`  ${cyan2(display.padEnd(maxCmdWidth + 2))}${desc7}`);
+    }
+    lines.push("");
+  }
+  lines.push(`Use ${cyan2("cleo <command> --help")} for more information about a command.`);
+  return lines.join("\n");
+}
+function createCustomShowUsage(version2, shims, aliasMap2) {
+  return async (cmd, parent) => {
+    if (!parent) {
+      const meta3 = await (typeof cmd.meta === "function" ? cmd.meta() : cmd.meta);
+      if (meta3?.name === "cleo") {
+        console.log(renderGroupedHelp(version2, shims, aliasMap2) + "\n");
+        return;
+      }
+    }
+    await showUsage(cmd, parent);
+  };
+}
+
 // packages/cleo/src/cli/middleware/output-format.ts
 import { resolveOutputFormat } from "@cleocode/lafs";
 function resolveFormat2(opts, defaults) {
@@ -118220,6 +118557,786 @@ Task ${taskId} reassigned to you by ${active.agentId}. Run: cleo show ${taskId}
       { command: "agent health" }
     );
   });
+  agent.command("install <path>").description("Install an agent from a .cantz archive or agent directory").option("--global", "Install to global tier (~/.local/share/cleo/cant/agents/)").action(async (sourcePath, opts) => {
+    try {
+      const { existsSync: existsSync131, mkdirSync: mkdirSync31, cpSync, readFileSync: readFileSync101, rmSync: rmSync3, statSync: statSync22 } = await import("node:fs");
+      const { join: join131, basename: basename19, resolve: resolve16 } = await import("node:path");
+      const { homedir: homedir7 } = await import("node:os");
+      const { tmpdir: tmpdir3 } = await import("node:os");
+      const resolvedPath = resolve16(sourcePath);
+      if (!existsSync131(resolvedPath)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_NOT_FOUND",
+              message: `Path does not exist: ${resolvedPath}`
+            }
+          },
+          { command: "agent install" }
+        );
+        process.exitCode = 4;
+        return;
+      }
+      let agentDir;
+      let agentName;
+      let tempDir = null;
+      const isCantzArchive = resolvedPath.endsWith(".cantz") && statSync22(resolvedPath).isFile();
+      if (isCantzArchive) {
+        const { execFileSync: execFileSync19 } = await import("node:child_process");
+        tempDir = join131(tmpdir3(), `cleo-agent-install-${Date.now()}`);
+        mkdirSync31(tempDir, { recursive: true });
+        try {
+          execFileSync19("unzip", ["-o", "-q", resolvedPath, "-d", tempDir], {
+            encoding: "utf-8",
+            timeout: 3e4
+          });
+        } catch (unzipErr) {
+          if (tempDir) rmSync3(tempDir, { recursive: true, force: true });
+          cliOutput(
+            {
+              success: false,
+              error: {
+                code: "E_VALIDATION",
+                message: `Failed to extract .cantz archive: ${String(unzipErr)}`
+              }
+            },
+            { command: "agent install" }
+          );
+          process.exitCode = 6;
+          return;
+        }
+        const { readdirSync: readdirSync42 } = await import("node:fs");
+        const topLevel = readdirSync42(tempDir).filter((entry) => {
+          const entryPath = join131(tempDir, entry);
+          return statSync22(entryPath).isDirectory();
+        });
+        if (topLevel.length !== 1) {
+          if (tempDir) rmSync3(tempDir, { recursive: true, force: true });
+          cliOutput(
+            {
+              success: false,
+              error: {
+                code: "E_VALIDATION",
+                message: `Archive must contain exactly one top-level directory, found ${topLevel.length}`
+              }
+            },
+            { command: "agent install" }
+          );
+          process.exitCode = 6;
+          return;
+        }
+        agentName = topLevel[0];
+        agentDir = join131(tempDir, agentName);
+      } else if (statSync22(resolvedPath).isDirectory()) {
+        agentDir = resolvedPath;
+        agentName = basename19(resolvedPath);
+      } else {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Path must be a .cantz file or a directory: ${resolvedPath}`
+            }
+          },
+          { command: "agent install" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      const personaPath = join131(agentDir, "persona.cant");
+      if (!existsSync131(personaPath)) {
+        if (tempDir) rmSync3(tempDir, { recursive: true, force: true });
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Agent directory must contain persona.cant: ${personaPath}`
+            }
+          },
+          { command: "agent install" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      const isGlobal = opts["global"] === true;
+      let targetRoot;
+      if (isGlobal) {
+        const home = homedir7();
+        const xdgData = process.env["XDG_DATA_HOME"] ?? join131(home, ".local", "share");
+        targetRoot = join131(xdgData, "cleo", "cant", "agents");
+      } else {
+        targetRoot = join131(process.cwd(), ".cleo", "cant", "agents");
+      }
+      const targetDir = join131(targetRoot, agentName);
+      mkdirSync31(targetRoot, { recursive: true });
+      cpSync(agentDir, targetDir, { recursive: true, force: true });
+      if (tempDir) {
+        rmSync3(tempDir, { recursive: true, force: true });
+      }
+      let registered = false;
+      try {
+        const persona = readFileSync101(join131(targetDir, "persona.cant"), "utf-8");
+        const descMatch = persona.match(/description:\s*"([^"]+)"/);
+        const displayName = descMatch?.[1] ?? agentName;
+        const { AgentRegistryAccessor: AgentRegistryAccessor2, getDb: getDb4 } = await Promise.resolve().then(() => (init_internal(), internal_exports));
+        await getDb4();
+        const registry2 = new AgentRegistryAccessor2(process.cwd());
+        const existing = await registry2.get(agentName);
+        if (!existing) {
+          await registry2.register({
+            agentId: agentName,
+            displayName,
+            apiKey: "local-installed",
+            apiBaseUrl: "local",
+            classification: "specialist",
+            privacyTier: "private",
+            capabilities: [],
+            skills: [],
+            transportType: "http",
+            transportConfig: {},
+            isActive: false
+          });
+          registered = true;
+        }
+      } catch {
+      }
+      cliOutput(
+        {
+          success: true,
+          data: {
+            agent: agentName,
+            tier: isGlobal ? "global" : "project",
+            path: targetDir,
+            registered
+          }
+        },
+        { command: "agent install" }
+      );
+    } catch (err) {
+      cliOutput(
+        { success: false, error: { code: "E_INSTALL", message: String(err) } },
+        { command: "agent install" }
+      );
+      process.exitCode = 1;
+    }
+  });
+  agent.command("pack <dir>").description("Package an agent directory as a .cantz archive").action(async (dir) => {
+    try {
+      const { existsSync: existsSync131, statSync: statSync22 } = await import("node:fs");
+      const { resolve: resolve16, basename: basename19, dirname: dirname29 } = await import("node:path");
+      const { execFileSync: execFileSync19 } = await import("node:child_process");
+      const resolvedDir = resolve16(dir);
+      if (!existsSync131(resolvedDir) || !statSync22(resolvedDir).isDirectory()) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_NOT_FOUND",
+              message: `Directory does not exist: ${resolvedDir}`
+            }
+          },
+          { command: "agent pack" }
+        );
+        process.exitCode = 4;
+        return;
+      }
+      const { join: join131 } = await import("node:path");
+      const personaPath = join131(resolvedDir, "persona.cant");
+      if (!existsSync131(personaPath)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Agent directory must contain persona.cant: ${personaPath}`
+            }
+          },
+          { command: "agent pack" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      const agentName = basename19(resolvedDir);
+      const archiveName = `${agentName}.cantz`;
+      const archivePath = resolve16(archiveName);
+      const parentDir = dirname29(resolvedDir);
+      try {
+        execFileSync19("zip", ["-r", archivePath, agentName], {
+          cwd: parentDir,
+          encoding: "utf-8",
+          timeout: 3e4
+        });
+      } catch (zipErr) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_PACK",
+              message: `Failed to create archive: ${String(zipErr)}`
+            }
+          },
+          { command: "agent pack" }
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const archiveStats = statSync22(archivePath);
+      const { readdirSync: readdirSync42 } = await import("node:fs");
+      let fileCount = 0;
+      const countFiles2 = (dirPath) => {
+        const entries = readdirSync42(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isFile()) {
+            fileCount++;
+          } else if (entry.isDirectory()) {
+            countFiles2(join131(dirPath, entry.name));
+          }
+        }
+      };
+      countFiles2(resolvedDir);
+      cliOutput(
+        {
+          success: true,
+          data: {
+            archive: archivePath,
+            agent: agentName,
+            files: fileCount,
+            size: archiveStats.size
+          }
+        },
+        { command: "agent pack" }
+      );
+    } catch (err) {
+      cliOutput(
+        { success: false, error: { code: "E_PACK", message: String(err) } },
+        { command: "agent pack" }
+      );
+      process.exitCode = 1;
+    }
+  });
+  agent.command("create").description("Scaffold a new agent package with persona.cant and manifest.json").requiredOption("--name <name>", "Agent name (kebab-case)").requiredOption("--role <role>", "Agent role: orchestrator, lead, worker, or docs-worker").option("--tier <tier>", "Agent tier: low, mid, or high (defaults based on role)").option("--team <teamName>", "Team this agent belongs to").option("--domain <description>", "Domain description for file permissions and context").option("--global", "Create in global tier (~/.local/share/cleo/cant/agents/)").option("--seed-brain", "Create expertise/mental-model-seed.md and seed a BRAIN observation").option("--parent <parentAgent>", "Parent agent name in the hierarchy").action(async (opts) => {
+    try {
+      const { existsSync: existsSync131, mkdirSync: mkdirSync31, writeFileSync: writeFileSync25 } = await import("node:fs");
+      const { join: join131 } = await import("node:path");
+      const { homedir: homedir7 } = await import("node:os");
+      const name2 = opts["name"];
+      const role = opts["role"];
+      const tier = opts["tier"] ?? inferTierFromRole(role);
+      const team = opts["team"];
+      const domain2 = opts["domain"];
+      const isGlobal = opts["global"] === true;
+      const seedBrain = opts["seedBrain"] === true;
+      const parent = opts["parent"];
+      const validRoles = ["orchestrator", "lead", "worker", "docs-worker"];
+      if (!validRoles.includes(role)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Invalid role "${role}". Must be one of: ${validRoles.join(", ")}`,
+              fix: `cleo agent create --name ${name2} --role worker`
+            }
+          },
+          { command: "agent create" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      const validTiers = ["low", "mid", "high"];
+      if (!validTiers.includes(tier)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Invalid tier "${tier}". Must be one of: ${validTiers.join(", ")}`,
+              fix: `cleo agent create --name ${name2} --role ${role} --tier mid`
+            }
+          },
+          { command: "agent create" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name2)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Agent name must be kebab-case: "${name2}"`,
+              fix: "Use lowercase letters, numbers, and hyphens. Must start with a letter."
+            }
+          },
+          { command: "agent create" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      let targetRoot;
+      if (isGlobal) {
+        const home = homedir7();
+        const xdgData = process.env["XDG_DATA_HOME"] ?? join131(home, ".local", "share");
+        targetRoot = join131(xdgData, "cleo", "cant", "agents");
+      } else {
+        targetRoot = join131(process.cwd(), ".cleo", "cant", "agents");
+      }
+      const agentDir = join131(targetRoot, name2);
+      if (existsSync131(agentDir)) {
+        cliOutput(
+          {
+            success: false,
+            error: {
+              code: "E_VALIDATION",
+              message: `Agent directory already exists: ${agentDir}`,
+              fix: "Remove the existing directory or choose a different name."
+            }
+          },
+          { command: "agent create" }
+        );
+        process.exitCode = 6;
+        return;
+      }
+      mkdirSync31(agentDir, { recursive: true });
+      const personaContent = generatePersonaCant({
+        name: name2,
+        role,
+        tier,
+        team,
+        domain: domain2,
+        parent
+      });
+      writeFileSync25(join131(agentDir, "persona.cant"), personaContent, "utf-8");
+      const manifest = generateManifest2({ name: name2, role, tier, domain: domain2 });
+      writeFileSync25(
+        join131(agentDir, "manifest.json"),
+        `${JSON.stringify(manifest, null, 2)}
+`,
+        "utf-8"
+      );
+      const createdFiles = [
+        join131(agentDir, "persona.cant"),
+        join131(agentDir, "manifest.json")
+      ];
+      if (team) {
+        const teamConfigContent = generateTeamConfig(name2, role, team);
+        writeFileSync25(join131(agentDir, "team-config.cant"), teamConfigContent, "utf-8");
+        createdFiles.push(join131(agentDir, "team-config.cant"));
+      }
+      if (seedBrain) {
+        const expertiseDir = join131(agentDir, "expertise");
+        mkdirSync31(expertiseDir, { recursive: true });
+        const seedContent = generateMentalModelSeed(name2, role, domain2);
+        writeFileSync25(join131(expertiseDir, "mental-model-seed.md"), seedContent, "utf-8");
+        createdFiles.push(join131(expertiseDir, "mental-model-seed.md"));
+        try {
+          const { execFile: execFile9 } = await import("node:child_process");
+          const { promisify: promisify9 } = await import("node:util");
+          const execFileAsync6 = promisify9(execFile9);
+          await execFileAsync6(
+            "cleo",
+            [
+              "observe",
+              `Agent ${name2} created with role ${role}`,
+              "--title",
+              `Agent creation: ${name2}`
+            ],
+            { encoding: "utf-8", timeout: 1e4 }
+          ).catch(() => {
+          });
+        } catch {
+        }
+      }
+      let registered = false;
+      try {
+        const { AgentRegistryAccessor: AgentRegistryAccessor2, getDb: getDb4 } = await Promise.resolve().then(() => (init_internal(), internal_exports));
+        await getDb4();
+        const registry2 = new AgentRegistryAccessor2(process.cwd());
+        const existing = await registry2.get(name2);
+        if (!existing) {
+          const descMatch = personaContent.match(/description:\s*"([^"]+)"/);
+          const displayName = descMatch?.[1] ?? name2;
+          await registry2.register({
+            agentId: name2,
+            displayName,
+            apiKey: "local-created",
+            apiBaseUrl: "local",
+            classification: role,
+            privacyTier: "private",
+            capabilities: [],
+            skills: [],
+            transportType: "http",
+            transportConfig: {},
+            isActive: false
+          });
+          registered = true;
+        }
+      } catch {
+      }
+      cliOutput(
+        {
+          success: true,
+          data: {
+            agent: name2,
+            role,
+            tier,
+            directory: agentDir,
+            scope: isGlobal ? "global" : "project",
+            files: createdFiles,
+            registered,
+            brainSeeded: seedBrain
+          }
+        },
+        { command: "agent create" }
+      );
+    } catch (err) {
+      cliOutput(
+        { success: false, error: { code: "E_CREATE", message: String(err) } },
+        { command: "agent create" }
+      );
+      process.exitCode = 1;
+    }
+  });
+}
+function inferTierFromRole(role) {
+  if (role === "orchestrator") return "high";
+  return "mid";
+}
+function generatePersonaCant(params) {
+  const { name: name2, role, tier, team, domain: domain2, parent } = params;
+  switch (role) {
+    case "orchestrator":
+      return generateOrchestratorPersona(name2, tier, team, parent);
+    case "lead":
+      return generateLeadPersona(name2, tier, team, domain2, parent);
+    case "worker":
+      return generateWorkerPersona(name2, tier, team, domain2, parent);
+    case "docs-worker":
+      return generateDocsWorkerPersona(name2, tier, team, domain2, parent);
+    default:
+      return generateWorkerPersona(name2, tier, team, domain2, parent);
+  }
+}
+function generateOrchestratorPersona(name2, tier, team, parent) {
+  const parentLine = parent ? `
+  parent: ${parent}` : "";
+  const teamComment = team ? `
+# Team: ${team}` : "";
+  return `---
+kind: agent
+version: "1"
+---
+
+# ${name2} \u2014 orchestrator agent.${teamComment}
+# Coordinates the team, classifies work, dispatches to leads/workers.
+
+agent ${name2}:
+  role: orchestrator${parentLine}
+  tier: ${tier}
+  description: "Orchestrator agent. Reads task context, classifies work, dispatches to leads, and synthesizes results. Does not execute code \u2014 coordinates."
+  consult-when: "Cross-team decisions, scope changes, human-in-the-loop escalation, or when a lead reports a blocking ambiguity"
+
+  context_sources:
+    - source: decisions
+      query: "recent architectural and project decisions"
+      max_entries: 5
+    - source: patterns
+      query: "project conventions and established patterns"
+      max_entries: 3
+  on_overflow: escalate_tier
+
+  mental_model:
+    scope: project
+    max_tokens: 2000
+    on_load:
+      validate: true
+
+  permissions:
+    tasks: read, write
+    session: read, write
+    memory: read, write
+
+  skills:
+    - ct-cleo
+    - ct-task-executor
+
+  tools:
+    core: [Read, Grep, Glob]
+    dispatch: [dispatch_worker, report_to_user]
+
+  on SessionStart:
+    session "Read active tasks and recent decisions to build situational awareness"
+      context: [active-tasks, memory-bridge, recent-decisions]
+
+  on TaskCompleted:
+    if **the completed task unblocks downstream work**:
+      session "Reassess task queue and dispatch next work"
+`;
+}
+function generateLeadPersona(name2, tier, team, domain2, parent) {
+  const parentLine = parent ? `
+  parent: ${parent}` : "\n  parent: cleo-orchestrator";
+  const teamComment = team ? `
+# Team: ${team}` : "";
+  const domainDesc = domain2 ? ` Specializes in ${domain2}.` : "";
+  return `---
+kind: agent
+version: "1"
+---
+
+# ${name2} \u2014 lead agent.${teamComment}
+# Decomposes tasks, reviews worker output, decides technical approach.
+# MUST NOT hold Edit/Write/Bash tools (TEAM-002 / ULTRAPLAN 10.3).
+
+agent ${name2}:
+  role: lead${parentLine}
+  tier: ${tier}
+  description: "Development lead.${domainDesc} Decomposes tasks into concrete implementation steps, reviews worker output, and decides technical approach. Does not write code directly."
+  consult-when: "Implementation strategy, code architecture, refactoring direction, task decomposition, or when workers need clarification"
+
+  context_sources:
+    - source: patterns
+      query: "codebase conventions and architecture patterns"
+      max_entries: 5
+    - source: decisions
+      query: "technical decisions affecting implementation"
+      max_entries: 3
+  on_overflow: escalate_tier
+
+  mental_model:
+    scope: project
+    max_tokens: 1000
+    on_load:
+      validate: true
+
+  permissions:
+    files:
+      read: ["**/*"]
+
+  skills:
+    - ct-cleo
+    - ct-dev-workflow
+    - ct-task-executor
+
+  tools:
+    core: [Read, Grep, Glob]
+    dispatch: [dispatch_worker, report_to_orchestrator]
+
+  on SessionStart:
+    session "Review current task assignments and worker availability"
+      context: [active-tasks, memory-bridge]
+
+  on TaskCompleted:
+    if **the completed task introduced new code**:
+      session "Review worker output for quality and completeness before reporting to orchestrator"
+`;
+}
+function generateWorkerPersona(name2, tier, team, domain2, parent) {
+  const parentLine = parent ? `
+  parent: ${parent}` : "\n  parent: dev-lead";
+  const teamComment = team ? `
+# Team: ${team}` : "";
+  const domainDesc = domain2 ? ` Specializes in ${domain2}.` : "";
+  const writeGlobs = deriveWriteGlobs(domain2);
+  return `---
+kind: agent
+version: "1"
+---
+
+# ${name2} \u2014 worker agent.${teamComment}
+# Executes code changes within declared file globs.
+
+agent ${name2}:
+  role: worker${parentLine}
+  tier: ${tier}
+  description: "Code worker.${domainDesc} Reads requirements, writes code, runs tests, and validates changes. Operates within declared file permission globs."
+  consult-when: "Writing code, fixing bugs, running tests, formatting, or any file modification task"
+
+  context_sources:
+    - source: patterns
+      query: "coding conventions and testing patterns"
+      max_entries: 5
+    - source: learnings
+      query: "past implementation mistakes and fixes"
+      max_entries: 3
+  on_overflow: escalate_tier
+
+  mental_model:
+    scope: project
+    max_tokens: 1000
+    on_load:
+      validate: true
+
+  permissions:
+    files:
+      write: ${JSON.stringify(writeGlobs)}
+      read: ["**/*"]
+      delete: ${JSON.stringify(writeGlobs)}
+
+  skills:
+    - ct-cleo
+    - ct-dev-workflow
+    - ct-task-executor
+
+  tools:
+    core: [Read, Edit, Write, Bash, Glob, Grep]
+
+  on SessionStart:
+    session "Check assigned task and read relevant source files before starting work"
+      context: [active-tasks, memory-bridge]
+
+  on PostToolUse:
+    if tool.name == "Write" or tool.name == "Edit":
+      session "Verify the change compiles and passes lint before proceeding"
+`;
+}
+function generateDocsWorkerPersona(name2, tier, team, domain2, parent) {
+  const parentLine = parent ? `
+  parent: ${parent}` : "\n  parent: dev-lead";
+  const teamComment = team ? `
+# Team: ${team}` : "";
+  const domainDesc = domain2 ? ` Specializes in ${domain2} documentation.` : "";
+  return `---
+kind: agent
+version: "1"
+---
+
+# ${name2} \u2014 documentation worker agent.${teamComment}
+# Writes and maintains documentation within declared globs.
+
+agent ${name2}:
+  role: worker${parentLine}
+  tier: ${tier}
+  description: "Documentation worker.${domainDesc} Writes READMEs, updates guides, adds TSDoc comments, and maintains project documentation. Operates within declared documentation file globs."
+  consult-when: "Writing documentation, updating READMEs, adding TSDoc comments, or improving existing docs"
+
+  context_sources:
+    - source: patterns
+      query: "documentation conventions and style patterns"
+      max_entries: 3
+    - source: decisions
+      query: "architectural decisions needing documentation"
+      max_entries: 3
+  on_overflow: escalate_tier
+
+  mental_model:
+    scope: project
+    max_tokens: 1000
+    on_load:
+      validate: true
+
+  permissions:
+    files:
+      write: ["docs/**", "**/*.md", "**/*.mdx"]
+      read: ["**/*"]
+      delete: ["docs/**"]
+
+  skills:
+    - ct-cleo
+    - ct-documentor
+    - ct-docs-write
+
+  tools:
+    core: [Read, Edit, Write, Bash, Glob, Grep]
+
+  on SessionStart:
+    session "Check assigned documentation task and review existing docs for context"
+      context: [active-tasks, memory-bridge]
+
+  on PostToolUse:
+    if tool.name == "Write" or tool.name == "Edit":
+      session "Verify markdown renders correctly and follows project style conventions"
+`;
+}
+function deriveWriteGlobs(domain2) {
+  const defaults = ["src/**", "packages/**", "lib/**", "test/**", "tests/**"];
+  if (!domain2) return defaults;
+  const lower = domain2.toLowerCase();
+  if (lower.includes("frontend") || lower.includes("ui") || lower.includes("component")) {
+    return ["src/**", "packages/**", "components/**", "styles/**", "public/**", "test/**"];
+  }
+  if (lower.includes("backend") || lower.includes("api") || lower.includes("server")) {
+    return ["src/**", "packages/**", "lib/**", "api/**", "test/**", "tests/**"];
+  }
+  if (lower.includes("infra") || lower.includes("deploy") || lower.includes("ci")) {
+    return [".github/**", "infra/**", "deploy/**", "scripts/**", "Dockerfile*"];
+  }
+  if (lower.includes("test") || lower.includes("qa") || lower.includes("quality")) {
+    return ["test/**", "tests/**", "src/**/*.test.*", "src/**/*.spec.*", "packages/**/*.test.*"];
+  }
+  if (lower.includes("rust") || lower.includes("crate")) {
+    return ["crates/**", "src/**", "Cargo.toml", "test/**"];
+  }
+  if (lower.includes("doc")) {
+    return ["docs/**", "**/*.md", "**/*.mdx"];
+  }
+  return defaults;
+}
+function generateManifest2(params) {
+  return {
+    name: params.name,
+    version: "1.0.0",
+    description: `${capitalizeFirst(params.role)} agent${params.domain ? ` for ${params.domain}` : ""}`,
+    cant: {
+      minVersion: "1",
+      tier: params.tier,
+      role: params.role === "docs-worker" ? "worker" : params.role
+    },
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function generateTeamConfig(name2, role, team) {
+  return `---
+kind: team-config
+version: "1"
+---
+
+# Team membership for ${name2}
+
+team ${team}:
+  member ${name2}:
+    role: ${role}
+    status: active
+`;
+}
+function generateMentalModelSeed(name2, role, domain2) {
+  const domainSection = domain2 ? `## Domain
+
+${domain2}
+` : `## Domain
+
+TODO: Describe the domain this agent specializes in.
+`;
+  return `# Mental Model Seed: ${name2}
+
+> Auto-generated at ${(/* @__PURE__ */ new Date()).toISOString()}
+> Role: ${role}
+
+${domainSection}
+## Key Patterns
+
+TODO: Document recurring patterns this agent should recognize.
+
+## Known Pitfalls
+
+TODO: Document common mistakes or anti-patterns in this domain.
+
+## Decision History
+
+TODO: Track important decisions and their rationale.
+
+## Learning Log
+
+TODO: Record discoveries and insights as the agent operates.
+`;
+}
+function capitalizeFirst(str) {
+  if (str.length === 0) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
 // packages/cleo/src/cli/commands/agents.ts
@@ -125330,5 +126447,7 @@ var main = defineCommand({
   },
   subCommands
 });
-runMain(main);
+var aliasMap = buildAliasMap(rootShim._subcommands);
+var customShowUsage = createCustomShowUsage(CLI_VERSION, rootShim._subcommands, aliasMap);
+runMain(main, { showUsage: customShowUsage });
 //# sourceMappingURL=index.js.map