apcore-cli 0.7.0 → 0.8.1

package/dist/index.js

@@ -220,8 +220,8 @@ var init_audit = __esm({
       );
       logPath;
       writeFailureWarned = false;
-      constructor(path5) {
-        this.logPath = path5 ?? _AuditLogger.DEFAULT_PATH;
+      constructor(path6) {
+        this.logPath = path6 ?? _AuditLogger.DEFAULT_PATH;
         this.ensureDirectory();
       }
       ensureDirectory() {
@@ -267,7 +267,7 @@ var init_audit = __esm({
         try {
           return os.userInfo().username;
         } catch {
-          return process.env.USER ?? process.env.USERNAME ?? "unknown";
+          return process.env.USER ?? process.env.LOGNAME ?? process.env.USERNAME ?? "unknown";
         }
       }
     };
@@ -276,7 +276,7 @@ var init_audit = __esm({
 
 // src/security/config-encryptor.ts
 import * as crypto2 from "crypto";
-import * as os2 from "os";
+import * as os3 from "os";
 async function getKeytar() {
   if (keytarModule) return keytarModule;
   try {
@@ -405,7 +405,7 @@ var init_config_encryptor = __esm({
           );
           _ConfigEncryptor.weakFallbackWarned = true;
         }
-        const hostname2 = os2.hostname();
+        const hostname2 = os3.hostname();
         const username = process.env.USER ?? process.env.USERNAME ?? "unknown";
         const material = `${hostname2}:${username}`;
         return crypto2.pbkdf2Sync(material, salt, PBKDF2_ITERATIONS, 32, "sha256");
@@ -437,7 +437,7 @@ var init_config_encryptor = __esm({
         const nonce = data.subarray(0, 12);
         const tag = data.subarray(12, 28);
         const ct = data.subarray(28);
-        const hostname2 = os2.hostname();
+        const hostname2 = os3.hostname();
         const username = process.env.USER ?? process.env.USERNAME ?? "unknown";
         const passphrase = process.env.APCORE_CLI_CONFIG_PASSPHRASE;
         const materials = passphrase ? [passphrase, `${hostname2}:${username}`] : [`${hostname2}:${username}`];
@@ -543,6 +543,10 @@ var init_auth = __esm({
 });
 
 // src/security/sandbox.ts
+import { spawn } from "child_process";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join as join4, resolve as resolvePath } from "path";
 function buildSandboxEnv(tmpDir) {
   const env = {};
   for (const key of SANDBOX_ALLOW_KEYS) {
@@ -557,7 +561,7 @@ function buildSandboxEnv(tmpDir) {
   env.TMPDIR = tmpDir;
   return env;
 }
-var SANDBOX_ALLOW_KEYS, SANDBOX_ALLOW_PREFIX, SANDBOX_DENY_PREFIX, SANDBOX_DENY_KEYS, SANDBOX_OUTPUT_SIZE_LIMIT, Sandbox;
+var SANDBOX_ALLOW_KEYS, SANDBOX_ALLOW_PREFIX, SANDBOX_DENY_PREFIX, SANDBOX_DENY_KEYS, SANDBOX_DEFAULT_OUTPUT_SIZE_LIMIT, Sandbox;
 var init_sandbox = __esm({
   "src/security/sandbox.ts"() {
     "use strict";
@@ -567,14 +571,41 @@ var init_sandbox = __esm({
     SANDBOX_ALLOW_PREFIX = "APCORE_";
     SANDBOX_DENY_PREFIX = "APCORE_AUTH_";
     SANDBOX_DENY_KEYS = ["APCORE_AUTH_API_KEY"];
-    SANDBOX_OUTPUT_SIZE_LIMIT = 64 * 1024 * 1024;
+    SANDBOX_DEFAULT_OUTPUT_SIZE_LIMIT = 64 * 1024 * 1024;
     Sandbox = class {
+      /** Default post-capture stdout+stderr byte budget for sandboxed children. */
+      static DEFAULT_MAX_OUTPUT_BYTES = SANDBOX_DEFAULT_OUTPUT_SIZE_LIMIT;
       enabled;
       timeoutSeconds;
+      extensionsRoot = null;
+      maxOutputBytes = SANDBOX_DEFAULT_OUTPUT_SIZE_LIMIT;
       constructor(enabled = false, timeoutSeconds = 300) {
         this.enabled = enabled;
         this.timeoutSeconds = timeoutSeconds;
       }
+      /**
+       * Set the extensions root that is forwarded to the sandboxed runner via
+       * `APCORE_EXTENSIONS_ROOT`. The path is resolved to absolute when injected
+       * so the child (whose cwd is the fresh sandbox tempdir) can locate modules.
+       *
+       * Builder-style — returns `this` so call sites can chain. Mirrors Python's
+       * `Sandbox.with_extensions_root` (D1-004 cross-SDK parity).
+       */
+      withExtensionsRoot(extensionsRoot) {
+        this.extensionsRoot = extensionsRoot;
+        return this;
+      }
+      /**
+       * Cap the post-capture stdout+stderr byte budget for the sandboxed
+       * subprocess. Default: 64 MiB (`Sandbox.DEFAULT_MAX_OUTPUT_BYTES`).
+       *
+       * Builder-style — returns `this`. Mirrors Python's
+       * `Sandbox.with_max_output_bytes` (D1-004 cross-SDK parity).
+       */
+      withMaxOutputBytes(maxOutputBytes) {
+        this.maxOutputBytes = maxOutputBytes;
+        return this;
+      }
       /**
        * Execute a module, optionally inside a sandboxed subprocess.
        */
@@ -585,12 +616,13 @@ var init_sandbox = __esm({
         return this._sandboxedExecute(moduleId, inputData);
       }
       async _sandboxedExecute(moduleId, inputData) {
-        const { spawn } = await import("child_process");
-        const { tmpdir } = await import("os");
-        const { join: join3 } = await import("path");
-        const { mkdtempSync, rmSync } = await import("fs");
-        const tmpDir = mkdtempSync(join3(tmpdir(), "apcore_sandbox_"));
+        const tmpDir = mkdtempSync(join4(tmpdir(), "apcore_sandbox_"));
         const env = buildSandboxEnv(tmpDir);
+        if (this.extensionsRoot !== null) {
+          env.APCORE_EXTENSIONS_ROOT = resolvePath(this.extensionsRoot);
+        } else if (env.APCORE_EXTENSIONS_ROOT) {
+          env.APCORE_EXTENSIONS_ROOT = resolvePath(env.APCORE_EXTENSIONS_ROOT);
+        }
         const binaryPath = process.argv[1];
         const child = spawn(process.execPath, [binaryPath, "--internal-sandbox-runner", moduleId], {
           env,
@@ -599,11 +631,14 @@ var init_sandbox = __esm({
         });
         let stdout = "";
         let stderr = "";
-        let totalBytes = 0;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
         let sizeExceeded = false;
+        const outputCap = this.maxOutputBytes;
         child.stdout.on("data", (chunk) => {
-          totalBytes += chunk.length;
-          if (totalBytes > SANDBOX_OUTPUT_SIZE_LIMIT) {
+          if (sizeExceeded) return;
+          stdoutBytes += chunk.length;
+          if (stdoutBytes > outputCap) {
             sizeExceeded = true;
             child.kill("SIGKILL");
             return;
@@ -611,6 +646,13 @@ var init_sandbox = __esm({
           stdout += chunk.toString();
         });
         child.stderr.on("data", (chunk) => {
+          if (sizeExceeded) return;
+          stderrBytes += chunk.length;
+          if (stderrBytes > outputCap) {
+            sizeExceeded = true;
+            child.kill("SIGKILL");
+            return;
+          }
           stderr += chunk.toString();
         });
         child.stdin.write(JSON.stringify(inputData));
@@ -631,7 +673,10 @@ var init_sandbox = __esm({
             } catch {
             }
             if (sizeExceeded) {
-              reject(new ModuleExecutionError(`Sandbox module '${moduleId}' output exceeded 64MiB limit.`));
+              const limitMiB = Math.floor(outputCap / (1024 * 1024));
+              reject(new ModuleExecutionError(
+                `Sandbox module '${moduleId}' output exceeded ${limitMiB}MiB limit.`
+              ));
               return;
             }
             if (code !== 0) {
@@ -685,9 +730,9 @@ init_esm_shims();
 // src/main.ts
 init_esm_shims();
 init_errors();
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import * as path4 from "path";
+import * as path5 from "path";
 import { Command as Command5, CommanderError, Option as Option4 } from "commander";
 
 // src/ref-resolver.ts
@@ -786,6 +831,10 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
         properties: {},
         required: []
       };
+      if (typeof obj.properties === "object" && obj.properties !== null) {
+        Object.assign(merged.properties, obj.properties);
+      }
+      const siblingRequired = Array.isArray(obj.required) ? obj.required.slice() : [];
       const allRequiredSets = [];
       for (const subSchema of obj[keyword]) {
         const resolved = resolveNode(
@@ -806,6 +855,7 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
           allRequiredSets.push(new Set(resolved.required));
         }
       }
+      let branchRequired = [];
       if (allRequiredSets.length > 0) {
         let intersection = allRequiredSets[0];
         for (let i = 1; i < allRequiredSets.length; i++) {
@@ -813,10 +863,17 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
             [...intersection].filter((x) => allRequiredSets[i].has(x))
           );
         }
-        merged.required = [...intersection];
-      } else {
-        merged.required = [];
+        branchRequired = [...intersection];
       }
+      const seen = /* @__PURE__ */ new Set();
+      const combinedRequired = [];
+      for (const r of [...siblingRequired, ...branchRequired]) {
+        if (!seen.has(r)) {
+          seen.add(r);
+          combinedRequired.push(r);
+        }
+      }
+      merged.required = combinedRequired;
       for (const [k, v] of Object.entries(obj)) {
         if (k !== keyword && !(k in merged)) {
           merged[k] = v;
@@ -832,7 +889,7 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
         propSchema,
         defs,
         visited,
-        depth + 1,
+        depth,
         maxDepth,
         moduleId
       );
@@ -844,6 +901,7 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
 // src/schema-parser.ts
 init_esm_shims();
 init_errors();
+init_logger();
 var BOOLEAN_FLAG = /* @__PURE__ */ Symbol("BOOLEAN_FLAG");
 function mapType(propName, propSchema) {
   const schemaType = propSchema.type;
@@ -896,6 +954,13 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
   const requiredList = schema.required ?? [];
   const options = [];
   const flagNames = {};
+  for (const reqName of requiredList) {
+    if (!(reqName in properties)) {
+      warn(
+        `Required property '${reqName}' not found in properties, skipping.`
+      );
+    }
+  }
   for (const [propName, propSchema] of Object.entries(properties)) {
     const flagName = "--" + propName.replace(/_/g, "-");
     if (RESERVED_NAMES.has(propName)) {
@@ -903,14 +968,14 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
         `Error: Module schema property '${propName}' conflicts with a reserved CLI option name. Rename the property.
 `
       );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
     }
     if (flagName in flagNames) {
       process.stderr.write(
         `Error: Flag name collision: properties '${propName}' and '${flagNames[flagName]}' both map to '${flagName}'.
 `
       );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
     }
     flagNames[flagName] = propName;
     const typeResult = mapType(propName, propSchema);
@@ -926,7 +991,7 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
           `Error: Flag name collision: boolean property '${propName}' auto-generates '${noFlag}' which is already used by property '${flagNames[noFlag]}'.
 `
         );
-        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+        process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
       }
       flagNames[noFlag] = propName;
       const defaultVal = propSchema.default ?? false;
@@ -1132,6 +1197,27 @@ async function promptWithTimeout(moduleDef, timeout) {
 init_esm_shims();
 init_errors();
 import yaml from "js-yaml";
+var TOOLKIT_MISSING_HINT = "The 'markdown' and 'skill' output formats require the apcore-toolkit peer dependency. Install with: npm install apcore-toolkit@^0.6";
+function descriptorToScanned(m) {
+  const metadata = m.metadata ?? {};
+  const display = metadata["display"] ?? null;
+  return {
+    moduleId: m.id,
+    description: m.description ?? "",
+    inputSchema: m.inputSchema ?? {},
+    outputSchema: m.outputSchema ?? {},
+    tags: m.tags ?? [],
+    target: "",
+    version: "1.0.0",
+    annotations: m.annotations ?? null,
+    documentation: null,
+    suggestedAlias: null,
+    examples: [],
+    metadata,
+    display,
+    warnings: []
+  };
+}
 function csvCellString(value) {
   if (value === null || value === void 0) return "";
   if (typeof value === "object") return JSON.stringify(value);
@@ -1160,7 +1246,7 @@ function formatTable(headers, rows) {
   );
   return [headerLine, sep2, ...dataLines].join("\n") + "\n";
 }
-function formatModuleList(modules, format, filterTags, showDeps = false, exposureFilter) {
+async function formatModuleList(modules, format, filterTags, showDeps = false, exposureFilter) {
   if (format === "table") {
     if (modules.length === 0 && filterTags && filterTags.length > 0) {
       process.stdout.write(
@@ -1205,6 +1291,17 @@ function formatModuleList(modules, format, filterTags, showDeps = false, exposur
       return entry;
     });
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else if (format === "markdown" || format === "skill") {
+    let toolkit;
+    try {
+      toolkit = await import("apcore-toolkit");
+    } catch {
+      throw new Error(TOOLKIT_MISSING_HINT);
+    }
+    const scanned = modules.map(descriptorToScanned);
+    process.stdout.write(
+      toolkit.formatModules(scanned, { style: format, display: true }) + "\n"
+    );
   }
 }
 function annotationsToDict(annotations) {
@@ -1218,7 +1315,7 @@ function annotationsToDict(annotations) {
   }
   return Object.keys(result).length > 0 ? result : null;
 }
-function formatModuleDetail(moduleDef, format) {
+async function formatModuleDetail(moduleDef, format) {
   if (format === "table") {
     process.stdout.write(`
 Module: ${moduleDef.id}
@@ -1289,6 +1386,16 @@ Tags: ${tags.join(", ")}
       }
     }
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else if (format === "markdown" || format === "skill") {
+    let toolkit;
+    try {
+      toolkit = await import("apcore-toolkit");
+    } catch {
+      throw new Error(TOOLKIT_MISSING_HINT);
+    }
+    process.stdout.write(
+      toolkit.formatModule(descriptorToScanned(moduleDef), { style: format, display: true }) + "\n"
+    );
   }
 }
 function selectFields(result, fields) {
@@ -2133,6 +2240,98 @@ init_esm_shims();
 import { Command as Command2, Option as Option2 } from "commander";
 init_errors();
 init_audit();
+
+// src/system-usage.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;
+}
+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 ?? "");
+  });
+  return { used: true };
+}
+
+// src/discovery.ts
 var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
 function validateTag(tag) {
   if (!TAG_PATTERN.test(tag)) {
@@ -2166,7 +2365,9 @@ function getAnnotationFlag(moduleDef, 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).option("--format <format>", "Output format.", void 0).option("-s, --search <query>", "Filter by substring match on ID and description.").addOption(
+  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")
@@ -2216,14 +2417,18 @@ function registerListCommand(apcliGroup, registry, exposureFilter) {
       }
     }
     if (opts.sort === "calls" || opts.sort === "errors" || opts.sort === "latency") {
-      process.stderr.write(
-        `Warning: Usage data not available; sorting by id. Sort by ${opts.sort} requires system.usage modules.
+      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.
 `
-      );
-    }
-    modules.sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""));
-    if (opts.reverse) {
-      modules.reverse();
+        );
+      }
+    } else {
+      modules.sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""));
+      if (opts.reverse) {
+        modules.reverse();
+      }
     }
     let showExposureCol = false;
     if (exposureFilter && opts.exposure !== "all") {
@@ -2238,12 +2443,14 @@ function registerListCommand(apcliGroup, registry, exposureFilter) {
     }
     const fmt = resolveFormat(opts.format);
     const filterTagsArg = opts.tag.length > 0 ? opts.tag : void 0;
-    formatModuleList(modules, fmt, filterTagsArg, opts.deps, showExposureCol ? exposureFilter : 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").option("--format <format>", "Output format.", void 0).action((moduleId, opts) => {
+  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) {
@@ -2254,7 +2461,7 @@ function registerDescribeCommand(apcliGroup, registry) {
       process.exit(EXIT_CODES.MODULE_NOT_FOUND);
     }
     const fmt = resolveFormat(opts.format);
-    formatModuleDetail(moduleDef, fmt);
+    void formatModuleDetail(moduleDef, fmt);
   });
   apcliGroup.addCommand(describeCmd);
 }
@@ -2374,8 +2581,8 @@ function registerValidateCommand(cli, registry, executor) {
 
 // src/system-cmd.ts
 init_esm_shims();
-init_errors();
 import { Command as Command3 } from "commander";
+init_errors();
 async function callSystemModule(executor, moduleId, inputs) {
   if (executor.call) {
     return executor.call(moduleId, inputs);
@@ -2394,6 +2601,15 @@ function emitErrorAndExit(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 formatHealthSummaryTty(result) {
   const summary = result.summary ?? {};
   const modules = result.modules ?? [];
@@ -2534,9 +2750,10 @@ function registerUsageCommand(apcliGroup, executor) {
   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", "Signal explicit intent (forwarded to server-side approval gate).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+  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,
@@ -2554,9 +2771,10 @@ function registerEnableCommand(apcliGroup, executor) {
   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", "Signal explicit intent (forwarded to server-side approval gate).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+  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,
@@ -2574,9 +2792,10 @@ function registerDisableCommand(apcliGroup, executor) {
   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", "Signal explicit intent (forwarded to server-side approval gate).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+  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
@@ -2614,7 +2833,7 @@ function registerConfigCommand(apcliGroup, executor) {
     }
   });
   configGroup.addCommand(configGetCmd);
-  const configSetCmd = new Command3("set").description("Update a runtime configuration value (audit-logged; server-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("--format <format>", "Output format.").action(async (key, value, opts) => {
+  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 {
@@ -2623,6 +2842,7 @@ function registerConfigCommand(apcliGroup, executor) {
       parsedValue = value;
     }
     try {
+      await requireApprovalForSystemCommand("system.control.update_config", opts.yes);
       const result = await callSystemModule(executor, "system.control.update_config", {
         key,
         value: parsedValue,
@@ -2818,7 +3038,29 @@ function registerPipelineCommand(cli, executor) {
 init_esm_shims();
 init_errors();
 init_logger();
-var RESERVED_GROUP_NAMES = /* @__PURE__ */ new Set(["apcli"]);
+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",
@@ -2847,6 +3089,7 @@ var ApcliGroup = class _ApcliGroup {
   _disableEnv;
   _registryInjected;
   _fromCliConfig;
+  _name;
   constructor(init) {
     this._mode = init.mode;
     this._include = init.include;
@@ -2854,6 +3097,16 @@ var ApcliGroup = class _ApcliGroup {
     this._disableEnv = init.disableEnv;
     this._registryInjected = init.registryInjected;
     this._fromCliConfig = init.fromCliConfig;
+    this._name = init.name;
+  }
+  /**
+   * 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 })`.
@@ -2874,6 +3127,18 @@ var ApcliGroup = class _ApcliGroup {
    * 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
+      );
+    }
     return _ApcliGroup._build(
       config,
       opts,
@@ -2887,8 +3152,12 @@ var ApcliGroup = class _ApcliGroup {
    * 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") {
-      return [null, `apcore.yaml 'apcli:' must be a bool, object, or null; got ${typeof config}`];
+    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"];
@@ -2905,6 +3174,8 @@ var ApcliGroup = class _ApcliGroup {
   // 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",
@@ -2912,7 +3183,8 @@ var ApcliGroup = class _ApcliGroup {
         exclude: [],
         disableEnv: false,
         registryInjected: opts.registryInjected,
-        fromCliConfig
+        fromCliConfig,
+        name
       });
     }
     if (config === false) {
@@ -2922,7 +3194,8 @@ var ApcliGroup = class _ApcliGroup {
         exclude: [],
         disableEnv: false,
         registryInjected: opts.registryInjected,
-        fromCliConfig
+        fromCliConfig,
+        name
       });
     }
     if (config === void 0 || config === null) {
@@ -2932,7 +3205,8 @@ var ApcliGroup = class _ApcliGroup {
         exclude: [],
         disableEnv: false,
         registryInjected: opts.registryInjected,
-        fromCliConfig
+        fromCliConfig,
+        name
       });
     }
     if (typeof config !== "object" || Array.isArray(config)) {
@@ -2980,7 +3254,8 @@ var ApcliGroup = class _ApcliGroup {
       exclude,
       disableEnv,
       registryInjected: opts.registryInjected,
-      fromCliConfig
+      fromCliConfig,
+      name
     });
   }
   /**
@@ -3073,7 +3348,8 @@ var ApcliGroup = class _ApcliGroup {
    */
   _parseEnv(raw) {
     if (raw === void 0 || raw === "") return null;
-    const normalized = raw.toLowerCase();
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "") return null;
     if (normalized === "show" || normalized === "1" || normalized === "true") {
       return "all";
     }
@@ -3272,8 +3548,30 @@ function canonicalFormatHelp(cmd, helper) {
   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 = path4.dirname(fileURLToPath2(import.meta.url));
+var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
 var verboseHelp = false;
 function setVerboseHelp(verbose) {
   verboseHelp = verbose;
@@ -3312,7 +3610,7 @@ function resolveStringOption(cliValue, envValue) {
 }
 var VERSION = "0.0.0";
 try {
-  const pkg = JSON.parse(readFileSync2(path4.resolve(__dirname2, "../package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync3(path5.resolve(__dirname2, "../package.json"), "utf-8"));
   VERSION = pkg.version;
 } catch {
 }
@@ -3372,6 +3670,10 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
   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;
@@ -3382,6 +3684,10 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
     extraCommands = extensionsDirOrOpts.extraCommands;
     expose = extensionsDirOrOpts.expose;
     apcliOption = extensionsDirOrOpts.apcli;
+    appVersion = extensionsDirOrOpts.version;
+    appDescription = extensionsDirOrOpts.description;
+    builtinGroupName = extensionsDirOrOpts.builtinGroupName;
+    allowedPrefixes = extensionsDirOrOpts.allowedPrefixes;
   } else {
     extensionsDir = extensionsDirOrOpts;
   }
@@ -3392,7 +3698,7 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
     setAuditLogger(auditLogger);
   } catch {
   }
-  const resolvedProgName = progName ?? path4.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
+  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)) {
@@ -3418,7 +3724,10 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
     }
   }
   const registryInjected = registry !== void 0;
-  const program = new Command5(resolvedProgName).exitOverride().version(VERSION, "-V, --version", "Print version").helpOption("-h, --help", "Print help").addHelpCommand("help [command]", "Print this message or the help of the given subcommand(s)").description("apcore CLI \u2014 execute apcore modules from the command line").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
+  const 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("--verbose", "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");
@@ -3426,21 +3735,39 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
     program.option("--binding <path>", "Path to binding.yaml for display overlay");
   }
   let apcliCfg;
-  if (apcliOption instanceof ApcliGroup) {
-    apcliCfg = apcliOption;
-  } else if (apcliOption !== void 0) {
-    apcliCfg = ApcliGroup.fromCliConfig(apcliOption, { registryInjected });
-  } else {
-    let yamlVal = null;
-    try {
-      const resolver = new ConfigResolver();
-      yamlVal = resolver.resolveObject("apcli");
-    } catch {
-      yamlVal = null;
+  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
+      });
     }
-    apcliCfg = ApcliGroup.fromYaml(yamlVal, { registryInjected });
+  } catch (e) {
+    process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}
+`);
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
-  const apcliGroup = program.command("apcli", { hidden: !apcliCfg.isGroupVisible() }).description("apcore-cli built-in commands");
+  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) {
@@ -3466,17 +3793,17 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
     process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
   _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter);
-  _registerDeprecationShims(program, apcliGroup, registryInjected, resolvedProgName);
   program.addHelpText("after", [
     "",
-    "Use --help --verbose to show all options (including built-in apcore options).",
+    "Use --help --verbose to show all options (including built-in options).",
     "Use --help --man to display a formatted man page."
   ].join("\n"));
-  configureManHelp(program, resolvedProgName, VERSION);
+  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 (RESERVED_GROUP_NAMES.has(cmdName)) {
+      if (_reservedForExtra.has(cmdName)) {
         process.stderr.write(
           `Error: extraCommands name '${cmdName}' is reserved
 `
@@ -3485,21 +3812,11 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
       }
       const existing = program.commands.find((c) => c.name() === cmdName);
       if (existing) {
-        const isShim = existing.__isDeprecationShim === true;
-        if (isShim) {
-          warn(
-            `extraCommands '${cmdName}' overrides the deprecation shim for the same name. The shim will be removed.`
-          );
-          const cmds = program.commands;
-          const idx = cmds.indexOf(existing);
-          if (idx >= 0) cmds.splice(idx, 1);
-        } else {
-          process.stderr.write(
-            `Error: extraCommands name '${cmdName}' collides with an existing command
+        process.stderr.write(
+          `Error: extraCommands name '${cmdName}' collides with an existing command
 `
-          );
-          process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-        }
+        );
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
       }
       program.addCommand(cmd);
     }
@@ -3508,7 +3825,7 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
     const opts = thisCommand.opts();
     const commandsDir = opts.commandsDir;
     const bindingPath = opts.binding;
-    await applyToolkitIntegration(commandsDir, bindingPath);
+    await applyToolkitIntegration(commandsDir, bindingPath, { allowedPrefixes });
   });
   return program;
 }
@@ -3559,53 +3876,11 @@ function _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exp
     entry.register(apcliGroup, registry, executor);
   }
 }
-var _DEPRECATED_ROOT_COMMANDS = [
-  "list",
-  "describe",
-  "exec",
-  "init",
-  "validate",
-  "health",
-  "usage",
-  "enable",
-  "disable",
-  "reload",
-  "config",
-  "completion",
-  "describe-pipeline"
-];
-function _registerDeprecationShims(root, apcliGroup, registryInjected, cliName) {
-  if (registryInjected) return;
-  for (const name of _DEPRECATED_ROOT_COMMANDS) {
-    const apcliSub = apcliGroup.commands.find((c) => c.name() === name);
-    if (!apcliSub) continue;
-    if (root.commands.some((c) => c.name() === name)) continue;
-    const shim = root.command(name).description(`[DEPRECATED] Use '${cliName} apcli ${name}' instead.`).allowUnknownOption(true).allowExcessArguments(true).helpOption(false);
-    shim.__isDeprecationShim = true;
-    shim.action(async function() {
-      process.stderr.write(
-        `WARNING: '${name}' as a root-level command is deprecated. Use '${cliName} apcli ${name}' instead.
-         Will be removed in v0.8. See: https://aiperceivable.github.io/apcore-cli/features/builtin-group/#11-migration
-`
-      );
-      const tail = _collectShimForwardArgs(this);
-      await apcliSub.parseAsync(tail, { from: "user" });
-    });
-  }
-}
-function _collectShimForwardArgs(shim) {
-  const shimArgs = (shim.args ?? []).slice();
-  if (shimArgs.length > 0) return shimArgs;
-  const shimName = shim.name();
-  const idx = process.argv.indexOf(shimName);
-  if (idx < 0) return [];
-  return process.argv.slice(idx + 1);
-}
 var bindingDisplayMap = /* @__PURE__ */ new Map();
 function lookupBindingDisplay(moduleId) {
   return bindingDisplayMap.get(moduleId);
 }
-async function applyToolkitIntegration(commandsDir, bindingPath) {
+async function applyToolkitIntegration(commandsDir, bindingPath, options = {}) {
   if (!commandsDir && !bindingPath) {
     return;
   }
@@ -3625,14 +3900,14 @@ async function applyToolkitIntegration(commandsDir, bindingPath) {
   }
   if (bindingPath) {
     try {
-      await loadBindingDisplayOverlay(toolkit, bindingPath);
+      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}`);
     }
   }
 }
-async function loadBindingDisplayOverlay(toolkit, bindingPath) {
+async function loadBindingDisplayOverlay(toolkit, bindingPath, allowedPrefixes) {
   const BindingLoaderCtor = toolkit.BindingLoader;
   const DisplayResolverCtor = toolkit.DisplayResolver;
   if (!BindingLoaderCtor || !DisplayResolverCtor) {
@@ -3642,11 +3917,23 @@ async function loadBindingDisplayOverlay(toolkit, bindingPath) {
   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`
+      );
+      continue;
+    }
     const meta = entry.metadata ?? {};
     const display = meta.display;
     if (display && typeof display === "object" && !Array.isArray(display)) {
@@ -3656,7 +3943,12 @@ async function loadBindingDisplayOverlay(toolkit, bindingPath) {
 }
 function main(progName) {
   verboseHelp = hasVerboseFlag();
-  const program = createCli(void 0, progName, verboseHelp);
+  const program = createCli({
+    progName,
+    verbose: verboseHelp,
+    version: VERSION,
+    description: `${progName ?? "apcore-cli"} \u2014 execute apcore modules from the command line`
+  });
   try {
     program.parse(process.argv);
   } catch (error) {
@@ -3737,7 +4029,15 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
     cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
   }
   for (const opt of schemaOptions) {
-    if (opt.parseArg) {
+    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);
@@ -3761,24 +4061,12 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
     );
     const approvalToken = options.approvalToken;
     const schemaKwargs = {};
-    const builtinKeys = /* @__PURE__ */ new Set([
-      "input",
-      "yes",
-      "largeInput",
-      "format",
-      "fields",
-      "sandbox",
-      "verbose",
-      "dryRun",
-      "trace",
-      "stream",
-      "strategy",
-      "approvalTimeout",
-      "approvalToken"
-    ]);
-    for (const [k, v] of Object.entries(options)) {
-      if (!builtinKeys.has(k)) {
-        schemaKwargs[k] = v;
+    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];
       }
     }
     let merged = {};
@@ -3963,22 +4251,6 @@ Pipeline Trace (strategy: ${trace.strategyName}, ${stepCount} steps, ${trace.tot
   });
   return cmd;
 }
-function validateModuleId(moduleId) {
-  if (moduleId.length > 192) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 192 characters.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/.test(moduleId)) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-}
 async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
   const cliKwargsNonNull = {};
   for (const [k, v] of Object.entries(cliKwargs)) {
@@ -3997,7 +4269,7 @@ async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
   } else {
     source = `file '${stdinFlag}'`;
     try {
-      raw = readFileSync2(stdinFlag, "utf-8");
+      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}
@@ -4083,7 +4355,7 @@ import { Command as Command6 } from "commander";
 init_logger();
 init_errors();
 function assertNotReserved(kind, name, moduleId) {
-  if (!RESERVED_GROUP_NAMES.has(name)) return;
+  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.
@@ -4337,8 +4609,9 @@ var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
    */
   listCommands() {
     this.buildGroupMap();
+    const reserved = getReservedGroupNames();
     const groupNames = [...this.groupMap.keys()].filter(
-      (g) => !RESERVED_GROUP_NAMES.has(g)
+      (g) => !reserved.has(g)
     );
     const topNames = [...this.topLevelModules.keys()];
     return [.../* @__PURE__ */ new Set([...groupNames, ...topNames])].sort();
@@ -4397,6 +4670,7 @@ init_logger();
 init_security();
 export {
   ApcliGroup,
+  ApcliGroupError,
   ApprovalDeniedError,
   ApprovalTimeoutError,
   AuditLogger,
@@ -4423,10 +4697,10 @@ export {
   collectInput,
   configureManHelp,
   createCli,
-  emitErrorJson,
-  emitErrorTty,
   exitCodeForError,
   formatExecResult,
+  formatModuleDetail,
+  formatModuleList,
   getAuditLogger,
   getLogLevel,
   main,
@@ -4445,6 +4719,7 @@ export {
   registerReloadCommand,
   registerUsageCommand,
   registerValidateCommand,
+  resolveFormat,
   resolveRefs,
   schemaToCliOptions,
   setAuditLogger,