apcore-cli 0.4.0 → 0.5.0

package/dist/index.js

@@ -1,5 +1,11 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -50,11 +56,19 @@ function exitCodeForError(error2) {
       SCHEMA_CIRCULAR_REF: EXIT_CODES.SCHEMA_CIRCULAR_REF,
       APPROVAL_DENIED: EXIT_CODES.APPROVAL_DENIED,
       APPROVAL_TIMEOUT: EXIT_CODES.APPROVAL_TIMEOUT,
+      APPROVAL_PENDING: EXIT_CODES.APPROVAL_DENIED,
       CONFIG_NOT_FOUND: EXIT_CODES.CONFIG_NOT_FOUND,
       CONFIG_INVALID: EXIT_CODES.CONFIG_INVALID,
       MODULE_EXECUTE_ERROR: EXIT_CODES.MODULE_EXECUTE_ERROR,
       MODULE_TIMEOUT: EXIT_CODES.MODULE_TIMEOUT,
-      ACL_DENIED: EXIT_CODES.ACL_DENIED
+      ACL_DENIED: EXIT_CODES.ACL_DENIED,
+      // Config Bus errors (apcore >= 0.15.0)
+      CONFIG_NAMESPACE_RESERVED: EXIT_CODES.CONFIG_NAMESPACE_RESERVED,
+      CONFIG_NAMESPACE_DUPLICATE: EXIT_CODES.CONFIG_NAMESPACE_DUPLICATE,
+      CONFIG_ENV_PREFIX_CONFLICT: EXIT_CODES.CONFIG_ENV_PREFIX_CONFLICT,
+      CONFIG_MOUNT_ERROR: EXIT_CODES.CONFIG_MOUNT_ERROR,
+      CONFIG_BIND_ERROR: EXIT_CODES.CONFIG_BIND_ERROR,
+      ERROR_FORMATTER_DUPLICATE: EXIT_CODES.ERROR_FORMATTER_DUPLICATE
     };
     if (code && code in codeMap) {
       return codeMap[code];
@@ -124,6 +138,13 @@ var init_errors = __esm({
       CONFIG_INVALID: 47,
       SCHEMA_CIRCULAR_REF: 48,
       ACL_DENIED: 77,
+      // Config Bus errors (apcore >= 0.15.0)
+      CONFIG_NAMESPACE_RESERVED: 78,
+      CONFIG_NAMESPACE_DUPLICATE: 78,
+      CONFIG_ENV_PREFIX_CONFLICT: 78,
+      CONFIG_MOUNT_ERROR: 66,
+      CONFIG_BIND_ERROR: 65,
+      ERROR_FORMATTER_DUPLICATE: 70,
       KEYBOARD_INTERRUPT: 130
     };
   }
@@ -137,9 +158,9 @@ __export(audit_exports, {
   setAuditLogger: () => setAuditLogger
 });
 import * as crypto from "crypto";
-import * as fs2 from "fs";
+import * as fs3 from "fs";
 import * as os from "os";
-import * as path3 from "path";
+import * as path4 from "path";
 function setAuditLogger(auditLogger) {
   _auditLogger = auditLogger;
 }
@@ -153,7 +174,7 @@ var init_audit = __esm({
     init_esm_shims();
     _auditLogger = null;
     AuditLogger = class _AuditLogger {
-      static DEFAULT_PATH = path3.join(
+      static DEFAULT_PATH = path4.join(
         os.homedir(),
         ".apcore-cli",
         "audit.jsonl"
@@ -165,7 +186,7 @@ var init_audit = __esm({
       }
       ensureDirectory() {
         try {
-          fs2.mkdirSync(path3.dirname(this.logPath), { recursive: true });
+          fs3.mkdirSync(path4.dirname(this.logPath), { recursive: true });
         } catch {
         }
       }
@@ -180,7 +201,7 @@ var init_audit = __esm({
           duration_ms: durationMs
         };
         try {
-          fs2.appendFileSync(this.logPath, JSON.stringify(entry) + "\n");
+          fs3.appendFileSync(this.logPath, JSON.stringify(entry) + "\n");
         } catch (err) {
           console.warn(`Could not write audit log: ${err}`);
         }
@@ -381,9 +402,9 @@ var init_auth = __esm({
 
 // src/security/sandbox.ts
 import * as child_process from "child_process";
-import * as fs3 from "fs";
+import * as fs4 from "fs";
 import * as os3 from "os";
-import * as path4 from "path";
+import * as path5 from "path";
 var Sandbox;
 var init_sandbox = __esm({
   "src/security/sandbox.ts"() {
@@ -416,8 +437,8 @@ var init_sandbox = __esm({
             env[key] = value;
           }
         }
-        const tmpDir = fs3.mkdtempSync(
-          path4.join(os3.tmpdir(), "apcore_sandbox_")
+        const tmpDir = fs4.mkdtempSync(
+          path5.join(os3.tmpdir(), "apcore_sandbox_")
         );
         try {
           env.HOME = tmpDir;
@@ -455,7 +476,7 @@ var init_sandbox = __esm({
           );
         } finally {
           try {
-            fs3.rmSync(tmpDir, { recursive: true, force: true });
+            fs4.rmSync(tmpDir, { recursive: true, force: true });
           } catch {
           }
         }
@@ -491,10 +512,10 @@ init_esm_shims();
 // src/main.ts
 init_esm_shims();
 init_errors();
-import { readFileSync } from "fs";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import * as path5 from "path";
-import { Command, CommanderError, Option } from "commander";
+import { readFileSync as readFileSync3 } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import * as path6 from "path";
+import { Command as Command2, CommanderError, Option as Option2 } from "commander";
 
 // src/ref-resolver.ts
 init_esm_shims();
@@ -1218,1120 +1239,1196 @@ function getCliDisplayFields(descriptor) {
   return [name, desc, tags];
 }
 
-// src/main.ts
-var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
-var verboseHelp = false;
-function setVerboseHelp(verbose) {
-  verboseHelp = verbose;
-}
-var docsUrl = null;
-function setDocsUrl(url) {
-  docsUrl = url;
-}
-function hasVerboseFlag() {
-  return process.argv.includes("--verbose");
-}
-var VERSION = "0.0.0";
-try {
-  const pkg = JSON.parse(readFileSync(path5.resolve(__dirname2, "../package.json"), "utf-8"));
-  VERSION = pkg.version;
-} catch {
-}
-function createCli(extensionsDir, progName, verbose = false) {
-  verboseHelp = verbose;
-  const resolvedProgName = progName ?? path5.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
-  const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? "WARNING";
-  setLogLevel(cliLogLevel);
-  const program = new Command(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--commands-dir <path>", "Path to convention-based commands directory").option("--binding <path>", "Path to binding.yaml for display overlay").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
-  const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
-  void resolvedExtDir;
-  registerInitCommand(program);
-  program.hook("preAction", async (thisCommand) => {
-    const opts = thisCommand.opts();
-    const commandsDir = opts.commandsDir;
-    const bindingPath = opts.binding;
-    await applyToolkitIntegration(commandsDir, bindingPath);
-  });
-  return program;
-}
-async function applyToolkitIntegration(commandsDir, bindingPath) {
-  if (!commandsDir && !bindingPath) {
-    return;
-  }
+// src/config.ts
+init_esm_shims();
+import * as fs2 from "fs";
+import yaml from "js-yaml";
+var DEFAULTS = {
+  "extensions.root": "./extensions",
+  "logging.level": "WARNING",
+  "sandbox.enabled": false,
+  "cli.stdin_buffer_limit": 10485760,
+  "cli.auto_approve": false,
+  "cli.help_text_max_length": 1e3,
+  // Namespace-mode aliases (apcore >= 0.15.0 Config Bus)
+  "apcore-cli.stdin_buffer_limit": 10485760,
+  "apcore-cli.auto_approve": false,
+  "apcore-cli.help_text_max_length": 1e3,
+  "apcore-cli.logging_level": "WARNING"
+};
+var NAMESPACE_TO_LEGACY = {
+  "apcore-cli.stdin_buffer_limit": "cli.stdin_buffer_limit",
+  "apcore-cli.auto_approve": "cli.auto_approve",
+  "apcore-cli.help_text_max_length": "cli.help_text_max_length",
+  "apcore-cli.logging_level": "logging.level"
+};
+var LEGACY_TO_NAMESPACE = Object.fromEntries(
+  Object.entries(NAMESPACE_TO_LEGACY).map(([k, v]) => [v, k])
+);
+function registerConfigNamespace() {
   try {
-    const toolkitModule = "apcore-toolkit";
-    const toolkit = await import(
-      /* @vite-ignore */
-      toolkitModule
-    );
-    if (commandsDir) {
-      console.warn("Convention scanning not yet available in TypeScript toolkit");
-    }
-    if (bindingPath) {
-      const resolver = new toolkit.DisplayResolver();
-      void resolver;
+    const { Config } = __require("apcore-js");
+    if (typeof Config?.registerNamespace === "function") {
+      Config.registerNamespace({
+        name: "apcore-cli",
+        envPrefix: "APCORE_CLI",
+        defaults: {
+          stdin_buffer_limit: 10485760,
+          auto_approve: false,
+          help_text_max_length: 1e3,
+          logging_level: "WARNING"
+        }
+      });
     }
   } catch {
-    console.warn("apcore-toolkit not installed \u2014 toolkit features unavailable");
   }
 }
-function main(progName) {
-  verboseHelp = hasVerboseFlag();
-  const program = createCli(void 0, progName, verboseHelp);
-  try {
-    program.parse(process.argv);
-  } catch (error2) {
-    if (error2 instanceof CommanderError) {
-      process.exit(error2.exitCode);
+var ConfigResolver = class {
+  cliFlags;
+  configPath;
+  fileCache = null;
+  fileCacheLoaded = false;
+  constructor(cliFlags, configPath) {
+    this.cliFlags = cliFlags ?? {};
+    this.configPath = configPath ?? "apcore.yaml";
+  }
+  /**
+   * Resolve a single configuration key across all four tiers.
+   */
+  resolve(key, cliFlag, envVar) {
+    const flagKey = cliFlag ?? key;
+    if (flagKey in this.cliFlags) {
+      const value = this.cliFlags[flagKey];
+      if (value !== null && value !== void 0) {
+        return value;
+      }
     }
-    const code = exitCodeForError(error2);
-    if (error2 instanceof Error) {
-      process.stderr.write(`Error: ${error2.message}
-`);
+    if (envVar) {
+      const envValue = process.env[envVar];
+      if (envValue !== void 0 && envValue !== "") {
+        return envValue;
+      }
     }
-    process.exit(code);
-  }
-}
-function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName, verbose = verboseHelp) {
-  const moduleId = moduleDef.id;
-  let resolvedSchema = {};
-  let schemaOptions = [];
-  const display = getDisplay(moduleDef);
-  const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
-  const effectiveCmdName = cmdName ?? cliDisplay.alias ?? moduleId;
-  const cmdHelp = cliDisplay.description ?? moduleDef.description;
-  const inputSchema = moduleDef.inputSchema;
-  if (inputSchema && typeof inputSchema === "object" && inputSchema.properties) {
-    try {
-      resolvedSchema = resolveRefs(inputSchema, 32, moduleId);
-    } catch {
-      resolvedSchema = inputSchema;
+    const fileValue = this.resolveFromFile(key);
+    if (fileValue !== void 0) {
+      return fileValue;
     }
-    schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
-  }
-  const cmd = new Command(effectiveCmdName).description(cmdHelp);
-  const inputOpt = new Option("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
-  const yesOpt = new Option("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
-  const largeInputOpt = new Option("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
-  const formatOpt = new Option("--format <format>", "Set output format: 'json' for machine-readable, 'table' for human-readable");
-  const sandboxOpt = new Option("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
-  if (!verbose) {
-    inputOpt.hideHelp();
-    yesOpt.hideHelp();
-    largeInputOpt.hideHelp();
-    formatOpt.hideHelp();
-  }
-  cmd.addOption(inputOpt);
-  cmd.addOption(yesOpt);
-  cmd.addOption(largeInputOpt);
-  cmd.addOption(formatOpt);
-  cmd.addOption(sandboxOpt);
-  const footerParts = [];
-  if (!verbose) {
-    footerParts.push("Use --verbose to show all options (including built-in apcore options).");
-  }
-  if (docsUrl) {
-    footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);
-  }
-  if (footerParts.length > 0) {
-    cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
-  }
-  for (const opt of schemaOptions) {
-    if (opt.parseArg) {
-      cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
-    } else {
-      cmd.option(opt.flags, opt.description, opt.defaultValue);
+    const altKey = NAMESPACE_TO_LEGACY[key] ?? LEGACY_TO_NAMESPACE[key];
+    if (altKey) {
+      const altFileValue = this.resolveFromFile(altKey);
+      if (altFileValue !== void 0) {
+        return altFileValue;
+      }
     }
+    return DEFAULTS[key];
   }
-  cmd.action(async (options) => {
-    const stdinFlag = options.input;
-    const autoApprove = options.yes;
-    const largeInput = options.largeInput;
-    const outputFormat = options.format;
-    const sandboxEnabled = options.sandbox;
-    const schemaKwargs = {};
-    const builtinKeys = /* @__PURE__ */ new Set(["input", "yes", "largeInput", "format", "sandbox", "verbose"]);
-    for (const [k, v] of Object.entries(options)) {
-      if (!builtinKeys.has(k)) {
-        schemaKwargs[k] = v;
-      }
+  /**
+   * Load a value from the config file using a dot-separated key path.
+   */
+  resolveFromFile(key) {
+    if (!this.fileCacheLoaded) {
+      this.fileCache = this.loadConfigFile();
+      this.fileCacheLoaded = true;
+    }
+    if (this.fileCache === null) {
+      return void 0;
     }
+    return this.fileCache[key];
+  }
+  /**
+   * Load and flatten a YAML config file.
+   */
+  loadConfigFile() {
+    let content;
     try {
-      const merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
-      const reconverted = reconvertEnumValues(merged, schemaOptions);
-      await checkApproval(moduleDef, autoApprove);
-      const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
-      const sandbox = new Sandbox2(sandboxEnabled);
-      const startTime = performance.now();
-      const result = await sandbox.execute(moduleId, reconverted, executor);
-      const durationMs = Math.round(performance.now() - startTime);
-      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-      const auditLogger = getAuditLogger2();
-      if (auditLogger) {
-        auditLogger.logExecution(moduleId, reconverted, "success", 0, durationMs);
-      }
-      formatExecResult(result, outputFormat);
+      content = fs2.readFileSync(this.configPath, "utf-8");
     } catch (err) {
-      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-      const auditLogger = getAuditLogger2();
-      const code = exitCodeForError(err);
-      if (auditLogger) {
-        auditLogger.logExecution(moduleId, {}, "error", code, 0);
-      }
-      if (err instanceof Error) {
-        process.stderr.write(`Error: ${err.message}
-`);
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        return null;
       }
-      process.exit(code);
+      console.warn(
+        `Configuration file '${this.configPath}' is malformed, using defaults.`
+      );
+      return null;
     }
-  });
-  return cmd;
-}
-function validateModuleId(moduleId) {
-  if (moduleId.length > 128) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/.test(moduleId)) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-}
-async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
-  const cliKwargsNonNull = {};
-  for (const [k, v] of Object.entries(cliKwargs)) {
-    if (v !== null && v !== void 0) {
-      cliKwargsNonNull[k] = v;
+    let parsed;
+    try {
+      parsed = yaml.load(content);
+    } catch {
+      console.warn(
+        `Configuration file '${this.configPath}' is malformed, using defaults.`
+      );
+      return null;
     }
-  }
-  if (!stdinFlag) {
-    return cliKwargsNonNull;
-  }
-  if (stdinFlag === "-") {
-    const raw = await readStdin();
-    const rawSize = Buffer.byteLength(raw, "utf-8");
-    if (rawSize > 10485760 && !largeInput) {
-      process.stderr.write(
-        "Error: STDIN input exceeds 10MB limit. Use --large-input to override.\n"
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-    }
-    if (!raw) {
-      return cliKwargsNonNull;
-    }
-    let stdinData;
-    try {
-      stdinData = JSON.parse(raw);
-    } catch {
-      process.stderr.write(
-        "Error: STDIN does not contain valid JSON.\n"
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.warn(
+        `Configuration file '${this.configPath}' is malformed, using defaults.`
       );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      return null;
     }
-    if (typeof stdinData !== "object" || stdinData === null || Array.isArray(stdinData)) {
-      process.stderr.write(
-        `Error: STDIN JSON must be an object, got ${Array.isArray(stdinData) ? "array" : typeof stdinData}.
-`
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    return this.flattenDict(parsed);
+  }
+  /**
+   * Flatten nested dict to dot-notation keys.
+   */
+  flattenDict(d, prefix = "") {
+    const result = {};
+    for (const [key, value] of Object.entries(d)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        Object.assign(
+          result,
+          this.flattenDict(value, fullKey)
+        );
+      } else {
+        result[fullKey] = value;
+      }
     }
-    return { ...stdinData, ...cliKwargsNonNull };
+    return result;
   }
-  return cliKwargsNonNull;
+};
+
+// src/shell.ts
+init_esm_shims();
+init_errors();
+import { readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import * as path3 from "path";
+import { spawnSync } from "child_process";
+import { Command, Help, Option } from "commander";
+var __dirname2 = path3.dirname(fileURLToPath2(import.meta.url));
+var SHELL_VERSION = "0.0.0";
+try {
+  const pkg = JSON.parse(readFileSync2(path3.resolve(__dirname2, "../package.json"), "utf-8"));
+  SHELL_VERSION = pkg.version;
+} catch {
 }
-function readStdin() {
-  return new Promise((resolve3, reject) => {
-    const chunks = [];
-    const onData = (chunk) => chunks.push(chunk);
-    const onEnd = () => {
-      cleanup();
-      resolve3(Buffer.concat(chunks).toString("utf-8"));
-    };
-    const onError = (err) => {
-      cleanup();
-      reject(err);
-    };
-    const cleanup = () => {
-      process.stdin.removeListener("data", onData);
-      process.stdin.removeListener("end", onEnd);
-      process.stdin.removeListener("error", onError);
-    };
-    process.stdin.on("data", onData);
-    process.stdin.on("end", onEnd);
-    process.stdin.on("error", onError);
-    process.stdin.resume();
-  });
+function makeFunctionName(progName) {
+  return "_" + progName.replace(/[^a-zA-Z0-9]/g, "_");
 }
-function reconvertEnumValues(kwargs, options) {
-  const result = { ...kwargs };
-  for (const opt of options) {
-    if (!opt.enumOriginalTypes) continue;
-    const paramName = opt.name;
-    if (!(paramName in result) || result[paramName] === null || result[paramName] === void 0) {
-      continue;
-    }
-    const strVal = String(result[paramName]);
-    const origType = opt.enumOriginalTypes[strVal];
-    if (origType === "int") {
-      result[paramName] = parseInt(strVal, 10);
-    } else if (origType === "float") {
-      result[paramName] = parseFloat(strVal);
-    } else if (origType === "bool") {
-      result[paramName] = strVal.toLowerCase() === "true";
-    }
-  }
-  return result;
+function shellQuote(s) {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+function generateBashCompletion(progName) {
+  const fn = makeFunctionName(progName);
+  const quoted = shellQuote(progName);
+  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e "process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})" 2>/dev/null`;
+  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const ids=JSON.parse(m).map(x=>x.id);
+const g=new Set(),t=[];
+ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});
+console.log([...g].sort().concat(t.sort()).join(' '))
+" 2>/dev/null`;
+  const groupCmdsCmd = `${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const g=process.env._APCORE_GRP;
+JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
+" 2>/dev/null`;
+  return `${fn}() {
+    local cur prev opts
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+    if [[ \${COMP_CWORD} -eq 1 ]]; then
+        opts="completion describe exec init list man"
+        local groups_and_top=$(${groupsAndTopCmd})
+        COMPREPLY=( $(compgen -W "\${opts} \${groups_and_top}" -- \${cur}) )
+        return 0
+    fi
+
+    if [[ \${COMP_CWORD} -eq 2 ]]; then
+        if [[ "\${COMP_WORDS[1]}" == "exec" ]]; then
+            local modules=$(${moduleListCmd})
+            COMPREPLY=( $(compgen -W "\${modules}" -- \${cur}) )
+            return 0
+        fi
+        export _APCORE_GRP="\${COMP_WORDS[1]}"
+        local group_cmds=$(${groupCmdsCmd})
+        COMPREPLY=( $(compgen -W "\${group_cmds}" -- \${cur}) )
+        return 0
+    fi
 }
+complete -F ${fn} ${quoted}
+`;
+}
+function generateZshCompletion(progName) {
+  const fn = makeFunctionName(progName);
+  const quoted = shellQuote(progName);
+  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e "process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})" 2>/dev/null`;
+  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const ids=JSON.parse(m).map(x=>x.id);
+const g=new Set(),t=[];
+ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});
+console.log([...g].sort().concat(t.sort()).join(' '))
+" 2>/dev/null`;
+  const groupCmdsCmd = `${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const g=process.env._APCORE_GRP;
+JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
+" 2>/dev/null`;
+  return `#compdef ${progName}
 
-// src/cli.ts
-init_esm_shims();
-import { Command as Command2 } from "commander";
-var BUILTIN_COMMANDS = ["completion", "describe", "exec", "init", "list", "man"];
-var LazyModuleGroup = class {
-  registry;
-  executor;
-  helpTextMaxLength;
-  commandCache = /* @__PURE__ */ new Map();
-  /** alias -> canonical module_id (populated lazily) */
-  aliasMap = /* @__PURE__ */ new Map();
-  /** module_id -> descriptor cache (populated during alias map build) */
-  descriptorCache = /* @__PURE__ */ new Map();
-  aliasMapBuilt = false;
-  constructor(registry, executor, helpTextMaxLength = 1e3) {
-    this.registry = registry;
-    this.executor = executor;
-    this.helpTextMaxLength = helpTextMaxLength;
+${fn}() {
+    local -a commands
+    commands=(
+        'list:List available modules'
+        'describe:Show module metadata and schema'
+        'completion:Generate shell completion script'
+        'init:Scaffolding commands'
+        'man:Generate man page'
+    )
+
+    _arguments -C \\
+        '1:command:->command' \\
+        '*::arg:->args'
+
+    case "$state" in
+        command)
+            _describe -t commands '${progName} commands' commands
+            local -a groups_and_top
+            groups_and_top=($(${groupsAndTopCmd}))
+            compadd -a groups_and_top
+            ;;
+        args)
+            case "\${words[1]}" in
+                exec)
+                    local modules
+                    modules=($(${moduleListCmd}))
+                    compadd -a modules
+                    ;;
+                *)
+                    export _APCORE_GRP="\${words[1]}"
+                    local -a group_cmds
+                    group_cmds=($(${groupCmdsCmd}))
+                    compadd -a group_cmds
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+compdef ${fn} ${quoted}
+`;
+}
+function generateFishCompletion(progName) {
+  const quoted = shellQuote(progName);
+  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e \\"process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})\\" 2>/dev/null`;
+  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e \\"const m=require('fs').readFileSync('/dev/stdin','utf8');const ids=JSON.parse(m).map(x=>x.id);const g=new Set(),t=[];ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});console.log([...g].sort().concat(t.sort()).join('\\\\n'))\\" 2>/dev/null`;
+  return `# Fish completions for ${progName}
+complete -c ${quoted} -n "__fish_use_subcommand" -a list -d "List available modules"
+complete -c ${quoted} -n "__fish_use_subcommand" -a describe -d "Show module metadata and schema"
+complete -c ${quoted} -n "__fish_use_subcommand" -a completion -d "Generate shell completion script"
+complete -c ${quoted} -n "__fish_use_subcommand" -a init -d "Scaffolding commands"
+complete -c ${quoted} -n "__fish_use_subcommand" -a man -d "Generate man page"
+complete -c ${quoted} -n "__fish_use_subcommand" -a "(${groupsAndTopCmd})" -d "Module group"
+
+complete -c ${quoted} -n "__fish_seen_subcommand_from exec" -a "(${moduleListCmd})"
+
+function __apcore_group_cmds
+    set -l grp (commandline -opc)[2]
+    set -x _APCORE_GRP $grp
+    ${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const g=process.env._APCORE_GRP;
+JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
+" 2>/dev/null
+end
+
+# Group subcommand completion \u2014 matches when position 1 is not a builtin
+complete -c ${quoted} -n "not __fish_use_subcommand; and not __fish_seen_subcommand_from list describe completion init man exec" -a "(__apcore_group_cmds)"
+`;
+}
+function buildSynopsis(command, progName, commandName) {
+  if (!command) {
+    return `\\fB${progName} ${commandName}\\fR [OPTIONS]`;
   }
-  /**
-   * Build alias->module_id map from display overlay metadata.
-   */
-  buildAliasMap() {
-    if (this.aliasMapBuilt) {
-      return;
-    }
-    try {
-      for (const descriptor of this.registry.listModules()) {
-        const moduleId = descriptor.id;
-        this.descriptorCache.set(moduleId, descriptor);
-        const display = getDisplay(descriptor);
-        const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
-        const cliAlias = cliDisplay.alias;
-        if (cliAlias && cliAlias !== moduleId) {
-          this.aliasMap.set(cliAlias, moduleId);
-        }
-      }
-      this.aliasMapBuilt = true;
-    } catch {
-      warn("Failed to build alias map from registry");
+  const parts = [`\\fB${progName} ${commandName}\\fR`];
+  for (const opt of command.options) {
+    const flag = opt.long ?? opt.short ?? "";
+    if (opt.isBoolean?.()) {
+      parts.push(`[${flag}]`);
+    } else if (opt.required) {
+      const typeName = (opt.argChoices ? "CHOICE" : "VALUE").toUpperCase();
+      parts.push(`${flag} \\fI${typeName}\\fR`);
+    } else {
+      const typeName = (opt.argChoices ? "CHOICE" : "VALUE").toUpperCase();
+      parts.push(`[${flag} \\fI${typeName}\\fR]`);
     }
   }
-  /**
-   * List all available command names from the Registry.
-   */
-  listCommands() {
-    this.buildAliasMap();
-    const reverse = /* @__PURE__ */ new Map();
-    for (const [alias, moduleId] of this.aliasMap) {
-      reverse.set(moduleId, alias);
+  for (const arg of command.registeredArguments ?? []) {
+    const meta = arg.name().toUpperCase();
+    if (arg.required) {
+      parts.push(`\\fI${meta}\\fR`);
+    } else {
+      parts.push(`[\\fI${meta}\\fR]`);
     }
-    const moduleIds = this.registry.listModules().map((m) => m.id);
-    const names = moduleIds.map((mid) => reverse.get(mid) ?? mid);
-    return [...new Set(names)].sort();
   }
-  /**
-   * Get or lazily build a Commander Command for the given module.
-   */
-  getCommand(cmdName) {
-    if (this.commandCache.has(cmdName)) {
-      return this.commandCache.get(cmdName);
-    }
-    this.buildAliasMap();
-    const moduleId = this.aliasMap.get(cmdName) ?? cmdName;
-    let moduleDef = this.descriptorCache.get(moduleId);
-    if (!moduleDef) {
-      moduleDef = this.registry.getModule(moduleId) ?? void 0;
-    }
-    if (!moduleDef) {
-      return null;
-    }
-    const cmd = buildModuleCommand(moduleDef, this.executor, this.helpTextMaxLength, cmdName);
-    this.commandCache.set(cmdName, cmd);
-    return cmd;
+  return parts.join(" ");
+}
+function generateManPage(commandName, command, progName, version = SHELL_VERSION) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const title = `${progName}-${commandName}`.toUpperCase();
+  const pkgLabel = `${progName} ${version}`;
+  const manualLabel = `${progName} Manual`;
+  const sections = [];
+  sections.push(`.TH "${title}" "1" "${today}" "${pkgLabel}" "${manualLabel}"`);
+  sections.push(".SH NAME");
+  const desc = command?.description() ?? commandName;
+  const nameDesc = desc.split("\n")[0].replace(/\.$/, "");
+  sections.push(`${progName}-${commandName} \\- ${nameDesc}`);
+  sections.push(".SH SYNOPSIS");
+  sections.push(buildSynopsis(command, progName, commandName));
+  if (command?.description()) {
+    sections.push(".SH DESCRIPTION");
+    sections.push(
+      command.description().replace(/\\/g, "\\\\").replace(/-/g, "\\-")
+    );
   }
-};
-var LazyGroup = class {
-  members;
-  _executor;
-  _helpTextMaxLength;
-  _cmdCache = /* @__PURE__ */ new Map();
-  command;
-  constructor(members, executor, name, helpTextMaxLength = 1e3) {
-    this.members = members;
-    this._executor = executor;
-    this._helpTextMaxLength = helpTextMaxLength;
-    this.command = new Command2(name).description(`${name} commands`);
-    for (const [cmdName, [, descriptor]] of this.members) {
-      const cmd = buildModuleCommand(
-        descriptor,
-        this._executor,
-        this._helpTextMaxLength,
-        cmdName
-      );
-      this._cmdCache.set(cmdName, cmd);
-      this.command.addCommand(cmd);
+  if (command && command.options.length > 0) {
+    sections.push(".SH OPTIONS");
+    for (const opt of command.options) {
+      const flag = [opt.short, opt.long].filter(Boolean).join(", ");
+      sections.push(".TP");
+      if (opt.isBoolean?.()) {
+        sections.push(`\\fB${flag}\\fR`);
+      } else {
+        sections.push(`\\fB${flag}\\fR \\fIVALUE\\fR`);
+      }
+      if (opt.description) {
+        sections.push(opt.description);
+      }
+      if (opt.defaultValue !== void 0 && !opt.isBoolean?.()) {
+        sections.push(`Default: ${opt.defaultValue}.`);
+      }
     }
   }
-  listCommands() {
-    return [...this.members.keys()].sort();
+  sections.push(".SH ENVIRONMENT");
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_EXTENSIONS_ROOT\\fR");
+  sections.push(
+    "Path to the apcore extensions directory. Overrides the default \\fI./extensions\\fR."
+  );
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_CLI_AUTO_APPROVE\\fR");
+  sections.push(
+    "Set to \\fB1\\fR to bypass approval prompts for modules that require human-in-the-loop confirmation."
+  );
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_CLI_LOGGING_LEVEL\\fR");
+  sections.push(
+    "CLI-specific logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. Takes priority over \\fBAPCORE_LOGGING_LEVEL\\fR. Default: WARNING."
+  );
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_LOGGING_LEVEL\\fR");
+  sections.push(
+    "Global apcore logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. Used as fallback when \\fBAPCORE_CLI_LOGGING_LEVEL\\fR is not set. Default: WARNING."
+  );
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_AUTH_API_KEY\\fR");
+  sections.push(
+    "API key for authenticating with the apcore registry."
+  );
+  sections.push(".SH EXIT CODES");
+  const exitCodes = [
+    ["0", "Success."],
+    ["1", "Module execution error."],
+    ["2", "Invalid CLI input or missing argument."],
+    ["44", "Module not found, disabled, or failed to load."],
+    ["45", "Input failed JSON Schema validation."],
+    [
+      "46",
+      "Approval denied, timed out, or no interactive terminal available."
+    ],
+    [
+      "47",
+      "Configuration error (extensions directory not found or unreadable)."
+    ],
+    ["48", "Schema contains a circular \\fB$ref\\fR."],
+    ["77", "ACL denied \u2014 insufficient permissions for this module."],
+    ["130", "Execution cancelled by user (SIGINT / Ctrl\\-C)."]
+  ];
+  for (const [code, meaning] of exitCodes) {
+    sections.push(`.TP
+\\fB${code}\\fR
+${meaning}`);
   }
-  getCommand(cmdName) {
-    if (this._cmdCache.has(cmdName)) {
-      return this._cmdCache.get(cmdName);
-    }
-    const entry = this.members.get(cmdName);
-    if (!entry) {
-      return null;
-    }
-    const [, descriptor] = entry;
-    const cmd = buildModuleCommand(
-      descriptor,
-      this._executor,
-      this._helpTextMaxLength,
-      cmdName
-    );
-    this._cmdCache.set(cmdName, cmd);
-    return cmd;
+  sections.push(".SH SEE ALSO");
+  sections.push(
+    [
+      `\\fB${progName}\\fR(1)`,
+      `\\fB${progName}\\-list\\fR(1)`,
+      `\\fB${progName}\\-describe\\fR(1)`,
+      `\\fB${progName}\\-completion\\fR(1)`
+    ].join(", ")
+  );
+  return sections.join("\n");
+}
+function roffEscape(s) {
+  return s.replace(/\\/g, "\\\\").replace(/-/g, "\\-").replace(/'/g, "\\(aq");
+}
+function buildProgramManPage(program, progName, version, description, docsUrl2) {
+  const help = new Help();
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const s = [];
+  const resolvedDesc = description ?? program.description() ?? `${progName} CLI`;
+  s.push(`.TH "${progName.toUpperCase()}" "1" "${today}" "${progName} ${version}" "${progName} Manual"`);
+  s.push(".SH NAME");
+  s.push(`${progName} \\- ${roffEscape(resolvedDesc)}`);
+  s.push(".SH SYNOPSIS");
+  s.push(`\\fB${progName}\\fR [\\fIglobal\\-options\\fR] \\fIcommand\\fR [\\fIcommand\\-options\\fR]`);
+  if (resolvedDesc) {
+    s.push(".SH DESCRIPTION");
+    s.push(roffEscape(resolvedDesc));
   }
-};
-var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
-  /** groupName -> { cmdName -> [moduleId, descriptor] } */
-  groupMap = /* @__PURE__ */ new Map();
-  /** cmdName -> [moduleId, descriptor] for top-level (ungrouped) modules */
-  topLevelModules = /* @__PURE__ */ new Map();
-  /** Cached LazyGroup instances */
-  groupCache = /* @__PURE__ */ new Map();
-  groupMapBuilt = false;
-  /**
-   * Determine (groupName | null, commandName) for a module from its display overlay.
-   */
-  static resolveGroup(moduleId, descriptor) {
-    if (!moduleId) {
-      warn("Empty module_id encountered in resolveGroup");
-      return [null, ""];
-    }
-    const display = getDisplay(descriptor);
-    const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
-    const explicitGroup = cliDisplay.group;
-    if (typeof explicitGroup === "string" && explicitGroup !== "") {
-      return [explicitGroup, cliDisplay.alias ?? moduleId];
-    }
-    if (explicitGroup === "") {
-      return [null, cliDisplay.alias ?? moduleId];
-    }
-    const cliName = cliDisplay.alias ?? moduleId;
-    if (cliName.includes(".")) {
-      const dotIdx = cliName.indexOf(".");
-      const group = cliName.substring(0, dotIdx);
-      const cmd = cliName.substring(dotIdx + 1);
-      return [group, cmd];
+  const globalOpts = help.visibleOptions(program).filter((o) => !["help", "version", "all", "man"].includes(o.long?.replace("--", "") ?? ""));
+  if (globalOpts.length > 0) {
+    s.push(".SH GLOBAL OPTIONS");
+    for (const opt of globalOpts) {
+      const flag = [opt.short, opt.long].filter(Boolean).join(", ");
+      s.push(".TP");
+      s.push(`\\fB${roffEscape(flag)}\\fR`);
+      if (opt.description) s.push(roffEscape(opt.description));
     }
-    return [null, cliName];
   }
-  /**
-   * Build the group map from registry modules.
-   */
-  buildGroupMap() {
-    if (this.groupMapBuilt) {
-      return;
-    }
-    try {
-      this.buildAliasMap();
-      for (const descriptor of this.registry.listModules()) {
-        const moduleId = descriptor.id;
-        const cached = this.descriptorCache.get(moduleId);
-        if (!cached) {
-          continue;
+  const allCommands = help.visibleCommands(program);
+  if (allCommands.length > 0) {
+    s.push(".SH COMMANDS");
+    for (const cmd of allCommands) {
+      if (cmd.name() === "help") continue;
+      const desc = help.subcommandDescription(cmd);
+      s.push(".TP");
+      s.push(`\\fB${progName} ${roffEscape(cmd.name())}\\fR`);
+      if (desc) s.push(roffEscape(desc));
+      const cmdHelp = new Help();
+      const opts = cmdHelp.visibleOptions(cmd).filter((o) => !["help", "version"].includes(o.long?.replace("--", "") ?? ""));
+      for (const opt of opts) {
+        const flag = [opt.short, opt.long].filter(Boolean).join(", ");
+        s.push(".RS");
+        s.push(".TP");
+        s.push(`\\fB${roffEscape(flag)}\\fR`);
+        if (opt.description) s.push(roffEscape(opt.description));
+        s.push(".RE");
+      }
+      const subCmds = cmdHelp.visibleCommands(cmd).filter((c) => c.name() !== "help");
+      for (const sub of subCmds) {
+        const subDesc = help.subcommandDescription(sub);
+        s.push(".TP");
+        s.push(`\\fB${progName} ${roffEscape(cmd.name())} ${roffEscape(sub.name())}\\fR`);
+        if (subDesc) s.push(roffEscape(subDesc));
+        const subOpts = cmdHelp.visibleOptions(sub).filter((o) => !["help", "version"].includes(o.long?.replace("--", "") ?? ""));
+        for (const opt of subOpts) {
+          const flag = [opt.short, opt.long].filter(Boolean).join(", ");
+          s.push(".RS");
+          s.push(".TP");
+          s.push(`\\fB${roffEscape(flag)}\\fR`);
+          if (opt.description) s.push(roffEscape(opt.description));
+          s.push(".RE");
         }
-        const [group, cmd] = _GroupedModuleGroup.resolveGroup(moduleId, cached);
-        if (group === null) {
-          this.topLevelModules.set(cmd, [moduleId, cached]);
-        } else if (!/^[a-z][a-z0-9_-]*$/.test(group)) {
-          warn(
-            `Module '${moduleId}': group name '${group}' is not shell-safe \u2014 treating as top-level.`
-          );
-          this.topLevelModules.set(cmd, [moduleId, cached]);
-        } else {
-          if (!this.groupMap.has(group)) {
-            this.groupMap.set(group, /* @__PURE__ */ new Map());
+      }
+    }
+  }
+  s.push(".SH ENVIRONMENT");
+  s.push(".TP");
+  s.push("\\fBAPCORE_EXTENSIONS_ROOT\\fR");
+  s.push("Path to the apcore extensions directory.");
+  s.push(".TP");
+  s.push("\\fBAPCORE_CLI_AUTO_APPROVE\\fR");
+  s.push("Set to \\fB1\\fR to bypass approval prompts.");
+  s.push(".TP");
+  s.push("\\fBAPCORE_CLI_LOGGING_LEVEL\\fR");
+  s.push("CLI\\-specific logging verbosity (DEBUG|INFO|WARNING|ERROR).");
+  s.push(".SH EXIT CODES");
+  const exitCodes = [
+    ["0", "Success."],
+    ["1", "Module execution error."],
+    ["2", "Invalid CLI input or missing argument."],
+    ["44", "Module not found, disabled, or failed to load."],
+    ["45", "Input failed JSON Schema validation."],
+    ["46", "Approval denied or timed out."],
+    ["47", "Configuration error."],
+    ["77", "ACL denied."],
+    ["130", "Cancelled by user (SIGINT)."]
+  ];
+  for (const [code, meaning] of exitCodes) {
+    s.push(`.TP
+\\fB${code}\\fR
+${meaning}`);
+  }
+  s.push(".SH SEE ALSO");
+  s.push(`\\fB${progName} \\-\\-help \\-\\-verbose\\fR for full option list.`);
+  if (docsUrl2) {
+    s.push(`.PP
+Full documentation at \\fI${roffEscape(docsUrl2)}\\fR`);
+  }
+  return s.join("\n");
+}
+function configureManHelp(program, progName, version, description, docsUrl2) {
+  const manOpt = new Option("--man", "Output man page in roff format (use with --help)").hideHelp();
+  program.addOption(manOpt);
+  program.addHelpText("beforeAll", () => {
+    if (program.opts().man) {
+      const roff = buildProgramManPage(program, progName, version, description, docsUrl2) + "\n";
+      if (process.stdout.isTTY) {
+        const pagers = [
+          { cmd: "mandoc", args: ["-a"] },
+          { cmd: "groff", args: ["-man", "-Tutf8"] }
+        ];
+        let rendered = false;
+        for (const { cmd, args } of pagers) {
+          const result = spawnSync(cmd, args, {
+            input: roff,
+            stdio: ["pipe", "pipe", "pipe"],
+            encoding: "utf-8"
+          });
+          if (result.status === 0 && result.stdout) {
+            const pager = process.env.PAGER || "less";
+            const pagerResult = spawnSync(pager, ["-R"], {
+              input: result.stdout,
+              stdio: ["pipe", "inherit", "inherit"]
+            });
+            if (pagerResult.status !== null) {
+              rendered = true;
+              break;
+            }
           }
-          this.groupMap.get(group).set(cmd, [moduleId, cached]);
         }
-      }
-      for (const groupName of this.groupMap.keys()) {
-        if (BUILTIN_COMMANDS.includes(groupName)) {
-          warn(
-            `Group name '${groupName}' collides with a built-in command and will be ignored`
-          );
+        if (!rendered) {
+          process.stdout.write(roff);
         }
+      } else {
+        process.stdout.write(roff);
       }
-      this.groupMapBuilt = true;
-    } catch {
-      warn("Failed to build group map");
+      process.exit(0);
+    }
+    return "";
+  });
+}
+function registerShellCommands(cli, progName = "apcore-cli") {
+  const completionCmd = new Command("completion").description(
+    "Generate a shell completion script and print it to stdout."
+  ).argument("<shell>", "Shell type: bash, zsh, or fish").action((shell) => {
+    const validShells = ["bash", "zsh", "fish"];
+    if (!validShells.includes(shell)) {
+      process.stderr.write(
+        `Error: Unknown shell '${shell}'. Expected: bash, zsh, or fish.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    const resolved = cli.name() || progName;
+    const generators = {
+      bash: () => generateBashCompletion(resolved),
+      zsh: () => generateZshCompletion(resolved),
+      fish: () => generateFishCompletion(resolved)
+    };
+    process.stdout.write(generators[shell]());
+  });
+  cli.addCommand(completionCmd);
+  const manCmd = new Command("man").description("Generate a roff man page for COMMAND and print it to stdout.").argument("<command>", "Command to generate man page for").action((commandName) => {
+    const knownBuiltins = /* @__PURE__ */ new Set(["completion", "describe", "exec", "init", "list", "man"]);
+    const cmd = cli.commands.find((c) => c.name() === commandName) ?? null;
+    if (!cmd && !knownBuiltins.has(commandName)) {
+      process.stderr.write(
+        `Error: Unknown command '${commandName}'.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
+    const resolved = cli.name() || progName;
+    const roff = generateManPage(commandName, cmd, resolved);
+    process.stdout.write(roff);
+  });
+  cli.addCommand(manCmd);
+}
+
+// src/main.ts
+var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
+var verboseHelp = false;
+function setVerboseHelp(verbose) {
+  verboseHelp = verbose;
+}
+var docsUrl = null;
+function setDocsUrl(url) {
+  docsUrl = url;
+}
+function hasVerboseFlag() {
+  return process.argv.includes("--verbose");
+}
+var VERSION = "0.0.0";
+try {
+  const pkg = JSON.parse(readFileSync3(path6.resolve(__dirname3, "../package.json"), "utf-8"));
+  VERSION = pkg.version;
+} catch {
+}
+function createCli(extensionsDir, progName, verbose = false) {
+  verboseHelp = verbose;
+  registerConfigNamespace();
+  const resolvedProgName = progName ?? path6.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
+  const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? "WARNING";
+  setLogLevel(cliLogLevel);
+  const program = new Command2(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--commands-dir <path>", "Path to convention-based commands directory").option("--binding <path>", "Path to binding.yaml for display overlay").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
+  const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
+  void resolvedExtDir;
+  program.addHelpText("after", [
+    "",
+    "Use --help --verbose to show all options (including built-in apcore options).",
+    "Use --help --man to display a formatted man page."
+  ].join("\n"));
+  registerInitCommand(program);
+  configureManHelp(program, resolvedProgName, VERSION);
+  program.hook("preAction", async (thisCommand) => {
+    const opts = thisCommand.opts();
+    const commandsDir = opts.commandsDir;
+    const bindingPath = opts.binding;
+    await applyToolkitIntegration(commandsDir, bindingPath);
+  });
+  return program;
+}
+async function applyToolkitIntegration(commandsDir, bindingPath) {
+  if (!commandsDir && !bindingPath) {
+    return;
   }
-  /**
-   * List all available command names: builtins + group names + top-level module names.
-   */
-  listCommands() {
-    this.buildGroupMap();
-    const groupNames = [...this.groupMap.keys()].filter(
-      (g) => !BUILTIN_COMMANDS.includes(g)
+  try {
+    const toolkitModule = "apcore-toolkit";
+    const toolkit = await import(
+      /* @vite-ignore */
+      toolkitModule
     );
-    const topNames = [...this.topLevelModules.keys()];
-    return [.../* @__PURE__ */ new Set([...BUILTIN_COMMANDS, ...groupNames, ...topNames])].sort();
+    if (commandsDir) {
+      console.warn("Convention scanning not yet available in TypeScript toolkit");
+    }
+    if (bindingPath) {
+      const resolver = new toolkit.DisplayResolver();
+      void resolver;
+    }
+  } catch {
+    console.warn("apcore-toolkit not installed \u2014 toolkit features unavailable");
   }
-  /**
-   * Get a command by name: check builtins -> group cache -> group map -> top-level modules.
-   */
-  getCommand(cmdName) {
-    this.buildGroupMap();
-    if (this.groupCache.has(cmdName)) {
-      return this.groupCache.get(cmdName).command;
+}
+function main(progName) {
+  verboseHelp = hasVerboseFlag();
+  const program = createCli(void 0, progName, verboseHelp);
+  try {
+    program.parse(process.argv);
+  } catch (error2) {
+    if (error2 instanceof CommanderError) {
+      process.exit(error2.exitCode);
     }
-    if (this.groupMap.has(cmdName)) {
-      const lazyGrp = new LazyGroup(
-        this.groupMap.get(cmdName),
-        this.executor,
-        cmdName,
-        this.helpTextMaxLength
-      );
-      this.groupCache.set(cmdName, lazyGrp);
-      return lazyGrp.command;
+    const code = exitCodeForError(error2);
+    if (error2 instanceof Error) {
+      process.stderr.write(`Error: ${error2.message}
+`);
     }
-    if (this.topLevelModules.has(cmdName)) {
-      if (this.commandCache.has(cmdName)) {
-        return this.commandCache.get(cmdName);
-      }
-      const [, descriptor] = this.topLevelModules.get(cmdName);
-      const cmd = buildModuleCommand(
-        descriptor,
-        this.executor,
-        this.helpTextMaxLength,
-        cmdName
-      );
-      this.commandCache.set(cmdName, cmd);
-      return cmd;
+    process.exit(code);
+  }
+}
+function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName, verbose = verboseHelp) {
+  const moduleId = moduleDef.id;
+  let resolvedSchema = {};
+  let schemaOptions = [];
+  const display = getDisplay(moduleDef);
+  const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+  const effectiveCmdName = cmdName ?? cliDisplay.alias ?? moduleId;
+  const cmdHelp = cliDisplay.description ?? moduleDef.description;
+  const inputSchema = moduleDef.inputSchema;
+  if (inputSchema && typeof inputSchema === "object" && inputSchema.properties) {
+    try {
+      resolvedSchema = resolveRefs(inputSchema, 32, moduleId);
+    } catch {
+      resolvedSchema = inputSchema;
     }
-    return null;
+    schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
   }
-  /** Expose groupMap for testing. */
-  getGroupMap() {
-    return this.groupMap;
+  const cmd = new Command2(effectiveCmdName).description(cmdHelp);
+  const inputOpt = new Option2("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
+  const yesOpt = new Option2("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
+  const largeInputOpt = new Option2("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
+  const formatOpt = new Option2("--format <format>", "Set output format: 'json' for machine-readable, 'table' for human-readable");
+  const sandboxOpt = new Option2("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
+  if (!verbose) {
+    inputOpt.hideHelp();
+    yesOpt.hideHelp();
+    largeInputOpt.hideHelp();
+    formatOpt.hideHelp();
   }
-  /** Expose topLevelModules for testing. */
-  getTopLevelModules() {
-    return this.topLevelModules;
+  cmd.addOption(inputOpt);
+  cmd.addOption(yesOpt);
+  cmd.addOption(largeInputOpt);
+  cmd.addOption(formatOpt);
+  cmd.addOption(sandboxOpt);
+  const footerParts = [];
+  if (!verbose) {
+    footerParts.push("Use --verbose to show all options (including built-in apcore options).");
   }
-  /** Expose groupMapBuilt for testing. */
-  isGroupMapBuilt() {
-    return this.groupMapBuilt;
+  if (docsUrl) {
+    footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);
   }
-};
-
-// src/config.ts
-init_esm_shims();
-import * as fs4 from "fs";
-import yaml from "js-yaml";
-var DEFAULTS = {
-  "extensions.root": "./extensions",
-  "logging.level": "WARNING",
-  "sandbox.enabled": false,
-  "cli.stdin_buffer_limit": 10485760,
-  "cli.auto_approve": false,
-  "cli.help_text_max_length": 1e3
-};
-var ConfigResolver = class {
-  cliFlags;
-  configPath;
-  fileCache = null;
-  fileCacheLoaded = false;
-  constructor(cliFlags, configPath) {
-    this.cliFlags = cliFlags ?? {};
-    this.configPath = configPath ?? "apcore.yaml";
+  if (footerParts.length > 0) {
+    cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
   }
-  /**
-   * Resolve a single configuration key across all four tiers.
-   */
-  resolve(key, cliFlag, envVar) {
-    const flagKey = cliFlag ?? key;
-    if (flagKey in this.cliFlags) {
-      const value = this.cliFlags[flagKey];
-      if (value !== null && value !== void 0) {
-        return value;
-      }
-    }
-    if (envVar) {
-      const envValue = process.env[envVar];
-      if (envValue !== void 0 && envValue !== "") {
-        return envValue;
-      }
-    }
-    const fileValue = this.resolveFromFile(key);
-    if (fileValue !== void 0) {
-      return fileValue;
+  for (const opt of schemaOptions) {
+    if (opt.parseArg) {
+      cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
+    } else {
+      cmd.option(opt.flags, opt.description, opt.defaultValue);
     }
-    return DEFAULTS[key];
   }
-  /**
-   * Load a value from the config file using a dot-separated key path.
-   */
-  resolveFromFile(key) {
-    if (!this.fileCacheLoaded) {
-      this.fileCache = this.loadConfigFile();
-      this.fileCacheLoaded = true;
-    }
-    if (this.fileCache === null) {
-      return void 0;
+  cmd.action(async (options) => {
+    const stdinFlag = options.input;
+    const autoApprove = options.yes;
+    const largeInput = options.largeInput;
+    const outputFormat = options.format;
+    const sandboxEnabled = options.sandbox;
+    const schemaKwargs = {};
+    const builtinKeys = /* @__PURE__ */ new Set(["input", "yes", "largeInput", "format", "sandbox", "verbose"]);
+    for (const [k, v] of Object.entries(options)) {
+      if (!builtinKeys.has(k)) {
+        schemaKwargs[k] = v;
+      }
     }
-    return this.fileCache[key];
-  }
-  /**
-   * Load and flatten a YAML config file.
-   */
-  loadConfigFile() {
-    let content;
     try {
-      content = fs4.readFileSync(this.configPath, "utf-8");
+      const merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
+      const reconverted = reconvertEnumValues(merged, schemaOptions);
+      await checkApproval(moduleDef, autoApprove);
+      const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
+      const sandbox = new Sandbox2(sandboxEnabled);
+      const startTime = performance.now();
+      const result = await sandbox.execute(moduleId, reconverted, executor);
+      const durationMs = Math.round(performance.now() - startTime);
+      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+      const auditLogger = getAuditLogger2();
+      if (auditLogger) {
+        auditLogger.logExecution(moduleId, reconverted, "success", 0, durationMs);
+      }
+      formatExecResult(result, outputFormat);
     } catch (err) {
-      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
-        return null;
+      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+      const auditLogger = getAuditLogger2();
+      const code = exitCodeForError(err);
+      if (auditLogger) {
+        auditLogger.logExecution(moduleId, {}, "error", code, 0);
       }
-      console.warn(
-        `Configuration file '${this.configPath}' is malformed, using defaults.`
-      );
-      return null;
-    }
-    let parsed;
-    try {
-      parsed = yaml.load(content);
-    } catch {
-      console.warn(
-        `Configuration file '${this.configPath}' is malformed, using defaults.`
-      );
-      return null;
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-      console.warn(
-        `Configuration file '${this.configPath}' is malformed, using defaults.`
-      );
-      return null;
-    }
-    return this.flattenDict(parsed);
-  }
-  /**
-   * Flatten nested dict to dot-notation keys.
-   */
-  flattenDict(d, prefix = "") {
-    const result = {};
-    for (const [key, value] of Object.entries(d)) {
-      const fullKey = prefix ? `${prefix}.${key}` : key;
-      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-        Object.assign(
-          result,
-          this.flattenDict(value, fullKey)
-        );
-      } else {
-        result[fullKey] = value;
+      if (err instanceof Error) {
+        process.stderr.write(`Error: ${err.message}
+`);
       }
+      process.exit(code);
     }
-    return result;
-  }
-};
-
-// src/discovery.ts
-init_esm_shims();
-init_errors();
-import { Command as Command3 } from "commander";
-var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
-function validateTag(tag) {
-  if (!TAG_PATTERN.test(tag)) {
+  });
+  return cmd;
+}
+function validateModuleId(moduleId) {
+  if (moduleId.length > 128) {
     process.stderr.write(
-      `Error: Invalid tag format: '${tag}'. Tags must match [a-z][a-z0-9_-]*.
+      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/.test(moduleId)) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'.
 `
     );
     process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
 }
-function collectTag(value, previous) {
-  return previous.concat([value]);
-}
-function registerDiscoveryCommands(cli, registry) {
-  const listCmd = new Command3("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--format <format>", "Output format.", void 0).action((opts) => {
-    for (const t of opts.tag) {
-      validateTag(t);
+async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
+  const cliKwargsNonNull = {};
+  for (const [k, v] of Object.entries(cliKwargs)) {
+    if (v !== null && v !== void 0) {
+      cliKwargsNonNull[k] = v;
     }
-    const modules = [];
-    for (const m of registry.listModules()) {
-      modules.push(m);
+  }
+  if (!stdinFlag) {
+    return cliKwargsNonNull;
+  }
+  if (stdinFlag === "-") {
+    const raw = await readStdin();
+    const rawSize = Buffer.byteLength(raw, "utf-8");
+    if (rawSize > 10485760 && !largeInput) {
+      process.stderr.write(
+        "Error: STDIN input exceeds 10MB limit. Use --large-input to override.\n"
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
-    let filtered = modules;
-    if (opts.tag.length > 0) {
-      const filterTags = new Set(opts.tag);
-      filtered = modules.filter((m) => {
-        const mTags = m.tags ?? [];
-        return [...filterTags].every((t) => mTags.includes(t));
-      });
+    if (!raw) {
+      return cliKwargsNonNull;
     }
-    const fmt = resolveFormat(opts.format);
-    formatModuleList(filtered, fmt, opts.tag.length > 0 ? opts.tag : void 0);
-  });
-  cli.addCommand(listCmd);
-  const describeCmd = new Command3("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").option("--format <format>", "Output format.", void 0).action((moduleId, opts) => {
-    validateModuleId(moduleId);
-    const moduleDef = registry.getModule(moduleId);
-    if (!moduleDef) {
+    let stdinData;
+    try {
+      stdinData = JSON.parse(raw);
+    } catch {
       process.stderr.write(
-        `Error: Module '${moduleId}' not found.
+        "Error: STDIN does not contain valid JSON.\n"
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    if (typeof stdinData !== "object" || stdinData === null || Array.isArray(stdinData)) {
+      process.stderr.write(
+        `Error: STDIN JSON must be an object, got ${Array.isArray(stdinData) ? "array" : typeof stdinData}.
 `
       );
-      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
-    const fmt = resolveFormat(opts.format);
-    formatModuleDetail(moduleDef, fmt);
-  });
-  cli.addCommand(describeCmd);
-}
-
-// src/shell.ts
-init_esm_shims();
-init_errors();
-import { readFileSync as readFileSync3 } from "fs";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import * as path6 from "path";
-import { Command as Command4, Help, Option as Option2 } from "commander";
-var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
-var SHELL_VERSION = "0.0.0";
-try {
-  const pkg = JSON.parse(readFileSync3(path6.resolve(__dirname3, "../package.json"), "utf-8"));
-  SHELL_VERSION = pkg.version;
-} catch {
-}
-function makeFunctionName(progName) {
-  return "_" + progName.replace(/[^a-zA-Z0-9]/g, "_");
-}
-function shellQuote(s) {
-  return "'" + s.replace(/'/g, "'\\''") + "'";
-}
-function generateBashCompletion(progName) {
-  const fn = makeFunctionName(progName);
-  const quoted = shellQuote(progName);
-  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e "process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})" 2>/dev/null`;
-  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const ids=JSON.parse(m).map(x=>x.id);
-const g=new Set(),t=[];
-ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});
-console.log([...g].sort().concat(t.sort()).join(' '))
-" 2>/dev/null`;
-  const groupCmdsCmd = `${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const g=process.env._APCORE_GRP;
-JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
-" 2>/dev/null`;
-  return `${fn}() {
-    local cur prev opts
-    COMPREPLY=()
-    cur="\${COMP_WORDS[COMP_CWORD]}"
-    prev="\${COMP_WORDS[COMP_CWORD-1]}"
-
-    if [[ \${COMP_CWORD} -eq 1 ]]; then
-        opts="completion describe exec init list man"
-        local groups_and_top=$(${groupsAndTopCmd})
-        COMPREPLY=( $(compgen -W "\${opts} \${groups_and_top}" -- \${cur}) )
-        return 0
-    fi
-
-    if [[ \${COMP_CWORD} -eq 2 ]]; then
-        if [[ "\${COMP_WORDS[1]}" == "exec" ]]; then
-            local modules=$(${moduleListCmd})
-            COMPREPLY=( $(compgen -W "\${modules}" -- \${cur}) )
-            return 0
-        fi
-        export _APCORE_GRP="\${COMP_WORDS[1]}"
-        local group_cmds=$(${groupCmdsCmd})
-        COMPREPLY=( $(compgen -W "\${group_cmds}" -- \${cur}) )
-        return 0
-    fi
-}
-complete -F ${fn} ${quoted}
-`;
-}
-function generateZshCompletion(progName) {
-  const fn = makeFunctionName(progName);
-  const quoted = shellQuote(progName);
-  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e "process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})" 2>/dev/null`;
-  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const ids=JSON.parse(m).map(x=>x.id);
-const g=new Set(),t=[];
-ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});
-console.log([...g].sort().concat(t.sort()).join(' '))
-" 2>/dev/null`;
-  const groupCmdsCmd = `${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const g=process.env._APCORE_GRP;
-JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
-" 2>/dev/null`;
-  return `#compdef ${progName}
-
-${fn}() {
-    local -a commands
-    commands=(
-        'list:List available modules'
-        'describe:Show module metadata and schema'
-        'completion:Generate shell completion script'
-        'init:Scaffolding commands'
-        'man:Generate man page'
-    )
-
-    _arguments -C \\
-        '1:command:->command' \\
-        '*::arg:->args'
-
-    case "$state" in
-        command)
-            _describe -t commands '${progName} commands' commands
-            local -a groups_and_top
-            groups_and_top=($(${groupsAndTopCmd}))
-            compadd -a groups_and_top
-            ;;
-        args)
-            case "\${words[1]}" in
-                exec)
-                    local modules
-                    modules=($(${moduleListCmd}))
-                    compadd -a modules
-                    ;;
-                *)
-                    export _APCORE_GRP="\${words[1]}"
-                    local -a group_cmds
-                    group_cmds=($(${groupCmdsCmd}))
-                    compadd -a group_cmds
-                    ;;
-            esac
-            ;;
-    esac
+    return { ...stdinData, ...cliKwargsNonNull };
+  }
+  return cliKwargsNonNull;
 }
-
-compdef ${fn} ${quoted}
-`;
+function readStdin() {
+  return new Promise((resolve3, reject) => {
+    const chunks = [];
+    const onData = (chunk) => chunks.push(chunk);
+    const onEnd = () => {
+      cleanup();
+      resolve3(Buffer.concat(chunks).toString("utf-8"));
+    };
+    const onError = (err) => {
+      cleanup();
+      reject(err);
+    };
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.removeListener("end", onEnd);
+      process.stdin.removeListener("error", onError);
+    };
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+    process.stdin.on("error", onError);
+    process.stdin.resume();
+  });
 }
-function generateFishCompletion(progName) {
-  const quoted = shellQuote(progName);
-  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e \\"process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})\\" 2>/dev/null`;
-  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e \\"const m=require('fs').readFileSync('/dev/stdin','utf8');const ids=JSON.parse(m).map(x=>x.id);const g=new Set(),t=[];ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});console.log([...g].sort().concat(t.sort()).join('\\\\n'))\\" 2>/dev/null`;
-  return `# Fish completions for ${progName}
-complete -c ${quoted} -n "__fish_use_subcommand" -a list -d "List available modules"
-complete -c ${quoted} -n "__fish_use_subcommand" -a describe -d "Show module metadata and schema"
-complete -c ${quoted} -n "__fish_use_subcommand" -a completion -d "Generate shell completion script"
-complete -c ${quoted} -n "__fish_use_subcommand" -a init -d "Scaffolding commands"
-complete -c ${quoted} -n "__fish_use_subcommand" -a man -d "Generate man page"
-complete -c ${quoted} -n "__fish_use_subcommand" -a "(${groupsAndTopCmd})" -d "Module group"
-
-complete -c ${quoted} -n "__fish_seen_subcommand_from exec" -a "(${moduleListCmd})"
-
-function __apcore_group_cmds
-    set -l grp (commandline -opc)[2]
-    set -x _APCORE_GRP $grp
-    ${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const g=process.env._APCORE_GRP;
-JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
-" 2>/dev/null
-end
-
-# Group subcommand completion \u2014 matches when position 1 is not a builtin
-complete -c ${quoted} -n "not __fish_use_subcommand; and not __fish_seen_subcommand_from list describe completion init man exec" -a "(__apcore_group_cmds)"
-`;
+function reconvertEnumValues(kwargs, options) {
+  const result = { ...kwargs };
+  for (const opt of options) {
+    if (!opt.enumOriginalTypes) continue;
+    const paramName = opt.name;
+    if (!(paramName in result) || result[paramName] === null || result[paramName] === void 0) {
+      continue;
+    }
+    const strVal = String(result[paramName]);
+    const origType = opt.enumOriginalTypes[strVal];
+    if (origType === "int") {
+      result[paramName] = parseInt(strVal, 10);
+    } else if (origType === "float") {
+      result[paramName] = parseFloat(strVal);
+    } else if (origType === "bool") {
+      result[paramName] = strVal.toLowerCase() === "true";
+    }
+  }
+  return result;
 }
-function buildSynopsis(command, progName, commandName) {
-  if (!command) {
-    return `\\fB${progName} ${commandName}\\fR [OPTIONS]`;
+
+// src/cli.ts
+init_esm_shims();
+import { Command as Command3 } from "commander";
+var BUILTIN_COMMANDS = ["completion", "describe", "exec", "init", "list", "man"];
+var LazyModuleGroup = class {
+  registry;
+  executor;
+  helpTextMaxLength;
+  commandCache = /* @__PURE__ */ new Map();
+  /** alias -> canonical module_id (populated lazily) */
+  aliasMap = /* @__PURE__ */ new Map();
+  /** module_id -> descriptor cache (populated during alias map build) */
+  descriptorCache = /* @__PURE__ */ new Map();
+  aliasMapBuilt = false;
+  constructor(registry, executor, helpTextMaxLength = 1e3) {
+    this.registry = registry;
+    this.executor = executor;
+    this.helpTextMaxLength = helpTextMaxLength;
   }
-  const parts = [`\\fB${progName} ${commandName}\\fR`];
-  for (const opt of command.options) {
-    const flag = opt.long ?? opt.short ?? "";
-    if (opt.isBoolean?.()) {
-      parts.push(`[${flag}]`);
-    } else if (opt.required) {
-      const typeName = (opt.argChoices ? "CHOICE" : "VALUE").toUpperCase();
-      parts.push(`${flag} \\fI${typeName}\\fR`);
-    } else {
-      const typeName = (opt.argChoices ? "CHOICE" : "VALUE").toUpperCase();
-      parts.push(`[${flag} \\fI${typeName}\\fR]`);
+  /**
+   * Build alias->module_id map from display overlay metadata.
+   */
+  buildAliasMap() {
+    if (this.aliasMapBuilt) {
+      return;
+    }
+    try {
+      for (const descriptor of this.registry.listModules()) {
+        const moduleId = descriptor.id;
+        this.descriptorCache.set(moduleId, descriptor);
+        const display = getDisplay(descriptor);
+        const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+        const cliAlias = cliDisplay.alias;
+        if (cliAlias && cliAlias !== moduleId) {
+          this.aliasMap.set(cliAlias, moduleId);
+        }
+      }
+      this.aliasMapBuilt = true;
+    } catch {
+      warn("Failed to build alias map from registry");
     }
   }
-  for (const arg of command.registeredArguments ?? []) {
-    const meta = arg.name().toUpperCase();
-    if (arg.required) {
-      parts.push(`\\fI${meta}\\fR`);
-    } else {
-      parts.push(`[\\fI${meta}\\fR]`);
+  /**
+   * List all available command names from the Registry.
+   */
+  listCommands() {
+    this.buildAliasMap();
+    const reverse = /* @__PURE__ */ new Map();
+    for (const [alias, moduleId] of this.aliasMap) {
+      reverse.set(moduleId, alias);
     }
+    const moduleIds = this.registry.listModules().map((m) => m.id);
+    const names = moduleIds.map((mid) => reverse.get(mid) ?? mid);
+    return [...new Set(names)].sort();
   }
-  return parts.join(" ");
-}
-function generateManPage(commandName, command, progName, version = SHELL_VERSION) {
-  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  const title = `${progName}-${commandName}`.toUpperCase();
-  const pkgLabel = `${progName} ${version}`;
-  const manualLabel = `${progName} Manual`;
-  const sections = [];
-  sections.push(`.TH "${title}" "1" "${today}" "${pkgLabel}" "${manualLabel}"`);
-  sections.push(".SH NAME");
-  const desc = command?.description() ?? commandName;
-  const nameDesc = desc.split("\n")[0].replace(/\.$/, "");
-  sections.push(`${progName}-${commandName} \\- ${nameDesc}`);
-  sections.push(".SH SYNOPSIS");
-  sections.push(buildSynopsis(command, progName, commandName));
-  if (command?.description()) {
-    sections.push(".SH DESCRIPTION");
-    sections.push(
-      command.description().replace(/\\/g, "\\\\").replace(/-/g, "\\-")
-    );
+  /**
+   * Get or lazily build a Commander Command for the given module.
+   */
+  getCommand(cmdName) {
+    if (this.commandCache.has(cmdName)) {
+      return this.commandCache.get(cmdName);
+    }
+    this.buildAliasMap();
+    const moduleId = this.aliasMap.get(cmdName) ?? cmdName;
+    let moduleDef = this.descriptorCache.get(moduleId);
+    if (!moduleDef) {
+      moduleDef = this.registry.getModule(moduleId) ?? void 0;
+    }
+    if (!moduleDef) {
+      return null;
+    }
+    const cmd = buildModuleCommand(moduleDef, this.executor, this.helpTextMaxLength, cmdName);
+    this.commandCache.set(cmdName, cmd);
+    return cmd;
   }
-  if (command && command.options.length > 0) {
-    sections.push(".SH OPTIONS");
-    for (const opt of command.options) {
-      const flag = [opt.short, opt.long].filter(Boolean).join(", ");
-      sections.push(".TP");
-      if (opt.isBoolean?.()) {
-        sections.push(`\\fB${flag}\\fR`);
-      } else {
-        sections.push(`\\fB${flag}\\fR \\fIVALUE\\fR`);
-      }
-      if (opt.description) {
-        sections.push(opt.description);
-      }
-      if (opt.defaultValue !== void 0 && !opt.isBoolean?.()) {
-        sections.push(`Default: ${opt.defaultValue}.`);
-      }
+};
+var LazyGroup = class {
+  members;
+  _executor;
+  _helpTextMaxLength;
+  _cmdCache = /* @__PURE__ */ new Map();
+  command;
+  constructor(members, executor, name, helpTextMaxLength = 1e3) {
+    this.members = members;
+    this._executor = executor;
+    this._helpTextMaxLength = helpTextMaxLength;
+    this.command = new Command3(name).description(`${name} commands`);
+    for (const [cmdName, [, descriptor]] of this.members) {
+      const cmd = buildModuleCommand(
+        descriptor,
+        this._executor,
+        this._helpTextMaxLength,
+        cmdName
+      );
+      this._cmdCache.set(cmdName, cmd);
+      this.command.addCommand(cmd);
     }
   }
-  sections.push(".SH ENVIRONMENT");
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_EXTENSIONS_ROOT\\fR");
-  sections.push(
-    "Path to the apcore extensions directory. Overrides the default \\fI./extensions\\fR."
-  );
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_CLI_AUTO_APPROVE\\fR");
-  sections.push(
-    "Set to \\fB1\\fR to bypass approval prompts for modules that require human-in-the-loop confirmation."
-  );
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_CLI_LOGGING_LEVEL\\fR");
-  sections.push(
-    "CLI-specific logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. Takes priority over \\fBAPCORE_LOGGING_LEVEL\\fR. Default: WARNING."
-  );
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_LOGGING_LEVEL\\fR");
-  sections.push(
-    "Global apcore logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. Used as fallback when \\fBAPCORE_CLI_LOGGING_LEVEL\\fR is not set. Default: WARNING."
-  );
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_AUTH_API_KEY\\fR");
-  sections.push(
-    "API key for authenticating with the apcore registry."
-  );
-  sections.push(".SH EXIT CODES");
-  const exitCodes = [
-    ["0", "Success."],
-    ["1", "Module execution error."],
-    ["2", "Invalid CLI input or missing argument."],
-    ["44", "Module not found, disabled, or failed to load."],
-    ["45", "Input failed JSON Schema validation."],
-    [
-      "46",
-      "Approval denied, timed out, or no interactive terminal available."
-    ],
-    [
-      "47",
-      "Configuration error (extensions directory not found or unreadable)."
-    ],
-    ["48", "Schema contains a circular \\fB$ref\\fR."],
-    ["77", "ACL denied \u2014 insufficient permissions for this module."],
-    ["130", "Execution cancelled by user (SIGINT / Ctrl\\-C)."]
-  ];
-  for (const [code, meaning] of exitCodes) {
-    sections.push(`.TP
-\\fB${code}\\fR
-${meaning}`);
+  listCommands() {
+    return [...this.members.keys()].sort();
   }
-  sections.push(".SH SEE ALSO");
-  sections.push(
-    [
-      `\\fB${progName}\\fR(1)`,
-      `\\fB${progName}\\-list\\fR(1)`,
-      `\\fB${progName}\\-describe\\fR(1)`,
-      `\\fB${progName}\\-completion\\fR(1)`
-    ].join(", ")
-  );
-  return sections.join("\n");
-}
-function roffEscape(s) {
-  return s.replace(/\\/g, "\\\\").replace(/-/g, "\\-").replace(/'/g, "\\(aq");
-}
-function buildProgramManPage(program, progName, version, description, docsUrl2) {
-  const help = new Help();
-  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  const s = [];
-  const resolvedDesc = description ?? program.description() ?? `${progName} CLI`;
-  s.push(`.TH "${progName.toUpperCase()}" "1" "${today}" "${progName} ${version}" "${progName} Manual"`);
-  s.push(".SH NAME");
-  s.push(`${progName} \\- ${roffEscape(resolvedDesc)}`);
-  s.push(".SH SYNOPSIS");
-  s.push(`\\fB${progName}\\fR [\\fIglobal\\-options\\fR] \\fIcommand\\fR [\\fIcommand\\-options\\fR]`);
-  if (resolvedDesc) {
-    s.push(".SH DESCRIPTION");
-    s.push(roffEscape(resolvedDesc));
+  getCommand(cmdName) {
+    if (this._cmdCache.has(cmdName)) {
+      return this._cmdCache.get(cmdName);
+    }
+    const entry = this.members.get(cmdName);
+    if (!entry) {
+      return null;
+    }
+    const [, descriptor] = entry;
+    const cmd = buildModuleCommand(
+      descriptor,
+      this._executor,
+      this._helpTextMaxLength,
+      cmdName
+    );
+    this._cmdCache.set(cmdName, cmd);
+    return cmd;
   }
-  const globalOpts = help.visibleOptions(program).filter((o) => !["help", "version", "all", "man"].includes(o.long?.replace("--", "") ?? ""));
-  if (globalOpts.length > 0) {
-    s.push(".SH GLOBAL OPTIONS");
-    for (const opt of globalOpts) {
-      const flag = [opt.short, opt.long].filter(Boolean).join(", ");
-      s.push(".TP");
-      s.push(`\\fB${roffEscape(flag)}\\fR`);
-      if (opt.description) s.push(roffEscape(opt.description));
+};
+var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
+  /** groupName -> { cmdName -> [moduleId, descriptor] } */
+  groupMap = /* @__PURE__ */ new Map();
+  /** cmdName -> [moduleId, descriptor] for top-level (ungrouped) modules */
+  topLevelModules = /* @__PURE__ */ new Map();
+  /** Cached LazyGroup instances */
+  groupCache = /* @__PURE__ */ new Map();
+  groupMapBuilt = false;
+  /**
+   * Determine (groupName | null, commandName) for a module from its display overlay.
+   */
+  static resolveGroup(moduleId, descriptor) {
+    if (!moduleId) {
+      warn("Empty module_id encountered in resolveGroup");
+      return [null, ""];
+    }
+    const display = getDisplay(descriptor);
+    const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+    const explicitGroup = cliDisplay.group;
+    if (typeof explicitGroup === "string" && explicitGroup !== "") {
+      return [explicitGroup, cliDisplay.alias ?? moduleId];
+    }
+    if (explicitGroup === "") {
+      return [null, cliDisplay.alias ?? moduleId];
+    }
+    const cliName = cliDisplay.alias ?? moduleId;
+    if (cliName.includes(".")) {
+      const dotIdx = cliName.indexOf(".");
+      const group = cliName.substring(0, dotIdx);
+      const cmd = cliName.substring(dotIdx + 1);
+      return [group, cmd];
     }
+    return [null, cliName];
   }
-  const allCommands = help.visibleCommands(program);
-  if (allCommands.length > 0) {
-    s.push(".SH COMMANDS");
-    for (const cmd of allCommands) {
-      if (cmd.name() === "help") continue;
-      const desc = help.subcommandDescription(cmd);
-      s.push(".TP");
-      s.push(`\\fB${progName} ${roffEscape(cmd.name())}\\fR`);
-      if (desc) s.push(roffEscape(desc));
-      const cmdHelp = new Help();
-      const opts = cmdHelp.visibleOptions(cmd).filter((o) => !["help", "version"].includes(o.long?.replace("--", "") ?? ""));
-      for (const opt of opts) {
-        const flag = [opt.short, opt.long].filter(Boolean).join(", ");
-        s.push(".RS");
-        s.push(".TP");
-        s.push(`\\fB${roffEscape(flag)}\\fR`);
-        if (opt.description) s.push(roffEscape(opt.description));
-        s.push(".RE");
+  /**
+   * Build the group map from registry modules.
+   */
+  buildGroupMap() {
+    if (this.groupMapBuilt) {
+      return;
+    }
+    try {
+      this.buildAliasMap();
+      for (const descriptor of this.registry.listModules()) {
+        const moduleId = descriptor.id;
+        const cached = this.descriptorCache.get(moduleId);
+        if (!cached) {
+          continue;
+        }
+        const [group, cmd] = _GroupedModuleGroup.resolveGroup(moduleId, cached);
+        if (group === null) {
+          this.topLevelModules.set(cmd, [moduleId, cached]);
+        } else if (!/^[a-z][a-z0-9_-]*$/.test(group)) {
+          warn(
+            `Module '${moduleId}': group name '${group}' is not shell-safe \u2014 treating as top-level.`
+          );
+          this.topLevelModules.set(cmd, [moduleId, cached]);
+        } else {
+          if (!this.groupMap.has(group)) {
+            this.groupMap.set(group, /* @__PURE__ */ new Map());
+          }
+          this.groupMap.get(group).set(cmd, [moduleId, cached]);
+        }
       }
-      const subCmds = cmdHelp.visibleCommands(cmd).filter((c) => c.name() !== "help");
-      for (const sub of subCmds) {
-        const subDesc = help.subcommandDescription(sub);
-        s.push(".TP");
-        s.push(`\\fB${progName} ${roffEscape(cmd.name())} ${roffEscape(sub.name())}\\fR`);
-        if (subDesc) s.push(roffEscape(subDesc));
-        const subOpts = cmdHelp.visibleOptions(sub).filter((o) => !["help", "version"].includes(o.long?.replace("--", "") ?? ""));
-        for (const opt of subOpts) {
-          const flag = [opt.short, opt.long].filter(Boolean).join(", ");
-          s.push(".RS");
-          s.push(".TP");
-          s.push(`\\fB${roffEscape(flag)}\\fR`);
-          if (opt.description) s.push(roffEscape(opt.description));
-          s.push(".RE");
+      for (const groupName of this.groupMap.keys()) {
+        if (BUILTIN_COMMANDS.includes(groupName)) {
+          warn(
+            `Group name '${groupName}' collides with a built-in command and will be ignored`
+          );
         }
       }
+      this.groupMapBuilt = true;
+    } catch {
+      warn("Failed to build group map");
     }
   }
-  s.push(".SH ENVIRONMENT");
-  s.push(".TP");
-  s.push("\\fBAPCORE_EXTENSIONS_ROOT\\fR");
-  s.push("Path to the apcore extensions directory.");
-  s.push(".TP");
-  s.push("\\fBAPCORE_CLI_AUTO_APPROVE\\fR");
-  s.push("Set to \\fB1\\fR to bypass approval prompts.");
-  s.push(".TP");
-  s.push("\\fBAPCORE_CLI_LOGGING_LEVEL\\fR");
-  s.push("CLI\\-specific logging verbosity (DEBUG|INFO|WARNING|ERROR).");
-  s.push(".SH EXIT CODES");
-  const exitCodes = [
-    ["0", "Success."],
-    ["1", "Module execution error."],
-    ["2", "Invalid CLI input or missing argument."],
-    ["44", "Module not found, disabled, or failed to load."],
-    ["45", "Input failed JSON Schema validation."],
-    ["46", "Approval denied or timed out."],
-    ["47", "Configuration error."],
-    ["77", "ACL denied."],
-    ["130", "Cancelled by user (SIGINT)."]
-  ];
-  for (const [code, meaning] of exitCodes) {
-    s.push(`.TP
-\\fB${code}\\fR
-${meaning}`);
+  /**
+   * List all available command names: builtins + group names + top-level module names.
+   */
+  listCommands() {
+    this.buildGroupMap();
+    const groupNames = [...this.groupMap.keys()].filter(
+      (g) => !BUILTIN_COMMANDS.includes(g)
+    );
+    const topNames = [...this.topLevelModules.keys()];
+    return [.../* @__PURE__ */ new Set([...BUILTIN_COMMANDS, ...groupNames, ...topNames])].sort();
   }
-  s.push(".SH SEE ALSO");
-  s.push(`\\fB${progName} \\-\\-help \\-\\-verbose\\fR for full option list.`);
-  if (docsUrl2) {
-    s.push(`.PP
-Full documentation at \\fI${roffEscape(docsUrl2)}\\fR`);
+  /**
+   * Get a command by name: check builtins -> group cache -> group map -> top-level modules.
+   */
+  getCommand(cmdName) {
+    this.buildGroupMap();
+    if (this.groupCache.has(cmdName)) {
+      return this.groupCache.get(cmdName).command;
+    }
+    if (this.groupMap.has(cmdName)) {
+      const lazyGrp = new LazyGroup(
+        this.groupMap.get(cmdName),
+        this.executor,
+        cmdName,
+        this.helpTextMaxLength
+      );
+      this.groupCache.set(cmdName, lazyGrp);
+      return lazyGrp.command;
+    }
+    if (this.topLevelModules.has(cmdName)) {
+      if (this.commandCache.has(cmdName)) {
+        return this.commandCache.get(cmdName);
+      }
+      const [, descriptor] = this.topLevelModules.get(cmdName);
+      const cmd = buildModuleCommand(
+        descriptor,
+        this.executor,
+        this.helpTextMaxLength,
+        cmdName
+      );
+      this.commandCache.set(cmdName, cmd);
+      return cmd;
+    }
+    return null;
+  }
+  /** Expose groupMap for testing. */
+  getGroupMap() {
+    return this.groupMap;
+  }
+  /** Expose topLevelModules for testing. */
+  getTopLevelModules() {
+    return this.topLevelModules;
+  }
+  /** Expose groupMapBuilt for testing. */
+  isGroupMapBuilt() {
+    return this.groupMapBuilt;
+  }
+};
+
+// src/discovery.ts
+init_esm_shims();
+init_errors();
+import { Command as Command4 } from "commander";
+var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
+function validateTag(tag) {
+  if (!TAG_PATTERN.test(tag)) {
+    process.stderr.write(
+      `Error: Invalid tag format: '${tag}'. Tags must match [a-z][a-z0-9_-]*.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
-  return s.join("\n");
 }
-function configureManHelp(program, progName, version, description, docsUrl2) {
-  const manOpt = new Option2("--man", "Output man page in roff format (use with --help)").hideHelp();
-  program.addOption(manOpt);
-  program.addHelpText("beforeAll", () => {
-    if (program.opts().man) {
-      process.stdout.write(buildProgramManPage(program, progName, version, description, docsUrl2));
-      process.stdout.write("\n");
-      process.exit(0);
-    }
-    return "";
-  });
+function collectTag(value, previous) {
+  return previous.concat([value]);
 }
-function registerShellCommands(cli, progName = "apcore-cli") {
-  const completionCmd = new Command4("completion").description(
-    "Generate a shell completion script and print it to stdout."
-  ).argument("<shell>", "Shell type: bash, zsh, or fish").action((shell) => {
-    const validShells = ["bash", "zsh", "fish"];
-    if (!validShells.includes(shell)) {
-      process.stderr.write(
-        `Error: Unknown shell '${shell}'. Expected: bash, zsh, or fish.
-`
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+function registerDiscoveryCommands(cli, registry) {
+  const listCmd = new Command4("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--format <format>", "Output format.", void 0).action((opts) => {
+    for (const t of opts.tag) {
+      validateTag(t);
     }
-    const resolved = cli.name() || progName;
-    const generators = {
-      bash: () => generateBashCompletion(resolved),
-      zsh: () => generateZshCompletion(resolved),
-      fish: () => generateFishCompletion(resolved)
-    };
-    process.stdout.write(generators[shell]());
+    const modules = [];
+    for (const m of registry.listModules()) {
+      modules.push(m);
+    }
+    let filtered = modules;
+    if (opts.tag.length > 0) {
+      const filterTags = new Set(opts.tag);
+      filtered = modules.filter((m) => {
+        const mTags = m.tags ?? [];
+        return [...filterTags].every((t) => mTags.includes(t));
+      });
+    }
+    const fmt = resolveFormat(opts.format);
+    formatModuleList(filtered, fmt, opts.tag.length > 0 ? opts.tag : void 0);
   });
-  cli.addCommand(completionCmd);
-  const manCmd = new Command4("man").description("Generate a roff man page for COMMAND and print it to stdout.").argument("<command>", "Command to generate man page for").action((commandName) => {
-    const knownBuiltins = /* @__PURE__ */ new Set(["completion", "describe", "exec", "init", "list", "man"]);
-    const cmd = cli.commands.find((c) => c.name() === commandName) ?? null;
-    if (!cmd && !knownBuiltins.has(commandName)) {
+  cli.addCommand(listCmd);
+  const describeCmd = new Command4("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").option("--format <format>", "Output format.", void 0).action((moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getModule(moduleId);
+    if (!moduleDef) {
       process.stderr.write(
-        `Error: Unknown command '${commandName}'.
+        `Error: Module '${moduleId}' not found.
 `
       );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
     }
-    const resolved = cli.name() || progName;
-    const roff = generateManPage(commandName, cmd, resolved);
-    process.stdout.write(roff);
+    const fmt = resolveFormat(opts.format);
+    formatModuleDetail(moduleDef, fmt);
   });
-  cli.addCommand(manCmd);
+  cli.addCommand(describeCmd);
 }
 
 // src/index.ts
@@ -2379,6 +2476,7 @@ export {
   main,
   mapType,
   reconvertEnumValues,
+  registerConfigNamespace,
   registerDiscoveryCommands,
   registerInitCommand,
   registerShellCommands,