codex-subagent-kit 0.1.0

package/dist/cli.js

@@ -0,0 +1,1550 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  buildProgram: () => buildProgram,
+  main: () => main
+});
+module.exports = __toCommonJS(cli_exports);
+var import_node_path8 = require("path");
+var import_commander = require("commander");
+
+// src/catalog.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var TOML = __toESM(require("@iarna/toml"));
+
+// src/paths.ts
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var TOOL_DIR_NAME = "subagent-kit";
+var CATEGORY_OVERRIDE_KEY = "codex_subagent_kit_category";
+var DEFAULT_SYNC_SOURCE_NAME = "voltagent";
+function resolveProjectToolDir(projectRoot) {
+  return (0, import_node_path.resolve)(projectRoot, ".codex", TOOL_DIR_NAME);
+}
+function resolveGlobalToolDir(home = (0, import_node_os.homedir)()) {
+  return (0, import_node_path.resolve)(home, ".codex", TOOL_DIR_NAME);
+}
+function resolveProjectCatalogDir(projectRoot) {
+  return (0, import_node_path.resolve)(resolveProjectToolDir(projectRoot), "catalog", "categories");
+}
+function resolveGlobalCatalogDir(home) {
+  return (0, import_node_path.resolve)(resolveGlobalToolDir(home), "catalog", "categories");
+}
+function resolveProjectSourcesDir(projectRoot) {
+  return (0, import_node_path.resolve)(resolveProjectToolDir(projectRoot), "sources");
+}
+function resolveGlobalSourcesDir(home) {
+  return (0, import_node_path.resolve)(resolveGlobalToolDir(home), "sources");
+}
+function resolveProjectSourceCategoriesDir(projectRoot, sourceName = DEFAULT_SYNC_SOURCE_NAME) {
+  return (0, import_node_path.resolve)(resolveProjectSourcesDir(projectRoot), sourceName, "categories");
+}
+function resolveGlobalSourceCategoriesDir(sourceName = DEFAULT_SYNC_SOURCE_NAME, home) {
+  return (0, import_node_path.resolve)(resolveGlobalSourcesDir(home), sourceName, "categories");
+}
+function resolveSourceCategoryDirs(root) {
+  try {
+    return normalizeCatalogRoots(
+      (0, import_node_fs.readdirSync)(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => (0, import_node_path.resolve)(root, entry.name, "categories")).filter((categoriesRoot) => (0, import_node_fs.existsSync)(categoriesRoot))
+    );
+  } catch {
+    return [];
+  }
+}
+function resolveProjectSourceCategoriesDirs(projectRoot) {
+  return resolveSourceCategoryDirs(resolveProjectSourcesDir(projectRoot));
+}
+function resolveGlobalSourceCategoriesDirs(home) {
+  return resolveSourceCategoryDirs(resolveGlobalSourcesDir(home));
+}
+function resolveProjectAgentsDir(projectRoot) {
+  return (0, import_node_path.resolve)(projectRoot, ".codex", "agents");
+}
+function resolveGlobalAgentsDir(home = (0, import_node_os.homedir)()) {
+  return (0, import_node_path.resolve)(home, ".codex", "agents");
+}
+function normalizeCatalogRoots(roots) {
+  if (!roots) {
+    return [];
+  }
+  return roots.filter((root) => root.trim()).map((root) => (0, import_node_path.resolve)(root));
+}
+
+// src/catalog.ts
+var BUILTIN_CATEGORIES_DIR = (0, import_node_path2.resolve)(__dirname, "..", "builtin_catalog", "categories");
+var IMPORTED_AGENTS_CATEGORY = {
+  key: "imported-agents",
+  title: "Imported & External",
+  description: "Portable TOML agent definitions discovered from project/global agent directories."
+};
+var builtinCatalogCache = null;
+function readToml(path) {
+  return TOML.parse((0, import_node_fs2.readFileSync)(path, "utf8"));
+}
+function listDirectories(path) {
+  if (!(0, import_node_fs2.existsSync)(path)) {
+    return [];
+  }
+  return (0, import_node_fs2.readdirSync)(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => (0, import_node_path2.resolve)(path, entry.name)).sort();
+}
+function listTomlFiles(path) {
+  if (!(0, import_node_fs2.existsSync)(path)) {
+    return [];
+  }
+  return (0, import_node_fs2.readdirSync)(path, { withFileTypes: true }).filter((entry) => entry.isFile() && (0, import_node_path2.extname)(entry.name) === ".toml").map((entry) => (0, import_node_path2.resolve)(path, entry.name)).sort();
+}
+function categoryKeyFromDir(directoryName) {
+  const match = directoryName.match(/^(\d+)-(.*)$/);
+  return match ? match[2] : directoryName;
+}
+function fallbackTitleFromKey(key) {
+  return key.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function parseCategoryDir(categoryDir) {
+  const key = categoryKeyFromDir((0, import_node_path2.basename)(categoryDir));
+  let title = fallbackTitleFromKey(key);
+  let description = title;
+  const readmePath = (0, import_node_path2.resolve)(categoryDir, "README.md");
+  if (!(0, import_node_fs2.existsSync)(readmePath)) {
+    return { key, title, description };
+  }
+  const lines = (0, import_node_fs2.readFileSync)(readmePath, "utf8").split(/\r?\n/).map((line) => line.trim());
+  for (const line of lines) {
+    if (!line.startsWith("#")) {
+      continue;
+    }
+    const parsedTitle = line.replace(/^#+\s*/, "").trim();
+    const numericTitle = parsedTitle.match(/^\d+\.\s+(.*)$/);
+    title = numericTitle ? numericTitle[1].trim() : parsedTitle || title;
+    break;
+  }
+  for (const line of lines) {
+    if (!line || line.startsWith("#") || line === "Included agents:") {
+      continue;
+    }
+    description = line;
+    break;
+  }
+  return { key, title, description };
+}
+function readInstructions(data) {
+  const developerInstructions = data.developer_instructions;
+  if (typeof developerInstructions === "string" && developerInstructions.trim()) {
+    return developerInstructions.trimEnd();
+  }
+  const instructions = data.instructions;
+  if (typeof instructions === "string" && instructions.trim()) {
+    return instructions.trimEnd();
+  }
+  if (instructions && typeof instructions === "object" && "text" in instructions && typeof instructions.text === "string" && instructions.text.trim()) {
+    return instructions.text.trimEnd();
+  }
+  throw new Error("missing instructions text");
+}
+function requiredString(data, key) {
+  const value = data[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`missing required string field: ${key}`);
+  }
+  return value.trim();
+}
+function parseAgentFile(path, source, inheritedCategory) {
+  const data = readToml(path);
+  const explicitCategory = data[CATEGORY_OVERRIDE_KEY];
+  if (explicitCategory !== void 0 && (typeof explicitCategory !== "string" || !explicitCategory.trim())) {
+    throw new Error(`invalid ${CATEGORY_OVERRIDE_KEY}`);
+  }
+  return {
+    key: (0, import_node_path2.basename)(path, ".toml"),
+    category: typeof explicitCategory === "string" && explicitCategory.trim() ? explicitCategory.trim() : inheritedCategory ?? IMPORTED_AGENTS_CATEGORY.key,
+    name: requiredString(data, "name"),
+    description: requiredString(data, "description"),
+    model: requiredString(data, "model"),
+    reasoningEffort: requiredString(data, "model_reasoning_effort"),
+    sandboxMode: requiredString(data, "sandbox_mode"),
+    developerInstructions: readInstructions(data),
+    source,
+    definitionPath: path
+  };
+}
+function loadCatalogRoot(root, source) {
+  const categories = /* @__PURE__ */ new Map();
+  const agents = /* @__PURE__ */ new Map();
+  if (!(0, import_node_fs2.existsSync)(root)) {
+    return { categories, agents };
+  }
+  for (const categoryDir of listDirectories(root)) {
+    const category = parseCategoryDir(categoryDir);
+    categories.set(category.key, category);
+    for (const file of listTomlFiles(categoryDir)) {
+      const agent = parseAgentFile(file, source, category.key);
+      agents.set(agent.key, agent);
+    }
+  }
+  return { categories, agents };
+}
+function getBuiltinCatalog() {
+  if (builtinCatalogCache) {
+    return builtinCatalogCache;
+  }
+  const builtin = loadCatalogRoot(BUILTIN_CATEGORIES_DIR, "builtin");
+  if (builtin.categories.size === 0) {
+    throw new Error(`builtin catalog is empty: ${BUILTIN_CATEGORIES_DIR}`);
+  }
+  builtinCatalogCache = builtin;
+  return builtin;
+}
+function mergeCatalogInto(target, incoming) {
+  for (const [key, category] of incoming.categories) {
+    target.categories.set(key, category);
+  }
+  for (const [key, agent] of incoming.agents) {
+    target.agents.set(key, agent);
+  }
+}
+function loadExternalAgents(directory, source, inheritedAgents) {
+  if (!(0, import_node_fs2.existsSync)(directory)) {
+    return [];
+  }
+  const loaded = [];
+  for (const file of listTomlFiles(directory)) {
+    try {
+      const inheritedCategory = inheritedAgents.get((0, import_node_path2.basename)(file, ".toml"))?.category;
+      loaded.push(parseAgentFile(file, source, inheritedCategory));
+    } catch {
+      continue;
+    }
+  }
+  return loaded;
+}
+function buildCatalogState(options = {}) {
+  const includeProject = options.includeProject ?? false;
+  const includeGlobal = options.includeGlobal ?? false;
+  const homeDir = options.homeDir;
+  const catalogRoots = normalizeCatalogRoots(options.catalogRoots);
+  const builtin = getBuiltinCatalog();
+  const state = {
+    categories: new Map(builtin.categories),
+    agents: new Map(builtin.agents)
+  };
+  if (includeGlobal) {
+    for (const root of resolveGlobalSourceCategoriesDirs(homeDir)) {
+      mergeCatalogInto(state, loadCatalogRoot(root, `global-source:${(0, import_node_path2.basename)((0, import_node_path2.resolve)(root, ".."))}`));
+    }
+    mergeCatalogInto(state, loadCatalogRoot(resolveGlobalCatalogDir(homeDir), "global-catalog"));
+  }
+  if (includeProject && options.projectRoot) {
+    for (const root of resolveProjectSourceCategoriesDirs(options.projectRoot)) {
+      mergeCatalogInto(state, loadCatalogRoot(root, `project-source:${(0, import_node_path2.basename)((0, import_node_path2.resolve)(root, ".."))}`));
+    }
+    mergeCatalogInto(
+      state,
+      loadCatalogRoot(resolveProjectCatalogDir(options.projectRoot), "project-catalog")
+    );
+  }
+  for (const root of catalogRoots) {
+    mergeCatalogInto(state, loadCatalogRoot(root, "catalog-root"));
+  }
+  state.categories.set(IMPORTED_AGENTS_CATEGORY.key, IMPORTED_AGENTS_CATEGORY);
+  if (includeGlobal) {
+    for (const agent of loadExternalAgents(
+      resolveGlobalAgentsDir(homeDir),
+      "global",
+      state.agents
+    )) {
+      state.agents.set(agent.key, agent);
+    }
+  }
+  if (includeProject && options.projectRoot) {
+    for (const agent of loadExternalAgents(
+      resolveProjectAgentsDir(options.projectRoot),
+      "project",
+      state.agents
+    )) {
+      state.agents.set(agent.key, agent);
+    }
+  }
+  return state;
+}
+function getAgentMap(options = {}) {
+  return buildCatalogState(options).agents;
+}
+function getCategories(options = {}) {
+  const state = buildCatalogState(options);
+  const usedCategories = new Set([...state.agents.values()].map((agent) => agent.category));
+  return [...state.categories.values()].filter((category) => usedCategories.has(category.key));
+}
+function getAgents(options = {}) {
+  const categories = getCategories(options);
+  const agents = [...getAgentMap(options).values()];
+  const categoryOrder = new Map(categories.map((category, index) => [category.key, index]));
+  return agents.sort((left, right) => {
+    const leftOrder = categoryOrder.get(left.category) ?? categoryOrder.size;
+    const rightOrder = categoryOrder.get(right.category) ?? categoryOrder.size;
+    if (leftOrder !== rightOrder) {
+      return leftOrder - rightOrder;
+    }
+    const byName = left.name.localeCompare(right.name, void 0, { sensitivity: "base" });
+    if (byName !== 0) {
+      return byName;
+    }
+    return left.key.localeCompare(right.key);
+  });
+}
+function getAgentsByCategory(categoryKeys, options = {}) {
+  const agents = getAgents(options);
+  if (!categoryKeys || categoryKeys.size === 0) {
+    return agents;
+  }
+  return agents.filter((agent) => categoryKeys.has(agent.category));
+}
+function renderCatalogOutput(options = {}) {
+  const categories = getCategories(options);
+  const agents = getAgents(options);
+  const lines = [];
+  for (const category of categories) {
+    lines.push(`[${category.title}]`);
+    lines.push(`  key: ${category.key}`);
+    lines.push(`  description: ${category.description}`);
+    for (const agent of agents) {
+      if (agent.category !== category.key) {
+        continue;
+      }
+      const sourceSuffix = agent.source === "builtin" ? "" : ` [${agent.source}]`;
+      lines.push(`  - ${agent.key}: ${agent.description}${sourceSuffix}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+// src/catalog-import.ts
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
+var CatalogImportError = class extends Error {
+};
+function resolveTargetRoot(projectRoot, scope, homeDir) {
+  if (scope === "project") {
+    return resolveProjectCatalogDir(projectRoot);
+  }
+  if (scope === "global") {
+    return resolveGlobalCatalogDir(homeDir);
+  }
+  throw new CatalogImportError(`unsupported scope: ${scope}`);
+}
+function categoryKeyFromDir2(directoryName) {
+  const match = directoryName.match(/^(\d+)-(.*)$/);
+  return match ? match[2] : directoryName;
+}
+function resolveTargetCategoryDir(targetRoot, sourceCategoryDir) {
+  const sourceKey = categoryKeyFromDir2((0, import_node_path3.basename)(sourceCategoryDir));
+  if ((0, import_node_fs3.existsSync)(targetRoot)) {
+    for (const entry of (0, import_node_fs3.readdirSync)(targetRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      if (categoryKeyFromDir2(entry.name) === sourceKey) {
+        return (0, import_node_path3.resolve)(targetRoot, entry.name);
+      }
+    }
+  }
+  return (0, import_node_path3.resolve)(targetRoot, (0, import_node_path3.basename)(sourceCategoryDir));
+}
+function ensureDirectory(path, createdPaths, preservedPaths) {
+  if ((0, import_node_fs3.existsSync)(path)) {
+    if (!(0, import_node_fs3.statSync)(path).isDirectory()) {
+      throw new CatalogImportError(`expected directory but found file: ${path}`);
+    }
+    preservedPaths.push(path);
+    return;
+  }
+  (0, import_node_fs3.mkdirSync)(path, { recursive: true });
+  createdPaths.push(path);
+}
+function copyFile(source, destination, overwrite, createdPaths, preservedPaths) {
+  if ((0, import_node_fs3.existsSync)(destination) && !overwrite) {
+    if ((0, import_node_fs3.statSync)(destination).isDirectory()) {
+      throw new CatalogImportError(`expected file but found directory: ${destination}`);
+    }
+    preservedPaths.push(destination);
+    return;
+  }
+  (0, import_node_fs3.mkdirSync)((0, import_node_path3.dirname)(destination), { recursive: true });
+  (0, import_node_fs3.copyFileSync)(source, destination);
+  createdPaths.push(destination);
+}
+function scanSourceRoots(catalogRoots) {
+  const normalizedRoots = normalizeCatalogRoots(catalogRoots);
+  if (normalizedRoots.length === 0) {
+    throw new CatalogImportError("catalog import requires at least one --catalog-root");
+  }
+  const categories = /* @__PURE__ */ new Map();
+  const agents = /* @__PURE__ */ new Map();
+  const issues = [];
+  for (const root of normalizedRoots) {
+    if (!(0, import_node_fs3.existsSync)(root)) {
+      throw new CatalogImportError(`catalog root does not exist: ${root}`);
+    }
+    for (const entry of (0, import_node_fs3.readdirSync)(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const categoryDir = (0, import_node_path3.resolve)(root, entry.name);
+      const category = parseCategoryDir(categoryDir);
+      const readmePath = (0, import_node_path3.resolve)(categoryDir, "README.md");
+      categories.set(category.key, {
+        key: category.key,
+        directory: categoryDir,
+        readmePath: (0, import_node_fs3.existsSync)(readmePath) ? readmePath : void 0
+      });
+      for (const file of (0, import_node_fs3.readdirSync)(categoryDir, { withFileTypes: true })) {
+        if (!file.isFile() || !file.name.endsWith(".toml")) {
+          continue;
+        }
+        const path = (0, import_node_path3.resolve)(categoryDir, file.name);
+        try {
+          const agent = parseAgentFile(path, "catalog-root", category.key);
+          agents.set(agent.key, {
+            key: agent.key,
+            path,
+            categoryKey: category.key,
+            categoryDirectory: categoryDir,
+            readmePath: (0, import_node_fs3.existsSync)(readmePath) ? readmePath : void 0
+          });
+        } catch (error) {
+          issues.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+    }
+  }
+  if (issues.length > 0) {
+    throw new CatalogImportError(
+      `source catalog contains malformed templates:
+${issues.map((issue) => `- ${issue}`).join("\n")}`
+    );
+  }
+  return { categories, agents };
+}
+function importCatalog(options) {
+  if (options.agentKeys.length === 0 && options.categoryKeys.length === 0) {
+    throw new CatalogImportError("catalog import requires --agents, --categories, or both");
+  }
+  const { categories, agents } = scanSourceRoots(options.catalogRoots);
+  const missingCategories = options.categoryKeys.filter((key) => !categories.has(key));
+  if (missingCategories.length > 0) {
+    throw new CatalogImportError(`unknown category keys: ${missingCategories.join(", ")}`);
+  }
+  const missingAgents = options.agentKeys.filter((key) => !agents.has(key));
+  if (missingAgents.length > 0) {
+    throw new CatalogImportError(`unknown agent keys: ${missingAgents.join(", ")}`);
+  }
+  const targetRoot = resolveTargetRoot(options.projectRoot, options.scope, options.homeDir);
+  const createdPaths = [];
+  const preservedPaths = [];
+  ensureDirectory(targetRoot, createdPaths, preservedPaths);
+  const selectedCategories = new Set(options.categoryKeys);
+  const selectedAgents = new Set(options.agentKeys);
+  const copyPlan = /* @__PURE__ */ new Map();
+  for (const categoryKey of options.categoryKeys) {
+    const categorySource = categories.get(categoryKey);
+    if (!categorySource) {
+      continue;
+    }
+    const targetCategoryDir = resolveTargetCategoryDir(targetRoot, categorySource.directory);
+    ensureDirectory(targetCategoryDir, createdPaths, preservedPaths);
+    if (categorySource.readmePath) {
+      copyPlan.set(categorySource.readmePath, (0, import_node_path3.resolve)(targetCategoryDir, "README.md"));
+    }
+    for (const agentSource of agents.values()) {
+      if (agentSource.categoryDirectory !== categorySource.directory) {
+        continue;
+      }
+      selectedAgents.add(agentSource.key);
+      copyPlan.set(agentSource.path, (0, import_node_path3.resolve)(targetCategoryDir, (0, import_node_path3.basename)(agentSource.path)));
+    }
+  }
+  for (const agentKey of options.agentKeys) {
+    const agentSource = agents.get(agentKey);
+    if (!agentSource) {
+      continue;
+    }
+    selectedCategories.add(agentSource.categoryKey);
+    const targetCategoryDir = resolveTargetCategoryDir(targetRoot, agentSource.categoryDirectory);
+    ensureDirectory(targetCategoryDir, createdPaths, preservedPaths);
+    if (agentSource.readmePath) {
+      copyPlan.set(agentSource.readmePath, (0, import_node_path3.resolve)(targetCategoryDir, "README.md"));
+    }
+    copyPlan.set(agentSource.path, (0, import_node_path3.resolve)(targetCategoryDir, (0, import_node_path3.basename)(agentSource.path)));
+  }
+  for (const [source, destination] of [...copyPlan.entries()].sort(
+    (left, right) => left[1].localeCompare(right[1])
+  )) {
+    copyFile(source, destination, options.overwrite ?? false, createdPaths, preservedPaths);
+  }
+  return {
+    targetRoot,
+    importedCategoryKeys: [...selectedCategories].sort(),
+    importedAgentKeys: [...selectedAgents].sort(),
+    createdPaths,
+    preservedPaths
+  };
+}
+
+// src/catalog-sync.ts
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
+var VOLTAGENT_TREE_API_URL = "https://api.github.com/repos/VoltAgent/awesome-codex-subagents/git/trees/main?recursive=1";
+var VOLTAGENT_RAW_BASE_URL = "https://raw.githubusercontent.com/VoltAgent/awesome-codex-subagents/main/";
+var CatalogSyncError = class extends Error {
+};
+function normalizeSourceName(sourceName) {
+  const candidate = sourceName.trim().toLowerCase();
+  if (!candidate) {
+    throw new CatalogSyncError("catalog sync requires a non-empty source name");
+  }
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(candidate)) {
+    throw new CatalogSyncError(
+      "source names may contain only lowercase letters, digits, hyphens, and underscores"
+    );
+  }
+  return candidate;
+}
+function resolveCategoriesRoot(sourceRoot) {
+  const root = (0, import_node_path4.resolve)(sourceRoot);
+  if ((0, import_node_fs4.existsSync)(root) && (0, import_node_path4.basename)(root) === "categories") {
+    return root;
+  }
+  const nested = (0, import_node_path4.resolve)(root, "categories");
+  if ((0, import_node_fs4.existsSync)(nested)) {
+    return nested;
+  }
+  throw new CatalogSyncError(`expected a categories/ directory but found: ${sourceRoot}`);
+}
+function prepareTargetRoot(targetRoot) {
+  (0, import_node_fs4.mkdirSync)((0, import_node_path4.resolve)(targetRoot, ".."), { recursive: true });
+  if ((0, import_node_fs4.existsSync)(targetRoot)) {
+    (0, import_node_fs4.rmSync)(targetRoot, { recursive: true, force: true });
+  }
+  (0, import_node_fs4.mkdirSync)(targetRoot, { recursive: true });
+}
+function listRelativeCatalogFiles(root) {
+  const discovered = [];
+  function walk(current) {
+    for (const entry of (0, import_node_fs4.readdirSync)(current, { withFileTypes: true })) {
+      const absolutePath = (0, import_node_path4.resolve)(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolutePath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (entry.name === "README.md" || entry.name.endsWith(".toml")) {
+        discovered.push(absolutePath.slice(root.length + 1));
+      }
+    }
+  }
+  walk(root);
+  return discovered.sort();
+}
+function copyLocalSource(sourceRoot, targetRoot) {
+  const categoriesRoot = resolveCategoriesRoot(sourceRoot);
+  const copiedPaths = [];
+  for (const relativePath of listRelativeCatalogFiles(categoriesRoot)) {
+    const sourcePath = (0, import_node_path4.resolve)(categoriesRoot, relativePath);
+    const destination = (0, import_node_path4.resolve)(targetRoot, relativePath);
+    (0, import_node_fs4.mkdirSync)((0, import_node_path4.resolve)(destination, ".."), { recursive: true });
+    (0, import_node_fs4.cpSync)(sourcePath, destination);
+    copiedPaths.push(destination);
+  }
+  return copiedPaths;
+}
+async function fetchJson(url) {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "codex-subagent-kit"
+    }
+  });
+  if (!response.ok) {
+    throw new CatalogSyncError(`failed to fetch upstream catalog metadata: ${response.status}`);
+  }
+  return await response.json();
+}
+async function fetchText(url) {
+  const response = await fetch(url, {
+    headers: { "User-Agent": "codex-subagent-kit" }
+  });
+  if (!response.ok) {
+    throw new CatalogSyncError(`failed to fetch upstream catalog file: ${url}`);
+  }
+  return response.text();
+}
+async function downloadVoltAgentSource(targetRoot) {
+  const payload = await fetchJson(VOLTAGENT_TREE_API_URL);
+  const tree = payload.tree;
+  if (!Array.isArray(tree)) {
+    throw new CatalogSyncError("unexpected upstream catalog metadata payload");
+  }
+  const upstreamPaths = tree.map((entry) => entry && typeof entry === "object" ? entry.path : void 0).filter((path) => typeof path === "string" && path.startsWith("categories/")).filter((path) => path.endsWith(".toml") || path.endsWith("README.md")).sort();
+  if (upstreamPaths.length === 0) {
+    throw new CatalogSyncError("upstream catalog did not expose any categories files");
+  }
+  const copiedPaths = [];
+  for (const upstreamPath of upstreamPaths) {
+    const relativePath = upstreamPath.replace(/^categories\//, "");
+    const destination = (0, import_node_path4.resolve)(targetRoot, relativePath);
+    (0, import_node_fs4.mkdirSync)((0, import_node_path4.resolve)(destination, ".."), { recursive: true });
+    (0, import_node_fs4.writeFileSync)(destination, await fetchText(`${VOLTAGENT_RAW_BASE_URL}${upstreamPath}`), "utf8");
+    copiedPaths.push(destination);
+  }
+  return copiedPaths;
+}
+async function syncCatalog(options) {
+  const sourceName = normalizeSourceName(options.sourceName ?? DEFAULT_SYNC_SOURCE_NAME);
+  const targetRoot = options.scope === "project" ? resolveProjectSourceCategoriesDir(options.projectRoot, sourceName) : resolveGlobalSourceCategoriesDir(sourceName, options.homeDir);
+  prepareTargetRoot(targetRoot);
+  let copiedPaths;
+  let sourceLabel;
+  if (options.sourceRoot) {
+    copiedPaths = copyLocalSource(options.sourceRoot, targetRoot);
+    sourceLabel = resolveCategoriesRoot(options.sourceRoot);
+  } else {
+    if (sourceName !== DEFAULT_SYNC_SOURCE_NAME) {
+      throw new CatalogSyncError(
+        "remote sync is only supported for the default voltagent source without --source-root"
+      );
+    }
+    copiedPaths = await downloadVoltAgentSource(targetRoot);
+    sourceLabel = "VoltAgent/awesome-codex-subagents@main";
+  }
+  if (copiedPaths.length === 0) {
+    throw new CatalogSyncError("catalog sync did not copy any README or TOML files");
+  }
+  return {
+    sourceName,
+    targetRoot,
+    sourceLabel,
+    copiedPaths
+  };
+}
+
+// src/doctor.ts
+var import_node_fs6 = require("fs");
+var import_node_path6 = require("path");
+
+// src/generator.ts
+var import_node_fs5 = require("fs");
+var import_node_path5 = require("path");
+var GenerationError = class extends Error {
+};
+var ORCHESTRATOR_CATEGORY = "meta-orchestration";
+var DEFAULT_ORCHESTRATOR_KEY = "multi-agent-coordinator";
+function renderAgentFile(agent) {
+  const lines = [
+    `name = ${JSON.stringify(agent.name)}`,
+    `description = ${JSON.stringify(agent.description)}`,
+    `model = ${JSON.stringify(agent.model)}`,
+    `model_reasoning_effort = ${JSON.stringify(agent.reasoningEffort)}`,
+    `sandbox_mode = ${JSON.stringify(agent.sandboxMode)}`,
+    'developer_instructions = """',
+    agent.developerInstructions.trimEnd(),
+    '"""'
+  ];
+  if (agent.categoryOverride) {
+    lines.push(`codex_subagent_kit_category = ${JSON.stringify(agent.categoryOverride)}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function resolveTargetDir(scope, projectRoot, homeDir) {
+  if (scope === "project") {
+    return resolveProjectAgentsDir(projectRoot);
+  }
+  if (scope === "global") {
+    return resolveGlobalAgentsDir(homeDir);
+  }
+  throw new GenerationError(`unsupported scope: ${scope}`);
+}
+function installAgents(options) {
+  const agentMap = getAgentMap({
+    projectRoot: options.projectRoot,
+    homeDir: options.homeDir,
+    includeProject: options.scope === "project",
+    includeGlobal: true,
+    catalogRoots: options.catalogRoots
+  });
+  const missing = options.agentKeys.filter((key) => !agentMap.has(key));
+  if (missing.length > 0) {
+    throw new GenerationError(`unknown agent keys: ${missing.join(", ")}`);
+  }
+  const targetDir = resolveTargetDir(options.scope, options.projectRoot, options.homeDir);
+  (0, import_node_fs5.mkdirSync)(targetDir, { recursive: true });
+  const agentPaths = [];
+  const agentPreservedPaths = [];
+  for (const key of options.agentKeys) {
+    const agent = agentMap.get(key);
+    if (!agent) {
+      continue;
+    }
+    const filePath = (0, import_node_path5.resolve)(targetDir, `${agent.key}.toml`);
+    if ((0, import_node_fs5.existsSync)(filePath) && !options.overwrite) {
+      agentPreservedPaths.push(filePath);
+      continue;
+    }
+    (0, import_node_fs5.writeFileSync)(
+      filePath,
+      renderAgentFile({
+        name: agent.name,
+        description: agent.description,
+        model: agent.model,
+        reasoningEffort: agent.reasoningEffort,
+        sandboxMode: agent.sandboxMode,
+        developerInstructions: agent.developerInstructions
+      }),
+      "utf8"
+    );
+    agentPaths.push(filePath);
+  }
+  return {
+    agentPaths,
+    agentPreservedPaths
+  };
+}
+
+// src/doctor.ts
+function scanCatalogRoot(root, source, missingIsIssue = false) {
+  const categories = /* @__PURE__ */ new Map();
+  const agents = /* @__PURE__ */ new Map();
+  const issues = [];
+  let checkedTemplates = 0;
+  if (!(0, import_node_fs6.existsSync)(root)) {
+    if (missingIsIssue) {
+      issues.push({ path: root, message: "catalog root does not exist" });
+    }
+    return { categories, agents, issues, checkedTemplates };
+  }
+  for (const entry of (0, import_node_fs6.readdirSync)(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const categoryDir = (0, import_node_path6.resolve)(root, entry.name);
+    const category = parseCategoryDir(categoryDir);
+    categories.set(category.key, category);
+    for (const file of (0, import_node_fs6.readdirSync)(categoryDir, { withFileTypes: true })) {
+      if (!file.isFile() || !file.name.endsWith(".toml")) {
+        continue;
+      }
+      const path = (0, import_node_path6.resolve)(categoryDir, file.name);
+      checkedTemplates += 1;
+      try {
+        const agent = parseAgentFile(path, source, category.key);
+        agents.set(agent.key, agent);
+      } catch (error) {
+        issues.push({ path, message: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+  return { categories, agents, issues, checkedTemplates };
+}
+function scanInstalledAgents(directory, source, inheritedAgents) {
+  const agents = [];
+  const issues = [];
+  let checkedFiles = 0;
+  if (!(0, import_node_fs6.existsSync)(directory)) {
+    return { agents, issues, checkedFiles };
+  }
+  for (const file of (0, import_node_fs6.readdirSync)(directory, { withFileTypes: true })) {
+    if (!file.isFile() || !file.name.endsWith(".toml")) {
+      continue;
+    }
+    const path = (0, import_node_path6.resolve)(directory, file.name);
+    checkedFiles += 1;
+    try {
+      const inheritedCategory = inheritedAgents.get(file.name.replace(/\.toml$/, ""))?.category;
+      agents.push(parseAgentFile(path, source, inheritedCategory));
+    } catch (error) {
+      issues.push({ path, message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return { agents, issues, checkedFiles };
+}
+function runDoctor(options) {
+  const catalogCounts = [];
+  const installedCounts = [];
+  const issues = [];
+  const builtin = scanCatalogRoot(BUILTIN_CATEGORIES_DIR, "builtin");
+  catalogCounts.push(["built-in", builtin.checkedTemplates]);
+  issues.push(...builtin.issues);
+  const categories = new Map(builtin.categories);
+  const agentMap = new Map(builtin.agents);
+  for (const root of resolveGlobalSourceCategoriesDirs(options.homeDir)) {
+    const sourceName = (0, import_node_path6.basename)((0, import_node_path6.dirname)(root)) || "unknown";
+    const synced = scanCatalogRoot(root, `global-source:${sourceName}`);
+    catalogCounts.push([`global source: ${sourceName}`, synced.checkedTemplates]);
+    issues.push(...synced.issues);
+    for (const [key, category] of synced.categories) categories.set(key, category);
+    for (const [key, agent] of synced.agents) agentMap.set(key, agent);
+  }
+  const globalCatalog = scanCatalogRoot(resolveGlobalCatalogDir(options.homeDir), "global-catalog");
+  catalogCounts.push(["global catalog", globalCatalog.checkedTemplates]);
+  issues.push(...globalCatalog.issues);
+  for (const [key, category] of globalCatalog.categories) categories.set(key, category);
+  for (const [key, agent] of globalCatalog.agents) agentMap.set(key, agent);
+  if (options.scope === "project") {
+    for (const root of resolveProjectSourceCategoriesDirs(options.projectRoot)) {
+      const sourceName = (0, import_node_path6.basename)((0, import_node_path6.dirname)(root)) || "unknown";
+      const synced = scanCatalogRoot(root, `project-source:${sourceName}`);
+      catalogCounts.push([`project source: ${sourceName}`, synced.checkedTemplates]);
+      issues.push(...synced.issues);
+      for (const [key, category] of synced.categories) categories.set(key, category);
+      for (const [key, agent] of synced.agents) agentMap.set(key, agent);
+    }
+    const projectCatalog = scanCatalogRoot(
+      resolveProjectCatalogDir(options.projectRoot),
+      "project-catalog"
+    );
+    catalogCounts.push(["project catalog", projectCatalog.checkedTemplates]);
+    issues.push(...projectCatalog.issues);
+    for (const [key, category] of projectCatalog.categories) categories.set(key, category);
+    for (const [key, agent] of projectCatalog.agents) agentMap.set(key, agent);
+  }
+  for (const root of normalizeCatalogRoots(options.catalogRoots)) {
+    const extra = scanCatalogRoot(root, "catalog-root", true);
+    catalogCounts.push([`catalog root: ${root}`, extra.checkedTemplates]);
+    issues.push(...extra.issues);
+    for (const [key, category] of extra.categories) categories.set(key, category);
+    for (const [key, agent] of extra.agents) agentMap.set(key, agent);
+  }
+  categories.set(IMPORTED_AGENTS_CATEGORY.key, IMPORTED_AGENTS_CATEGORY);
+  const globalInstalled = scanInstalledAgents(
+    resolveGlobalAgentsDir(options.homeDir),
+    "global",
+    agentMap
+  );
+  installedCounts.push(["global agents", globalInstalled.checkedFiles]);
+  issues.push(...globalInstalled.issues);
+  for (const agent of globalInstalled.agents) {
+    agentMap.set(agent.key, agent);
+  }
+  let targetDir;
+  if (options.scope === "project") {
+    const projectInstalledDir = resolveTargetDir("project", options.projectRoot);
+    const projectInstalled = scanInstalledAgents(projectInstalledDir, "project", agentMap);
+    installedCounts.push(["project agents", projectInstalled.checkedFiles]);
+    issues.push(...projectInstalled.issues);
+    targetDir = projectInstalledDir;
+    if (projectInstalled.checkedFiles === 0) {
+      issues.push({ path: targetDir, message: "no installed agent definitions found in target scope" });
+    }
+  } else {
+    targetDir = resolveTargetDir("global", options.projectRoot, options.homeDir);
+    if (globalInstalled.checkedFiles === 0) {
+      issues.push({ path: targetDir, message: "no installed agent definitions found in target scope" });
+    }
+  }
+  return {
+    scope: options.scope,
+    targetDir,
+    catalogCounts,
+    installedCounts,
+    issues
+  };
+}
+function renderDoctorReport(report) {
+  const lines = [
+    `status: ${report.issues.length === 0 ? "ok" : "issues found"}`,
+    `scope: ${report.scope}`,
+    `target: ${report.targetDir}`,
+    "",
+    "Catalog templates checked:"
+  ];
+  for (const [label, count] of report.catalogCounts) {
+    lines.push(`- ${label}: ${count}`);
+  }
+  lines.push("");
+  lines.push("Installed agent files checked:");
+  for (const [label, count] of report.installedCounts) {
+    lines.push(`- ${label}: ${count}`);
+  }
+  lines.push("");
+  if (report.issues.length === 0) {
+    lines.push("Issues: none");
+  } else {
+    lines.push("Issues:");
+    for (const issue of report.issues) {
+      lines.push(issue.path ? `- ${issue.path}: ${issue.message}` : `- ${issue.message}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/meta.ts
+var STABLE_COMMANDS = [
+  "catalog",
+  "catalog import",
+  "catalog sync",
+  "install",
+  "doctor",
+  "usage",
+  "template init",
+  "tui"
+];
+
+// src/templates.ts
+var import_node_fs7 = require("fs");
+var import_node_path7 = require("path");
+var DEFAULT_MODEL = "gpt-5.4";
+var DEFAULT_REASONING_EFFORT = "medium";
+var DEFAULT_SANDBOX_MODE = "read-only";
+var ORCHESTRATOR_CATEGORY2 = "meta-orchestration";
+var SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var TemplateError = class extends Error {
+};
+function validateSlug(value, fieldName) {
+  const normalized = value.trim().toLowerCase();
+  if (!SLUG_PATTERN.test(normalized)) {
+    throw new TemplateError(
+      `${fieldName} must be a lowercase slug using letters, numbers, and hyphens`
+    );
+  }
+  return normalized;
+}
+function titleFromSlug(value) {
+  return value.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function categoryKeyFromDir3(directoryName) {
+  const match = directoryName.match(/^(\d+)-(.*)$/);
+  return match ? match[2] : directoryName;
+}
+function normalizePrefix(prefix) {
+  if (prefix === void 0) {
+    return void 0;
+  }
+  const stripped = prefix.trim();
+  if (!stripped) {
+    return void 0;
+  }
+  if (!/^\d+$/.test(stripped)) {
+    throw new TemplateError("category prefix must be numeric");
+  }
+  return stripped.padStart(2, "0");
+}
+function nextPrefix(root) {
+  if (!existsDirectory(root)) {
+    return "11";
+  }
+  const numericPrefixes = (0, import_node_fs7.readdirSync)(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name.match(/^(\d+)-/)).filter((match) => Boolean(match)).map((match) => Number.parseInt(match[1], 10));
+  return String(Math.max(10, ...numericPrefixes) + 1).padStart(2, "0");
+}
+function existsDirectory(path) {
+  try {
+    return (0, import_node_fs7.statSync)(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function ensureDirectory2(path, createdPaths, preservedPaths) {
+  if (existsDirectory(path)) {
+    preservedPaths.push(path);
+    return;
+  }
+  try {
+    (0, import_node_fs7.mkdirSync)(path, { recursive: false });
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      (0, import_node_fs7.mkdirSync)(path, { recursive: true });
+    } else {
+      throw error;
+    }
+  }
+  createdPaths.push(path);
+}
+function writeFile(path, content, overwrite, createdPaths, preservedPaths) {
+  try {
+    const stats = (0, import_node_fs7.statSync)(path);
+    if (stats.isDirectory()) {
+      throw new TemplateError(`expected file but found directory: ${path}`);
+    }
+    if (!overwrite) {
+      preservedPaths.push(path);
+      return;
+    }
+  } catch (error) {
+    if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+      if (error instanceof TemplateError) {
+        throw error;
+      }
+      throw error;
+    }
+  }
+  (0, import_node_fs7.writeFileSync)(path, content, "utf8");
+  createdPaths.push(path);
+}
+function resolveTargetRoot2(options) {
+  if (options.catalogRoot) {
+    return (0, import_node_path7.resolve)(options.catalogRoot);
+  }
+  if (options.scope === "project") {
+    return resolveProjectCatalogDir(options.projectRoot);
+  }
+  if (options.scope === "global") {
+    return resolveGlobalCatalogDir();
+  }
+  throw new TemplateError(`unsupported scope: ${options.scope}`);
+}
+function resolveCategoryDir(root, categoryKey, categoryPrefix) {
+  if (existsDirectory(root)) {
+    for (const entry of (0, import_node_fs7.readdirSync)(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      if (categoryKeyFromDir3(entry.name) === categoryKey) {
+        const match = entry.name.match(/^(\d+)-/);
+        return {
+          categoryDir: (0, import_node_path7.resolve)(root, entry.name),
+          resolvedPrefix: match ? match[1] : ""
+        };
+      }
+    }
+  }
+  const effectivePrefix = categoryPrefix ?? nextPrefix(root);
+  return {
+    categoryDir: (0, import_node_path7.resolve)(root, `${effectivePrefix}-${categoryKey}`),
+    resolvedPrefix: effectivePrefix
+  };
+}
+function renderCategoryReadme(options) {
+  const headingNumber = options.categoryPrefix ? `${Number.parseInt(options.categoryPrefix, 10)}. ` : "";
+  return `# ${headingNumber}${options.categoryTitle}
+
+${options.categoryDescription}
+`;
+}
+function renderAgentTemplate(options) {
+  return renderAgentFile({
+    name: options.agentName,
+    description: options.agentDescription,
+    model: options.model,
+    reasoningEffort: options.reasoningEffort,
+    sandboxMode: options.sandboxMode,
+    developerInstructions: [
+      `You are \`${options.agentKey}\`.`,
+      "",
+      "Responsibilities:",
+      "- TODO: define the primary ownership boundary.",
+      "- TODO: define what inputs to expect.",
+      "- TODO: define what outputs to return.",
+      "",
+      "Constraints:",
+      "- Stay within the assigned scope.",
+      "- Escalate when requirements are ambiguous or cross ownership boundaries."
+    ].join("\n"),
+    categoryOverride: options.categoryOverride
+  });
+}
+function initTemplate(options) {
+  const normalizedCategoryKey = validateSlug(options.categoryKey, "category key");
+  const normalizedAgentKey = validateSlug(options.agentKey, "agent key");
+  const normalizedPrefix = normalizePrefix(options.categoryPrefix);
+  const targetRoot = resolveTargetRoot2(options);
+  const createdPaths = [];
+  const preservedPaths = [];
+  ensureDirectory2(targetRoot, createdPaths, preservedPaths);
+  const { categoryDir, resolvedPrefix } = resolveCategoryDir(
+    targetRoot,
+    normalizedCategoryKey,
+    normalizedPrefix
+  );
+  ensureDirectory2(categoryDir, createdPaths, preservedPaths);
+  const resolvedCategoryTitle = (options.categoryTitle ?? titleFromSlug(normalizedCategoryKey)).trim();
+  const resolvedCategoryDescription = (options.categoryDescription ?? `Custom templates for the ${resolvedCategoryTitle.toLowerCase()} workflow.`).trim();
+  const resolvedAgentName = (options.agentName ?? normalizedAgentKey).trim();
+  const resolvedAgentDescription = (options.agentDescription ?? `TODO: describe when to use ${normalizedAgentKey}.`).trim();
+  const readmePath = (0, import_node_path7.resolve)(categoryDir, "README.md");
+  writeFile(
+    readmePath,
+    renderCategoryReadme({
+      categoryTitle: resolvedCategoryTitle,
+      categoryDescription: resolvedCategoryDescription,
+      categoryPrefix: resolvedPrefix
+    }),
+    options.overwrite ?? false,
+    createdPaths,
+    preservedPaths
+  );
+  let categoryOverride = options.orchestrator ? ORCHESTRATOR_CATEGORY2 : void 0;
+  if (normalizedCategoryKey === ORCHESTRATOR_CATEGORY2) {
+    categoryOverride = void 0;
+  }
+  const agentPath = (0, import_node_path7.resolve)(categoryDir, `${normalizedAgentKey}.toml`);
+  writeFile(
+    agentPath,
+    renderAgentTemplate({
+      agentKey: normalizedAgentKey,
+      agentName: resolvedAgentName,
+      agentDescription: resolvedAgentDescription,
+      model: (options.model ?? DEFAULT_MODEL).trim(),
+      reasoningEffort: (options.reasoningEffort ?? DEFAULT_REASONING_EFFORT).trim(),
+      sandboxMode: (options.sandboxMode ?? DEFAULT_SANDBOX_MODE).trim(),
+      categoryOverride
+    }),
+    options.overwrite ?? false,
+    createdPaths,
+    preservedPaths
+  );
+  return {
+    targetRoot,
+    categoryDir,
+    readmePath,
+    agentPath,
+    createdPaths,
+    preservedPaths
+  };
+}
+
+// src/tui.ts
+var import_prompts = require("@inquirer/prompts");
+var defaultPromptAdapter = {
+  select: import_prompts.select,
+  checkbox: import_prompts.checkbox,
+  confirm: import_prompts.confirm
+};
+var defaultDeps = {
+  installAgentsImpl: installAgents,
+  runDoctorImpl: runDoctor
+};
+function defaultAgentSelection(scope, agentSpecs) {
+  void scope;
+  void agentSpecs;
+  return /* @__PURE__ */ new Set();
+}
+function validateAgentSelection(scope, agentSpecs, selectedAgents) {
+  void scope;
+  void agentSpecs;
+  if (selectedAgents.size === 0) {
+    return "Select at least one subagent.";
+  }
+  return void 0;
+}
+function formatResultSummary(result, validationReport) {
+  const lines = [
+    "Install complete",
+    `validation: ${validationReport.issues.length === 0 ? "ok" : "issues found"}`
+  ];
+  for (const path of result.agentPaths.slice(0, 8)) {
+    lines.push(path);
+  }
+  for (const path of result.agentPreservedPaths.slice(0, 4)) {
+    lines.push(`agent preserved: ${path}`);
+  }
+  if (validationReport.issues.length > 0) {
+    lines.push("issues:");
+    for (const issue of validationReport.issues.slice(0, 4)) {
+      lines.push(issue.path ? `- ${issue.path}: ${issue.message}` : `- ${issue.message}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function runTui(projectRoot, options = {}) {
+  const prompt = options.promptAdapter ?? defaultPromptAdapter;
+  const deps = { ...defaultDeps, ...options.deps };
+  try {
+    while (true) {
+      const scope = await prompt.select({
+        message: `Choose an install target for ${projectRoot}`,
+        choices: [
+          { value: "project", name: "Project (.codex/agents in current project)" },
+          { value: "global", name: "Global (~/.codex/agents)" }
+        ]
+      });
+      const categories = getCategories({
+        projectRoot,
+        includeProject: scope === "project",
+        includeGlobal: true,
+        catalogRoots: options.catalogRoots
+      });
+      const selectedCategoryKeys = await prompt.checkbox({
+        message: "Select categories. Leave empty to browse all agents.",
+        choices: categories.map((category) => ({
+          value: category.key,
+          name: `${category.title} - ${category.description}`
+        }))
+      });
+      const categorySet = new Set(selectedCategoryKeys);
+      const agentSpecs = getAgentsByCategory(categorySet, {
+        projectRoot,
+        includeProject: scope === "project",
+        includeGlobal: true,
+        catalogRoots: options.catalogRoots
+      });
+      const defaultSelected = defaultAgentSelection(scope, agentSpecs);
+      const selectedAgentsList = await prompt.checkbox({
+        message: "Select subagents.",
+        choices: agentSpecs.map((agent) => ({
+          value: agent.key,
+          name: `${agent.name} - ${agent.description}`,
+          checked: defaultSelected.has(agent.key) ? true : void 0
+        }))
+      });
+      const selectedAgents = new Set(selectedAgentsList);
+      const validationError = validateAgentSelection(scope, agentSpecs, selectedAgents);
+      if (validationError) {
+        console.error(validationError);
+        continue;
+      }
+      const confirmed = await prompt.confirm({
+        message: `Install ${selectedAgents.size} agent(s) into ${resolveTargetDir(scope, projectRoot)}?`,
+        default: true
+      });
+      if (!confirmed) {
+        continue;
+      }
+      const result = deps.installAgentsImpl({
+        scope,
+        projectRoot,
+        agentKeys: [...selectedAgents].sort(),
+        catalogRoots: options.catalogRoots
+      });
+      const validationReport = deps.runDoctorImpl({
+        projectRoot,
+        scope,
+        catalogRoots: options.catalogRoots
+      });
+      console.log(formatResultSummary(result, validationReport));
+      return validationReport.issues.length === 0 ? 0 : 1;
+    }
+  } catch (error) {
+    if (error instanceof GenerationError) {
+      console.error(`error: ${error.message}`);
+      return 1;
+    }
+    const errorName = error instanceof Error ? error.name : "";
+    if (errorName === "ExitPromptError") {
+      return 130;
+    }
+    throw error;
+  }
+}
+
+// src/usage.ts
+var UsageError = class extends Error {
+};
+function visibleInstalledAgents(options) {
+  const agents = getAgents({
+    projectRoot: options.projectRoot,
+    homeDir: options.homeDir,
+    includeProject: options.scope === "project",
+    includeGlobal: true
+  });
+  const visible = agents.filter((agent) => agent.source === "project" || agent.source === "global");
+  if (visible.length === 0) {
+    throw new UsageError("no installed agents were found for the selected scope");
+  }
+  return visible;
+}
+function starterPrompt(task, orchestratorKey, workerKeys) {
+  if (orchestratorKey) {
+    if (workerKeys.length > 0) {
+      return `Use ${orchestratorKey} to coordinate this task: "${task}". Delegate to ${workerKeys.join(", ")} when appropriate.`;
+    }
+    return `Use ${orchestratorKey} for this task: "${task}".`;
+  }
+  if (workerKeys.length > 0) {
+    return `For this task: "${task}", use these installed agents as needed: ${workerKeys.join(", ")}.`;
+  }
+  throw new UsageError("no installed agents were found for the selected scope");
+}
+function renderUsageGuide(options) {
+  const visibleAgents = visibleInstalledAgents(options);
+  const taskText = (options.task ?? "<describe the task here>").trim();
+  const orchestrators = visibleAgents.filter((agent) => agent.category === ORCHESTRATOR_CATEGORY);
+  let orchestratorKey;
+  if (orchestrators.length > 0) {
+    orchestratorKey = orchestrators.find((agent) => agent.key === DEFAULT_ORCHESTRATOR_KEY)?.key ?? orchestrators[0]?.key;
+  }
+  const workerKeys = visibleAgents.filter((agent) => agent.key !== orchestratorKey).map((agent) => agent.key);
+  const lines = [
+    `scope: ${options.scope}`,
+    "visible installed agents:",
+    ...visibleAgents.map((agent) => `- ${agent.key} [${agent.source}] - ${agent.description}`),
+    "",
+    "starter prompt:",
+    starterPrompt(taskText, orchestratorKey, workerKeys),
+    "",
+    "direct prompt ideas:",
+    ...visibleAgents.slice(0, 6).map(
+      (agent) => `- Use ${agent.key} for this task: "${taskText}". Focus on: ${agent.description}`
+    ),
+    "",
+    "session tip:",
+    "- If Codex spawns a subagent thread, use /agent to inspect or continue that thread."
+  ];
+  return lines.join("\n");
+}
+
+// src/cli.ts
+function collectRepeatedOption(value, previous = []) {
+  return [...previous, value];
+}
+function buildCatalogCommand() {
+  const catalog = new import_commander.Command("catalog").description("Browse the stable subagent catalog.").argument("[operation]", "Optional operation. Use 'import' for persistent catalog imports.").option("--project-root <path>", "Project root used for project-scope catalog discovery.", ".").option("--scope <scope>", "Catalog visibility scope: project or global.", "project").option(
+    "--catalog-root <path>",
+    "One external awesome-style categories root. Repeat to provide more than one.",
+    collectRepeatedOption,
+    []
+  ).option("--source-name <name>", "Synced source name for catalog sync.", "voltagent").option("--source-root <path>", "Local awesome-style categories root used for catalog sync.").option("--agents <keys>", "Comma-separated agent keys to import.").option("--categories <keys>", "Comma-separated category keys to import.").option("--overwrite", "Overwrite existing imported templates.").action(async (operation, options) => {
+    if (!operation) {
+      console.log(
+        renderCatalogOutput({
+          projectRoot: options.projectRoot,
+          includeProject: options.scope === "project",
+          includeGlobal: true,
+          catalogRoots: options.catalogRoot ?? []
+        })
+      );
+      return;
+    }
+    if (operation === "sync") {
+      try {
+        const result = await syncCatalog({
+          projectRoot: options.projectRoot,
+          scope: options.scope,
+          sourceName: options.sourceName,
+          sourceRoot: options.sourceRoot
+        });
+        console.log(`source: ${result.sourceName}`);
+        console.log(`origin: ${result.sourceLabel}`);
+        console.log(`target: ${result.targetRoot}`);
+        console.log(`files: ${result.copiedPaths.length}`);
+        for (const path of result.copiedPaths.slice(0, 10)) {
+          console.log(`synced: ${path}`);
+        }
+        if (result.copiedPaths.length > 10) {
+          console.log(`... ${result.copiedPaths.length - 10} more`);
+        }
+      } catch (error) {
+        const message = error instanceof CatalogSyncError ? error.message : String(error);
+        console.error(`error: ${message}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+    if (operation !== "import") {
+      console.error(`error: unknown catalog operation: ${operation}`);
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const result = importCatalog({
+        projectRoot: options.projectRoot,
+        scope: options.scope,
+        catalogRoots: options.catalogRoot ?? [],
+        agentKeys: (options.agents ?? "").split(",").map((item) => item.trim()).filter(Boolean),
+        categoryKeys: (options.categories ?? "").split(",").map((item) => item.trim()).filter(Boolean),
+        overwrite: options.overwrite
+      });
+      console.log(`target: ${result.targetRoot}`);
+      if (result.importedCategoryKeys.length > 0) {
+        console.log(`categories: ${result.importedCategoryKeys.join(", ")}`);
+      }
+      if (result.importedAgentKeys.length > 0) {
+        console.log(`agents: ${result.importedAgentKeys.join(", ")}`);
+      }
+      for (const path of result.createdPaths) {
+        console.log(`created: ${path}`);
+      }
+      for (const path of result.preservedPaths) {
+        console.log(`preserved: ${path}`);
+      }
+    } catch (error) {
+      const message = error instanceof CatalogImportError ? error.message : String(error);
+      console.error(`error: ${message}`);
+      process.exitCode = 1;
+    }
+  });
+  return catalog;
+}
+function buildTemplateCommand() {
+  const template = new import_commander.Command("template").description("Scaffold custom catalog templates.");
+  template.command("init").description("Create a category README and agent TOML skeleton.").option("--project-root <path>", "Project root used for project-scope templates.", ".").option("--scope <scope>", "Template target scope: project or global.", "project").option("--catalog-root <path>", "Explicit external categories root.").requiredOption("--category <key>", "Category key, for example custom-ops.").option("--category-prefix <prefix>", "Numeric category prefix, for example 11.").option("--category-title <title>", "Display title for the category.").option("--category-description <description>", "Short category description.").requiredOption("--agent <key>", "Agent key, for example custom-coordinator.").option("--agent-name <name>", "Human-friendly agent name.").option("--agent-description <description>", "Short agent description.").option("--model <model>", "Model name used in the generated TOML.", "gpt-5.4").option("--reasoning-effort <level>", "Model reasoning effort.", "medium").option("--sandbox-mode <mode>", "Sandbox mode stored in the generated TOML.", "read-only").option("--orchestrator", "Mark the generated agent as a root orchestrator template.").option("--overwrite", "Overwrite existing template files.").action((options) => {
+    try {
+      const result = initTemplate({
+        projectRoot: options.projectRoot,
+        scope: options.scope,
+        catalogRoot: options.catalogRoot,
+        categoryKey: options.category,
+        categoryPrefix: options.categoryPrefix,
+        categoryTitle: options.categoryTitle,
+        categoryDescription: options.categoryDescription,
+        agentKey: options.agent,
+        agentName: options.agentName,
+        agentDescription: options.agentDescription,
+        model: options.model,
+        reasoningEffort: options.reasoningEffort,
+        sandboxMode: options.sandboxMode,
+        orchestrator: options.orchestrator,
+        overwrite: options.overwrite
+      });
+      console.log(`target: ${result.targetRoot}`);
+      console.log(`category: ${result.categoryDir}`);
+      console.log(`agent: ${result.agentPath}`);
+      for (const path of result.createdPaths) {
+        console.log(`created: ${path}`);
+      }
+      for (const path of result.preservedPaths) {
+        console.log(`preserved: ${path}`);
+      }
+    } catch (error) {
+      const message = error instanceof TemplateError ? error.message : String(error);
+      console.error(`error: ${message}`);
+      process.exitCode = 1;
+    }
+  });
+  return template;
+}
+function buildProgram() {
+  const program = new import_commander.Command();
+  program.name("codex-subagent-kit").description("Install and manage Codex subagent catalogs, templates, and TOML definitions.").addHelpText(
+    "after",
+    [
+      "",
+      `Stable commands available: ${STABLE_COMMANDS.join(", ")}`
+    ].join("\n")
+  ).action(async () => {
+    process.exitCode = await runTui((0, import_node_path8.resolve)(process.cwd()), {
+      catalogRoots: []
+    });
+  });
+  program.command("install").description("Install selected subagents without the TUI.").requiredOption("--scope <scope>", "Install target scope: project or global.").requiredOption("--agents <keys>", "Comma-separated agent keys.").option("--project-root <path>", "Project root used for project-scope installs.", ".").option(
+    "--catalog-root <path>",
+    "One external awesome-style categories root. Repeat to provide more than one.",
+    collectRepeatedOption,
+    []
+  ).option("--overwrite", "Overwrite existing generated agent files.").option("--validate", "Run doctor immediately after install.").action((options) => {
+    try {
+      const result = installAgents({
+        scope: options.scope,
+        projectRoot: options.projectRoot,
+        agentKeys: options.agents.split(",").map((item) => item.trim()).filter(Boolean),
+        catalogRoots: options.catalogRoot ?? [],
+        overwrite: options.overwrite
+      });
+      console.log(`target: ${resolveTargetDir(options.scope, options.projectRoot)}`);
+      for (const path of result.agentPaths) {
+        console.log(path);
+      }
+      for (const path of result.agentPreservedPaths) {
+        console.log(`agent preserved: ${path}`);
+      }
+      if (!options.validate) {
+        return;
+      }
+      const report = runDoctor({
+        projectRoot: options.projectRoot,
+        scope: options.scope,
+        catalogRoots: options.catalogRoot ?? []
+      });
+      console.log("");
+      console.log(renderDoctorReport(report));
+      if (report.issues.length > 0) {
+        process.exitCode = 1;
+      }
+    } catch (error) {
+      const message = error instanceof GenerationError ? error.message : String(error);
+      console.error(`error: ${message}`);
+      process.exitCode = 1;
+    }
+  });
+  program.command("doctor").description("Validate installed agent definitions and injected catalog roots.").option("--project-root <path>", "Project root used for project-scope validation.", ".").option("--scope <scope>", "Validation scope: project or global.", "project").option(
+    "--catalog-root <path>",
+    "One external awesome-style categories root. Repeat to provide more than one.",
+    collectRepeatedOption,
+    []
+  ).action((options) => {
+    const report = runDoctor({
+      projectRoot: options.projectRoot,
+      scope: options.scope,
+      catalogRoots: options.catalogRoot ?? []
+    });
+    console.log(renderDoctorReport(report));
+    if (report.issues.length > 0) {
+      process.exitCode = 1;
+    }
+  });
+  program.command("usage").description("Render starter prompts for the installed agents visible in the selected scope.").option("--project-root <path>", "Project root used for project-scope usage output.", ".").option("--scope <scope>", "Usage scope: project or global.", "project").option("--task <description>", "Task description to embed in the starter prompt.").action((options) => {
+    try {
+      console.log(
+        renderUsageGuide({
+          projectRoot: options.projectRoot,
+          scope: options.scope,
+          task: options.task
+        })
+      );
+    } catch (error) {
+      const message = error instanceof UsageError ? error.message : String(error);
+      console.error(`error: ${message}`);
+      process.exitCode = 1;
+    }
+  });
+  program.command("tui").description("Run the interactive install-first TUI.").option("--project-root <path>", "Project root used for the install session.", ".").option(
+    "--catalog-root <path>",
+    "One external awesome-style categories root. Repeat to provide more than one.",
+    collectRepeatedOption,
+    []
+  ).action(async (options) => {
+    process.exitCode = await runTui((0, import_node_path8.resolve)(options.projectRoot), {
+      catalogRoots: options.catalogRoot ?? []
+    });
+  });
+  program.addCommand(buildCatalogCommand());
+  program.addCommand(buildTemplateCommand());
+  return program;
+}
+async function main(argv = process.argv) {
+  const program = buildProgram();
+  await program.parseAsync(argv);
+  return typeof process.exitCode === "number" ? process.exitCode : 0;
+}
+if (require.main === module) {
+  void main().then((exitCode) => {
+    process.exitCode = exitCode;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildProgram,
+  main
+});