apcore-cli 0.9.0 → 0.10.0

package/dist/index.js

@@ -115,6 +115,7 @@ var init_errors = __esm({
       }
     };
     SchemaValidationError = class extends Error {
+      code = "SCHEMA_VALIDATION_ERROR";
       constructor(message = "Schema validation failed") {
         super(message);
         this.name = "SchemaValidationError";
@@ -651,7 +652,7 @@ var init_sandbox = __esm({
        */
       async execute(moduleId, inputData, executor) {
         if (!this.enabled) {
-          return executor.execute(moduleId, inputData);
+          return executor.call(moduleId, inputData);
         }
         return this._sandboxedExecute(moduleId, inputData);
       }
@@ -780,7 +781,7 @@ init_errors();
 import { readFileSync as readFileSync3 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import * as path5 from "path";
-import { Command as Command5, CommanderError, Option as Option4 } from "commander";
+import { Command as Command6, CommanderError, Option as Option4 } from "commander";
 
 // src/ref-resolver.ts
 init_esm_shims();
@@ -953,9 +954,17 @@ function mapType(propName, propSchema) {
     array: "string"
   };
   if (!schemaType) {
+    warn(`No type specified for property '${propName}', defaulting to string.`);
     return "string";
   }
-  return typeMap[schemaType] ?? "string";
+  const mapped = typeMap[schemaType];
+  if (mapped === void 0) {
+    warn(
+      `Unknown schema type '${schemaType}' for property '${propName}', defaulting to string.`
+    );
+    return "string";
+  }
+  return mapped;
 }
 function extractHelp(propSchema, maxLength = 1e3) {
   let text = propSchema["x-llm-description"];
@@ -1154,7 +1163,7 @@ var CliApprovalHandler = class {
     const message = extra.approval_message ?? `Module '${moduleId}' requires approval to execute.`;
     process.stderr.write(message + "\n");
     try {
-      await promptWithTimeout({ id: moduleId }, this.timeout);
+      await promptWithTimeout({ moduleId }, this.timeout);
       return { status: "approved", approved_by: "tty_user" };
     } catch {
       return { status: "rejected", reason: "User rejected or timed out" };
@@ -1177,7 +1186,7 @@ async function checkApproval(moduleDef, autoApprove, timeout) {
   if (!requiresApproval) {
     return;
   }
-  const moduleId = moduleDef.id;
+  const moduleId = moduleDef.moduleId;
   if (autoApprove) {
     return;
   }
@@ -1201,7 +1210,7 @@ async function checkApproval(moduleDef, autoApprove, timeout) {
 }
 async function promptWithTimeout(moduleDef, timeout) {
   timeout = Math.max(1, Math.min(timeout, 3600));
-  const moduleId = moduleDef.id;
+  const moduleId = moduleDef.moduleId;
   const annotations = moduleDef.annotations;
   const message = (annotations ? getAnnotation(annotations, "approval_message") : void 0) ?? `Module '${moduleId}' requires approval to execute.`;
   process.stderr.write(message + "\n");
@@ -1247,7 +1256,7 @@ function descriptorToScanned(m) {
   const metadata = m.metadata ?? {};
   const display = metadata["display"] ?? null;
   return {
-    moduleId: m.id,
+    moduleId: m.moduleId,
     description: m.description ?? "",
     inputSchema: m.inputSchema ?? {},
     outputSchema: m.outputSchema ?? {},
@@ -1303,13 +1312,13 @@ async function formatModuleList(modules, format, filterTags, showDeps = false, e
     if (showDeps) headers.push("Deps");
     if (exposureFilter) headers.push("Exposure");
     const rows = modules.map((m) => {
-      const base = [m.id, truncate(m.description, 80), (m.tags ?? []).join(", ")];
+      const base = [m.moduleId, truncate(m.description, 80), (m.tags ?? []).join(", ")];
       if (showDeps) {
         const deps = m.dependencies;
         base.push(String(Array.isArray(deps) ? deps.length : 0));
       }
       if (exposureFilter) {
-        base.push(exposureFilter.isExposed(m.id ?? "") ? "\u2713" : "\u2014");
+        base.push(exposureFilter.isExposed(m.moduleId ?? "") ? "\u2713" : "\u2014");
       }
       return base;
     });
@@ -1317,7 +1326,7 @@ async function formatModuleList(modules, format, filterTags, showDeps = false, e
   } else if (format === "json") {
     const result = modules.map((m) => {
       const entry = {
-        id: m.id,
+        id: m.moduleId,
         description: m.description,
         tags: m.tags ?? []
       };
@@ -1326,7 +1335,7 @@ async function formatModuleList(modules, format, filterTags, showDeps = false, e
         entry.dependency_count = Array.isArray(deps) ? deps.length : 0;
       }
       if (exposureFilter) {
-        entry.exposed = exposureFilter.isExposed(m.id ?? "");
+        entry.exposed = exposureFilter.isExposed(m.moduleId ?? "");
       }
       return entry;
     });
@@ -1358,7 +1367,7 @@ function annotationsToDict(annotations) {
 async function formatModuleDetail(moduleDef, format) {
   if (format === "table") {
     process.stdout.write(`
-Module: ${moduleDef.id}
+Module: ${moduleDef.moduleId}
 `);
     process.stdout.write(`
 Description:
@@ -1406,7 +1415,7 @@ Tags: ${tags.join(", ")}
     }
   } else if (format === "json") {
     const result = {
-      id: moduleDef.id,
+      id: moduleDef.moduleId,
       description: moduleDef.description
     };
     if (moduleDef.inputSchema) result.input_schema = moduleDef.inputSchema;
@@ -1755,7 +1764,7 @@ function getDisplay(descriptor) {
   if (display && typeof display === "object" && !Array.isArray(display)) {
     return display;
   }
-  const overlay = lookupBindingDisplay(descriptor.id);
+  const overlay = lookupBindingDisplay(descriptor.moduleId);
   return overlay ?? {};
 }
 
@@ -1810,9 +1819,9 @@ var LEGACY_TO_NAMESPACE = Object.fromEntries(
 function registerConfigNamespace() {
   try {
     const nodeRequire = createRequire(import.meta.url);
-    const { Config } = nodeRequire("apcore-js");
-    if (typeof Config?.registerNamespace === "function") {
-      Config.registerNamespace({
+    const { Config: Config2 } = nodeRequire("apcore-js");
+    if (typeof Config2?.registerNamespace === "function") {
+      Config2.registerNamespace({
         name: "apcore-cli",
         envPrefix: "APCORE_CLI",
         defaults: NAMESPACE_DEFAULTS
@@ -2273,2445 +2282,2491 @@ function registerCompletionCommand(host) {
 
 // src/discovery.ts
 init_esm_shims();
-import { Command as Command2, Option as Option2 } from "commander";
-init_errors();
-init_audit();
+import { Command as Command3, Option as Option2 } from "commander";
 
-// src/system-usage.ts
+// src/cli.ts
 init_esm_shims();
-import * as fs4 from "fs";
-import * as os2 from "os";
-import * as path4 from "path";
-var PERIOD_TO_MS = {
-  "1h": 60 * 60 * 1e3,
-  "24h": 24 * 60 * 60 * 1e3,
-  "7d": 7 * 24 * 60 * 60 * 1e3,
-  "30d": 30 * 24 * 60 * 60 * 1e3
-};
-var DEFAULT_AUDIT_PATH = path4.join(
-  os2.homedir(),
-  ".apcore-cli",
-  "audit.jsonl"
-);
-function computeSummary(options = {}) {
-  const auditPath = options.auditPath ?? DEFAULT_AUDIT_PATH;
-  const period = options.period ?? "24h";
-  const cutoff = (options.now ?? /* @__PURE__ */ new Date()).getTime() - PERIOD_TO_MS[period];
-  if (!fs4.existsSync(auditPath)) {
-    return /* @__PURE__ */ new Map();
-  }
-  let raw;
-  try {
-    raw = fs4.readFileSync(auditPath, "utf-8");
-  } catch {
-    return /* @__PURE__ */ new Map();
-  }
-  const counts = /* @__PURE__ */ new Map();
-  const errors = /* @__PURE__ */ new Map();
-  const latencySum = /* @__PURE__ */ new Map();
-  for (const line of raw.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    let entry;
-    try {
-      entry = JSON.parse(trimmed);
-    } catch {
-      continue;
-    }
-    const ts = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : NaN;
-    if (Number.isNaN(ts) || ts < cutoff) continue;
-    const moduleId = typeof entry.module_id === "string" ? entry.module_id : null;
-    if (!moduleId) continue;
-    counts.set(moduleId, (counts.get(moduleId) ?? 0) + 1);
-    if (entry.status === "error") {
-      errors.set(moduleId, (errors.get(moduleId) ?? 0) + 1);
-    }
-    const duration = entry.duration_ms;
-    if (typeof duration === "number") {
-      latencySum.set(moduleId, (latencySum.get(moduleId) ?? 0) + duration);
-    }
-  }
-  const out = /* @__PURE__ */ new Map();
-  for (const [id, calls] of counts) {
-    out.set(id, {
-      module_id: id,
-      calls,
-      errors: errors.get(id) ?? 0,
-      latency_ms: calls > 0 ? (latencySum.get(id) ?? 0) / calls : 0
-    });
-  }
-  return out;
+import { Command as Command2 } from "commander";
+
+// src/exposure.ts
+init_esm_shims();
+init_logger();
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function sortModulesByUsage(modules, field, options = {}) {
-  const reverse = options.reverse ?? true;
-  const summary = computeSummary({
-    auditPath: options.auditPath,
-    period: options.period
-  });
-  if (summary.size === 0) {
-    modules.sort((a, b) => (a.id ?? a.module_id ?? "").localeCompare(b.id ?? b.module_id ?? ""));
-    if (reverse) modules.reverse();
-    return { used: false };
-  }
-  const key = (m) => {
-    const id = m.id ?? m.module_id ?? "";
-    const s = summary.get(id);
-    if (!s) return 0;
-    return field === "latency" ? s.latency_ms : field === "calls" ? s.calls : s.errors;
-  };
-  modules.sort((a, b) => {
-    const diff = key(a) - key(b);
-    if (diff !== 0) return reverse ? -diff : diff;
-    return (a.id ?? a.module_id ?? "").localeCompare(b.id ?? b.module_id ?? "");
+function compilePattern(pattern) {
+  const sentinel = "\0GLOB\0";
+  const escaped = pattern.replaceAll("**", sentinel);
+  const parts = escaped.split("*");
+  const regexParts = parts.map((p) => {
+    const restored = p.replaceAll(sentinel, "**");
+    return escapeRegex(restored);
   });
-  return { used: true };
+  let regex = regexParts.join("[^.]*");
+  regex = regex.replaceAll("\\*\\*", ".+");
+  return new RegExp(`^${regex}$`);
 }
-
-// src/discovery.ts
-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_-]*.
+var ExposureFilter = class _ExposureFilter {
+  static VALID_MODES = ["all", "include", "exclude", "none"];
+  _mode;
+  _compiledInclude;
+  _compiledExclude;
+  constructor(mode = "all", include, exclude) {
+    if (!_ExposureFilter.VALID_MODES.includes(mode)) {
+      process.stderr.write(
+        `Warning: Unknown ExposureFilter mode '${mode}' \u2014 defaulting to 'none'. Valid modes: ${_ExposureFilter.VALID_MODES.join(", ")}.
 `
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      );
+      mode = "none";
+    }
+    this._mode = mode;
+    const dedup = (arr) => [...new Set(arr)];
+    this._compiledInclude = dedup(include ?? []).map(compilePattern);
+    this._compiledExclude = dedup(exclude ?? []).map(compilePattern);
   }
-}
-function collectTag(value, previous) {
-  return previous.concat([value]);
-}
-function collectAnnotation(value, previous) {
-  return previous.concat([value]);
-}
-function getAnnotationFlag(moduleDef, flag) {
-  const annotations = moduleDef.annotations;
-  if (!annotations || typeof annotations !== "object") return false;
-  const ann = annotations;
-  const map = {
-    "destructive": "destructive",
-    "requires-approval": "requires_approval",
-    "readonly": "readonly",
-    "streaming": "streaming",
-    "cacheable": "cacheable",
-    "idempotent": "idempotent",
-    "paginated": "paginated"
-  };
-  const attr = map[flag] ?? flag;
-  return ann[attr] === true;
-}
-function registerListCommand(apcliGroup, registry, exposureFilter) {
-  const listCmd = new Command2("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--flat", "Show flat list (no grouping).", false).addOption(
-    new Option2("--format <format>", "Output format.").choices(["table", "json", "csv", "yaml", "jsonl", "markdown", "skill"])
-  ).option("-s, --search <query>", "Filter by substring match on ID and description.").addOption(
-    new Option2("--status <status>", "Filter by module status.").choices(["enabled", "disabled", "all"]).default("enabled")
-  ).option("-a, --annotation <flag>", "Filter by annotation flag (AND logic). Repeatable.", collectAnnotation, []).addOption(
-    new Option2("--sort <field>", "Sort order.").choices(["id", "calls", "errors", "latency"]).default("id")
-  ).option("--reverse", "Reverse sort order.", false).option("--deprecated", "Include deprecated modules.", false).option("--deps", "Show dependency count column.", false).addOption(
-    new Option2("--exposure <mode>", "Filter by exposure status.").choices(["exposed", "hidden", "all"]).default("exposed")
-  ).action((opts) => {
-    for (const t of opts.tag) {
-      validateTag(t);
+  /** Return true if the module should be exposed as a CLI command. */
+  isExposed(moduleId) {
+    if (this._mode === "all") return true;
+    if (this._mode === "include") {
+      return this._compiledInclude.some((rx) => rx.test(moduleId));
     }
-    let modules = [];
-    for (const m of registry.listModules()) {
-      modules.push(m);
+    if (this._mode === "exclude") {
+      return !this._compiledExclude.some((rx) => rx.test(moduleId));
     }
-    if (opts.tag.length > 0) {
-      const filterTags = new Set(opts.tag);
-      modules = modules.filter((m) => {
-        const mTags = m.tags ?? [];
-        return [...filterTags].every((t) => mTags.includes(t));
-      });
+    return false;
+  }
+  /** Partition moduleIds into [exposed, hidden] lists. */
+  filterModules(moduleIds) {
+    const exposed = [];
+    const hidden = [];
+    for (const mid of moduleIds) {
+      (this.isExposed(mid) ? exposed : hidden).push(mid);
     }
-    if (opts.search) {
-      const query = opts.search.toLowerCase();
-      modules = modules.filter(
-        (m) => (m.id ?? "").toLowerCase().includes(query) || (m.description ?? "").toLowerCase().includes(query)
-      );
+    return [exposed, hidden];
+  }
+  /**
+   * Create an ExposureFilter from a parsed config dict.
+   *
+   * Expected: `{ expose: { mode: "include", include: ["admin.*"] } }`
+   */
+  static fromConfig(config) {
+    const expose = config.expose ?? {};
+    if (typeof expose !== "object" || expose === null || Array.isArray(expose)) {
+      warn("Invalid 'expose' config (expected dict), using mode: all.");
+      return new _ExposureFilter();
     }
-    if (opts.status === "enabled") {
-      modules = modules.filter((m) => {
-        const enabled = m.enabled;
-        return enabled !== false;
-      });
-    } else if (opts.status === "disabled") {
-      modules = modules.filter((m) => {
-        const enabled = m.enabled;
-        return enabled === false;
-      });
+    const exposeObj = expose;
+    const mode = exposeObj.mode ?? "all";
+    if (!["all", "include", "exclude"].includes(mode)) {
+      throw new Error(
+        `Invalid expose mode: '${mode}'. Must be one of: all, include, exclude.`
+      );
     }
-    if (!opts.deprecated) {
-      modules = modules.filter((m) => {
-        const deprecated = m.deprecated;
-        return deprecated !== true;
-      });
+    let include = exposeObj.include ?? [];
+    if (!Array.isArray(include)) {
+      warn("Invalid 'expose.include' (expected list), ignoring.");
+      include = [];
     }
-    if (opts.annotation.length > 0) {
-      for (const annFlag of opts.annotation) {
-        modules = modules.filter((m) => getAnnotationFlag(m, annFlag));
-      }
+    let exclude = exposeObj.exclude ?? [];
+    if (!Array.isArray(exclude)) {
+      warn("Invalid 'expose.exclude' (expected list), ignoring.");
+      exclude = [];
     }
-    if (opts.sort === "calls" || opts.sort === "errors" || opts.sort === "latency") {
-      const { used } = sortModulesByUsage(modules, opts.sort, { reverse: !opts.reverse });
-      if (!used) {
-        process.stderr.write(
-          `note: no usage data available for --sort ${opts.sort}; sorted by id. Run some modules first to populate ~/.apcore-cli/audit.jsonl.
-`
-        );
-      }
-    } else {
-      modules.sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""));
-      if (opts.reverse) {
-        modules.reverse();
+    const filterList = (arr, label) => {
+      const result = [];
+      for (const p of arr) {
+        if (!p) {
+          warn(`Empty pattern in expose.${label}, skipping.`);
+        } else {
+          result.push(String(p));
+        }
       }
-    }
-    let showExposureCol = false;
-    if (exposureFilter && opts.exposure !== "all") {
-      if (opts.exposure === "exposed") {
-        modules = modules.filter((m) => exposureFilter.isExposed(m.id ?? ""));
-      } else if (opts.exposure === "hidden") {
-        modules = modules.filter((m) => !exposureFilter.isExposed(m.id ?? ""));
-      }
-    }
-    if (opts.exposure === "all" && exposureFilter) {
-      showExposureCol = true;
-    }
-    const fmt = resolveFormat(opts.format);
-    const filterTagsArg = opts.tag.length > 0 ? opts.tag : void 0;
-    void formatModuleList(modules, fmt, filterTagsArg, opts.deps, showExposureCol ? exposureFilter : void 0);
-  });
-  apcliGroup.addCommand(listCmd);
-}
-function registerDescribeCommand(apcliGroup, registry) {
-  const describeCmd = new Command2("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").addOption(
-    new Option2("--format <format>", "Output format.").choices(["table", "json", "csv", "yaml", "jsonl", "markdown", "skill"])
-  ).action((moduleId, opts) => {
-    validateModuleId(moduleId);
-    const moduleDef = registry.getModule(moduleId);
-    if (!moduleDef) {
-      process.stderr.write(
-        `Error: Module '${moduleId}' not found.
-`
-      );
-      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
-    }
-    const fmt = resolveFormat(opts.format);
-    void formatModuleDetail(moduleDef, fmt);
-  });
-  apcliGroup.addCommand(describeCmd);
-}
-function registerExecCommand(apcliGroup, registry, executor) {
-  const execCmd = new Command2("exec").description("Execute a module by ID with JSON input.").argument("<module-id>", "Module ID to execute").option("--format <format>", "Output format (json, table, csv, yaml, jsonl).").option("--fields <fields>", "Comma-separated dot-paths to select from the result.").option(
-    "--input <json>",
-    "JSON object passed as input to the module. Use '-' to read JSON from stdin."
-  ).option("-y, --yes", "Auto-approve if the module declares requires_approval.", false).option(
-    "--approval-timeout <seconds>",
-    "Seconds to wait for interactive approval.",
-    parseInt
-  ).option("--sandbox", "Run module in an isolated subprocess with restricted env.", false).option("--strategy <name>", "Execution strategy (standard, parallel, sequential, etc.).").option("--trace", "Enable pipeline trace output.", false).option("--dry-run", "Validate inputs without executing the module.", false).option("--stream", "Stream output as JSONL instead of buffering.", false).action(async (moduleId, opts) => {
-    validateModuleId(moduleId);
-    const moduleDef = registry.getModule(moduleId);
-    if (!moduleDef) {
-      process.stderr.write(`Error: Module '${moduleId}' not found.
-`);
-      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
-    }
-    let merged = {};
-    if (opts.input === "-") {
-      merged = await collectInput("-", {}, false);
-    } else if (opts.input !== void 0) {
-      try {
-        const parsed = JSON.parse(opts.input);
-        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-          process.stderr.write("Error: --input JSON must be an object.\n");
-          process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-        }
-        merged = parsed;
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`Error: --input is not valid JSON: ${msg}
-`);
-        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-      }
-    }
-    const startTime = performance.now();
-    try {
-      await checkApproval(moduleDef, opts.yes, opts.approvalTimeout);
-      if (opts.dryRun) {
-        if (executor.validate) {
-          const preflight = await executor.validate(moduleId, merged);
-          formatPreflightResult(preflight, opts.format);
-        } else {
-          process.stdout.write(JSON.stringify({ valid: true }) + "\n");
-        }
-        return;
-      }
-      let result;
-      if ((opts.trace || opts.strategy) && executor.callWithTrace) {
-        const [res] = await executor.callWithTrace(moduleId, merged, { strategy: opts.strategy });
-        result = res;
-      } else {
-        const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
-        const sandbox = new Sandbox2(opts.sandbox);
-        result = await sandbox.execute(moduleId, merged, executor);
-      }
-      const durationMs = Math.round(performance.now() - startTime);
-      const fmt = resolveFormat(opts.format);
-      formatExecResult(result, fmt, opts.fields);
-      const auditLogger = getAuditLogger();
-      if (auditLogger) {
-        auditLogger.logExecution(moduleId, merged, "success", 0, durationMs);
-      }
-    } catch (err) {
-      const exitCode = exitCodeForError(err);
-      const durationMs = Math.round(performance.now() - startTime);
-      try {
-        const auditLogger = getAuditLogger();
-        if (auditLogger) {
-          auditLogger.logExecution(moduleId, merged, "error", exitCode, durationMs);
-        }
-      } catch {
-      }
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : err}
-`);
-      process.exit(exitCode);
-    }
-  });
-  apcliGroup.addCommand(execCmd);
-}
-function registerValidateCommand(cli, registry, executor) {
-  const validateCmd = new Command2("validate").description("Run preflight checks without executing a module.").argument("<module-id>", "Module ID to validate").option("--input <source>", "JSON input file or '-' for stdin.").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    validateModuleId(moduleId);
-    const moduleDef = registry.getModule(moduleId);
-    if (!moduleDef) {
-      process.stderr.write(`Error: Module '${moduleId}' not found.
-`);
-      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
-    }
-    const merged = opts.input ? await collectInput(opts.input, {}, false) : {};
-    if (!executor.validate) {
-      process.stderr.write("Error: Executor does not support validate.\n");
-      process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
-    }
-    try {
-      const preflight = await executor.validate(moduleId, merged);
-      formatPreflightResult(preflight, opts.format);
-      process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
-    } catch (err) {
-      const exitCode = exitCodeForError(err);
-      try {
-        const auditLogger = getAuditLogger();
-        if (auditLogger) {
-          auditLogger.logExecution(moduleId, merged, "error", exitCode, 0);
-        }
-      } catch {
-      }
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : err}
-`);
-      process.exit(exitCode);
-    }
-  });
-  cli.addCommand(validateCmd);
-}
+      return result;
+    };
+    return new _ExposureFilter(
+      mode,
+      filterList(include, "include"),
+      filterList(exclude, "exclude")
+    );
+  }
+};
 
-// src/system-cmd.ts
+// src/cli.ts
+init_logger();
+
+// src/builtin-group.ts
 init_esm_shims();
-import { Command as Command3 } from "commander";
 init_errors();
-async function callSystemModule(executor, moduleId, inputs) {
-  if (executor.call) {
-    return executor.call(moduleId, inputs);
-  }
-  return executor.execute(moduleId, inputs);
-}
-function emitResult(jsonPayload, fmt, ttyRender) {
-  if (fmt === "json" || !process.stdout.isTTY) {
-    process.stdout.write(JSON.stringify(jsonPayload, null, 2) + "\n");
-  } else {
-    ttyRender();
+init_logger();
+var ApcliGroupError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ApcliGroupError";
   }
+};
+var DEFAULT_BUILTIN_GROUP_NAME = "apcli";
+var RESERVED_GROUP_NAMES = /* @__PURE__ */ new Set([DEFAULT_BUILTIN_GROUP_NAME]);
+var _effectiveReservedNames = RESERVED_GROUP_NAMES;
+function getReservedGroupNames() {
+  return _effectiveReservedNames;
 }
-function emitErrorAndExit(e) {
-  process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-  process.exit(exitCodeForError(e));
-}
-async function requireApprovalForSystemCommand(moduleId, autoApprove) {
-  const syntheticModuleDef = {
-    id: moduleId,
-    name: moduleId,
-    description: `system command: ${moduleId}`,
-    annotations: { requires_approval: true }
-  };
-  await checkApproval(syntheticModuleDef, autoApprove, void 0);
+function setReservedGroupNames(names) {
+  _effectiveReservedNames = names;
 }
-function formatHealthSummaryTty(result) {
-  const summary = result.summary ?? {};
-  const modules = result.modules ?? [];
-  if (modules.length === 0) {
-    process.stdout.write("No modules found.\n");
-    return;
-  }
-  const total = summary.total_modules ?? modules.length;
-  process.stdout.write(`Health Overview (${total} modules)
-
-`);
-  process.stdout.write(`  ${"Module".padEnd(28)} ${"Status".padEnd(12)} ${"Error Rate".padEnd(12)} Top Error
-`);
-  process.stdout.write(`  ${"-".repeat(28)} ${"-".repeat(12)} ${"-".repeat(12)} ${"-".repeat(20)}
-`);
-  for (const m of modules) {
-    const top = m.top_error;
-    const topStr = top ? `${top.code} (${top.count ?? "?"})` : "\u2014";
-    const rate = `${((m.error_rate ?? 0) * 100).toFixed(1)}%`;
-    process.stdout.write(
-      `  ${String(m.module_id).padEnd(28)} ${String(m.status).padEnd(12)} ${rate.padEnd(12)} ${topStr}
-`
+var _NAME_REGEX = /^[a-z][a-z0-9_-]*$/;
+function _validateBuiltinGroupName(name) {
+  if (!name || !_NAME_REGEX.test(name)) {
+    throw new ApcliGroupError(
+      `builtinGroupName ${JSON.stringify(name)} must match /^[a-z][a-z0-9_-]*$/ (non-empty, lowercase, alphanumeric + '_' / '-', leading letter).`
     );
   }
-  const parts = [];
-  for (const key of ["healthy", "degraded", "error"]) {
-    const count = summary[key];
-    if (count) parts.push(`${count} ${key}`);
-  }
-  process.stdout.write(`
-Summary: ${parts.join(", ") || "no data"}
-`);
-}
-function formatHealthModuleTty(result) {
-  process.stdout.write(`Module: ${result.module_id ?? "?"}
-`);
-  process.stdout.write(`Status: ${result.status ?? "unknown"}
-`);
-  const total = result.total_calls ?? 0;
-  const errors = result.error_count ?? 0;
-  const rate = result.error_rate ?? 0;
-  const avg = result.avg_latency_ms ?? 0;
-  const p99 = result.p99_latency_ms ?? 0;
-  process.stdout.write(`Calls: ${total.toLocaleString()} total | ${errors.toLocaleString()} errors | ${(rate * 100).toFixed(1)}% error rate
-`);
-  process.stdout.write(`Latency: ${avg.toFixed(0)}ms avg | ${p99.toFixed(0)}ms p99
-`);
-  const recent = result.recent_errors ?? [];
-  if (recent.length > 0) {
-    process.stdout.write(`
-Recent Errors (top ${recent.length}):
-`);
-    for (const e of recent) {
-      const count = e.count ?? "?";
-      const last = e.last_occurred ?? "?";
-      process.stdout.write(`  ${String(e.code ?? "?").padEnd(24)} x${count}  (last: ${last})
-`);
-    }
-  }
 }
-function formatUsageSummaryTty(result) {
-  const modules = result.modules ?? [];
-  const period = result.period ?? "?";
-  if (modules.length === 0) {
-    process.stdout.write(`No usage data for period ${period}.
-`);
-    return;
+var VALID_USER_MODES = /* @__PURE__ */ new Set([
+  "all",
+  "none",
+  "include",
+  "exclude"
+]);
+var APCLI_SUBCOMMAND_NAMES = /* @__PURE__ */ new Set([
+  "list",
+  "describe",
+  "exec",
+  "validate",
+  "init",
+  "health",
+  "usage",
+  "enable",
+  "disable",
+  "reload",
+  "config",
+  "completion",
+  "describe-pipeline"
+]);
+var ApcliGroup = class _ApcliGroup {
+  _mode;
+  _include;
+  _exclude;
+  _disableEnv;
+  _registryInjected;
+  _fromCliConfig;
+  _name;
+  constructor(init) {
+    this._mode = init.mode;
+    this._include = init.include;
+    this._exclude = init.exclude;
+    this._disableEnv = init.disableEnv;
+    this._registryInjected = init.registryInjected;
+    this._fromCliConfig = init.fromCliConfig;
+    this._name = init.name;
   }
-  process.stdout.write(`Usage Summary (last ${period})
-
-`);
-  process.stdout.write(`  ${"Module".padEnd(24)} ${"Calls".padStart(8)} ${"Errors".padStart(8)} ${"Avg Latency".padStart(12)} ${"Trend".padStart(10)}
-`);
-  process.stdout.write(`  ${"-".repeat(24)} ${"-".repeat(8)} ${"-".repeat(8)} ${"-".repeat(12)} ${"-".repeat(10)}
-`);
-  for (const m of modules) {
-    const avg = `${(m.avg_latency_ms ?? 0).toFixed(0)}ms`;
-    process.stdout.write(
-      `  ${String(m.module_id).padEnd(24)} ${String(m.call_count ?? 0).padStart(8)} ${String(m.error_count ?? 0).padStart(8)} ${avg.padStart(12)} ${String(m.trend ?? "").padStart(10)}
-`
+  /**
+   * Resolved name for the built-in command group (default `"apcli"`).
+   * Overridable via createCli's `builtinGroupName` option for downstream
+   * branded CLIs that want a custom namespace. Cross-SDK parity with
+   * Python `ApcliGroup.name` (2026-05-08).
+   */
+  get name() {
+    return this._name;
+  }
+  /**
+   * Tier 1 constructor — config came from `createCli({ apcli })`.
+   *
+   * A non-auto mode from this tier wins over env var and yaml.
+   */
+  static fromCliConfig(config, opts) {
+    return _ApcliGroup._build(
+      config,
+      opts,
+      /*fromCliConfig*/
+      true
     );
   }
-  const totalCalls = result.total_calls ?? modules.reduce((s, m) => s + (m.call_count ?? 0), 0);
-  const totalErrors = result.total_errors ?? modules.reduce((s, m) => s + (m.error_count ?? 0), 0);
-  process.stdout.write(`
-Total: ${totalCalls.toLocaleString()} calls | ${totalErrors.toLocaleString()} errors
-`);
-}
-function registerHealthCommand(apcliGroup, executor) {
-  const healthCmd = new Command3("health").description("Show module health status. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed health").option("--threshold <number>", "Error rate threshold (default: 0.01).", parseFloat, 0.01).option("--all", "Include healthy modules.", false).option("--errors <count>", "Max recent errors (module detail only).", parseInt, 10).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    const fmt = resolveFormat(opts.format);
-    try {
-      if (moduleId) {
-        const result = await callSystemModule(executor, "system.health.module", {
-          module_id: moduleId,
-          error_limit: opts.errors
-        });
-        emitResult(result, fmt, () => formatHealthModuleTty(result));
-      } else {
-        const result = await callSystemModule(executor, "system.health.summary", {
-          error_rate_threshold: opts.threshold,
-          include_healthy: opts.all
-        });
-        emitResult(result, fmt, () => formatHealthSummaryTty(result));
-      }
-    } catch (e) {
-      emitErrorAndExit(e);
+  /**
+   * Tier 3 constructor — config came from `apcore.yaml`.
+   *
+   * Env var (Tier 2) may override the yaml-supplied mode.
+   */
+  static fromYaml(config, opts) {
+    if (config !== null && config !== void 0 && typeof config !== "boolean" && (typeof config !== "object" || Array.isArray(config))) {
+      const got = Array.isArray(config) ? "array" : typeof config;
+      warn(
+        `apcore.yaml apcli has unexpected type ${got}; using auto-detect.`
+      );
+      return _ApcliGroup._build(
+        void 0,
+        opts,
+        /*fromCliConfig*/
+        false
+      );
     }
-  });
-  apcliGroup.addCommand(healthCmd);
-}
-function registerUsageCommand(apcliGroup, executor) {
-  const usageCmd = new Command3("usage").description("Show module usage statistics. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed usage").option("--period <period>", "Time window: 1h, 24h, 7d, 30d.", "24h").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    const fmt = resolveFormat(opts.format);
-    try {
-      let result;
-      if (moduleId) {
-        result = await callSystemModule(executor, "system.usage.module", {
-          module_id: moduleId,
-          period: opts.period
-        });
-      } else {
-        result = await callSystemModule(executor, "system.usage.summary", {
-          period: opts.period
-        });
-      }
-      emitResult(result, fmt, () => {
-        if (moduleId) {
-          formatExecResult(result, fmt);
-        } else {
-          formatUsageSummaryTty(result);
+    return _ApcliGroup._build(
+      config,
+      opts,
+      /*fromCliConfig*/
+      false
+    );
+  }
+  /**
+   * Non-panicking Tier 3 factory (A-001 parity with Rust's `try_from_yaml`).
+   * Returns `[instance, null]` on success or `[null, errorMessage]` on invalid input.
+   * Use this in programmatic contexts where throwing/exiting is unwanted.
+   */
+  static tryFromYaml(config, opts) {
+    if (config !== null && config !== void 0 && typeof config !== "boolean" && (typeof config !== "object" || Array.isArray(config))) {
+      const got = Array.isArray(config) ? "array" : typeof config;
+      return [
+        null,
+        `apcore.yaml 'apcli:' must be a bool, object, or null; got ${got}`
+      ];
+    }
+    if (config !== null && config !== void 0 && typeof config === "object" && !Array.isArray(config)) {
+      const mode = config["mode"];
+      if (mode !== void 0 && mode !== null) {
+        const validModes = ["all", "none", "include", "exclude"];
+        if (typeof mode !== "string" || !validModes.includes(mode)) {
+          return [null, `Invalid apcli mode: '${mode}'. Must be one of: all, none, include, exclude.`];
         }
-      });
-    } catch (e) {
-      emitErrorAndExit(e);
+      }
     }
-  });
-  apcliGroup.addCommand(usageCmd);
-}
-function registerEnableCommand(apcliGroup, executor) {
-  const enableCmd = new Command3("enable").description("Enable a disabled module at runtime.").argument("<module-id>", "Module ID to enable").requiredOption("--reason <reason>", "Reason for enabling (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    const fmt = resolveFormat(opts.format);
-    try {
-      await requireApprovalForSystemCommand("system.control.toggle_feature", opts.yes);
-      const result = await callSystemModule(executor, "system.control.toggle_feature", {
-        module_id: moduleId,
-        enabled: true,
-        reason: opts.reason
-      });
-      emitResult(result, fmt, () => {
-        process.stdout.write(`Module '${moduleId}' enabled.
-  Reason: ${opts.reason}
-`);
+    return [_ApcliGroup.fromYaml(config, opts), null];
+  }
+  // -------------------------------------------------------------------------
+  // Internal builder — shared by both factories
+  // -------------------------------------------------------------------------
+  static _build(config, opts, fromCliConfig) {
+    const name = opts.name ?? DEFAULT_BUILTIN_GROUP_NAME;
+    _validateBuiltinGroupName(name);
+    if (config === true) {
+      return new _ApcliGroup({
+        mode: "all",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig,
+        name
       });
-    } catch (e) {
-      emitErrorAndExit(e);
     }
-  });
-  apcliGroup.addCommand(enableCmd);
-}
-function registerDisableCommand(apcliGroup, executor) {
-  const disableCmd = new Command3("disable").description("Disable a module at runtime (calls are rejected until re-enabled).").argument("<module-id>", "Module ID to disable").requiredOption("--reason <reason>", "Reason for disabling (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    const fmt = resolveFormat(opts.format);
-    try {
-      await requireApprovalForSystemCommand("system.control.toggle_feature", opts.yes);
-      const result = await callSystemModule(executor, "system.control.toggle_feature", {
-        module_id: moduleId,
-        enabled: false,
-        reason: opts.reason
-      });
-      emitResult(result, fmt, () => {
-        process.stdout.write(`Module '${moduleId}' disabled.
-  Reason: ${opts.reason}
-`);
+    if (config === false) {
+      return new _ApcliGroup({
+        mode: "none",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig,
+        name
       });
-    } catch (e) {
-      emitErrorAndExit(e);
     }
-  });
-  apcliGroup.addCommand(disableCmd);
-}
-function registerReloadCommand(apcliGroup, executor) {
-  const reloadCmd = new Command3("reload").description("Hot-reload a module from disk.").argument("<module-id>", "Module ID to reload").requiredOption("--reason <reason>", "Reason for reload (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    const fmt = resolveFormat(opts.format);
-    try {
-      await requireApprovalForSystemCommand("system.control.reload_module", opts.yes);
-      const result = await callSystemModule(executor, "system.control.reload_module", {
-        module_id: moduleId,
-        reason: opts.reason
-      });
-      emitResult(result, fmt, () => {
-        const prev = result.previous_version ?? "?";
-        const newVer = result.new_version ?? "?";
-        const dur = result.reload_duration_ms ?? "?";
-        process.stdout.write(`Module '${moduleId}' reloaded.
-`);
-        process.stdout.write(`  Version: ${prev} -> ${newVer}
-`);
-        process.stdout.write(`  Duration: ${dur}ms
-`);
+    if (config === void 0 || config === null) {
+      return new _ApcliGroup({
+        mode: "auto",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig,
+        name
       });
-    } catch (e) {
-      emitErrorAndExit(e);
     }
-  });
-  apcliGroup.addCommand(reloadCmd);
-}
-function registerConfigCommand(apcliGroup, executor) {
-  const configGroup = new Command3("config").description("Read or update runtime configuration.");
-  const configGetCmd = new Command3("get").description("Read a configuration value by dot-path key.").argument("<key>", "Configuration key (dot-path)").option("--format <format>", "Output format.", "table").action(async (key, opts) => {
-    const fmt = resolveFormat(opts.format);
-    try {
-      const result = await callSystemModule(executor, "system.config.get", { key });
-      const value = result?.value ?? result;
-      emitResult({ key, value }, fmt, () => {
-        process.stdout.write(`${key} = ${JSON.stringify(value)}
-`);
-      });
-    } catch (e) {
-      emitErrorAndExit(e);
-    }
-  });
-  configGroup.addCommand(configGetCmd);
-  const configSetCmd = new Command3("set").description("Update a runtime configuration value (audit-logged; client-side approval gate applies).").argument("<key>", "Configuration key (dot-path)").argument("<value>", "New value").requiredOption("--reason <reason>", "Reason for config change (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (key, value, opts) => {
-    const fmt = resolveFormat(opts.format);
-    let parsedValue;
-    try {
-      parsedValue = JSON.parse(value);
-    } catch {
-      parsedValue = value;
+    if (typeof config !== "object" || Array.isArray(config)) {
+      process.stderr.write(
+        `Error: apcli config must be a boolean or object; got ${Array.isArray(config) ? "array" : typeof config}.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
-    try {
-      await requireApprovalForSystemCommand("system.control.update_config", opts.yes);
-      const result = await callSystemModule(executor, "system.control.update_config", {
-        key,
-        value: parsedValue,
-        reason: opts.reason
-      });
-      emitResult(result, fmt, () => {
-        const old = result.old_value ?? "?";
-        const newVal = result.new_value ?? "?";
-        process.stdout.write(`Config updated: ${key}
-`);
-        process.stdout.write(`  ${JSON.stringify(old)} -> ${JSON.stringify(newVal)}
-`);
-        process.stdout.write(`  Reason: ${opts.reason}
-`);
-      });
-    } catch (e) {
-      emitErrorAndExit(e);
+    const cfg = config;
+    let mode;
+    if (cfg.mode === void 0 || cfg.mode === null) {
+      mode = "auto";
+    } else if (typeof cfg.mode !== "string") {
+      process.stderr.write(
+        `Error: apcli.mode must be a string; got ${typeof cfg.mode}. Expected one of all|none|include|exclude.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    } else if (!VALID_USER_MODES.has(cfg.mode)) {
+      process.stderr.write(
+        `Error: apcli.mode '${cfg.mode}' is invalid. Expected one of all|none|include|exclude.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    } else {
+      mode = cfg.mode;
     }
-  });
-  configGroup.addCommand(configSetCmd);
-  apcliGroup.addCommand(configGroup);
-}
-
-// src/strategy.ts
-init_esm_shims();
-import { Command as Command4, Option as Option3 } from "commander";
-function lookupStrategyInfo(executor, strategyName) {
-  if (typeof executor.describePipeline === "function") {
-    try {
-      const current = executor.describePipeline();
-      if (current && current.name === strategyName) {
-        return { info: current, isCurrent: true };
+    const include = _ApcliGroup._normalizeList(cfg.include, "include");
+    const exclude = _ApcliGroup._normalizeList(cfg.exclude, "exclude");
+    const rawDisableEnv = cfg.disableEnv !== void 0 ? cfg.disableEnv : cfg["disable_env"];
+    let disableEnv = false;
+    if (rawDisableEnv !== void 0) {
+      if (typeof rawDisableEnv === "boolean") {
+        disableEnv = rawDisableEnv;
+      } else {
+        warn(
+          `apcli.disable_env must be boolean; got ${typeof rawDisableEnv}. Treating as false.`
+        );
       }
-    } catch {
     }
+    return new _ApcliGroup({
+      mode,
+      include,
+      exclude,
+      disableEnv,
+      registryInjected: opts.registryInjected,
+      fromCliConfig,
+      name
+    });
   }
-  const ctor = executor.constructor;
-  if (ctor && typeof ctor.listStrategies === "function") {
-    try {
-      const all = ctor.listStrategies();
-      const info = all.find((s) => s.name === strategyName) ?? null;
-      return { info, isCurrent: false };
-    } catch {
-      return { info: null, isCurrent: false };
+  /**
+   * Normalize an include/exclude list. Non-array → warn and return [].
+   *
+   * Unknown but well-formed entries emit a WARNING (spec §7 error table,
+   * T-APCLI-25) but are retained in the returned list for forward-compat —
+   * if apcore-cli later adds a subcommand named `foo`, existing configs
+   * continue to work without a config change. At runtime, unknown names
+   * simply never match any registered subcommand.
+   */
+  static _normalizeList(raw, label) {
+    if (raw === void 0 || raw === null) return [];
+    if (!Array.isArray(raw)) {
+      warn(`apcli.${label} must be a list; got ${typeof raw}. Ignoring.`);
+      return [];
     }
-  }
-  return { info: null, isCurrent: false };
-}
-var PRESET_STEPS = {
-  standard: [
-    "context_creation",
-    "call_chain_guard",
-    "module_lookup",
-    "acl_check",
-    "approval_gate",
-    "middleware_before",
-    "input_validation",
-    "execute",
-    "output_validation",
-    "middleware_after",
-    "return_result"
-  ],
-  internal: [
-    "context_creation",
-    "call_chain_guard",
-    "module_lookup",
-    "middleware_before",
-    "input_validation",
-    "execute",
-    "output_validation",
-    "middleware_after",
-    "return_result"
-  ],
-  testing: [
-    "context_creation",
-    "module_lookup",
-    "middleware_before",
-    "input_validation",
-    "execute",
-    "output_validation",
-    "middleware_after",
-    "return_result"
-  ],
-  performance: [
-    "context_creation",
-    "call_chain_guard",
-    "module_lookup",
-    "acl_check",
-    "approval_gate",
-    "input_validation",
-    "execute",
-    "output_validation",
-    "return_result"
-  ],
-  minimal: [
-    "context_creation",
-    "module_lookup",
-    "execute",
-    "return_result"
-  ]
-};
-function registerPipelineCommand(cli, executor) {
-  const pipelineCmd = new Command4("describe-pipeline").description("Show the execution pipeline steps for a strategy.").addOption(
-    new Option3("--strategy <name>", "Strategy to describe (default: standard).").choices(["standard", "internal", "testing", "performance", "minimal"]).default("standard")
-  ).option("--format <format>", "Output format.").action((opts) => {
-    const fmt = resolveFormat(opts.format);
-    const { info, isCurrent } = lookupStrategyInfo(executor, opts.strategy);
-    if (info) {
-      const strategySteps = isCurrent ? executor.currentStrategy?.steps ?? [] : [];
-      const header = `Pipeline: ${info.name} (${info.stepCount} steps)`;
-      if (fmt === "json" || !process.stdout.isTTY) {
-        const payload = {
-          strategy: info.name,
-          step_count: info.stepCount,
-          description: info.description,
-          steps: info.stepNames.map((name, i) => {
-            const stepMeta = strategySteps[i];
-            return {
-              index: i + 1,
-              name,
-              pure: stepMeta?.pure ?? false,
-              removable: stepMeta?.removable ?? true,
-              timeout_ms: stepMeta?.timeoutMs ?? null
-            };
-          })
-        };
-        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-      } else {
-        process.stdout.write(`${header}
-
-`);
-        process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
-`);
-        process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
-`);
-        for (let i = 0; i < info.stepNames.length; i++) {
-          const stepMeta = strategySteps[i];
-          const pure = stepMeta?.pure ? "yes" : "no";
-          const removable = stepMeta?.removable !== false ? "yes" : "no";
-          const timeout = stepMeta?.timeoutMs ? `${stepMeta.timeoutMs}ms` : "\u2014";
-          process.stdout.write(`  ${String(i + 1).padEnd(4)} ${info.stepNames[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} ${timeout}
-`);
+    const out = [];
+    for (const entry of raw) {
+      if (typeof entry === "string" && entry.length > 0) {
+        if (!APCLI_SUBCOMMAND_NAMES.has(entry)) {
+          warn(
+            `Unknown apcli subcommand '${entry}' in ${label} list \u2014 ignoring.`
+          );
         }
+        out.push(entry);
+      } else {
+        warn(`apcli.${label} contains non-string entry; skipping.`);
       }
-      return;
     }
-    const steps = PRESET_STEPS[opts.strategy] ?? [];
-    const pureSteps = /* @__PURE__ */ new Set([
-      "context_creation",
-      "call_chain_guard",
-      "module_lookup",
-      "acl_check",
-      "input_validation"
-    ]);
-    const nonRemovable = /* @__PURE__ */ new Set([
-      "context_creation",
-      "module_lookup",
-      "execute",
-      "return_result"
-    ]);
-    if (fmt === "json" || !process.stdout.isTTY) {
-      const payload = {
-        strategy: opts.strategy,
-        step_count: steps.length,
-        steps: steps.map((s, i) => ({
-          index: i + 1,
-          name: s,
-          pure: pureSteps.has(s),
-          removable: !nonRemovable.has(s)
-        }))
-      };
-      process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-    } else {
-      process.stdout.write(`Pipeline: ${opts.strategy} (${steps.length} steps)
-
-`);
-      process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
-`);
-      process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
-`);
-      for (let i = 0; i < steps.length; i++) {
-        const pure = pureSteps.has(steps[i]) ? "yes" : "no";
-        const removable = nonRemovable.has(steps[i]) ? "no" : "yes";
-        process.stdout.write(`  ${String(i + 1).padEnd(4)} ${steps[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} \u2014
-`);
-      }
-    }
-  });
-  cli.addCommand(pipelineCmd);
-}
-
-// src/builtin-group.ts
-init_esm_shims();
-init_errors();
-init_logger();
-var ApcliGroupError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ApcliGroupError";
-  }
-};
-var DEFAULT_BUILTIN_GROUP_NAME = "apcli";
-var RESERVED_GROUP_NAMES = /* @__PURE__ */ new Set([DEFAULT_BUILTIN_GROUP_NAME]);
-var _effectiveReservedNames = RESERVED_GROUP_NAMES;
-function getReservedGroupNames() {
-  return _effectiveReservedNames;
-}
-function setReservedGroupNames(names) {
-  _effectiveReservedNames = names;
-}
-var _NAME_REGEX = /^[a-z][a-z0-9_-]*$/;
-function _validateBuiltinGroupName(name) {
-  if (!name || !_NAME_REGEX.test(name)) {
-    throw new ApcliGroupError(
-      `builtinGroupName ${JSON.stringify(name)} must match /^[a-z][a-z0-9_-]*$/ (non-empty, lowercase, alphanumeric + '_' / '-', leading letter).`
-    );
-  }
-}
-var VALID_USER_MODES = /* @__PURE__ */ new Set([
-  "all",
-  "none",
-  "include",
-  "exclude"
-]);
-var APCLI_SUBCOMMAND_NAMES = /* @__PURE__ */ new Set([
-  "list",
-  "describe",
-  "exec",
-  "validate",
-  "init",
-  "health",
-  "usage",
-  "enable",
-  "disable",
-  "reload",
-  "config",
-  "completion",
-  "describe-pipeline"
-]);
-var ApcliGroup = class _ApcliGroup {
-  _mode;
-  _include;
-  _exclude;
-  _disableEnv;
-  _registryInjected;
-  _fromCliConfig;
-  _name;
-  constructor(init) {
-    this._mode = init.mode;
-    this._include = init.include;
-    this._exclude = init.exclude;
-    this._disableEnv = init.disableEnv;
-    this._registryInjected = init.registryInjected;
-    this._fromCliConfig = init.fromCliConfig;
-    this._name = init.name;
+    return out;
   }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
   /**
-   * Resolved name for the built-in command group (default `"apcli"`).
-   * Overridable via createCli's `builtinGroupName` option for downstream
-   * branded CLIs that want a custom namespace. Cross-SDK parity with
-   * Python `ApcliGroup.name` (2026-05-08).
+   * Resolve effective visibility mode after applying tier precedence.
+   *
+   * Returns one of `"all" | "none" | "include" | "exclude"` — never `"auto"`.
+   *
+   * Tier order (spec §4.4):
+   *   1. CliConfig non-auto wins outright.
+   *   2. `APCORE_CLI_APCLI` env var (unless sealed by disableEnv).
+   *   3. yaml non-auto.
+   *   4. Auto-detect from registryInjected.
    */
-  get name() {
-    return this._name;
+  resolveVisibility() {
+    if (this._fromCliConfig && this._mode !== "auto") {
+      return this._mode;
+    }
+    if (!this._disableEnv) {
+      const envMode = this._parseEnv(process.env.APCORE_CLI_APCLI);
+      if (envMode !== null) {
+        return envMode;
+      }
+    }
+    if (this._mode !== "auto") {
+      return this._mode;
+    }
+    return this._registryInjected ? "none" : "all";
   }
   /**
-   * Tier 1 constructor — config came from `createCli({ apcli })`.
+   * True iff `subcommand` passes the include/exclude filter.
    *
-   * A non-auto mode from this tier wins over env var and yaml.
+   * Callers MUST first check {@link resolveVisibility} — this method throws
+   * under modes `"all"` or `"none"` (caller bug per spec §4.6).
    */
-  static fromCliConfig(config, opts) {
-    return _ApcliGroup._build(
-      config,
-      opts,
-      /*fromCliConfig*/
-      true
+  isSubcommandIncluded(subcommand) {
+    const mode = this.resolveVisibility();
+    if (mode === "include") return this._include.includes(subcommand);
+    if (mode === "exclude") return !this._exclude.includes(subcommand);
+    throw new Error(
+      `isSubcommandIncluded called under mode '${mode}'; caller should bypass.`
     );
   }
+  /** True iff the `apcli` group itself should appear in root `--help`. */
+  isGroupVisible() {
+    return this.resolveVisibility() !== "none";
+  }
+  // -------------------------------------------------------------------------
+  // Env parser (Tier 2) — co-located per spec §4.4
+  // -------------------------------------------------------------------------
   /**
-   * Tier 3 constructor — config came from `apcore.yaml`.
+   * Parse APCORE_CLI_APCLI. Case-insensitive.
    *
-   * Env var (Tier 2) may override the yaml-supplied mode.
+   * - `show` / `1` / `true` → `"all"`
+   * - `hide` / `0` / `false` → `"none"`
+   * - Empty / unset → `null`
+   * - Anything else → warn and return `null`
    */
-  static fromYaml(config, opts) {
-    if (config !== null && config !== void 0 && typeof config !== "boolean" && (typeof config !== "object" || Array.isArray(config))) {
-      const got = Array.isArray(config) ? "array" : typeof config;
-      warn(
-        `apcore.yaml apcli has unexpected type ${got}; using auto-detect.`
-      );
-      return _ApcliGroup._build(
-        void 0,
-        opts,
-        /*fromCliConfig*/
-        false
-      );
+  _parseEnv(raw) {
+    if (raw === void 0 || raw === "") return null;
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "") return null;
+    if (normalized === "show" || normalized === "1" || normalized === "true") {
+      return "all";
     }
-    return _ApcliGroup._build(
-      config,
-      opts,
-      /*fromCliConfig*/
-      false
+    if (normalized === "hide" || normalized === "0" || normalized === "false") {
+      return "none";
+    }
+    warn(
+      `Unknown APCORE_CLI_APCLI value '${raw}', ignoring. Expected: show, hide, 1, 0, true, false.`
     );
+    return null;
+  }
+};
+
+// src/cli.ts
+init_errors();
+function listAllDefinitions(registry) {
+  const defs = [];
+  for (const id of registry.list()) {
+    const def = registry.getDefinition(id);
+    if (def) defs.push(def);
+  }
+  return defs;
+}
+function assertNotReserved(kind, name, moduleId) {
+  if (!getReservedGroupNames().has(name)) return;
+  let msg;
+  if (kind === "group") {
+    msg = `Error: Module '${moduleId}': display.cli.group '${name}' is reserved. Use a different CLI alias or set display.cli.group to another value.
+`;
+  } else if (kind === "auto-group") {
+    msg = `Error: Module '${moduleId}': auto-group '${name}' is reserved. Rename the module id or set display.cli.group to another value.
+`;
+  } else {
+    msg = `Error: Module '${moduleId}': top-level CLI name '${name}' is reserved. Use a different CLI alias.
+`;
+  }
+  process.stderr.write(msg);
+  process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+}
+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;
   }
   /**
-   * Non-panicking Tier 3 factory (A-001 parity with Rust's `try_from_yaml`).
-   * Returns `[instance, null]` on success or `[null, errorMessage]` on invalid input.
-   * Use this in programmatic contexts where throwing/exiting is unwanted.
+   * Build alias->module_id map from display overlay metadata.
    */
-  static tryFromYaml(config, opts) {
-    if (config !== null && config !== void 0 && typeof config !== "boolean" && (typeof config !== "object" || Array.isArray(config))) {
-      const got = Array.isArray(config) ? "array" : typeof config;
-      return [
-        null,
-        `apcore.yaml 'apcli:' must be a bool, object, or null; got ${got}`
-      ];
+  buildAliasMap() {
+    if (this.aliasMapBuilt) {
+      return;
     }
-    if (config !== null && config !== void 0 && typeof config === "object" && !Array.isArray(config)) {
-      const mode = config["mode"];
-      if (mode !== void 0 && mode !== null) {
-        const validModes = ["all", "none", "include", "exclude"];
-        if (typeof mode !== "string" || !validModes.includes(mode)) {
-          return [null, `Invalid apcli mode: '${mode}'. Must be one of: all, none, include, exclude.`];
+    try {
+      for (const descriptor of listAllDefinitions(this.registry)) {
+        const moduleId = descriptor.moduleId;
+        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");
     }
-    return [_ApcliGroup.fromYaml(config, opts), null];
   }
-  // -------------------------------------------------------------------------
-  // Internal builder — shared by both factories
-  // -------------------------------------------------------------------------
-  static _build(config, opts, fromCliConfig) {
-    const name = opts.name ?? DEFAULT_BUILTIN_GROUP_NAME;
-    _validateBuiltinGroupName(name);
-    if (config === true) {
-      return new _ApcliGroup({
-        mode: "all",
-        include: [],
-        exclude: [],
-        disableEnv: false,
-        registryInjected: opts.registryInjected,
-        fromCliConfig,
-        name
-      });
+  /**
+   * 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);
     }
-    if (config === false) {
-      return new _ApcliGroup({
-        mode: "none",
-        include: [],
-        exclude: [],
-        disableEnv: false,
-        registryInjected: opts.registryInjected,
-        fromCliConfig,
-        name
-      });
+    const moduleIds = listAllDefinitions(this.registry).map((m) => m.moduleId);
+    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);
     }
-    if (config === void 0 || config === null) {
-      return new _ApcliGroup({
-        mode: "auto",
-        include: [],
-        exclude: [],
-        disableEnv: false,
-        registryInjected: opts.registryInjected,
-        fromCliConfig,
-        name
-      });
+    this.buildAliasMap();
+    const moduleId = this.aliasMap.get(cmdName) ?? cmdName;
+    let moduleDef = this.descriptorCache.get(moduleId);
+    if (!moduleDef) {
+      moduleDef = this.registry.getDefinition(moduleId) ?? void 0;
     }
-    if (typeof config !== "object" || Array.isArray(config)) {
-      process.stderr.write(
-        `Error: apcli config must be a boolean or object; got ${Array.isArray(config) ? "array" : typeof config}.
-`
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    if (!moduleDef) {
+      return null;
     }
-    const cfg = config;
-    let mode;
-    if (cfg.mode === void 0 || cfg.mode === null) {
-      mode = "auto";
-    } else if (typeof cfg.mode !== "string") {
-      process.stderr.write(
-        `Error: apcli.mode must be a string; got ${typeof cfg.mode}. Expected one of all|none|include|exclude.
-`
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-    } else if (!VALID_USER_MODES.has(cfg.mode)) {
-      process.stderr.write(
-        `Error: apcli.mode '${cfg.mode}' is invalid. Expected one of all|none|include|exclude.
-`
+    const cmd = buildModuleCommand(moduleDef, this.executor, this.helpTextMaxLength, cmdName);
+    this.commandCache.set(cmdName, cmd);
+    return cmd;
+  }
+};
+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
       );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-    } else {
-      mode = cfg.mode;
+      this._cmdCache.set(cmdName, cmd);
+      this.command.addCommand(cmd);
     }
-    const include = _ApcliGroup._normalizeList(cfg.include, "include");
-    const exclude = _ApcliGroup._normalizeList(cfg.exclude, "exclude");
-    const rawDisableEnv = cfg.disableEnv !== void 0 ? cfg.disableEnv : cfg["disable_env"];
-    let disableEnv = false;
-    if (rawDisableEnv !== void 0) {
-      if (typeof rawDisableEnv === "boolean") {
-        disableEnv = rawDisableEnv;
-      } else {
-        warn(
-          `apcli.disable_env must be boolean; got ${typeof rawDisableEnv}. Treating as false.`
-        );
-      }
+  }
+  listCommands() {
+    return [...this.members.keys()].sort();
+  }
+  getCommand(cmdName) {
+    if (this._cmdCache.has(cmdName)) {
+      return this._cmdCache.get(cmdName);
     }
-    return new _ApcliGroup({
-      mode,
-      include,
-      exclude,
-      disableEnv,
-      registryInjected: opts.registryInjected,
-      fromCliConfig,
-      name
-    });
+    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;
+  }
+};
+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;
+  /** Exposure filter (FE-12) — controls which modules appear as CLI commands */
+  exposureFilter;
+  /** Effective group depth (CLAUDE.md v0.6.0): constructor arg > APCORE_CLI_GROUP_DEPTH env > 1. */
+  groupDepth;
+  constructor(registry, executor, helpTextMaxLength = 1e3, exposureFilter, groupDepth) {
+    super(registry, executor, helpTextMaxLength);
+    this.exposureFilter = exposureFilter ?? new ExposureFilter();
+    this.groupDepth = _GroupedModuleGroup.resolveGroupDepth(groupDepth);
   }
   /**
-   * Normalize an include/exclude list. Non-array → warn and return [].
-   *
-   * Unknown but well-formed entries emit a WARNING (spec §7 error table,
-   * T-APCLI-25) but are retained in the returned list for forward-compat —
-   * if apcore-cli later adds a subcommand named `foo`, existing configs
-   * continue to work without a config change. At runtime, unknown names
-   * simply never match any registered subcommand.
+   * Resolve group depth from constructor arg > APCORE_CLI_GROUP_DEPTH env > default 1.
+   * Invalid env values (non-integer, non-positive) fall through to the default.
    */
-  static _normalizeList(raw, label) {
-    if (raw === void 0 || raw === null) return [];
-    if (!Array.isArray(raw)) {
-      warn(`apcli.${label} must be a list; got ${typeof raw}. Ignoring.`);
-      return [];
+  static resolveGroupDepth(explicit) {
+    if (explicit !== void 0 && Number.isFinite(explicit) && explicit > 0) {
+      return Math.floor(explicit);
     }
-    const out = [];
-    for (const entry of raw) {
-      if (typeof entry === "string" && entry.length > 0) {
-        if (!APCLI_SUBCOMMAND_NAMES.has(entry)) {
-          warn(
-            `Unknown apcli subcommand '${entry}' in ${label} list \u2014 ignoring.`
-          );
-        }
-        out.push(entry);
-      } else {
-        warn(`apcli.${label} contains non-string entry; skipping.`);
+    const raw = process.env.APCORE_CLI_GROUP_DEPTH;
+    if (raw !== void 0 && raw !== "") {
+      const parsed = parseInt(raw, 10);
+      if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed;
       }
     }
-    return out;
+    return 1;
   }
-  // -------------------------------------------------------------------------
-  // Public API
-  // -------------------------------------------------------------------------
   /**
-   * Resolve effective visibility mode after applying tier precedence.
-   *
-   * Returns one of `"all" | "none" | "include" | "exclude"` — never `"auto"`.
+   * Determine (groupName | null, commandName) for a module from its display overlay.
    *
-   * Tier order (spec §4.4):
-   *   1. CliConfig non-auto wins outright.
-   *   2. `APCORE_CLI_APCLI` env var (unless sealed by disableEnv).
-   *   3. yaml non-auto.
-   *   4. Auto-detect from registryInjected.
+   * @param groupDepth  Number of dotted segments to consume as the group prefix.
+   *                    Defaults to 1 (e.g., "math.add" → group="math", cmd="add").
+   *                    Set to 2 for multi-level grouping (e.g., "math.trig.sin" →
+   *                    group="math.trig", cmd="sin").
    */
-  resolveVisibility() {
-    if (this._fromCliConfig && this._mode !== "auto") {
-      return this._mode;
+  static resolveGroup(moduleId, descriptor, groupDepth = 1) {
+    if (!moduleId) {
+      warn("Empty module_id encountered in resolveGroup");
+      return [null, ""];
     }
-    if (!this._disableEnv) {
-      const envMode = this._parseEnv(process.env.APCORE_CLI_APCLI);
-      if (envMode !== null) {
-        return envMode;
-      }
+    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 (this._mode !== "auto") {
-      return this._mode;
+    if (explicitGroup === "") {
+      return [null, cliDisplay.alias ?? moduleId];
     }
-    return this._registryInjected ? "none" : "all";
+    const cliName = cliDisplay.alias ?? moduleId;
+    if (cliName.includes(".")) {
+      const parts = cliName.split(".");
+      const depth = Math.max(1, Math.min(groupDepth, parts.length - 1));
+      const group = parts.slice(0, depth).join(".");
+      const cmd = parts.slice(depth).join(".");
+      return [group, cmd];
+    }
+    return [null, cliName];
   }
   /**
-   * True iff `subcommand` passes the include/exclude filter.
+   * Build the group map from registry modules.
    *
-   * Callers MUST first check {@link resolveVisibility} — this method throws
-   * under modes `"all"` or `"none"` (caller bug per spec §4.6).
+   * FE-13: hard-fails with exit 2 when a module resolves to the reserved
+   * `apcli` namespace in any of three ways — explicit `display.cli.group`,
+   * auto-grouped dotted prefix, or top-level alias/id. See spec §4.10.
    */
-  isSubcommandIncluded(subcommand) {
-    const mode = this.resolveVisibility();
-    if (mode === "include") return this._include.includes(subcommand);
-    if (mode === "exclude") return !this._exclude.includes(subcommand);
-    throw new Error(
-      `isSubcommandIncluded called under mode '${mode}'; caller should bypass.`
-    );
-  }
-  /** True iff the `apcli` group itself should appear in root `--help`. */
-  isGroupVisible() {
-    return this.resolveVisibility() !== "none";
-  }
-  // -------------------------------------------------------------------------
-  // Env parser (Tier 2) — co-located per spec §4.4
-  // -------------------------------------------------------------------------
-  /**
-   * Parse APCORE_CLI_APCLI. Case-insensitive.
-   *
-   * - `show` / `1` / `true` → `"all"`
-   * - `hide` / `0` / `false` → `"none"`
-   * - Empty / unset → `null`
-   * - Anything else → warn and return `null`
-   */
-  _parseEnv(raw) {
-    if (raw === void 0 || raw === "") return null;
-    const normalized = raw.trim().toLowerCase();
-    if (normalized === "") return null;
-    if (normalized === "show" || normalized === "1" || normalized === "true") {
-      return "all";
-    }
-    if (normalized === "hide" || normalized === "0" || normalized === "false") {
-      return "none";
-    }
-    warn(
-      `Unknown APCORE_CLI_APCLI value '${raw}', ignoring. Expected: show, hide, 1, 0, true, false.`
-    );
-    return null;
-  }
-};
-
-// src/exposure.ts
-init_esm_shims();
-init_logger();
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function compilePattern(pattern) {
-  const sentinel = "\0GLOB\0";
-  const escaped = pattern.replaceAll("**", sentinel);
-  const parts = escaped.split("*");
-  const regexParts = parts.map((p) => {
-    const restored = p.replaceAll(sentinel, "**");
-    return escapeRegex(restored);
-  });
-  let regex = regexParts.join("[^.]*");
-  regex = regex.replaceAll("\\*\\*", ".+");
-  return new RegExp(`^${regex}$`);
-}
-var ExposureFilter = class _ExposureFilter {
-  static VALID_MODES = ["all", "include", "exclude", "none"];
-  _mode;
-  _compiledInclude;
-  _compiledExclude;
-  constructor(mode = "all", include, exclude) {
-    if (!_ExposureFilter.VALID_MODES.includes(mode)) {
-      process.stderr.write(
-        `Warning: Unknown ExposureFilter mode '${mode}' \u2014 defaulting to 'none'. Valid modes: ${_ExposureFilter.VALID_MODES.join(", ")}.
-`
-      );
-      mode = "none";
-    }
-    this._mode = mode;
-    const dedup = (arr) => [...new Set(arr)];
-    this._compiledInclude = dedup(include ?? []).map(compilePattern);
-    this._compiledExclude = dedup(exclude ?? []).map(compilePattern);
-  }
-  /** Return true if the module should be exposed as a CLI command. */
-  isExposed(moduleId) {
-    if (this._mode === "all") return true;
-    if (this._mode === "include") {
-      return this._compiledInclude.some((rx) => rx.test(moduleId));
-    }
-    if (this._mode === "exclude") {
-      return !this._compiledExclude.some((rx) => rx.test(moduleId));
+  buildGroupMap() {
+    if (this.groupMapBuilt) {
+      return;
     }
-    return false;
-  }
-  /** Partition moduleIds into [exposed, hidden] lists. */
-  filterModules(moduleIds) {
-    const exposed = [];
-    const hidden = [];
-    for (const mid of moduleIds) {
-      (this.isExposed(mid) ? exposed : hidden).push(mid);
+    this.buildAliasMap();
+    for (const descriptor of listAllDefinitions(this.registry)) {
+      const moduleId = descriptor.moduleId;
+      const cached = this.descriptorCache.get(moduleId);
+      if (!cached) {
+        continue;
+      }
+      if (!this.exposureFilter.isExposed(moduleId)) {
+        continue;
+      }
+      const display = getDisplay(cached);
+      const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+      const explicitGroup = typeof cliDisplay.group === "string" && cliDisplay.group !== "" ? cliDisplay.group : void 0;
+      if (explicitGroup !== void 0) {
+        assertNotReserved("group", explicitGroup, moduleId);
+      }
+      const [group, cmd] = _GroupedModuleGroup.resolveGroup(moduleId, cached, this.groupDepth);
+      if (group !== null && explicitGroup === void 0) {
+        assertNotReserved("auto-group", group, moduleId);
+      }
+      if (group === null) {
+        assertNotReserved("top-level", cmd, moduleId);
+        this.topLevelModules.set(cmd, [moduleId, cached]);
+      } else if (!/^[a-z][a-z0-9_-]*(\.[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]);
+      }
     }
-    return [exposed, hidden];
+    this.groupMapBuilt = true;
   }
   /**
-   * Create an ExposureFilter from a parsed config dict.
+   * List all available command names: group names + top-level module names.
    *
-   * Expected: `{ expose: { mode: "include", include: ["admin.*"] } }`
+   * FE-13: the built-in subcommand list is no longer folded in here — those
+   * commands live under the `apcli` prefix and are registered directly by
+   * `createCli`.
    */
-  static fromConfig(config) {
-    const expose = config.expose ?? {};
-    if (typeof expose !== "object" || expose === null || Array.isArray(expose)) {
-      warn("Invalid 'expose' config (expected dict), using mode: all.");
-      return new _ExposureFilter();
+  listCommands() {
+    this.buildGroupMap();
+    const reserved = getReservedGroupNames();
+    const groupNames = [...this.groupMap.keys()].filter(
+      (g) => !reserved.has(g)
+    );
+    const topNames = [...this.topLevelModules.keys()];
+    return [.../* @__PURE__ */ new Set([...groupNames, ...topNames])].sort();
+  }
+  /**
+   * 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;
     }
-    const exposeObj = expose;
-    const mode = exposeObj.mode ?? "all";
-    if (!["all", "include", "exclude"].includes(mode)) {
-      throw new Error(
-        `Invalid expose mode: '${mode}'. Must be one of: all, include, exclude.`
+    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;
     }
-    let include = exposeObj.include ?? [];
-    if (!Array.isArray(include)) {
-      warn("Invalid 'expose.include' (expected list), ignoring.");
-      include = [];
-    }
-    let exclude = exposeObj.exclude ?? [];
-    if (!Array.isArray(exclude)) {
-      warn("Invalid 'expose.exclude' (expected list), ignoring.");
-      exclude = [];
-    }
-    const filterList = (arr, label) => {
-      const result = [];
-      for (const p of arr) {
-        if (!p) {
-          warn(`Empty pattern in expose.${label}, skipping.`);
-        } else {
-          result.push(String(p));
-        }
+    if (this.topLevelModules.has(cmdName)) {
+      if (this.commandCache.has(cmdName)) {
+        return this.commandCache.get(cmdName);
       }
-      return result;
-    };
-    return new _ExposureFilter(
-      mode,
-      filterList(include, "include"),
-      filterList(exclude, "exclude")
-    );
+      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/main.ts
+// src/discovery.ts
+init_errors();
 init_audit();
 
-// src/canonical-help.ts
+// src/system-usage.ts
 init_esm_shims();
-function resolveHelpText(cmd, section) {
-  const bag = cmd._helpText;
-  const v = bag?.[section];
-  if (typeof v === "function") return v({ error: false, command: cmd });
-  return v ?? "";
-}
-function uppercasePlaceholders(flags) {
-  return flags.replace(/<([a-zA-Z0-9_-]+)>/g, (_, name) => `<${name.toUpperCase()}>`).replace(/\[([a-zA-Z0-9_-]+)\]/g, (_, name) => `[${name.toUpperCase()}]`);
-}
-function optionTerm(opt) {
-  const flags = uppercasePlaceholders(opt.flags);
-  if (!opt.short && flags.startsWith("--")) return "    " + flags;
-  return flags;
-}
-function optionDescription(opt) {
-  let desc = opt.description;
-  const d = opt.defaultValue;
-  if (d !== void 0 && d !== false && d !== "" && d !== null) {
-    desc = `${desc} [default: ${String(d)}]`;
+import * as fs4 from "fs";
+import * as os2 from "os";
+import * as path4 from "path";
+var PERIOD_TO_MS = {
+  "1h": 60 * 60 * 1e3,
+  "24h": 24 * 60 * 60 * 1e3,
+  "7d": 7 * 24 * 60 * 60 * 1e3,
+  "30d": 30 * 24 * 60 * 60 * 1e3
+};
+var DEFAULT_AUDIT_PATH = path4.join(
+  os2.homedir(),
+  ".apcore-cli",
+  "audit.jsonl"
+);
+function computeSummary(options = {}) {
+  const auditPath = options.auditPath ?? DEFAULT_AUDIT_PATH;
+  const period = options.period ?? "24h";
+  const cutoff = (options.now ?? /* @__PURE__ */ new Date()).getTime() - PERIOD_TO_MS[period];
+  if (!fs4.existsSync(auditPath)) {
+    return /* @__PURE__ */ new Map();
   }
-  return desc;
-}
-function reorderHelpVersionLast(opts) {
-  const helpOpts = [];
-  const versionOpts = [];
-  const rest = [];
-  for (const o of opts) {
-    if (o.long === "--help") helpOpts.push(o);
-    else if (o.long === "--version") versionOpts.push(o);
-    else rest.push(o);
+  let raw;
+  try {
+    raw = fs4.readFileSync(auditPath, "utf-8");
+  } catch {
+    return /* @__PURE__ */ new Map();
   }
-  return [...rest, ...helpOpts, ...versionOpts];
-}
-function canonicalFormatHelp(cmd, helper) {
-  const sections = [];
-  const beforeAll = resolveHelpText(cmd, "beforeAll");
-  if (beforeAll) sections.push(beforeAll);
-  const desc = cmd.description();
-  if (desc) sections.push(desc);
-  const before = resolveHelpText(cmd, "before");
-  if (before) sections.push(before);
-  const visibleOpts = reorderHelpVersionLast(helper.visibleOptions(cmd));
-  const visibleCmds = helper.visibleCommands(cmd);
-  const args = cmd.registeredArguments ?? [];
-  let usage = `Usage: ${cmd.name()}`;
-  if (visibleOpts.length > 0) usage += " [OPTIONS]";
-  for (const a of args) {
-    const n = a.name().toUpperCase();
-    usage += a.required ? ` <${n}>` : ` [${n}]`;
+  const counts = /* @__PURE__ */ new Map();
+  const errors = /* @__PURE__ */ new Map();
+  const latencySum = /* @__PURE__ */ new Map();
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const ts = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : NaN;
+    if (Number.isNaN(ts) || ts < cutoff) continue;
+    const moduleId = typeof entry.module_id === "string" ? entry.module_id : null;
+    if (!moduleId) continue;
+    counts.set(moduleId, (counts.get(moduleId) ?? 0) + 1);
+    if (entry.status === "error") {
+      errors.set(moduleId, (errors.get(moduleId) ?? 0) + 1);
+    }
+    const duration = entry.duration_ms;
+    if (typeof duration === "number") {
+      latencySum.set(moduleId, (latencySum.get(moduleId) ?? 0) + duration);
+    }
   }
-  if (visibleCmds.length > 0) usage += " [COMMAND]";
-  sections.push(usage);
-  if (visibleCmds.length > 0) {
-    const terms = visibleCmds.map((c) => c.name());
-    const w = Math.max(...terms.map((t) => t.length));
-    const lines = ["Commands:"];
-    visibleCmds.forEach((sub, i) => {
-      lines.push(`  ${terms[i].padEnd(w)}  ${sub.description()}`);
+  const out = /* @__PURE__ */ new Map();
+  for (const [id, calls] of counts) {
+    out.set(id, {
+      module_id: id,
+      calls,
+      errors: errors.get(id) ?? 0,
+      latency_ms: calls > 0 ? (latencySum.get(id) ?? 0) / calls : 0
     });
-    sections.push(lines.join("\n"));
   }
-  if (visibleOpts.length > 0) {
-    const terms = visibleOpts.map(optionTerm);
-    const w = Math.max(...terms.map((t) => t.length));
-    const lines = ["Options:"];
-    visibleOpts.forEach((opt, i) => {
-      lines.push(`  ${terms[i].padEnd(w)}  ${optionDescription(opt)}`);
-    });
-    sections.push(lines.join("\n"));
+  return out;
+}
+function sortModulesByUsage(modules, field, options = {}) {
+  const reverse = options.reverse ?? true;
+  const summary = computeSummary({
+    auditPath: options.auditPath,
+    period: options.period
+  });
+  const idOf = (m) => m.moduleId ?? m.id ?? m.module_id ?? "";
+  if (summary.size === 0) {
+    modules.sort((a, b) => idOf(a).localeCompare(idOf(b)));
+    if (reverse) modules.reverse();
+    return { used: false };
   }
-  const after = resolveHelpText(cmd, "after");
-  if (after) sections.push(after);
-  const afterAll = resolveHelpText(cmd, "afterAll");
-  if (afterAll) sections.push(afterAll);
-  return sections.join("\n\n") + "\n";
+  const key = (m) => {
+    const id = idOf(m);
+    const s = summary.get(id);
+    if (!s) return 0;
+    return field === "latency" ? s.latency_ms : field === "calls" ? s.calls : s.errors;
+  };
+  modules.sort((a, b) => {
+    const diff = key(a) - key(b);
+    if (diff !== 0) return reverse ? -diff : diff;
+    return idOf(a).localeCompare(idOf(b));
+  });
+  return { used: true };
 }
 
-// src/validate.ts
-init_esm_shims();
-init_errors();
-var MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
-var MAX_MODULE_ID_LENGTH = 192;
-function validateModuleId(moduleId) {
-  if (moduleId.length > MAX_MODULE_ID_LENGTH) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'. Maximum length is ${MAX_MODULE_ID_LENGTH} characters.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  if (!MODULE_ID_PATTERN.test(moduleId)) {
+// src/discovery.ts
+var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
+function validateTag(tag) {
+  if (!TAG_PATTERN.test(tag)) {
     process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'.
+      `Error: Invalid tag format: '${tag}'. Tags must match [a-z][a-z0-9_-]*.
 `
     );
     process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
 }
-
-// src/main.ts
-var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
-var verboseHelp = false;
-function setAllOptionsHelp(allOptions) {
-  verboseHelp = allOptions;
-}
-function setVerboseHelp(verbose) {
-  setAllOptionsHelp(verbose);
+function collectTag(value, previous) {
+  return previous.concat([value]);
 }
-var docsUrl = null;
-function setDocsUrl(url) {
-  docsUrl = url;
+function collectAnnotation(value, previous) {
+  return previous.concat([value]);
 }
-function hasVerboseFlag() {
-  return process.argv.includes("--all-options");
+function getAnnotationFlag(moduleDef, flag) {
+  const annotations = moduleDef.annotations;
+  if (!annotations || typeof annotations !== "object") return false;
+  const ann = annotations;
+  const map = {
+    "destructive": "destructive",
+    "requires-approval": "requires_approval",
+    "readonly": "readonly",
+    "streaming": "streaming",
+    "cacheable": "cacheable",
+    "idempotent": "idempotent",
+    "paginated": "paginated"
+  };
+  const attr = map[flag] ?? flag;
+  return ann[attr] === true;
 }
-function resolveIntOption(cliValue, envValue, defaultValue) {
-  if (cliValue !== void 0 && Number.isFinite(cliValue) && cliValue > 0) {
-    return cliValue;
-  }
-  if (envValue !== void 0 && envValue !== "") {
-    const parsed = parseInt(envValue, 10);
-    if (Number.isFinite(parsed) && parsed > 0) {
-      return parsed;
+function registerListCommand(apcliGroup, registry, exposureFilter) {
+  const listCmd = new Command3("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--flat", "Show flat list (no grouping).", false).addOption(
+    new Option2("--format <format>", "Output format.").choices(["table", "json", "csv", "yaml", "jsonl", "markdown", "skill"])
+  ).option("-s, --search <query>", "Filter by substring match on ID and description.").addOption(
+    new Option2("--status <status>", "Filter by module status.").choices(["enabled", "disabled", "all"]).default("enabled")
+  ).option("-a, --annotation <flag>", "Filter by annotation flag (AND logic). Repeatable.", collectAnnotation, []).addOption(
+    new Option2("--sort <field>", "Sort order.").choices(["id", "calls", "errors", "latency"]).default("id")
+  ).option("--reverse", "Reverse sort order.", false).option("--deprecated", "Include deprecated modules.", false).option("--deps", "Show dependency count column.", false).addOption(
+    new Option2("--exposure <mode>", "Filter by exposure status.").choices(["exposed", "hidden", "all"]).default("exposed")
+  ).action((opts) => {
+    for (const t of opts.tag) {
+      validateTag(t);
     }
-    process.stderr.write(
-      `Warning: invalid integer env value '${envValue}'; using default ${defaultValue}.
-`
-    );
-  }
-  return defaultValue;
-}
-function resolveStringOption(cliValue, envValue) {
-  if (typeof cliValue === "string" && cliValue !== "") {
-    return cliValue;
-  }
-  if (envValue !== void 0 && envValue !== "") {
-    return envValue;
-  }
-  return void 0;
-}
-var VERSION = "0.0.0";
-try {
-  const pkg = JSON.parse(readFileSync3(path5.resolve(__dirname2, "../package.json"), "utf-8"));
-  VERSION = pkg.version;
-} catch {
-}
-function emitErrorJson(e, exitCode) {
-  const err = e instanceof Error ? e : new Error(String(e));
-  const errRecord = err;
-  const code = errRecord.code ?? "UNKNOWN";
-  const payload = {
-    error: true,
-    code,
-    message: err.message,
-    exit_code: exitCode
-  };
-  for (const field of ["details", "suggestion", "ai_guidance", "retryable", "user_fixable"]) {
-    const val = errRecord[field];
-    if (val !== void 0 && val !== null) {
-      payload[field] = val;
+    let modules = [];
+    for (const m of listAllDefinitions(registry)) {
+      modules.push(m);
     }
-  }
-  process.stderr.write(JSON.stringify(payload) + "\n");
-}
-function emitErrorTty(e, exitCode) {
-  const err = e instanceof Error ? e : new Error(String(e));
-  const errRecord = err;
-  const code = errRecord.code;
-  const header = code ? `Error [${code}]: ${err.message}` : `Error: ${err.message}`;
-  process.stderr.write(header + "\n");
-  const details = errRecord.details;
-  if (details && typeof details === "object" && !Array.isArray(details)) {
-    process.stderr.write("\n  Details:\n");
-    for (const [k, v] of Object.entries(details)) {
-      process.stderr.write(`    ${k}: ${v}
-`);
+    if (opts.tag.length > 0) {
+      const filterTags = new Set(opts.tag);
+      modules = modules.filter((m) => {
+        const mTags = m.tags ?? [];
+        return [...filterTags].every((t) => mTags.includes(t));
+      });
     }
-  }
-  const suggestion = errRecord.suggestion;
-  if (suggestion) {
-    process.stderr.write(`
-  Suggestion: ${suggestion}
-`);
-  }
-  const retryable = errRecord.retryable;
-  if (retryable !== void 0 && retryable !== null) {
-    const label = retryable ? "Yes" : "No (same input will fail again)";
-    process.stderr.write(`  Retryable: ${label}
-`);
-  }
-  process.stderr.write(`
-  Exit code: ${exitCode}
-`);
-}
-function createCli(extensionsDirOrOpts, progName, allOptions = false) {
-  let extensionsDir;
-  let registry;
-  let executor;
-  let extraCommands;
-  let app;
-  let expose;
-  let apcliOption;
-  let appVersion;
-  let appDescription;
-  let allowedPrefixes;
-  let builtinGroupName;
-  if (typeof extensionsDirOrOpts === "object" && extensionsDirOrOpts !== null) {
-    extensionsDir = extensionsDirOrOpts.extensionsDir;
-    progName = extensionsDirOrOpts.progName ?? progName;
-    allOptions = extensionsDirOrOpts.allOptions ?? extensionsDirOrOpts.verbose ?? allOptions;
-    app = extensionsDirOrOpts.app;
-    registry = extensionsDirOrOpts.registry;
-    executor = extensionsDirOrOpts.executor;
-    extraCommands = extensionsDirOrOpts.extraCommands;
-    expose = extensionsDirOrOpts.expose;
-    apcliOption = extensionsDirOrOpts.apcli;
-    appVersion = extensionsDirOrOpts.version;
-    appDescription = extensionsDirOrOpts.description;
-    builtinGroupName = extensionsDirOrOpts.builtinGroupName;
-    allowedPrefixes = extensionsDirOrOpts.allowedPrefixes;
-  } else {
-    extensionsDir = extensionsDirOrOpts;
-  }
-  verboseHelp = allOptions;
-  registerConfigNamespace();
-  try {
-    const auditLogger = new AuditLogger();
-    setAuditLogger(auditLogger);
-  } catch {
-  }
-  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);
-  if (app && (registry || executor)) {
-    process.stderr.write("Error: app is mutually exclusive with registry/executor\n");
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  if (app) {
-    registry = app.registry;
-    executor = app.executor;
-  }
-  if (executor && !registry) {
-    process.stderr.write("Error: executor requires registry \u2014 pass both or neither\n");
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  if (executor && typeof executor.setApprovalHandler === "function") {
-    try {
-      const handler = new CliApprovalHandler(
-        /*autoApprove*/
-        false
+    if (opts.search) {
+      const query = opts.search.toLowerCase();
+      modules = modules.filter(
+        (m) => (m.moduleId ?? "").toLowerCase().includes(query) || (m.description ?? "").toLowerCase().includes(query)
       );
-      executor.setApprovalHandler(handler);
-    } catch {
     }
-  }
-  const registryInjected = registry !== void 0;
-  const program = new Command5(resolvedProgName).exitOverride().helpOption("-h, --help", "Print help").addHelpCommand("help [command]", "Print this message or the help of the given subcommand(s)").description(appDescription ?? `${resolvedProgName} CLI`).option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--all-options", "Show all options in help output (including built-in options)");
-  if (appVersion) {
-    program.version(appVersion, "-V, --version", "Print version");
-  }
-  program.configureHelp({ formatHelp: canonicalFormatHelp });
-  if (!registryInjected) {
-    program.option("--extensions-dir <path>", "Path to extensions directory");
-    program.option("--commands-dir <path>", "Path to convention-based commands directory");
-    program.option("--binding <path>", "Path to binding.yaml for display overlay");
-  }
-  let apcliCfg;
-  try {
-    if (apcliOption instanceof ApcliGroup) {
-      if (builtinGroupName !== void 0 && builtinGroupName !== "apcli" && apcliOption.name !== builtinGroupName) {
-        throw new Error(
-          `builtinGroupName=${JSON.stringify(builtinGroupName)} conflicts with the name on the supplied ApcliGroup (${JSON.stringify(apcliOption.name)}). Pass only one.`
-        );
-      }
-      apcliCfg = apcliOption;
-    } else if (apcliOption !== void 0) {
-      apcliCfg = ApcliGroup.fromCliConfig(apcliOption, {
-        registryInjected,
-        name: builtinGroupName
+    if (opts.status === "enabled") {
+      modules = modules.filter((m) => {
+        const enabled = m.enabled;
+        return enabled !== false;
       });
-    } else {
-      let yamlVal = null;
-      try {
-        const resolver = new ConfigResolver();
-        yamlVal = resolver.resolveObject("apcli");
-      } catch {
-        yamlVal = null;
-      }
-      apcliCfg = ApcliGroup.fromYaml(yamlVal, {
-        registryInjected,
-        name: builtinGroupName
+    } else if (opts.status === "disabled") {
+      modules = modules.filter((m) => {
+        const enabled = m.enabled;
+        return enabled === false;
       });
     }
-  } catch (e) {
-    process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}
-`);
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  setReservedGroupNames(/* @__PURE__ */ new Set([apcliCfg.name]));
-  const apcliGroup = program.command(apcliCfg.name, { hidden: !apcliCfg.isGroupVisible() }).description("Built-in commands");
-  if (registry) {
-    program._registry = registry;
-    if (executor) {
-      program._executor = executor;
-    }
-  } else {
-    const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
-    void resolvedExtDir;
-  }
-  let exposureFilter;
-  try {
-    if (expose instanceof ExposureFilter) {
-      exposureFilter = expose;
-    } else if (typeof expose === "object" && expose !== null) {
-      exposureFilter = ExposureFilter.fromConfig({ expose });
-    } else {
-      exposureFilter = new ExposureFilter();
+    if (!opts.deprecated) {
+      modules = modules.filter((m) => {
+        const deprecated = m.deprecated;
+        return deprecated !== true;
+      });
     }
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`Error: invalid 'expose' option \u2014 ${msg}
-`);
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter);
-  program.addHelpText("after", [
-    "",
-    "Use --help --all-options to show all options (including built-in options).",
-    "Use --help --man to display a formatted man page."
-  ].join("\n"));
-  configureManHelp(program, resolvedProgName, appVersion ?? VERSION);
-  if (extraCommands && extraCommands.length > 0) {
-    const _reservedForExtra = /* @__PURE__ */ new Set([apcliCfg.name]);
-    for (const cmd of extraCommands) {
-      const cmdName = cmd.name();
-      if (_reservedForExtra.has(cmdName)) {
-        process.stderr.write(
-          `Error: extraCommands name '${cmdName}' is reserved
-`
-        );
-        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    if (opts.annotation.length > 0) {
+      for (const annFlag of opts.annotation) {
+        modules = modules.filter((m) => getAnnotationFlag(m, annFlag));
       }
-      const existing = program.commands.find((c) => c.name() === cmdName);
-      if (existing) {
+    }
+    if (opts.sort === "calls" || opts.sort === "errors" || opts.sort === "latency") {
+      const { used } = sortModulesByUsage(modules, opts.sort, { reverse: !opts.reverse });
+      if (!used) {
         process.stderr.write(
-          `Error: extraCommands name '${cmdName}' collides with an existing command
+          `note: no usage data available for --sort ${opts.sort}; sorted by id. Run some modules first to populate ~/.apcore-cli/audit.jsonl.
 `
         );
-        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
       }
-      program.addCommand(cmd);
-    }
-  }
-  program.hook("preAction", async (thisCommand) => {
-    const opts = thisCommand.opts();
-    const commandsDir = opts.commandsDir;
-    const bindingPath = opts.binding;
-    await applyToolkitIntegration(commandsDir, bindingPath, { allowedPrefixes });
-  });
-  return program;
-}
-var _ALWAYS_REGISTERED = /* @__PURE__ */ new Set(["exec"]);
-function _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter) {
-  const emitUnwiredError = () => {
-    process.stderr.write(
-      "Error: no module registry wired. In standalone mode, pass --extensions-dir <path> to enable module discovery.\n"
-    );
-    process.exit(EXIT_CODES.CONFIG_INVALID);
-  };
-  const effectiveRegistry = registry ?? {
-    listModules: () => emitUnwiredError(),
-    getModule: () => emitUnwiredError()
-  };
-  const TABLE = [
-    { name: "list", requiresExecutor: false, register: (g) => registerListCommand(g, effectiveRegistry, exposureFilter) },
-    { name: "describe", requiresExecutor: false, register: (g) => registerDescribeCommand(g, effectiveRegistry) },
-    { name: "exec", requiresExecutor: true, register: (g, _r, ex) => registerExecCommand(g, effectiveRegistry, ex) },
-    { name: "validate", requiresExecutor: true, register: (g, _r, ex) => registerValidateCommand(g, effectiveRegistry, ex) },
-    { name: "init", requiresExecutor: false, register: (g) => registerInitCommand(g) },
-    { name: "health", requiresExecutor: true, register: (g, _r, ex) => registerHealthCommand(g, ex) },
-    { name: "usage", requiresExecutor: true, register: (g, _r, ex) => registerUsageCommand(g, ex) },
-    { name: "enable", requiresExecutor: true, register: (g, _r, ex) => registerEnableCommand(g, ex) },
-    { name: "disable", requiresExecutor: true, register: (g, _r, ex) => registerDisableCommand(g, ex) },
-    { name: "reload", requiresExecutor: true, register: (g, _r, ex) => registerReloadCommand(g, ex) },
-    { name: "config", requiresExecutor: true, register: (g, _r, ex) => registerConfigCommand(g, ex) },
-    { name: "completion", requiresExecutor: false, register: (g) => registerCompletionCommand(g) },
-    { name: "describe-pipeline", requiresExecutor: true, register: (g, _r, ex) => registerPipelineCommand(g, ex) }
-  ];
-  const mode = apcliCfg.resolveVisibility();
-  for (const entry of TABLE) {
-    let shouldRegister;
-    if (mode === "all" || mode === "none") {
-      shouldRegister = true;
     } else {
-      shouldRegister = _ALWAYS_REGISTERED.has(entry.name) || apcliCfg.isSubcommandIncluded(entry.name);
+      modules.sort((a, b) => (a.moduleId ?? "").localeCompare(b.moduleId ?? ""));
+      if (opts.reverse) {
+        modules.reverse();
+      }
     }
-    if (!shouldRegister) continue;
-    if (entry.requiresExecutor && !executor) {
-      if (_ALWAYS_REGISTERED.has(entry.name)) {
-        warn(
-          `apcli.${entry.name} is in _ALWAYS_REGISTERED but no executor is wired \u2014 subcommand unavailable. Pass executor to createCli() or avoid ${entry.name} invocations.`
-        );
+    let showExposureCol = false;
+    if (exposureFilter && opts.exposure !== "all") {
+      if (opts.exposure === "exposed") {
+        modules = modules.filter((m) => exposureFilter.isExposed(m.moduleId ?? ""));
+      } else if (opts.exposure === "hidden") {
+        modules = modules.filter((m) => !exposureFilter.isExposed(m.moduleId ?? ""));
       }
-      continue;
     }
-    entry.register(apcliGroup, registry, executor);
-  }
-}
-var bindingDisplayMap = /* @__PURE__ */ new Map();
-function lookupBindingDisplay(moduleId) {
-  return bindingDisplayMap.get(moduleId);
-}
-async function applyToolkitIntegration(commandsDir, bindingPath, options = {}) {
-  if (!commandsDir && !bindingPath) {
-    return;
-  }
-  let toolkit;
-  try {
-    const toolkitModule = "apcore-toolkit";
-    toolkit = await import(
-      /* @vite-ignore */
-      toolkitModule
-    );
-  } catch {
-    warn("apcore-toolkit not installed \u2014 toolkit features unavailable");
-    return;
-  }
-  if (commandsDir) {
-    warn("Convention scanning not available in the TypeScript toolkit");
-  }
-  if (bindingPath) {
-    try {
-      await loadBindingDisplayOverlay(toolkit, bindingPath, options.allowedPrefixes);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      warn(`apcore-toolkit: failed to load binding '${bindingPath}': ${msg}`);
+    if (opts.exposure === "all" && exposureFilter) {
+      showExposureCol = true;
     }
-  }
+    const fmt = resolveFormat(opts.format);
+    const filterTagsArg = opts.tag.length > 0 ? opts.tag : void 0;
+    void formatModuleList(modules, fmt, filterTagsArg, opts.deps, showExposureCol ? exposureFilter : void 0);
+  });
+  apcliGroup.addCommand(listCmd);
 }
-async function loadBindingDisplayOverlay(toolkit, bindingPath, allowedPrefixes) {
-  const BindingLoaderCtor = toolkit.BindingLoader;
-  const DisplayResolverCtor = toolkit.DisplayResolver;
-  if (!BindingLoaderCtor || !DisplayResolverCtor) {
-    return;
-  }
-  const loader = new BindingLoaderCtor();
-  const scanned = loader.load(bindingPath);
-  const resolver = new DisplayResolverCtor();
-  const resolved = resolver.resolve(scanned, { bindingPath });
-  const prefixes = allowedPrefixes && allowedPrefixes.length > 0 ? allowedPrefixes : null;
-  const isTargetAllowed = (target) => {
-    if (!prefixes) return true;
-    if (typeof target !== "string" || target.length === 0) return true;
-    return prefixes.some((p) => target.startsWith(p));
-  };
-  for (const mod of resolved) {
-    if (!mod || typeof mod !== "object") continue;
-    const entry = mod;
-    const id = typeof entry.moduleId === "string" ? entry.moduleId : null;
-    if (!id) continue;
-    if (!isTargetAllowed(entry.target)) {
-      warn(
-        `apcore-toolkit: dropped binding entry '${id}' \u2014 target '${String(entry.target)}' is outside allowedPrefixes`
+function registerDescribeCommand(apcliGroup, registry) {
+  const describeCmd = new Command3("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").addOption(
+    new Option2("--format <format>", "Output format.").choices(["table", "json", "csv", "yaml", "jsonl", "markdown", "skill"])
+  ).action((moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getDefinition(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(
+        `Error: Module '${moduleId}' not found.
+`
       );
-      continue;
-    }
-    const meta = entry.metadata ?? {};
-    const display = meta.display;
-    if (display && typeof display === "object" && !Array.isArray(display)) {
-      bindingDisplayMap.set(id, display);
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
     }
-  }
-}
-function main(progName) {
-  verboseHelp = hasVerboseFlag();
-  const program = createCli({
-    progName,
-    allOptions: verboseHelp,
-    version: VERSION,
-    description: `${progName ?? "apcore-cli"} \u2014 execute modules from the command line`
+    const fmt = resolveFormat(opts.format);
+    void formatModuleDetail(moduleDef, fmt);
   });
-  try {
-    program.parse(process.argv);
-  } catch (error) {
-    if (error instanceof CommanderError) {
-      process.exit(error.exitCode);
+  apcliGroup.addCommand(describeCmd);
+}
+function registerExecCommand(apcliGroup, registry, executor) {
+  const execCmd = new Command3("exec").description("Execute a module by ID with JSON input.").argument("<module-id>", "Module ID to execute").option("--format <format>", "Output format (json, table, csv, yaml, jsonl).").option("--fields <fields>", "Comma-separated dot-paths to select from the result.").option(
+    "--input <json>",
+    "JSON object passed as input to the module. Use '-' to read JSON from stdin."
+  ).option("-y, --yes", "Auto-approve if the module declares requires_approval.", false).option(
+    "--approval-timeout <seconds>",
+    "Seconds to wait for interactive approval.",
+    parseInt
+  ).option("--sandbox", "Run module in an isolated subprocess with restricted env.", false).option("--strategy <name>", "Execution strategy (standard, parallel, sequential, etc.).").option("--trace", "Enable pipeline trace output.", false).option("--dry-run", "Validate inputs without executing the module.", false).option("--stream", "Stream output as JSONL instead of buffering.", false).action(async (moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getDefinition(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(`Error: Module '${moduleId}' not found.
+`);
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
     }
-    const code = exitCodeForError(error);
-    if (error instanceof Error) {
-      process.stderr.write(`Error: ${error.message}
+    let merged = {};
+    if (opts.input === "-") {
+      merged = await collectInput("-", {}, false);
+    } else if (opts.input !== void 0) {
+      try {
+        const parsed = JSON.parse(opts.input);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+          process.stderr.write("Error: --input JSON must be an object.\n");
+          process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+        }
+        merged = parsed;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: --input is not valid JSON: ${msg}
 `);
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      }
     }
-    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) {
+    const startTime = performance.now();
     try {
-      resolvedSchema = resolveRefs(inputSchema, 32, moduleId);
+      await checkApproval(moduleDef, opts.yes, opts.approvalTimeout);
+      if (opts.dryRun) {
+        if (executor.validate) {
+          const preflight = await executor.validate(moduleId, merged);
+          formatPreflightResult(preflight, opts.format);
+        } else {
+          process.stdout.write(JSON.stringify({ valid: true }) + "\n");
+        }
+        return;
+      }
+      let result;
+      if ((opts.trace || opts.strategy) && executor.callWithTrace) {
+        const [res] = await executor.callWithTrace(moduleId, merged, { strategy: opts.strategy });
+        result = res;
+      } else {
+        const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
+        const sandbox = new Sandbox2(opts.sandbox);
+        result = await sandbox.execute(moduleId, merged, executor);
+      }
+      const durationMs = Math.round(performance.now() - startTime);
+      const fmt = resolveFormat(opts.format);
+      formatExecResult(result, fmt, opts.fields);
+      const auditLogger = getAuditLogger();
+      if (auditLogger) {
+        auditLogger.logExecution(moduleId, merged, "success", 0, durationMs);
+      }
     } catch (err) {
-      if (err instanceof MaxDepthExceededError || err instanceof CircularRefError) {
-        process.stderr.write(`Error: ${err.message}
-`);
-        process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
+      const exitCode = exitCodeForError(err);
+      const durationMs = Math.round(performance.now() - startTime);
+      try {
+        const auditLogger = getAuditLogger();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, durationMs);
+        }
+      } catch {
       }
-      if (err instanceof UnresolvableRefError) {
-        process.stderr.write(`Error: ${err.message}
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : err}
 `);
-        process.exit(EXIT_CODES.SCHEMA_VALIDATION_ERROR);
-      }
-      resolvedSchema = inputSchema;
+      process.exit(exitCode);
     }
-    schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
-  }
-  const cmd = new Command5(effectiveCmdName).description(cmdHelp);
-  const inputOpt = new Option4("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
-  const yesOpt = new Option4("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
-  const largeInputOpt = new Option4("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
-  const formatOpt = new Option4("--format <format>", "Output format: json, table, csv, yaml, jsonl.").choices(["json", "table", "csv", "yaml", "jsonl"]);
-  const fieldsOpt = new Option4("--fields <fields>", "Comma-separated dot-paths to select from the result (e.g., 'status,data.count').");
-  const sandboxOpt = new Option4("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
-  const dryRunOpt = new Option4("--dry-run", "Run preflight checks without executing the module. Shows validation results.").default(false);
-  const traceOpt = new Option4("--trace", "Show execution pipeline trace with per-step timing after the result.").default(false);
-  const streamOpt = new Option4("--stream", "Stream module output as JSONL (one JSON object per line, flushed immediately).").default(false);
-  const strategyOpt = new Option4("--strategy <name>", "Execution pipeline strategy: standard (default), internal, testing, performance.").choices(["standard", "internal", "testing", "performance", "minimal"]);
-  const approvalTimeoutOpt = new Option4("--approval-timeout <seconds>", "Override approval prompt timeout in seconds (default: 60).").argParser(parseInt);
-  const approvalTokenOpt = new Option4("--approval-token <token>", "Resume a pending approval with the given token (for async approval flows).");
-  if (!verbose) {
-    inputOpt.hideHelp();
-    yesOpt.hideHelp();
-    largeInputOpt.hideHelp();
-    formatOpt.hideHelp();
-    fieldsOpt.hideHelp();
-    dryRunOpt.hideHelp();
-    traceOpt.hideHelp();
-    streamOpt.hideHelp();
-    strategyOpt.hideHelp();
-    approvalTimeoutOpt.hideHelp();
-    approvalTokenOpt.hideHelp();
-  }
-  cmd.addOption(inputOpt);
-  cmd.addOption(yesOpt);
-  cmd.addOption(largeInputOpt);
-  cmd.addOption(formatOpt);
-  cmd.addOption(fieldsOpt);
-  cmd.addOption(sandboxOpt);
-  cmd.addOption(dryRunOpt);
-  cmd.addOption(traceOpt);
-  cmd.addOption(streamOpt);
-  cmd.addOption(strategyOpt);
-  cmd.addOption(approvalTimeoutOpt);
-  cmd.addOption(approvalTokenOpt);
-  const footerParts = [];
-  if (!verbose) {
-    footerParts.push("Use --all-options to show all options (including built-in 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.isBooleanFlag) {
-      const flagBase = opt.name.replace(/_/g, "-");
-      cmd.addOption(
-        new Option4(`--${flagBase}`, opt.description).default(
-          opt.defaultValue
-        )
-      );
-      cmd.addOption(new Option4(`--no-${flagBase}`).hideHelp());
-    } else if (opt.parseArg) {
-      cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
-    } else {
-      cmd.option(opt.flags, opt.description, opt.defaultValue);
+  });
+  apcliGroup.addCommand(execCmd);
+}
+function registerValidateCommand(cli, registry, executor) {
+  const validateCmd = new Command3("validate").description("Run preflight checks without executing a module.").argument("<module-id>", "Module ID to validate").option("--input <source>", "JSON input file or '-' for stdin.").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getDefinition(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(`Error: Module '${moduleId}' not found.
+`);
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
     }
-  }
-  cmd.action(async (options) => {
-    const stdinFlag = options.input;
-    const autoApprove = options.yes;
-    const largeInput = options.largeInput;
-    const outputFormat = options.format;
-    const outputFields = options.fields;
-    const sandboxEnabled = options.sandbox;
-    const dryRun = options.dryRun;
-    const traceFlag = options.trace;
-    const streamFlag = options.stream;
-    const strategyName = resolveStringOption(options.strategy, process.env.APCORE_CLI_STRATEGY);
-    const approvalTimeout = resolveIntOption(
-      options.approvalTimeout,
-      process.env.APCORE_CLI_APPROVAL_TIMEOUT,
-      60
-    );
-    const approvalToken = options.approvalToken;
-    const schemaKwargs = {};
-    for (const opt of schemaOptions) {
-      const commanderKey = opt.name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
-      if (commanderKey in options) {
-        schemaKwargs[opt.name] = options[commanderKey];
-      } else if (opt.name in options) {
-        schemaKwargs[opt.name] = options[opt.name];
-      }
+    const merged = opts.input ? await collectInput(opts.input, {}, false) : {};
+    if (!executor.validate) {
+      process.stderr.write("Error: Executor does not support validate.\n");
+      process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
     }
-    let merged = {};
-    const startTime = performance.now();
     try {
-      merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
-      const reconverted = reconvertEnumValues(merged, schemaOptions);
-      merged = reconverted;
-      if (dryRun) {
-        if (!executor.validate) {
-          process.stderr.write("Error: Executor does not support validate.\n");
-          process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
+      const preflight = await executor.validate(moduleId, merged);
+      formatPreflightResult(preflight, opts.format);
+      process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+    } catch (err) {
+      const exitCode = exitCodeForError(err);
+      try {
+        const auditLogger = getAuditLogger();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, 0);
         }
-        const preflight = await executor.validate(moduleId, merged);
-        formatPreflightResult(preflight, outputFormat);
-        if (traceFlag) {
-          const pureSteps = /* @__PURE__ */ new Set([
-            "context_creation",
-            "call_chain_guard",
-            "module_lookup",
-            "acl_check",
-            "input_validation"
-          ]);
-          const allSteps = [
-            "context_creation",
-            "call_chain_guard",
-            "module_lookup",
-            "acl_check",
-            "approval_gate",
-            "middleware_before",
-            "input_validation",
-            "execute",
-            "output_validation",
-            "middleware_after",
-            "return_result"
-          ];
-          process.stderr.write("\nPipeline preview (dry-run):\n");
-          for (const s of allSteps) {
-            if (pureSteps.has(s)) {
-              process.stderr.write(`  \u2713 ${s.padEnd(24)} (pure \u2014 would execute)
+      } catch {
+      }
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : err}
 `);
-            } else {
-              process.stderr.write(`  \u25CB ${s.padEnd(24)} (impure \u2014 skipped in dry-run)
+      process.exit(exitCode);
+    }
+  });
+  cli.addCommand(validateCmd);
+}
+
+// src/system-cmd.ts
+init_esm_shims();
+import { Command as Command4 } from "commander";
+import { Config } from "apcore-js";
+init_errors();
+async function callSystemModule(executor, moduleId, inputs) {
+  return executor.call(moduleId, inputs);
+}
+function emitResult(jsonPayload, fmt, ttyRender) {
+  if (fmt === "json" || !process.stdout.isTTY) {
+    process.stdout.write(JSON.stringify(jsonPayload, null, 2) + "\n");
+  } else {
+    ttyRender();
+  }
+}
+function emitErrorAndExit(e) {
+  process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
 `);
-            }
-          }
-        }
-        process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+  process.exit(exitCodeForError(e));
+}
+async function requireApprovalForSystemCommand(moduleId, autoApprove) {
+  const syntheticModuleDef = {
+    moduleId,
+    name: moduleId,
+    description: `system command: ${moduleId}`,
+    annotations: { requires_approval: true }
+  };
+  await checkApproval(syntheticModuleDef, autoApprove, void 0);
+}
+function formatHealthSummaryTty(result) {
+  const summary = result.summary ?? {};
+  const modules = result.modules ?? [];
+  if (modules.length === 0) {
+    process.stdout.write("No modules found.\n");
+    return;
+  }
+  const total = summary.total_modules ?? modules.length;
+  process.stdout.write(`Health Overview (${total} modules)
+
+`);
+  process.stdout.write(`  ${"Module".padEnd(28)} ${"Status".padEnd(12)} ${"Error Rate".padEnd(12)} Top Error
+`);
+  process.stdout.write(`  ${"-".repeat(28)} ${"-".repeat(12)} ${"-".repeat(12)} ${"-".repeat(20)}
+`);
+  for (const m of modules) {
+    const top = m.top_error;
+    const topStr = top ? `${top.code} (${top.count ?? "?"})` : "\u2014";
+    const rate = `${((m.error_rate ?? 0) * 100).toFixed(1)}%`;
+    process.stdout.write(
+      `  ${String(m.module_id).padEnd(28)} ${String(m.status).padEnd(12)} ${rate.padEnd(12)} ${topStr}
+`
+    );
+  }
+  const parts = [];
+  for (const key of ["healthy", "degraded", "error"]) {
+    const count = summary[key];
+    if (count) parts.push(`${count} ${key}`);
+  }
+  process.stdout.write(`
+Summary: ${parts.join(", ") || "no data"}
+`);
+}
+function formatHealthModuleTty(result) {
+  process.stdout.write(`Module: ${result.module_id ?? "?"}
+`);
+  process.stdout.write(`Status: ${result.status ?? "unknown"}
+`);
+  const total = result.total_calls ?? 0;
+  const errors = result.error_count ?? 0;
+  const rate = result.error_rate ?? 0;
+  const avg = result.avg_latency_ms ?? 0;
+  const p99 = result.p99_latency_ms ?? 0;
+  process.stdout.write(`Calls: ${total.toLocaleString()} total | ${errors.toLocaleString()} errors | ${(rate * 100).toFixed(1)}% error rate
+`);
+  process.stdout.write(`Latency: ${avg.toFixed(0)}ms avg | ${p99.toFixed(0)}ms p99
+`);
+  const recent = result.recent_errors ?? [];
+  if (recent.length > 0) {
+    process.stdout.write(`
+Recent Errors (top ${recent.length}):
+`);
+    for (const e of recent) {
+      const count = e.count ?? "?";
+      const last = e.last_occurred ?? "?";
+      process.stdout.write(`  ${String(e.code ?? "?").padEnd(24)} x${count}  (last: ${last})
+`);
+    }
+  }
+}
+function formatUsageSummaryTty(result) {
+  const modules = result.modules ?? [];
+  const period = result.period ?? "?";
+  if (modules.length === 0) {
+    process.stdout.write(`No usage data for period ${period}.
+`);
+    return;
+  }
+  process.stdout.write(`Usage Summary (last ${period})
+
+`);
+  process.stdout.write(`  ${"Module".padEnd(24)} ${"Calls".padStart(8)} ${"Errors".padStart(8)} ${"Avg Latency".padStart(12)} ${"Trend".padStart(10)}
+`);
+  process.stdout.write(`  ${"-".repeat(24)} ${"-".repeat(8)} ${"-".repeat(8)} ${"-".repeat(12)} ${"-".repeat(10)}
+`);
+  for (const m of modules) {
+    const avg = `${(m.avg_latency_ms ?? 0).toFixed(0)}ms`;
+    process.stdout.write(
+      `  ${String(m.module_id).padEnd(24)} ${String(m.call_count ?? 0).padStart(8)} ${String(m.error_count ?? 0).padStart(8)} ${avg.padStart(12)} ${String(m.trend ?? "").padStart(10)}
+`
+    );
+  }
+  const totalCalls = result.total_calls ?? modules.reduce((s, m) => s + (m.call_count ?? 0), 0);
+  const totalErrors = result.total_errors ?? modules.reduce((s, m) => s + (m.error_count ?? 0), 0);
+  process.stdout.write(`
+Total: ${totalCalls.toLocaleString()} calls | ${totalErrors.toLocaleString()} errors
+`);
+}
+function registerHealthCommand(apcliGroup, executor) {
+  const healthCmd = new Command4("health").description("Show module health status. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed health").option("--threshold <number>", "Error rate threshold (default: 0.01).", parseFloat, 0.01).option("--all", "Include healthy modules.", false).option("--errors <count>", "Max recent errors (module detail only).", parseInt, 10).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      if (moduleId) {
+        const result = await callSystemModule(executor, "system.health.module", {
+          module_id: moduleId,
+          error_limit: opts.errors
+        });
+        emitResult(result, fmt, () => formatHealthModuleTty(result));
+      } else {
+        const result = await callSystemModule(executor, "system.health.summary", {
+          error_rate_threshold: opts.threshold,
+          include_healthy: opts.all
+        });
+        emitResult(result, fmt, () => formatHealthSummaryTty(result));
       }
-      if (approvalToken) {
-        merged._approval_token = approvalToken;
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(healthCmd);
+}
+function registerUsageCommand(apcliGroup, executor) {
+  const usageCmd = new Command4("usage").description("Show module usage statistics. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed usage").option("--period <period>", "Time window: 1h, 24h, 7d, 30d.", "24h").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      let result;
+      if (moduleId) {
+        result = await callSystemModule(executor, "system.usage.module", {
+          module_id: moduleId,
+          period: opts.period
+        });
+      } else {
+        result = await callSystemModule(executor, "system.usage.summary", {
+          period: opts.period
+        });
       }
-      await checkApproval(moduleDef, autoApprove, approvalTimeout);
-      if (streamFlag) {
-        if (resolveFormat(outputFormat) === "table") {
-          process.stderr.write("Warning: Streaming mode always outputs JSONL; --format table is ignored.\n");
-        }
-        const annotations = moduleDef.annotations;
-        const isStreaming = annotations?.streaming === true;
-        if (!isStreaming) {
-          process.stderr.write(
-            `Warning: Module '${moduleId}' does not declare streaming support. Falling back to standard execution.
-`
-          );
-        }
-        if (isStreaming && executor.stream) {
-          let chunks = 0;
-          for await (const chunk of executor.stream(moduleId, merged)) {
-            chunks++;
-            process.stdout.write(JSON.stringify(chunk) + "\n");
-            if (process.stderr.isTTY) {
-              process.stderr.write(`\rStreaming ${moduleId}... (${chunks} chunks)`);
-            }
-          }
-          if (process.stderr.isTTY) {
-            process.stderr.write("\n");
-          }
-          const durationMs2 = Math.round(performance.now() - startTime);
-          const { getAuditLogger: getAuditLogger3 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-          const auditLogger2 = getAuditLogger3();
-          if (auditLogger2) {
-            auditLogger2.logExecution(moduleId, merged, "success", 0, durationMs2);
-          }
-          return;
+      emitResult(result, fmt, () => {
+        if (moduleId) {
+          formatExecResult(result, fmt);
+        } else {
+          formatUsageSummaryTty(result);
         }
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(usageCmd);
+}
+function registerEnableCommand(apcliGroup, executor) {
+  const enableCmd = new Command4("enable").description("Enable a disabled module at runtime.").argument("<module-id>", "Module ID to enable").requiredOption("--reason <reason>", "Reason for enabling (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      await requireApprovalForSystemCommand("system.control.toggle_feature", opts.yes);
+      const result = await callSystemModule(executor, "system.control.toggle_feature", {
+        module_id: moduleId,
+        enabled: true,
+        reason: opts.reason
+      });
+      emitResult(result, fmt, () => {
+        process.stdout.write(`Module '${moduleId}' enabled.
+  Reason: ${opts.reason}
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(enableCmd);
+}
+function registerDisableCommand(apcliGroup, executor) {
+  const disableCmd = new Command4("disable").description("Disable a module at runtime (calls are rejected until re-enabled).").argument("<module-id>", "Module ID to disable").requiredOption("--reason <reason>", "Reason for disabling (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      await requireApprovalForSystemCommand("system.control.toggle_feature", opts.yes);
+      const result = await callSystemModule(executor, "system.control.toggle_feature", {
+        module_id: moduleId,
+        enabled: false,
+        reason: opts.reason
+      });
+      emitResult(result, fmt, () => {
+        process.stdout.write(`Module '${moduleId}' disabled.
+  Reason: ${opts.reason}
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(disableCmd);
+}
+function registerReloadCommand(apcliGroup, executor) {
+  const reloadCmd = new Command4("reload").description("Hot-reload a module from disk.").argument("<module-id>", "Module ID to reload").requiredOption("--reason <reason>", "Reason for reload (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      await requireApprovalForSystemCommand("system.control.reload_module", opts.yes);
+      const result = await callSystemModule(executor, "system.control.reload_module", {
+        module_id: moduleId,
+        reason: opts.reason
+      });
+      emitResult(result, fmt, () => {
+        const prev = result.previous_version ?? "?";
+        const newVer = result.new_version ?? "?";
+        const dur = result.reload_duration_ms ?? "?";
+        process.stdout.write(`Module '${moduleId}' reloaded.
+`);
+        process.stdout.write(`  Version: ${prev} -> ${newVer}
+`);
+        process.stdout.write(`  Duration: ${dur}ms
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(reloadCmd);
+}
+function registerConfigCommand(apcliGroup, executor) {
+  const configGroup = new Command4("config").description("Read or update runtime configuration.");
+  const configGetCmd = new Command4("get").description("Read a configuration value by dot-path key.").argument("<key>", "Configuration key (dot-path)").option("--format <format>", "Output format.", "table").action(async (key, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      const value = new Config().get(key);
+      emitResult({ key, value }, fmt, () => {
+        process.stdout.write(`${key} = ${JSON.stringify(value)}
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  configGroup.addCommand(configGetCmd);
+  const configSetCmd = new Command4("set").description("Update a runtime configuration value (audit-logged; client-side approval gate applies).").argument("<key>", "Configuration key (dot-path)").argument("<value>", "New value").requiredOption("--reason <reason>", "Reason for config change (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (key, value, opts) => {
+    const fmt = resolveFormat(opts.format);
+    let parsedValue;
+    try {
+      parsedValue = JSON.parse(value);
+    } catch {
+      parsedValue = value;
+    }
+    try {
+      await requireApprovalForSystemCommand("system.control.update_config", opts.yes);
+      const result = await callSystemModule(executor, "system.control.update_config", {
+        key,
+        value: parsedValue,
+        reason: opts.reason
+      });
+      emitResult(result, fmt, () => {
+        const old = result.old_value ?? "?";
+        const newVal = result.new_value ?? "?";
+        process.stdout.write(`Config updated: ${key}
+`);
+        process.stdout.write(`  ${JSON.stringify(old)} -> ${JSON.stringify(newVal)}
+`);
+        process.stdout.write(`  Reason: ${opts.reason}
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  configGroup.addCommand(configSetCmd);
+  apcliGroup.addCommand(configGroup);
+}
+
+// src/strategy.ts
+init_esm_shims();
+import { Command as Command5, Option as Option3 } from "commander";
+function lookupStrategyInfo(executor, strategyName) {
+  if (typeof executor.describePipeline === "function") {
+    try {
+      const current = executor.describePipeline();
+      if (current && current.name === strategyName) {
+        return { info: current, isCurrent: true };
       }
-      if (traceFlag && executor.callWithTrace) {
-        const [result2, trace] = await executor.callWithTrace(
-          moduleId,
-          merged,
-          strategyName ? { strategy: strategyName } : void 0
-        );
-        const durationMs2 = Math.round(performance.now() - startTime);
-        const resolved = resolveFormat(outputFormat);
-        if (resolved === "json" || !process.stdout.isTTY) {
-          const traceData = {
-            strategy: trace.strategyName,
-            total_duration_ms: trace.totalDurationMs,
-            success: trace.success,
-            steps: trace.steps.map((s) => ({
-              name: s.name,
-              duration_ms: s.durationMs,
-              skipped: s.skipped,
-              ...s.skipped ? { skip_reason: s.skipReason ?? null } : {}
-            }))
-          };
-          let output;
-          if (typeof result2 === "object" && result2 !== null && !Array.isArray(result2)) {
-            output = { ...result2, _trace: traceData };
-          } else {
-            output = { result: result2, _trace: traceData };
-          }
-          process.stdout.write(JSON.stringify(output, null, 2) + "\n");
-        } else {
-          formatExecResult(result2, outputFormat, outputFields);
-          const stepCount = trace.steps.length;
-          process.stderr.write(
-            `
-Pipeline Trace (strategy: ${trace.strategyName}, ${stepCount} steps, ${trace.totalDurationMs.toFixed(1)}ms)
-`
-          );
-          for (const s of trace.steps) {
-            if (s.skipped) {
-              const reason = s.skipReason ?? "n/a";
-              process.stderr.write(`  \u25CB ${s.name.padEnd(24)} ${"\u2014".padStart(8)}  skipped (${reason})
+    } catch {
+    }
+  }
+  const ctor = executor.constructor;
+  if (ctor && typeof ctor.listStrategies === "function") {
+    try {
+      const all = ctor.listStrategies();
+      const info = all.find((s) => s.name === strategyName) ?? null;
+      return { info, isCurrent: false };
+    } catch {
+      return { info: null, isCurrent: false };
+    }
+  }
+  return { info: null, isCurrent: false };
+}
+var PRESET_STEPS = {
+  standard: [
+    "context_creation",
+    "call_chain_guard",
+    "module_lookup",
+    "acl_check",
+    "approval_gate",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  internal: [
+    "context_creation",
+    "call_chain_guard",
+    "module_lookup",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  testing: [
+    "context_creation",
+    "module_lookup",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  performance: [
+    "context_creation",
+    "call_chain_guard",
+    "module_lookup",
+    "acl_check",
+    "approval_gate",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "return_result"
+  ],
+  minimal: [
+    "context_creation",
+    "module_lookup",
+    "execute",
+    "return_result"
+  ]
+};
+function registerPipelineCommand(cli, executor) {
+  const pipelineCmd = new Command5("describe-pipeline").description("Show the execution pipeline steps for a strategy.").addOption(
+    new Option3("--strategy <name>", "Strategy to describe (default: standard).").choices(["standard", "internal", "testing", "performance", "minimal"]).default("standard")
+  ).option("--format <format>", "Output format.").action((opts) => {
+    const fmt = resolveFormat(opts.format);
+    const { info, isCurrent } = lookupStrategyInfo(executor, opts.strategy);
+    if (info) {
+      const strategySteps = isCurrent ? executor.currentStrategy?.steps ?? [] : [];
+      const header = `Pipeline: ${info.name} (${info.stepCount} steps)`;
+      if (fmt === "json" || !process.stdout.isTTY) {
+        const payload = {
+          strategy: info.name,
+          step_count: info.stepCount,
+          description: info.description,
+          steps: info.stepNames.map((name, i) => {
+            const stepMeta = strategySteps[i];
+            return {
+              index: i + 1,
+              name,
+              pure: stepMeta?.pure ?? false,
+              removable: stepMeta?.removable ?? true,
+              timeout_ms: stepMeta?.timeoutMs ?? null
+            };
+          })
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+      } else {
+        process.stdout.write(`${header}
+
 `);
-            } else {
-              process.stderr.write(`  \u2713 ${s.name.padEnd(24)} ${(s.durationMs.toFixed(1) + "ms").padStart(8)}
+        process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
+`);
+        process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
+`);
+        for (let i = 0; i < info.stepNames.length; i++) {
+          const stepMeta = strategySteps[i];
+          const pure = stepMeta?.pure ? "yes" : "no";
+          const removable = stepMeta?.removable !== false ? "yes" : "no";
+          const timeout = stepMeta?.timeoutMs ? `${stepMeta.timeoutMs}ms` : "\u2014";
+          process.stdout.write(`  ${String(i + 1).padEnd(4)} ${info.stepNames[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} ${timeout}
 `);
-            }
-          }
-        }
-        const { getAuditLogger: getAL2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-        const al2 = getAL2();
-        if (al2) {
-          al2.logExecution(moduleId, merged, "success", 0, durationMs2);
         }
-        return;
       }
-      let result;
-      if (strategyName && executor.callWithTrace) {
-        const [res] = await executor.callWithTrace(
-          moduleId,
-          merged,
-          { strategy: strategyName }
-        );
-        result = res;
-        if (strategyName !== "standard" && process.stderr.isTTY) {
-          process.stderr.write(`Warning: Using '${strategyName}' strategy.
+      return;
+    }
+    const steps = PRESET_STEPS[opts.strategy] ?? [];
+    const pureSteps = /* @__PURE__ */ new Set([
+      "context_creation",
+      "call_chain_guard",
+      "module_lookup",
+      "acl_check",
+      "input_validation"
+    ]);
+    const nonRemovable = /* @__PURE__ */ new Set([
+      "context_creation",
+      "module_lookup",
+      "execute",
+      "return_result"
+    ]);
+    if (fmt === "json" || !process.stdout.isTTY) {
+      const payload = {
+        strategy: opts.strategy,
+        step_count: steps.length,
+        steps: steps.map((s, i) => ({
+          index: i + 1,
+          name: s,
+          pure: pureSteps.has(s),
+          removable: !nonRemovable.has(s)
+        }))
+      };
+      process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    } else {
+      process.stdout.write(`Pipeline: ${opts.strategy} (${steps.length} steps)
+
+`);
+      process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
+`);
+      process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
+`);
+      for (let i = 0; i < steps.length; i++) {
+        const pure = pureSteps.has(steps[i]) ? "yes" : "no";
+        const removable = nonRemovable.has(steps[i]) ? "no" : "yes";
+        process.stdout.write(`  ${String(i + 1).padEnd(4)} ${steps[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} \u2014
 `);
-        }
-      } else {
-        const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
-        const sandbox = new Sandbox2(sandboxEnabled);
-        result = await sandbox.execute(moduleId, merged, executor);
       }
-      const durationMs = Math.round(performance.now() - startTime);
-      formatExecResult(result, outputFormat, outputFields);
-      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-      const auditLogger = getAuditLogger2();
-      if (auditLogger) {
-        auditLogger.logExecution(moduleId, merged, "success", 0, durationMs);
+    }
+  });
+  cli.addCommand(pipelineCmd);
+}
+
+// src/main.ts
+import { BindingLoader, DisplayResolver } from "apcore-toolkit";
+init_audit();
+
+// src/canonical-help.ts
+init_esm_shims();
+function resolveHelpText(cmd, section) {
+  const bag = cmd._helpText;
+  const v = bag?.[section];
+  if (typeof v === "function") return v({ error: false, command: cmd });
+  return v ?? "";
+}
+function uppercasePlaceholders(flags) {
+  return flags.replace(/<([a-zA-Z0-9_-]+)>/g, (_, name) => `<${name.toUpperCase()}>`).replace(/\[([a-zA-Z0-9_-]+)\]/g, (_, name) => `[${name.toUpperCase()}]`);
+}
+function optionTerm(opt) {
+  const flags = uppercasePlaceholders(opt.flags);
+  if (!opt.short && flags.startsWith("--")) return "    " + flags;
+  return flags;
+}
+function optionDescription(opt) {
+  let desc = opt.description;
+  const d = opt.defaultValue;
+  if (d !== void 0 && d !== false && d !== "" && d !== null) {
+    desc = `${desc} [default: ${String(d)}]`;
+  }
+  return desc;
+}
+function reorderHelpVersionLast(opts) {
+  const helpOpts = [];
+  const versionOpts = [];
+  const rest = [];
+  for (const o of opts) {
+    if (o.long === "--help") helpOpts.push(o);
+    else if (o.long === "--version") versionOpts.push(o);
+    else rest.push(o);
+  }
+  return [...rest, ...helpOpts, ...versionOpts];
+}
+function canonicalFormatHelp(cmd, helper) {
+  const sections = [];
+  const beforeAll = resolveHelpText(cmd, "beforeAll");
+  if (beforeAll) sections.push(beforeAll);
+  const desc = cmd.description();
+  if (desc) sections.push(desc);
+  const before = resolveHelpText(cmd, "before");
+  if (before) sections.push(before);
+  const visibleOpts = reorderHelpVersionLast(helper.visibleOptions(cmd));
+  const visibleCmds = helper.visibleCommands(cmd);
+  const args = cmd.registeredArguments ?? [];
+  let usage = `Usage: ${cmd.name()}`;
+  if (visibleOpts.length > 0) usage += " [OPTIONS]";
+  for (const a of args) {
+    const n = a.name().toUpperCase();
+    usage += a.required ? ` <${n}>` : ` [${n}]`;
+  }
+  if (visibleCmds.length > 0) usage += " [COMMAND]";
+  sections.push(usage);
+  if (visibleCmds.length > 0) {
+    const terms = visibleCmds.map((c) => c.name());
+    const w = Math.max(...terms.map((t) => t.length));
+    const lines = ["Commands:"];
+    visibleCmds.forEach((sub, i) => {
+      lines.push(`  ${terms[i].padEnd(w)}  ${sub.description()}`);
+    });
+    sections.push(lines.join("\n"));
+  }
+  if (visibleOpts.length > 0) {
+    const terms = visibleOpts.map(optionTerm);
+    const w = Math.max(...terms.map((t) => t.length));
+    const lines = ["Options:"];
+    visibleOpts.forEach((opt, i) => {
+      lines.push(`  ${terms[i].padEnd(w)}  ${optionDescription(opt)}`);
+    });
+    sections.push(lines.join("\n"));
+  }
+  const after = resolveHelpText(cmd, "after");
+  if (after) sections.push(after);
+  const afterAll = resolveHelpText(cmd, "afterAll");
+  if (afterAll) sections.push(afterAll);
+  return sections.join("\n\n") + "\n";
+}
+
+// src/validate.ts
+init_esm_shims();
+init_errors();
+var MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+var MAX_MODULE_ID_LENGTH = 192;
+function validateModuleId(moduleId) {
+  if (moduleId.length > MAX_MODULE_ID_LENGTH) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'. Maximum length is ${MAX_MODULE_ID_LENGTH} characters.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (!MODULE_ID_PATTERN.test(moduleId)) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+}
+
+// src/main.ts
+var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
+var verboseHelp = false;
+function setAllOptionsHelp(allOptions) {
+  verboseHelp = allOptions;
+}
+function setVerboseHelp(verbose) {
+  setAllOptionsHelp(verbose);
+}
+var docsUrl = null;
+function setDocsUrl(url) {
+  docsUrl = url;
+}
+function hasVerboseFlag() {
+  return process.argv.includes("--all-options");
+}
+function resolveIntOption(cliValue, envValue, defaultValue) {
+  if (cliValue !== void 0 && Number.isFinite(cliValue) && cliValue > 0) {
+    return cliValue;
+  }
+  if (envValue !== void 0 && envValue !== "") {
+    const parsed = parseInt(envValue, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+    process.stderr.write(
+      `Warning: invalid integer env value '${envValue}'; using default ${defaultValue}.
+`
+    );
+  }
+  return defaultValue;
+}
+function resolveStringOption(cliValue, envValue) {
+  if (typeof cliValue === "string" && cliValue !== "") {
+    return cliValue;
+  }
+  if (envValue !== void 0 && envValue !== "") {
+    return envValue;
+  }
+  return void 0;
+}
+var VERSION = "0.0.0";
+try {
+  const pkg = JSON.parse(readFileSync3(path5.resolve(__dirname2, "../package.json"), "utf-8"));
+  VERSION = pkg.version;
+} catch {
+}
+function validateInputSchema(schema, input) {
+  const required = schema.required;
+  if (required && Array.isArray(required)) {
+    for (const field of required) {
+      const val = input[field];
+      if (val === null || val === void 0) {
+        return `'${field}' is required`;
       }
-    } catch (err) {
-      const exitCode = exitCodeForError(err);
-      const durationMs = Math.round(performance.now() - startTime);
-      try {
-        const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-        const auditLogger = getAuditLogger2();
-        if (auditLogger) {
-          auditLogger.logExecution(moduleId, merged, "error", exitCode, durationMs);
-        }
-      } catch {
+    }
+  }
+  const properties = schema.properties;
+  if (properties) {
+    for (const [field, propSchema] of Object.entries(properties)) {
+      const val = input[field];
+      if (val === null || val === void 0) continue;
+      const expectedType = propSchema.type;
+      if (!expectedType) continue;
+      const actualType = typeof val;
+      if (expectedType === "string" && actualType !== "string") {
+        return `'${field}' must be a string, got ${actualType}`;
       }
-      if (outputFormat === "json" || !process.stderr.isTTY) {
-        emitErrorJson(err, exitCode);
-      } else {
-        emitErrorTty(err, exitCode);
+      if ((expectedType === "integer" || expectedType === "number") && actualType !== "number") {
+        return `'${field}' must be a number, got ${actualType}`;
+      }
+      if (expectedType === "boolean" && actualType !== "boolean") {
+        return `'${field}' must be a boolean, got ${actualType}`;
       }
-      process.exit(exitCode);
     }
-  });
-  return cmd;
+  }
+  return null;
 }
-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;
+function emitErrorJson(e, exitCode) {
+  const err = e instanceof Error ? e : new Error(String(e));
+  const errRecord = err;
+  const code = errRecord.code ?? "UNKNOWN";
+  const payload = {
+    error: true,
+    code,
+    message: err.message,
+    exit_code: exitCode
+  };
+  for (const field of ["details", "suggestion", "ai_guidance", "retryable", "user_fixable"]) {
+    const val = errRecord[field];
+    if (val !== void 0 && val !== null) {
+      payload[field] = val;
     }
   }
-  if (!stdinFlag) {
-    return cliKwargsNonNull;
+  process.stderr.write(JSON.stringify(payload) + "\n");
+}
+function emitErrorTty(e, exitCode) {
+  const err = e instanceof Error ? e : new Error(String(e));
+  const errRecord = err;
+  const code = errRecord.code;
+  const header = code ? `Error [${code}]: ${err.message}` : `Error: ${err.message}`;
+  process.stderr.write(header + "\n");
+  const details = errRecord.details;
+  if (details && typeof details === "object" && !Array.isArray(details)) {
+    process.stderr.write("\n  Details:\n");
+    for (const [k, v] of Object.entries(details)) {
+      process.stderr.write(`    ${k}: ${v}
+`);
+    }
   }
-  let raw;
-  let source;
-  if (stdinFlag === "-") {
-    raw = await readStdin();
-    source = "STDIN";
+  const suggestion = errRecord.suggestion;
+  if (suggestion) {
+    process.stderr.write(`
+  Suggestion: ${suggestion}
+`);
+  }
+  const retryable = errRecord.retryable;
+  if (retryable !== void 0 && retryable !== null) {
+    const label = retryable ? "Yes" : "No (same input will fail again)";
+    process.stderr.write(`  Retryable: ${label}
+`);
+  }
+  process.stderr.write(`
+  Exit code: ${exitCode}
+`);
+}
+function createCli(extensionsDirOrOpts, progName, allOptions = false) {
+  let extensionsDir;
+  let registry;
+  let executor;
+  let extraCommands;
+  let app;
+  let expose;
+  let apcliOption;
+  let appVersion;
+  let appDescription;
+  let allowedPrefixes;
+  let builtinGroupName;
+  if (typeof extensionsDirOrOpts === "object" && extensionsDirOrOpts !== null) {
+    extensionsDir = extensionsDirOrOpts.extensionsDir;
+    progName = extensionsDirOrOpts.progName ?? progName;
+    allOptions = extensionsDirOrOpts.allOptions ?? extensionsDirOrOpts.verbose ?? allOptions;
+    app = extensionsDirOrOpts.app;
+    registry = extensionsDirOrOpts.registry;
+    executor = extensionsDirOrOpts.executor;
+    extraCommands = extensionsDirOrOpts.extraCommands;
+    expose = extensionsDirOrOpts.expose;
+    apcliOption = extensionsDirOrOpts.apcli;
+    appVersion = extensionsDirOrOpts.version;
+    appDescription = extensionsDirOrOpts.description;
+    builtinGroupName = extensionsDirOrOpts.builtinGroupName;
+    allowedPrefixes = extensionsDirOrOpts.allowedPrefixes;
   } else {
-    source = `file '${stdinFlag}'`;
+    extensionsDir = extensionsDirOrOpts;
+  }
+  verboseHelp = allOptions;
+  registerConfigNamespace();
+  try {
+    const auditLogger = new AuditLogger();
+    setAuditLogger(auditLogger);
+  } catch {
+  }
+  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);
+  if (app && (registry || executor)) {
+    process.stderr.write("Error: app is mutually exclusive with registry/executor\n");
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (app) {
+    registry = app.registry;
+    executor = app.executor;
+  }
+  if (executor && !registry) {
+    process.stderr.write("Error: executor requires registry \u2014 pass both or neither\n");
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (executor && typeof executor.setApprovalHandler === "function") {
     try {
-      raw = readFileSync3(stdinFlag, "utf-8");
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`Error: Could not read input ${source}: ${msg}
-`);
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      const handler = new CliApprovalHandler(
+        /*autoApprove*/
+        false
+      );
+      executor.setApprovalHandler(handler);
+    } catch {
     }
   }
-  const rawSize = Buffer.byteLength(raw, "utf-8");
-  if (rawSize > 10485760 && !largeInput) {
-    process.stderr.write(
-      `Error: ${source} input exceeds 10MB limit. Use --large-input to override.
-`
-    );
+  const registryInjected = registry !== void 0;
+  const program = new Command6(resolvedProgName).exitOverride().helpOption("-h, --help", "Print help").addHelpCommand("help [command]", "Print this message or the help of the given subcommand(s)").description(appDescription ?? `${resolvedProgName} CLI`).option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--all-options", "Show all options in help output (including built-in options)");
+  if (appVersion) {
+    program.version(appVersion, "-V, --version", "Print version");
+  }
+  program.configureHelp({ formatHelp: canonicalFormatHelp });
+  if (!registryInjected) {
+    program.option("--extensions-dir <path>", "Path to extensions directory");
+    program.option("--commands-dir <path>", "Path to convention-based commands directory");
+    program.option("--binding <path>", "Path to binding.yaml for display overlay");
+  }
+  let apcliCfg;
+  try {
+    if (apcliOption instanceof ApcliGroup) {
+      if (builtinGroupName !== void 0 && builtinGroupName !== "apcli" && apcliOption.name !== builtinGroupName) {
+        throw new Error(
+          `builtinGroupName=${JSON.stringify(builtinGroupName)} conflicts with the name on the supplied ApcliGroup (${JSON.stringify(apcliOption.name)}). Pass only one.`
+        );
+      }
+      apcliCfg = apcliOption;
+    } else if (apcliOption !== void 0) {
+      apcliCfg = ApcliGroup.fromCliConfig(apcliOption, {
+        registryInjected,
+        name: builtinGroupName
+      });
+    } else {
+      let yamlVal = null;
+      try {
+        const resolver = new ConfigResolver();
+        yamlVal = resolver.resolveObject("apcli");
+      } catch {
+        yamlVal = null;
+      }
+      apcliCfg = ApcliGroup.fromYaml(yamlVal, {
+        registryInjected,
+        name: builtinGroupName
+      });
+    }
+  } catch (e) {
+    process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}
+`);
     process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
-  if (!raw) {
-    return cliKwargsNonNull;
+  setReservedGroupNames(/* @__PURE__ */ new Set([apcliCfg.name]));
+  const apcliGroup = program.command(apcliCfg.name, { hidden: !apcliCfg.isGroupVisible() }).description("Built-in commands");
+  if (registry) {
+    program._registry = registry;
+    if (executor) {
+      program._executor = executor;
+    }
+  } else {
+    const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
+    void resolvedExtDir;
   }
-  let parsed;
+  let exposureFilter;
   try {
-    parsed = JSON.parse(raw);
-  } catch {
-    process.stderr.write(`Error: ${source} does not contain valid JSON.
+    if (expose instanceof ExposureFilter) {
+      exposureFilter = expose;
+    } else if (typeof expose === "object" && expose !== null) {
+      exposureFilter = ExposureFilter.fromConfig({ expose });
+    } else {
+      exposureFilter = new ExposureFilter();
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Error: invalid 'expose' option \u2014 ${msg}
 `);
     process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    process.stderr.write(
-      `Error: ${source} JSON must be an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}.
+  _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter);
+  program.addHelpText("after", [
+    "",
+    "Use --help --all-options to show all options (including built-in options).",
+    "Use --help --man to display a formatted man page."
+  ].join("\n"));
+  configureManHelp(program, resolvedProgName, appVersion ?? VERSION);
+  if (extraCommands && extraCommands.length > 0) {
+    const _reservedForExtra = /* @__PURE__ */ new Set([apcliCfg.name]);
+    for (const cmd of extraCommands) {
+      const cmdName = cmd.name();
+      if (_reservedForExtra.has(cmdName)) {
+        process.stderr.write(
+          `Error: extraCommands name '${cmdName}' is reserved
 `
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+        );
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      }
+      const existing = program.commands.find((c) => c.name() === cmdName);
+      if (existing) {
+        process.stderr.write(
+          `Error: extraCommands name '${cmdName}' collides with an existing command
+`
+        );
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      }
+      program.addCommand(cmd);
+    }
   }
-  return { ...parsed, ...cliKwargsNonNull };
-}
-function readStdin() {
-  return new Promise((resolve2, reject) => {
-    const chunks = [];
-    const onData = (chunk) => chunks.push(chunk);
-    const onEnd = () => {
-      cleanup();
-      resolve2(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();
+  program.hook("preAction", async (thisCommand) => {
+    const opts = thisCommand.opts();
+    const commandsDir = opts.commandsDir;
+    const bindingPath = opts.binding;
+    await applyToolkitIntegration(commandsDir, bindingPath, { allowedPrefixes });
   });
+  return program;
 }
-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;
+var _ALWAYS_REGISTERED = /* @__PURE__ */ new Set(["exec"]);
+function _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter) {
+  const emitUnwiredError = () => {
+    process.stderr.write(
+      "Error: no module registry wired. In standalone mode, pass --extensions-dir <path> to enable module discovery.\n"
+    );
+    process.exit(EXIT_CODES.CONFIG_INVALID);
+  };
+  const effectiveRegistry = registry ?? {
+    list: () => emitUnwiredError(),
+    getDefinition: () => emitUnwiredError()
+  };
+  const TABLE = [
+    { name: "list", requiresExecutor: false, register: (g) => registerListCommand(g, effectiveRegistry, exposureFilter) },
+    { name: "describe", requiresExecutor: false, register: (g) => registerDescribeCommand(g, effectiveRegistry) },
+    { name: "exec", requiresExecutor: true, register: (g, _r, ex) => registerExecCommand(g, effectiveRegistry, ex) },
+    { name: "validate", requiresExecutor: true, register: (g, _r, ex) => registerValidateCommand(g, effectiveRegistry, ex) },
+    { name: "init", requiresExecutor: false, register: (g) => registerInitCommand(g) },
+    { name: "health", requiresExecutor: true, register: (g, _r, ex) => registerHealthCommand(g, ex) },
+    { name: "usage", requiresExecutor: true, register: (g, _r, ex) => registerUsageCommand(g, ex) },
+    { name: "enable", requiresExecutor: true, register: (g, _r, ex) => registerEnableCommand(g, ex) },
+    { name: "disable", requiresExecutor: true, register: (g, _r, ex) => registerDisableCommand(g, ex) },
+    { name: "reload", requiresExecutor: true, register: (g, _r, ex) => registerReloadCommand(g, ex) },
+    { name: "config", requiresExecutor: true, register: (g, _r, ex) => registerConfigCommand(g, ex) },
+    { name: "completion", requiresExecutor: false, register: (g) => registerCompletionCommand(g) },
+    { name: "describe-pipeline", requiresExecutor: true, register: (g, _r, ex) => registerPipelineCommand(g, ex) }
+  ];
+  const _SYSTEM_COMMANDS = /* @__PURE__ */ new Set(["health", "usage", "enable", "disable", "reload", "config"]);
+  const systemModulesAvailable = (() => {
+    if (!executor) return false;
+    const reg = executor.registry ?? registry;
+    if (!reg) return false;
+    try {
+      return reg.getDefinition("system.health.summary") != null;
+    } catch {
+      return false;
     }
-    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";
+  })();
+  const mode = apcliCfg.resolveVisibility();
+  for (const entry of TABLE) {
+    let shouldRegister;
+    if (mode === "all" || mode === "none") {
+      shouldRegister = true;
+    } else {
+      shouldRegister = _ALWAYS_REGISTERED.has(entry.name) || apcliCfg.isSubcommandIncluded(entry.name);
+    }
+    if (!shouldRegister) continue;
+    if (_SYSTEM_COMMANDS.has(entry.name) && !systemModulesAvailable) continue;
+    if (entry.requiresExecutor && !executor) {
+      if (_ALWAYS_REGISTERED.has(entry.name)) {
+        warn(
+          `apcli.${entry.name} is in _ALWAYS_REGISTERED but no executor is wired \u2014 subcommand unavailable. Pass executor to createCli() or avoid ${entry.name} invocations.`
+        );
+      }
+      continue;
     }
+    entry.register(apcliGroup, registry, executor);
   }
-  return result;
 }
-
-// src/cli.ts
-init_esm_shims();
-import { Command as Command6 } from "commander";
-init_logger();
-init_errors();
-function assertNotReserved(kind, name, moduleId) {
-  if (!getReservedGroupNames().has(name)) return;
-  let msg;
-  if (kind === "group") {
-    msg = `Error: Module '${moduleId}': display.cli.group '${name}' is reserved. Use a different CLI alias or set display.cli.group to another value.
-`;
-  } else if (kind === "auto-group") {
-    msg = `Error: Module '${moduleId}': auto-group '${name}' is reserved. Rename the module id or set display.cli.group to another value.
-`;
-  } else {
-    msg = `Error: Module '${moduleId}': top-level CLI name '${name}' is reserved. Use a different CLI alias.
-`;
-  }
-  process.stderr.write(msg);
-  process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+var bindingDisplayMap = /* @__PURE__ */ new Map();
+function lookupBindingDisplay(moduleId) {
+  return bindingDisplayMap.get(moduleId);
 }
-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;
-  }
-  /**
-   * 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");
-    }
+async function applyToolkitIntegration(commandsDir, bindingPath, options = {}) {
+  if (!commandsDir && !bindingPath) {
+    return;
   }
-  /**
-   * 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();
+  if (commandsDir) {
+    warn("Convention scanning not available in the TypeScript toolkit");
   }
-  /**
-   * 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;
+  if (bindingPath) {
+    try {
+      await loadBindingDisplayOverlay(bindingPath, options.allowedPrefixes);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warn(`apcore-toolkit: failed to load binding '${bindingPath}': ${msg}`);
     }
-    const cmd = buildModuleCommand(moduleDef, this.executor, this.helpTextMaxLength, cmdName);
-    this.commandCache.set(cmdName, cmd);
-    return cmd;
   }
-};
-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 Command6(name).description(`${name} commands`);
-    for (const [cmdName, [, descriptor]] of this.members) {
-      const cmd = buildModuleCommand(
-        descriptor,
-        this._executor,
-        this._helpTextMaxLength,
-        cmdName
+}
+async function loadBindingDisplayOverlay(bindingPath, allowedPrefixes) {
+  const loader = new BindingLoader();
+  const scanned = loader.load(bindingPath);
+  const resolver = new DisplayResolver();
+  const resolved = resolver.resolve(scanned, { bindingPath });
+  const prefixes = allowedPrefixes && allowedPrefixes.length > 0 ? allowedPrefixes : null;
+  const isTargetAllowed = (target) => {
+    if (!prefixes) return true;
+    if (typeof target !== "string" || target.length === 0) return true;
+    return prefixes.some((p) => target.startsWith(p));
+  };
+  for (const mod of resolved) {
+    if (!mod || typeof mod !== "object") continue;
+    const entry = mod;
+    const id = typeof entry.moduleId === "string" ? entry.moduleId : null;
+    if (!id) continue;
+    if (!isTargetAllowed(entry.target)) {
+      warn(
+        `apcore-toolkit: dropped binding entry '${id}' \u2014 target '${String(entry.target)}' is outside allowedPrefixes`
       );
-      this._cmdCache.set(cmdName, cmd);
-      this.command.addCommand(cmd);
-    }
-  }
-  listCommands() {
-    return [...this.members.keys()].sort();
-  }
-  getCommand(cmdName) {
-    if (this._cmdCache.has(cmdName)) {
-      return this._cmdCache.get(cmdName);
+      continue;
     }
-    const entry = this.members.get(cmdName);
-    if (!entry) {
-      return null;
+    const meta = entry.metadata ?? {};
+    const display = meta.display;
+    if (display && typeof display === "object" && !Array.isArray(display)) {
+      bindingDisplayMap.set(id, display);
     }
-    const [, descriptor] = entry;
-    const cmd = buildModuleCommand(
-      descriptor,
-      this._executor,
-      this._helpTextMaxLength,
-      cmdName
-    );
-    this._cmdCache.set(cmdName, cmd);
-    return cmd;
-  }
-};
-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;
-  /** Exposure filter (FE-12) — controls which modules appear as CLI commands */
-  exposureFilter;
-  /** Effective group depth (CLAUDE.md v0.6.0): constructor arg > APCORE_CLI_GROUP_DEPTH env > 1. */
-  groupDepth;
-  constructor(registry, executor, helpTextMaxLength = 1e3, exposureFilter, groupDepth) {
-    super(registry, executor, helpTextMaxLength);
-    this.exposureFilter = exposureFilter ?? new ExposureFilter();
-    this.groupDepth = _GroupedModuleGroup.resolveGroupDepth(groupDepth);
   }
-  /**
-   * Resolve group depth from constructor arg > APCORE_CLI_GROUP_DEPTH env > default 1.
-   * Invalid env values (non-integer, non-positive) fall through to the default.
-   */
-  static resolveGroupDepth(explicit) {
-    if (explicit !== void 0 && Number.isFinite(explicit) && explicit > 0) {
-      return Math.floor(explicit);
+}
+function main(progName) {
+  verboseHelp = hasVerboseFlag();
+  const program = createCli({
+    progName,
+    allOptions: verboseHelp,
+    version: VERSION,
+    description: `${progName ?? "apcore-cli"} \u2014 execute modules from the command line`
+  });
+  try {
+    program.parse(process.argv);
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      process.exit(error.exitCode);
     }
-    const raw = process.env.APCORE_CLI_GROUP_DEPTH;
-    if (raw !== void 0 && raw !== "") {
-      const parsed = parseInt(raw, 10);
-      if (Number.isFinite(parsed) && parsed > 0) {
-        return parsed;
-      }
+    const code = exitCodeForError(error);
+    if (error instanceof Error) {
+      process.stderr.write(`Error: ${error.message}
+`);
     }
-    return 1;
+    process.exit(code);
   }
-  /**
-   * Determine (groupName | null, commandName) for a module from its display overlay.
-   *
-   * @param groupDepth  Number of dotted segments to consume as the group prefix.
-   *                    Defaults to 1 (e.g., "math.add" → group="math", cmd="add").
-   *                    Set to 2 for multi-level grouping (e.g., "math.trig.sin" →
-   *                    group="math.trig", cmd="sin").
-   */
-  static resolveGroup(moduleId, descriptor, groupDepth = 1) {
-    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];
+}
+function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName, verbose = verboseHelp) {
+  const moduleId = moduleDef.moduleId;
+  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 (err) {
+      if (err instanceof MaxDepthExceededError || err instanceof CircularRefError) {
+        process.stderr.write(`Error: ${err.message}
+`);
+        process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
+      }
+      if (err instanceof UnresolvableRefError) {
+        process.stderr.write(`Error: ${err.message}
+`);
+        process.exit(EXIT_CODES.SCHEMA_VALIDATION_ERROR);
+      }
+      resolvedSchema = inputSchema;
     }
-    const cliName = cliDisplay.alias ?? moduleId;
-    if (cliName.includes(".")) {
-      const parts = cliName.split(".");
-      const depth = Math.max(1, Math.min(groupDepth, parts.length - 1));
-      const group = parts.slice(0, depth).join(".");
-      const cmd = parts.slice(depth).join(".");
-      return [group, cmd];
+    schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
+  }
+  const cmd = new Command6(effectiveCmdName).description(cmdHelp);
+  const inputOpt = new Option4("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
+  const yesOpt = new Option4("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
+  const largeInputOpt = new Option4("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
+  const formatOpt = new Option4("--format <format>", "Output format: json, table, csv, yaml, jsonl.").choices(["json", "table", "csv", "yaml", "jsonl"]);
+  const fieldsOpt = new Option4("--fields <fields>", "Comma-separated dot-paths to select from the result (e.g., 'status,data.count').");
+  const sandboxOpt = new Option4("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
+  const dryRunOpt = new Option4("--dry-run", "Run preflight checks without executing the module. Shows validation results.").default(false);
+  const traceOpt = new Option4("--trace", "Show execution pipeline trace with per-step timing after the result.").default(false);
+  const streamOpt = new Option4("--stream", "Stream module output as JSONL (one JSON object per line, flushed immediately).").default(false);
+  const strategyOpt = new Option4("--strategy <name>", "Execution pipeline strategy: standard (default), internal, testing, performance.").choices(["standard", "internal", "testing", "performance", "minimal"]);
+  const approvalTimeoutOpt = new Option4("--approval-timeout <seconds>", "Override approval prompt timeout in seconds (default: 60).").argParser(parseInt);
+  const approvalTokenOpt = new Option4("--approval-token <token>", "Resume a pending approval with the given token (for async approval flows).");
+  if (!verbose) {
+    inputOpt.hideHelp();
+    yesOpt.hideHelp();
+    largeInputOpt.hideHelp();
+    formatOpt.hideHelp();
+    fieldsOpt.hideHelp();
+    dryRunOpt.hideHelp();
+    traceOpt.hideHelp();
+    streamOpt.hideHelp();
+    strategyOpt.hideHelp();
+    approvalTimeoutOpt.hideHelp();
+    approvalTokenOpt.hideHelp();
+  }
+  cmd.addOption(inputOpt);
+  cmd.addOption(yesOpt);
+  cmd.addOption(largeInputOpt);
+  cmd.addOption(formatOpt);
+  cmd.addOption(fieldsOpt);
+  cmd.addOption(sandboxOpt);
+  cmd.addOption(dryRunOpt);
+  cmd.addOption(traceOpt);
+  cmd.addOption(streamOpt);
+  cmd.addOption(strategyOpt);
+  cmd.addOption(approvalTimeoutOpt);
+  cmd.addOption(approvalTokenOpt);
+  const footerParts = [];
+  if (!verbose) {
+    footerParts.push("Use --all-options to show all options (including built-in 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.isBooleanFlag) {
+      const flagBase = opt.name.replace(/_/g, "-");
+      cmd.addOption(
+        new Option4(`--${flagBase}`, opt.description).default(
+          opt.defaultValue
+        )
+      );
+      cmd.addOption(new Option4(`--no-${flagBase}`).hideHelp());
+    } else if (opt.parseArg) {
+      cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
+    } else {
+      cmd.option(opt.flags, opt.description, opt.defaultValue);
     }
-    return [null, cliName];
   }
-  /**
-   * Build the group map from registry modules.
-   *
-   * FE-13: hard-fails with exit 2 when a module resolves to the reserved
-   * `apcli` namespace in any of three ways — explicit `display.cli.group`,
-   * auto-grouped dotted prefix, or top-level alias/id. See spec §4.10.
-   */
-  buildGroupMap() {
-    if (this.groupMapBuilt) {
-      return;
+  cmd.action(async (options) => {
+    const stdinFlag = options.input;
+    const autoApprove = options.yes;
+    const largeInput = options.largeInput;
+    const outputFormat = options.format;
+    const outputFields = options.fields;
+    const sandboxEnabled = options.sandbox;
+    const dryRun = options.dryRun;
+    const traceFlag = options.trace;
+    const streamFlag = options.stream;
+    const strategyName = resolveStringOption(options.strategy, process.env.APCORE_CLI_STRATEGY);
+    const approvalTimeout = resolveIntOption(
+      options.approvalTimeout,
+      process.env.APCORE_CLI_APPROVAL_TIMEOUT,
+      60
+    );
+    const approvalToken = options.approvalToken;
+    const schemaKwargs = {};
+    for (const opt of schemaOptions) {
+      const commanderKey = opt.name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+      if (commanderKey in options) {
+        schemaKwargs[opt.name] = options[commanderKey];
+      } else if (opt.name in options) {
+        schemaKwargs[opt.name] = options[opt.name];
+      }
     }
-    this.buildAliasMap();
-    for (const descriptor of this.registry.listModules()) {
-      const moduleId = descriptor.id;
-      const cached = this.descriptorCache.get(moduleId);
-      if (!cached) {
-        continue;
+    let merged = {};
+    const startTime = performance.now();
+    try {
+      merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
+      const reconverted = reconvertEnumValues(merged, schemaOptions);
+      merged = reconverted;
+      if (dryRun) {
+        if (!executor.validate) {
+          process.stderr.write("Error: Executor does not support validate.\n");
+          process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
+        }
+        const preflight = await executor.validate(moduleId, merged);
+        formatPreflightResult(preflight, outputFormat);
+        if (traceFlag) {
+          const pureSteps = /* @__PURE__ */ new Set([
+            "context_creation",
+            "call_chain_guard",
+            "module_lookup",
+            "acl_check",
+            "input_validation"
+          ]);
+          const allSteps = [
+            "context_creation",
+            "call_chain_guard",
+            "module_lookup",
+            "acl_check",
+            "approval_gate",
+            "middleware_before",
+            "input_validation",
+            "execute",
+            "output_validation",
+            "middleware_after",
+            "return_result"
+          ];
+          process.stderr.write("\nPipeline preview (dry-run):\n");
+          for (const s of allSteps) {
+            if (pureSteps.has(s)) {
+              process.stderr.write(`  \u2713 ${s.padEnd(24)} (pure \u2014 would execute)
+`);
+            } else {
+              process.stderr.write(`  \u25CB ${s.padEnd(24)} (impure \u2014 skipped in dry-run)
+`);
+            }
+          }
+        }
+        process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
       }
-      if (!this.exposureFilter.isExposed(moduleId)) {
-        continue;
+      if (resolvedSchema.properties) {
+        const validationErr = validateInputSchema(resolvedSchema, merged);
+        if (validationErr) {
+          throw new SchemaValidationError(`Validation failed: ${validationErr}`);
+        }
       }
-      const display = getDisplay(cached);
-      const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
-      const explicitGroup = typeof cliDisplay.group === "string" && cliDisplay.group !== "" ? cliDisplay.group : void 0;
-      if (explicitGroup !== void 0) {
-        assertNotReserved("group", explicitGroup, moduleId);
+      if (approvalToken) {
+        merged._approval_token = approvalToken;
+      }
+      await checkApproval(moduleDef, autoApprove, approvalTimeout);
+      if (streamFlag) {
+        if (resolveFormat(outputFormat) === "table") {
+          process.stderr.write("Warning: Streaming mode always outputs JSONL; --format table is ignored.\n");
+        }
+        const annotations = moduleDef.annotations;
+        const isStreaming = annotations?.streaming === true;
+        if (!isStreaming) {
+          process.stderr.write(
+            `Warning: Module '${moduleId}' does not declare streaming support. Falling back to standard execution.
+`
+          );
+        }
+        if (isStreaming && executor.stream) {
+          let chunks = 0;
+          for await (const chunk of executor.stream(moduleId, merged)) {
+            chunks++;
+            process.stdout.write(JSON.stringify(chunk) + "\n");
+            if (process.stderr.isTTY) {
+              process.stderr.write(`\rStreaming ${moduleId}... (${chunks} chunks)`);
+            }
+          }
+          if (process.stderr.isTTY) {
+            process.stderr.write("\n");
+          }
+          const durationMs2 = Math.round(performance.now() - startTime);
+          const { getAuditLogger: getAuditLogger3 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+          const auditLogger2 = getAuditLogger3();
+          if (auditLogger2) {
+            auditLogger2.logExecution(moduleId, merged, "success", 0, durationMs2);
+          }
+          return;
+        }
       }
-      const [group, cmd] = _GroupedModuleGroup.resolveGroup(moduleId, cached, this.groupDepth);
-      if (group !== null && explicitGroup === void 0) {
-        assertNotReserved("auto-group", group, moduleId);
+      if (traceFlag && executor.callWithTrace) {
+        const [result2, trace] = await executor.callWithTrace(
+          moduleId,
+          merged,
+          strategyName ? { strategy: strategyName } : void 0
+        );
+        const durationMs2 = Math.round(performance.now() - startTime);
+        const resolved = resolveFormat(outputFormat);
+        if (resolved === "json" || !process.stdout.isTTY) {
+          const traceData = {
+            strategy: trace.strategyName,
+            total_duration_ms: trace.totalDurationMs,
+            success: trace.success,
+            steps: trace.steps.map((s) => ({
+              name: s.name,
+              duration_ms: s.durationMs,
+              skipped: s.skipped,
+              ...s.skipped ? { skip_reason: s.skipReason ?? null } : {}
+            }))
+          };
+          let output;
+          if (typeof result2 === "object" && result2 !== null && !Array.isArray(result2)) {
+            output = { ...result2, _trace: traceData };
+          } else {
+            output = { result: result2, _trace: traceData };
+          }
+          process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+        } else {
+          formatExecResult(result2, outputFormat, outputFields);
+          const stepCount = trace.steps.length;
+          process.stderr.write(
+            `
+Pipeline Trace (strategy: ${trace.strategyName}, ${stepCount} steps, ${trace.totalDurationMs.toFixed(1)}ms)
+`
+          );
+          for (const s of trace.steps) {
+            if (s.skipped) {
+              const reason = s.skipReason ?? "n/a";
+              process.stderr.write(`  \u25CB ${s.name.padEnd(24)} ${"\u2014".padStart(8)}  skipped (${reason})
+`);
+            } else {
+              process.stderr.write(`  \u2713 ${s.name.padEnd(24)} ${(s.durationMs.toFixed(1) + "ms").padStart(8)}
+`);
+            }
+          }
+        }
+        const { getAuditLogger: getAL2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+        const al2 = getAL2();
+        if (al2) {
+          al2.logExecution(moduleId, merged, "success", 0, durationMs2);
+        }
+        return;
       }
-      if (group === null) {
-        assertNotReserved("top-level", cmd, moduleId);
-        this.topLevelModules.set(cmd, [moduleId, cached]);
-      } else if (!/^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)*$/.test(group)) {
-        warn(
-          `Module '${moduleId}': group name '${group}' is not shell-safe \u2014 treating as top-level.`
+      let result;
+      if (strategyName && executor.callWithTrace) {
+        const [res] = await executor.callWithTrace(
+          moduleId,
+          merged,
+          { strategy: strategyName }
         );
-        this.topLevelModules.set(cmd, [moduleId, cached]);
+        result = res;
+        if (strategyName !== "standard" && process.stderr.isTTY) {
+          process.stderr.write(`Warning: Using '${strategyName}' strategy.
+`);
+        }
       } else {
-        if (!this.groupMap.has(group)) {
-          this.groupMap.set(group, /* @__PURE__ */ new Map());
+        const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
+        const sandbox = new Sandbox2(sandboxEnabled);
+        result = await sandbox.execute(moduleId, merged, executor);
+      }
+      const durationMs = Math.round(performance.now() - startTime);
+      formatExecResult(result, outputFormat, outputFields);
+      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+      const auditLogger = getAuditLogger2();
+      if (auditLogger) {
+        auditLogger.logExecution(moduleId, merged, "success", 0, durationMs);
+      }
+    } catch (err) {
+      const exitCode = exitCodeForError(err);
+      const durationMs = Math.round(performance.now() - startTime);
+      try {
+        const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+        const auditLogger = getAuditLogger2();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, durationMs);
         }
-        this.groupMap.get(group).set(cmd, [moduleId, cached]);
+      } catch {
+      }
+      if (outputFormat === "json" || !process.stderr.isTTY) {
+        emitErrorJson(err, exitCode);
+      } else {
+        emitErrorTty(err, exitCode);
       }
+      process.exit(exitCode);
+    }
+  });
+  return cmd;
+}
+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;
     }
-    this.groupMapBuilt = true;
   }
-  /**
-   * List all available command names: group names + top-level module names.
-   *
-   * FE-13: the built-in subcommand list is no longer folded in here — those
-   * commands live under the `apcli` prefix and are registered directly by
-   * `createCli`.
-   */
-  listCommands() {
-    this.buildGroupMap();
-    const reserved = getReservedGroupNames();
-    const groupNames = [...this.groupMap.keys()].filter(
-      (g) => !reserved.has(g)
-    );
-    const topNames = [...this.topLevelModules.keys()];
-    return [.../* @__PURE__ */ new Set([...groupNames, ...topNames])].sort();
+  if (!stdinFlag) {
+    return cliKwargsNonNull;
   }
-  /**
-   * 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;
+  let raw;
+  let source;
+  if (stdinFlag === "-") {
+    raw = await readStdin();
+    source = "STDIN";
+  } else {
+    source = `file '${stdinFlag}'`;
+    try {
+      raw = readFileSync3(stdinFlag, "utf-8");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Error: Could not read input ${source}: ${msg}
+`);
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
-    return null;
   }
-  /** Expose groupMap for testing. */
-  getGroupMap() {
-    return this.groupMap;
+  const rawSize = Buffer.byteLength(raw, "utf-8");
+  if (rawSize > 10485760 && !largeInput) {
+    process.stderr.write(
+      `Error: ${source} input exceeds 10MB limit. Use --large-input to override.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
-  /** Expose topLevelModules for testing. */
-  getTopLevelModules() {
-    return this.topLevelModules;
+  if (!raw) {
+    return cliKwargsNonNull;
   }
-  /** Expose groupMapBuilt for testing. */
-  isGroupMapBuilt() {
-    return this.groupMapBuilt;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    process.stderr.write(`Error: ${source} does not contain valid JSON.
+`);
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
-};
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    process.stderr.write(
+      `Error: ${source} JSON must be an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  return { ...parsed, ...cliKwargsNonNull };
+}
+function readStdin() {
+  return new Promise((resolve2, reject) => {
+    const chunks = [];
+    const onData = (chunk) => chunks.push(chunk);
+    const onEnd = () => {
+      cleanup();
+      resolve2(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 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;
+}
 
 // src/index.ts
 init_errors();