apcore-cli 0.7.0 → 0.8.1

package/dist/bin/apcore-cli.js

@@ -157,6 +157,10 @@ __export(sandbox_exports, {
   Sandbox: () => Sandbox,
   runSandboxRunner: () => runSandboxRunner
 });
+import { spawn } from "child_process";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve as resolvePath } from "path";
 async function runSandboxRunner(moduleId) {
   const extensionsRoot = process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
   const apcore = await import("apcore-js").catch(() => {
@@ -205,7 +209,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";
@@ -215,14 +219,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.
        */
@@ -233,12 +264,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(join(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,
@@ -247,11 +279,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;
@@ -259,6 +294,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));
@@ -279,7 +321,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) {
@@ -400,6 +445,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(
@@ -420,6 +469,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++) {
@@ -427,10 +477,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;
@@ -446,7 +503,7 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
         propSchema,
         defs,
         visited,
-        depth + 1,
+        depth,
         maxDepth,
         moduleId
       );
@@ -462,6 +519,30 @@ var init_ref_resolver = __esm({
   }
 });
 
+// src/logger.ts
+function setLogLevel(level) {
+  const upper = level.toUpperCase();
+  if (upper in LEVELS) {
+    currentLevel = upper;
+  }
+}
+function shouldLog(level) {
+  return LEVELS[level] >= LEVELS[currentLevel];
+}
+function warn(message) {
+  if (shouldLog("WARNING")) process.stderr.write(`WARNING: ${message}
+`);
+}
+var LEVELS, currentLevel;
+var init_logger = __esm({
+  "src/logger.ts"() {
+    "use strict";
+    init_esm_shims();
+    LEVELS = { DEBUG: 0, INFO: 1, WARNING: 2, ERROR: 3 };
+    currentLevel = "WARNING";
+  }
+});
+
 // src/schema-parser.ts
 function mapType(propName, propSchema) {
   const schemaType = propSchema.type;
@@ -499,6 +580,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)) {
@@ -506,14 +594,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);
@@ -529,7 +617,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;
@@ -606,6 +694,7 @@ var init_schema_parser = __esm({
     "use strict";
     init_esm_shims();
     init_errors();
+    init_logger();
     BOOLEAN_FLAG = /* @__PURE__ */ Symbol("BOOLEAN_FLAG");
     RESERVED_NAMES = /* @__PURE__ */ new Set([
       "input",
@@ -763,6 +852,26 @@ var init_approval = __esm({
 
 // src/output.ts
 import yaml from "js-yaml";
+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);
@@ -791,7 +900,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(
@@ -836,6 +945,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) {
@@ -849,7 +969,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}
@@ -920,6 +1040,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) {
@@ -1068,35 +1198,13 @@ function firstFailedExitCode(result) {
   }
   return EXIT_CODES.MODULE_EXECUTE_ERROR;
 }
+var TOOLKIT_MISSING_HINT;
 var init_output = __esm({
   "src/output.ts"() {
     "use strict";
     init_esm_shims();
     init_errors();
-  }
-});
-
-// src/logger.ts
-function setLogLevel(level) {
-  const upper = level.toUpperCase();
-  if (upper in LEVELS) {
-    currentLevel = upper;
-  }
-}
-function shouldLog(level) {
-  return LEVELS[level] >= LEVELS[currentLevel];
-}
-function warn(message) {
-  if (shouldLog("WARNING")) process.stderr.write(`WARNING: ${message}
-`);
-}
-var LEVELS, currentLevel;
-var init_logger = __esm({
-  "src/logger.ts"() {
-    "use strict";
-    init_esm_shims();
-    LEVELS = { DEBUG: 0, INFO: 1, WARNING: 2, ERROR: 3 };
-    currentLevel = "WARNING";
+    TOOLKIT_MISSING_HINT = "The 'markdown' and 'skill' output formats require the apcore-toolkit peer dependency. Install with: npm install apcore-toolkit@^0.6";
   }
 });
 
@@ -1853,8 +1961,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() {
@@ -1900,16 +2008,112 @@ 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";
         }
       }
     };
   }
 });
 
+// src/system-usage.ts
+import * as fs4 from "fs";
+import * as os2 from "os";
+import * as path4 from "path";
+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 };
+}
+var PERIOD_TO_MS, DEFAULT_AUDIT_PATH;
+var init_system_usage = __esm({
+  "src/system-usage.ts"() {
+    "use strict";
+    init_esm_shims();
+    PERIOD_TO_MS = {
+      "1h": 60 * 60 * 1e3,
+      "24h": 24 * 60 * 60 * 1e3,
+      "7d": 7 * 24 * 60 * 60 * 1e3,
+      "30d": 30 * 24 * 60 * 60 * 1e3
+    };
+    DEFAULT_AUDIT_PATH = path4.join(
+      os2.homedir(),
+      ".apcore-cli",
+      "audit.jsonl"
+    );
+  }
+});
+
 // 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 {
@@ -2038,7 +2242,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");
@@ -2070,7 +2274,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}`];
@@ -2230,7 +2434,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")
@@ -2280,14 +2486,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") {
@@ -2302,12 +2512,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) {
@@ -2318,7 +2530,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);
 }
@@ -2445,6 +2657,7 @@ var init_discovery = __esm({
     init_main();
     init_output();
     init_audit();
+    init_system_usage();
     TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
   }
 });
@@ -2469,6 +2682,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 ?? [];
@@ -2609,9 +2831,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,
@@ -2629,9 +2852,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,
@@ -2649,9 +2873,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
@@ -2689,7 +2914,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 {
@@ -2698,6 +2923,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,
@@ -2724,6 +2950,7 @@ var init_system_cmd = __esm({
   "src/system-cmd.ts"() {
     "use strict";
     init_esm_shims();
+    init_approval();
     init_errors();
     init_output();
   }
@@ -2905,14 +3132,33 @@ var init_strategy = __esm({
 });
 
 // src/builtin-group.ts
-var RESERVED_GROUP_NAMES, VALID_USER_MODES, APCLI_SUBCOMMAND_NAMES, ApcliGroup;
+function setReservedGroupNames(names) {
+  _effectiveReservedNames = names;
+}
+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 ApcliGroupError, DEFAULT_BUILTIN_GROUP_NAME, RESERVED_GROUP_NAMES, _effectiveReservedNames, _NAME_REGEX, VALID_USER_MODES, APCLI_SUBCOMMAND_NAMES, ApcliGroup;
 var init_builtin_group = __esm({
   "src/builtin-group.ts"() {
     "use strict";
     init_esm_shims();
     init_errors();
     init_logger();
-    RESERVED_GROUP_NAMES = /* @__PURE__ */ new Set(["apcli"]);
+    ApcliGroupError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "ApcliGroupError";
+      }
+    };
+    DEFAULT_BUILTIN_GROUP_NAME = "apcli";
+    RESERVED_GROUP_NAMES = /* @__PURE__ */ new Set([DEFAULT_BUILTIN_GROUP_NAME]);
+    _effectiveReservedNames = RESERVED_GROUP_NAMES;
+    _NAME_REGEX = /^[a-z][a-z0-9_-]*$/;
     VALID_USER_MODES = /* @__PURE__ */ new Set([
       "all",
       "none",
@@ -2941,6 +3187,7 @@ var init_builtin_group = __esm({
       _disableEnv;
       _registryInjected;
       _fromCliConfig;
+      _name;
       constructor(init) {
         this._mode = init.mode;
         this._include = init.include;
@@ -2948,6 +3195,16 @@ var init_builtin_group = __esm({
         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 })`.
@@ -2968,6 +3225,18 @@ var init_builtin_group = __esm({
        * 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,
@@ -2981,8 +3250,12 @@ var init_builtin_group = __esm({
        * 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"];
@@ -2999,6 +3272,8 @@ var init_builtin_group = __esm({
       // 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",
@@ -3006,7 +3281,8 @@ var init_builtin_group = __esm({
             exclude: [],
             disableEnv: false,
             registryInjected: opts.registryInjected,
-            fromCliConfig
+            fromCliConfig,
+            name
           });
         }
         if (config === false) {
@@ -3016,7 +3292,8 @@ var init_builtin_group = __esm({
             exclude: [],
             disableEnv: false,
             registryInjected: opts.registryInjected,
-            fromCliConfig
+            fromCliConfig,
+            name
           });
         }
         if (config === void 0 || config === null) {
@@ -3026,7 +3303,8 @@ var init_builtin_group = __esm({
             exclude: [],
             disableEnv: false,
             registryInjected: opts.registryInjected,
-            fromCliConfig
+            fromCliConfig,
+            name
           });
         }
         if (typeof config !== "object" || Array.isArray(config)) {
@@ -3074,7 +3352,8 @@ var init_builtin_group = __esm({
           exclude,
           disableEnv,
           registryInjected: opts.registryInjected,
-          fromCliConfig
+          fromCliConfig,
+          name
         });
       }
       /**
@@ -3167,7 +3446,8 @@ var init_builtin_group = __esm({
        */
       _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";
         }
@@ -3376,6 +3656,34 @@ var init_canonical_help = __esm({
   }
 });
 
+// src/validate.ts
+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);
+  }
+}
+var MODULE_ID_PATTERN, MAX_MODULE_ID_LENGTH;
+var init_validate = __esm({
+  "src/validate.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+    MAX_MODULE_ID_LENGTH = 192;
+  }
+});
+
 // src/main.ts
 var main_exports = {};
 __export(main_exports, {
@@ -3384,9 +3692,6 @@ __export(main_exports, {
   clearBindingDisplayMap: () => clearBindingDisplayMap,
   collectInput: () => collectInput,
   createCli: () => createCli,
-  docsUrl: () => docsUrl,
-  emitErrorJson: () => emitErrorJson,
-  emitErrorTty: () => emitErrorTty,
   lookupBindingDisplay: () => lookupBindingDisplay,
   main: () => main,
   reconvertEnumValues: () => reconvertEnumValues,
@@ -3394,12 +3699,11 @@ __export(main_exports, {
   resolveStringOption: () => resolveStringOption,
   setDocsUrl: () => setDocsUrl,
   setVerboseHelp: () => setVerboseHelp,
-  validateModuleId: () => validateModuleId,
-  verboseHelp: () => verboseHelp
+  validateModuleId: () => validateModuleId
 });
-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";
 function setVerboseHelp(verbose) {
   verboseHelp = verbose;
@@ -3491,6 +3795,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;
@@ -3501,6 +3809,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;
   }
@@ -3511,7 +3823,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)) {
@@ -3537,7 +3849,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");
@@ -3545,21 +3860,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) {
@@ -3585,17 +3918,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
 `
@@ -3604,21 +3937,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);
     }
@@ -3627,7 +3950,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;
 }
@@ -3677,40 +4000,13 @@ function _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exp
     entry.register(apcliGroup, registry, executor);
   }
 }
-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);
-}
 function lookupBindingDisplay(moduleId) {
   return bindingDisplayMap.get(moduleId);
 }
 function clearBindingDisplayMap() {
   bindingDisplayMap.clear();
 }
-async function applyToolkitIntegration(commandsDir, bindingPath) {
+async function applyToolkitIntegration(commandsDir, bindingPath, options = {}) {
   if (!commandsDir && !bindingPath) {
     return;
   }
@@ -3730,14 +4026,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) {
@@ -3747,11 +4043,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)) {
@@ -3761,7 +4069,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) {
@@ -3842,7 +4155,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);
@@ -3866,24 +4187,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 = {};
@@ -4068,22 +4377,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)) {
@@ -4102,7 +4395,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}
@@ -4181,7 +4474,7 @@ function reconvertEnumValues(kwargs, options) {
   }
   return result;
 }
-var __dirname2, verboseHelp, docsUrl, VERSION, _ALWAYS_REGISTERED, _DEPRECATED_ROOT_COMMANDS, bindingDisplayMap;
+var __dirname2, verboseHelp, docsUrl, VERSION, _ALWAYS_REGISTERED, bindingDisplayMap;
 var init_main = __esm({
   "src/main.ts"() {
     "use strict";
@@ -4204,31 +4497,17 @@ var init_main = __esm({
     init_exposure();
     init_audit();
     init_canonical_help();
-    __dirname2 = path4.dirname(fileURLToPath2(import.meta.url));
+    init_validate();
+    __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
     verboseHelp = false;
     docsUrl = null;
     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 {
     }
     _ALWAYS_REGISTERED = /* @__PURE__ */ new Set(["exec"]);
-    _DEPRECATED_ROOT_COMMANDS = [
-      "list",
-      "describe",
-      "exec",
-      "init",
-      "validate",
-      "health",
-      "usage",
-      "enable",
-      "disable",
-      "reload",
-      "config",
-      "completion",
-      "describe-pipeline"
-    ];
     bindingDisplayMap = /* @__PURE__ */ new Map();
   }
 });