apcore-cli 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,11 +1,5 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -24,34 +18,36 @@ var init_esm_shims = __esm({
 });
 
 // src/errors.ts
-function exitCodeForError(error2) {
-  if (error2 instanceof ApprovalTimeoutError) {
+function exitCodeForError(error) {
+  if (error instanceof ApprovalTimeoutError) {
     return EXIT_CODES.APPROVAL_TIMEOUT;
   }
-  if (error2 instanceof ApprovalDeniedError) {
+  if (error instanceof ApprovalDeniedError) {
     return EXIT_CODES.APPROVAL_DENIED;
   }
-  if (error2 instanceof AuthenticationError) {
+  if (error instanceof AuthenticationError) {
     return EXIT_CODES.ACL_DENIED;
   }
-  if (error2 instanceof ConfigDecryptionError) {
+  if (error instanceof ConfigDecryptionError) {
     return EXIT_CODES.CONFIG_INVALID;
   }
-  if (error2 instanceof SchemaValidationError) {
+  if (error instanceof SchemaValidationError) {
     return EXIT_CODES.SCHEMA_VALIDATION_ERROR;
   }
-  if (error2 instanceof ModuleNotFoundError) {
+  if (error instanceof ModuleNotFoundError) {
     return EXIT_CODES.MODULE_NOT_FOUND;
   }
-  if (error2 instanceof ModuleExecutionError) {
+  if (error instanceof ModuleExecutionError) {
     return EXIT_CODES.MODULE_EXECUTE_ERROR;
   }
-  if (error2 instanceof Error) {
-    const code = error2.code;
+  if (error instanceof Error) {
+    const code = error.code;
     const codeMap = {
       MODULE_NOT_FOUND: EXIT_CODES.MODULE_NOT_FOUND,
       MODULE_LOAD_ERROR: EXIT_CODES.MODULE_LOAD_ERROR,
       MODULE_DISABLED: EXIT_CODES.MODULE_DISABLED,
+      DEPENDENCY_NOT_FOUND: EXIT_CODES.DEPENDENCY_NOT_FOUND,
+      DEPENDENCY_VERSION_MISMATCH: EXIT_CODES.DEPENDENCY_VERSION_MISMATCH,
       SCHEMA_VALIDATION_ERROR: EXIT_CODES.SCHEMA_VALIDATION_ERROR,
       SCHEMA_CIRCULAR_REF: EXIT_CODES.SCHEMA_CIRCULAR_REF,
       APPROVAL_DENIED: EXIT_CODES.APPROVAL_DENIED,
@@ -66,6 +62,7 @@ function exitCodeForError(error2) {
       CONFIG_NAMESPACE_RESERVED: EXIT_CODES.CONFIG_NAMESPACE_RESERVED,
       CONFIG_NAMESPACE_DUPLICATE: EXIT_CODES.CONFIG_NAMESPACE_DUPLICATE,
       CONFIG_ENV_PREFIX_CONFLICT: EXIT_CODES.CONFIG_ENV_PREFIX_CONFLICT,
+      CONFIG_ENV_MAP_CONFLICT: EXIT_CODES.CONFIG_ENV_MAP_CONFLICT,
       CONFIG_MOUNT_ERROR: EXIT_CODES.CONFIG_MOUNT_ERROR,
       CONFIG_BIND_ERROR: EXIT_CODES.CONFIG_BIND_ERROR,
       ERROR_FORMATTER_DUPLICATE: EXIT_CODES.ERROR_FORMATTER_DUPLICATE
@@ -131,6 +128,8 @@ var init_errors = __esm({
       MODULE_NOT_FOUND: 44,
       MODULE_LOAD_ERROR: 44,
       MODULE_DISABLED: 44,
+      DEPENDENCY_NOT_FOUND: 44,
+      DEPENDENCY_VERSION_MISMATCH: 44,
       SCHEMA_VALIDATION_ERROR: 45,
       APPROVAL_DENIED: 46,
       APPROVAL_TIMEOUT: 46,
@@ -151,43 +150,88 @@ var init_errors = __esm({
   }
 });
 
+// src/logger.ts
+function setLogLevel(level) {
+  const upper = level.toUpperCase();
+  if (upper in LEVELS) {
+    currentLevel = upper;
+  }
+}
+function getLogLevel() {
+  return currentLevel;
+}
+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/security/audit.ts
 var audit_exports = {};
 __export(audit_exports, {
   AuditLogger: () => AuditLogger,
+  canonicalizeForHash: () => canonicalizeForHash,
   getAuditLogger: () => getAuditLogger,
   setAuditLogger: () => setAuditLogger
 });
 import * as crypto from "crypto";
 import * as fs3 from "fs";
 import * as os from "os";
-import * as path4 from "path";
+import * as path3 from "path";
 function setAuditLogger(auditLogger) {
   _auditLogger = auditLogger;
 }
 function getAuditLogger() {
   return _auditLogger;
 }
+function canonicalizeForHash(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(canonicalizeForHash);
+  const src = value;
+  const sorted = {};
+  for (const key of Object.keys(src).sort()) {
+    sorted[key] = canonicalizeForHash(src[key]);
+  }
+  return sorted;
+}
 var _auditLogger, AuditLogger;
 var init_audit = __esm({
   "src/security/audit.ts"() {
     "use strict";
     init_esm_shims();
+    init_logger();
     _auditLogger = null;
     AuditLogger = class _AuditLogger {
-      static DEFAULT_PATH = path4.join(
+      static DEFAULT_PATH = path3.join(
         os.homedir(),
         ".apcore-cli",
         "audit.jsonl"
       );
       logPath;
-      constructor(path7) {
-        this.logPath = path7 ?? _AuditLogger.DEFAULT_PATH;
+      writeFailureWarned = false;
+      constructor(path6) {
+        this.logPath = path6 ?? _AuditLogger.DEFAULT_PATH;
         this.ensureDirectory();
       }
       ensureDirectory() {
+        const dir = path3.dirname(this.logPath);
         try {
-          fs3.mkdirSync(path4.dirname(this.logPath), { recursive: true });
+          fs3.mkdirSync(dir, { recursive: true });
+          try {
+            fs3.chmodSync(dir, 448);
+          } catch {
+          }
         } catch {
         }
       }
@@ -203,21 +247,27 @@ var init_audit = __esm({
         };
         try {
           fs3.appendFileSync(this.logPath, JSON.stringify(entry) + "\n");
+          try {
+            fs3.chmodSync(this.logPath, 384);
+          } catch {
+          }
         } catch (err) {
-          console.warn(`Could not write audit log: ${err}`);
+          if (!this.writeFailureWarned) {
+            this.writeFailureWarned = true;
+            warn(`Could not write audit log: ${err}`);
+          }
         }
       }
       hashInput(inputData) {
         const salt = crypto.randomBytes(16);
-        const sortedKeys = Object.keys(inputData).sort();
-        const payload = JSON.stringify(inputData, sortedKeys);
+        const payload = JSON.stringify(canonicalizeForHash(inputData));
         return crypto.createHash("sha256").update(Buffer.concat([salt, Buffer.from(payload, "utf-8")])).digest("hex");
       }
       getUser() {
         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";
         }
       }
     };
@@ -226,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 {
@@ -236,17 +286,34 @@ async function getKeytar() {
     return null;
   }
 }
-var keytarModule, ConfigEncryptor;
+var PBKDF2_ITERATIONS, V1_STATIC_SALT, keytarModule, ConfigEncryptor;
 var init_config_encryptor = __esm({
   "src/security/config-encryptor.ts"() {
     "use strict";
     init_esm_shims();
     init_errors();
+    init_logger();
+    PBKDF2_ITERATIONS = 6e5;
+    V1_STATIC_SALT = Buffer.from("apcore-cli-config-v1");
     keytarModule = null;
     ConfigEncryptor = class _ConfigEncryptor {
       static SERVICE_NAME = "apcore-cli";
+      // One-shot flag so the "obfuscation only" warning fires exactly once
+      // per process instead of once per encrypt/decrypt call.
+      static weakFallbackWarned = false;
       /**
        * Encrypt and store a configuration value.
+       *
+       * Cross-SDK contract (D10-003, 2026-04-26): when the OS keyring is
+       * detected as available but `setPassword` then throws (locked keyring,
+       * transient backend failure, permission revoked, etc.), the error is
+       * propagated wrapped in a `ConfigDecryptionError`. Previously TS
+       * caught the exception and silently fell through to AES file encryption
+       * — a quiet downgrade that surprised users who expected a hard failure.
+       * Python lets the keyring exception propagate raw; Rust returns
+       * `ConfigDecryptionError::KeyringError`. The fall-through to AES is
+       * still reached when `getKeytar()` returns `null` (keyring
+       * genuinely unavailable on this platform / install).
        */
       async store(key, value) {
         const keytar = await getKeytar();
@@ -254,12 +321,16 @@ var init_config_encryptor = __esm({
           try {
             await keytar.setPassword(_ConfigEncryptor.SERVICE_NAME, key, value);
             return `keyring:${key}`;
-          } catch {
+          } catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new ConfigDecryptionError(
+              `Failed to store '${key}' in OS keyring: ${detail}. Unset APCORE_CLI_CONFIG_PASSPHRASE-aware backends or unlock the keyring before retrying.`
+            );
           }
         }
-        console.warn("OS keyring unavailable. Using file-based encryption.");
+        warn("OS keyring unavailable. Using file-based encryption.");
         const ciphertext = this.aesEncrypt(value);
-        return `enc:${Buffer.from(ciphertext).toString("base64")}`;
+        return `enc:v2:${ciphertext.toString("base64")}`;
       }
       /**
        * Retrieve and decrypt a configuration value.
@@ -291,13 +362,20 @@ var init_config_encryptor = __esm({
             );
           }
         }
+        if (configValue.startsWith("enc:v2:")) {
+          const data = Buffer.from(configValue.slice("enc:v2:".length), "base64");
+          try {
+            return this.aesDecrypt(data);
+          } catch {
+            throw new ConfigDecryptionError(
+              `Failed to decrypt configuration value '${key}'. Re-configure with 'apcore-cli config set ${key}'.`
+            );
+          }
+        }
         if (configValue.startsWith("enc:")) {
-          const ciphertext = Buffer.from(
-            configValue.slice("enc:".length),
-            "base64"
-          );
+          const data = Buffer.from(configValue.slice("enc:".length), "base64");
           try {
-            return this.aesDecrypt(ciphertext);
+            return this.aesDecryptV1(data);
           } catch {
             throw new ConfigDecryptionError(
               `Failed to decrypt configuration value '${key}'. Re-configure with 'apcore-cli config set ${key}'.`
@@ -306,18 +384,35 @@ var init_config_encryptor = __esm({
         }
         return configValue;
       }
-      // NOTE: Best-effort fallback when OS keyring is unavailable.
-      // The key is derived from hostname + username (non-secret inputs).
-      // For production security, ensure the OS keyring is accessible.
-      deriveKey() {
-        const hostname2 = os2.hostname();
+      // Derive an AES-256 key with a provided salt (v2 format).
+      //
+      // Order of preference:
+      //   1. APCORE_CLI_CONFIG_PASSPHRASE env var — a real secret supplied by
+      //      the user; produces a key an attacker with filesystem read cannot
+      //      reconstruct without also knowing the passphrase.
+      //   2. hostname + username — obfuscation-only derivation for backward
+      //      compatibility. Emits a loud stderr warning on first use so
+      //      operators know the stored value is NOT protected against a
+      //      filesystem-read attacker.
+      deriveKey(salt) {
+        const passphrase = process.env.APCORE_CLI_CONFIG_PASSPHRASE;
+        if (passphrase && passphrase.length > 0) {
+          return crypto2.pbkdf2Sync(passphrase, salt, PBKDF2_ITERATIONS, 32, "sha256");
+        }
+        if (!_ConfigEncryptor.weakFallbackWarned) {
+          warn(
+            "APCORE_CLI_CONFIG_PASSPHRASE is not set. The `enc:v2:` fallback uses a key derived from hostname+username (non-secret inputs) and is OBFUSCATION ONLY \u2014 an attacker with filesystem read access can reconstruct the key. Set APCORE_CLI_CONFIG_PASSPHRASE or ensure the OS keyring is available for real encryption."
+          );
+          _ConfigEncryptor.weakFallbackWarned = true;
+        }
+        const hostname2 = os3.hostname();
         const username = process.env.USER ?? process.env.USERNAME ?? "unknown";
-        const salt = Buffer.from("apcore-cli-config-v1");
         const material = `${hostname2}:${username}`;
-        return crypto2.pbkdf2Sync(material, salt, 1e5, 32, "sha256");
+        return crypto2.pbkdf2Sync(material, salt, PBKDF2_ITERATIONS, 32, "sha256");
       }
       aesEncrypt(plaintext) {
-        const key = this.deriveKey();
+        const salt = crypto2.randomBytes(16);
+        const key = this.deriveKey(salt);
         const nonce = crypto2.randomBytes(12);
         const cipher = crypto2.createCipheriv("aes-256-gcm", key, nonce);
         const ct = Buffer.concat([
@@ -325,17 +420,39 @@ var init_config_encryptor = __esm({
           cipher.final()
         ]);
         const tag = cipher.getAuthTag();
-        return Buffer.concat([nonce, tag, ct]);
+        return Buffer.concat([salt, nonce, tag, ct]);
       }
       aesDecrypt(data) {
-        const key = this.deriveKey();
+        const salt = data.subarray(0, 16);
+        const nonce = data.subarray(16, 28);
+        const tag = data.subarray(28, 44);
+        const ct = data.subarray(44);
+        const key = this.deriveKey(salt);
+        const decipher = crypto2.createDecipheriv("aes-256-gcm", key, nonce);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf-8");
+      }
+      /** Decrypt legacy v1-format values: nonce(12)+tag(16)+ct, static salt. */
+      aesDecryptV1(data) {
         const nonce = data.subarray(0, 12);
         const tag = data.subarray(12, 28);
         const ct = data.subarray(28);
-        const decipher = crypto2.createDecipheriv("aes-256-gcm", key, nonce);
-        decipher.setAuthTag(tag);
-        const plaintext = Buffer.concat([decipher.update(ct), decipher.final()]);
-        return plaintext.toString("utf-8");
+        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}`];
+        for (const material of materials) {
+          for (const iterations of [6e5, 1e5]) {
+            try {
+              const key = crypto2.pbkdf2Sync(material, V1_STATIC_SALT, iterations, 32, "sha256");
+              const decipher = crypto2.createDecipheriv("aes-256-gcm", key, nonce);
+              decipher.setAuthTag(tag);
+              return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf-8");
+            } catch {
+            }
+          }
+        }
+        throw new Error("v1 decryption failed with all material+iteration combinations");
       }
     };
   }
@@ -371,12 +488,30 @@ var init_auth = __esm({
         }
         const strResult = String(result);
         if (strResult.startsWith("keyring:") || strResult.startsWith("enc:")) {
-          return this.encryptor.retrieve(strResult, "auth.api_key");
+          try {
+            return await this.encryptor.retrieve(strResult, "auth.api_key");
+          } catch (err) {
+            if (err instanceof ConfigDecryptionError) {
+              throw new AuthenticationError(
+                "Failed to decrypt stored API key. Re-configure with 'apcore-cli config set auth.api_key'."
+              );
+            }
+            throw err;
+          }
         }
         return strResult;
       }
       /**
        * Add authentication headers to an outgoing request.
+       *
+       * Cross-SDK contract (D10-002, 2026-04-26): the input `headers` object
+       * is mutated **in place** and the same reference is returned. Callers
+       * that share the headers reference (the documented pattern in
+       * apcore-cli/docs/features/security.md §AuthProvider) can read
+       * `headers.Authorization` after the call without re-binding the
+       * return value. Python and Rust both mutate-and-return; TS previously
+       * spread into a new object, which silently broke shared-reference
+       * callers.
        */
       async authenticateRequest(headers) {
         const key = await this.getApiKey();
@@ -385,7 +520,13 @@ var init_auth = __esm({
             "Remote registry requires authentication. Set --api-key, APCORE_AUTH_API_KEY, or auth.api_key in config."
           );
         }
-        return { ...headers, Authorization: `Bearer ${key}` };
+        if (/[\r\n]/.test(key)) {
+          throw new AuthenticationError(
+            "Malformed API key: contains invalid characters (CR/LF). Re-configure with 'apcore-cli config set auth.api_key'."
+          );
+        }
+        headers.Authorization = `Bearer ${key.trim()}`;
+        return headers;
       }
       /**
        * Handle an HTTP response status code for auth-related errors.
@@ -402,20 +543,64 @@ var init_auth = __esm({
 });
 
 // src/security/sandbox.ts
-import * as child_process from "child_process";
-import * as fs4 from "fs";
-import * as os3 from "os";
-import * as path5 from "path";
-var Sandbox;
+function buildSandboxEnv(tmpDir) {
+  const env = {};
+  for (const key of SANDBOX_ALLOW_KEYS) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  for (const [key, val] of Object.entries(process.env)) {
+    if (key.startsWith(SANDBOX_ALLOW_PREFIX) && !key.startsWith(SANDBOX_DENY_PREFIX) && !SANDBOX_DENY_KEYS.includes(key)) {
+      env[key] = val;
+    }
+  }
+  env.HOME = tmpDir;
+  env.TMPDIR = tmpDir;
+  return env;
+}
+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";
     init_esm_shims();
     init_errors();
+    SANDBOX_ALLOW_KEYS = ["PATH", "LANG", "LC_ALL"];
+    SANDBOX_ALLOW_PREFIX = "APCORE_";
+    SANDBOX_DENY_PREFIX = "APCORE_AUTH_";
+    SANDBOX_DENY_KEYS = ["APCORE_AUTH_API_KEY"];
+    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;
-      constructor(enabled = false) {
+      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.
@@ -424,63 +609,96 @@ var init_sandbox = __esm({
         if (!this.enabled) {
           return executor.execute(moduleId, inputData);
         }
-        return this.sandboxedExecute(moduleId, inputData);
+        return this._sandboxedExecute(moduleId, inputData);
       }
-      sandboxedExecute(moduleId, inputData) {
-        const env = {};
-        for (const key of ["PATH", "NODE_PATH", "LANG", "LC_ALL"]) {
-          if (process.env[key]) {
-            env[key] = process.env[key];
-          }
-        }
-        for (const [key, value] of Object.entries(process.env)) {
-          if (key.startsWith("APCORE_") && value) {
-            env[key] = value;
-          }
+      async _sandboxedExecute(moduleId, inputData) {
+        const { spawn } = await import("child_process");
+        const { tmpdir } = await import("os");
+        const { join: join4 } = await import("path");
+        const { mkdtempSync, rmSync } = await import("fs");
+        const tmpDir = mkdtempSync(join4(tmpdir(), "apcore_sandbox_"));
+        const env = buildSandboxEnv(tmpDir);
+        const { resolve: resolvePath } = await import("path");
+        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 tmpDir = fs4.mkdtempSync(
-          path5.join(os3.tmpdir(), "apcore_sandbox_")
-        );
-        try {
-          env.HOME = tmpDir;
-          env.TMPDIR = tmpDir;
-          const script = [
-            "let d='';",
-            "process.stdin.setEncoding('utf-8');",
-            "process.stdin.on('data',c=>d+=c);",
-            "process.stdin.on('end',()=>{",
-            "  const input=JSON.parse(d);",
-            `  process.stdout.write(JSON.stringify({error:"Sandbox runner not yet implemented for module: ${moduleId}"}));`,
-            "});"
-          ].join("");
-          const result = child_process.execFileSync(
-            process.execPath,
-            ["-e", script],
-            {
-              input: JSON.stringify(inputData),
-              env,
-              cwd: tmpDir,
-              timeout: 3e5,
-              maxBuffer: 10 * 1024 * 1024
-            }
-          );
-          return JSON.parse(result.toString("utf-8"));
-        } catch (err) {
-          if (err instanceof Error && "killed" in err && err.killed) {
-            throw new ModuleExecutionError(
-              `Error: Module '${moduleId}' timed out in sandbox.`
-            );
+        const binaryPath = process.argv[1];
+        const child = spawn(process.execPath, [binaryPath, "--internal-sandbox-runner", moduleId], {
+          env,
+          cwd: tmpDir,
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let sizeExceeded = false;
+        const outputCap = this.maxOutputBytes;
+        child.stdout.on("data", (chunk) => {
+          if (sizeExceeded) return;
+          stdoutBytes += chunk.length;
+          if (stdoutBytes > outputCap) {
+            sizeExceeded = true;
+            child.kill("SIGKILL");
+            return;
           }
-          const stderr = err instanceof Error && "stderr" in err ? String(err.stderr) : String(err);
-          throw new ModuleExecutionError(
-            `Error: Module '${moduleId}' execution failed: ${stderr}`
-          );
-        } finally {
-          try {
-            fs4.rmSync(tmpDir, { recursive: true, force: true });
-          } catch {
+          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));
+        child.stdin.end();
+        return new Promise((resolve2, reject) => {
+          const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(
+              new ModuleExecutionError(
+                `Sandbox module '${moduleId}' timed out after ${this.timeoutSeconds}s.`
+              )
+            );
+          }, this.timeoutSeconds * 1e3);
+          child.on("close", (code) => {
+            clearTimeout(timer);
+            try {
+              rmSync(tmpDir, { recursive: true, force: true });
+            } catch {
+            }
+            if (sizeExceeded) {
+              const limitMiB = Math.floor(outputCap / (1024 * 1024));
+              reject(new ModuleExecutionError(
+                `Sandbox module '${moduleId}' output exceeded ${limitMiB}MiB limit.`
+              ));
+              return;
+            }
+            if (code !== 0) {
+              reject(new ModuleExecutionError(
+                `Sandbox module '${moduleId}' exited with code ${code}.${stderr ? ` stderr: ${stderr}` : ""}`
+              ));
+              return;
+            }
+            try {
+              resolve2(JSON.parse(stdout));
+            } catch {
+              reject(new ModuleExecutionError(
+                `Sandbox module '${moduleId}' returned non-JSON output: ${stdout.slice(0, 200)}`
+              ));
+            }
+          });
+          child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(new ModuleExecutionError(`Failed to spawn sandbox process: ${err.message}`));
+          });
+        });
       }
     };
   }
@@ -514,9 +732,9 @@ init_esm_shims();
 init_esm_shims();
 init_errors();
 import { readFileSync as readFileSync3 } from "fs";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import * as path6 from "path";
-import { Command as Command6, CommanderError, Option as Option4 } from "commander";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import * as path5 from "path";
+import { Command as Command5, CommanderError, Option as Option4 } from "commander";
 
 // src/ref-resolver.ts
 init_esm_shims();
@@ -575,6 +793,12 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
       properties: {},
       required: []
     };
+    if (typeof obj.properties === "object" && obj.properties !== null) {
+      Object.assign(merged.properties, obj.properties);
+    }
+    if (Array.isArray(obj.required)) {
+      merged.required.push(...obj.required);
+    }
     for (const subSchema of obj.allOf) {
       const resolved = resolveNode(
         subSchema,
@@ -608,6 +832,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(
@@ -628,6 +856,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++) {
@@ -635,10 +864,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;
@@ -654,7 +890,7 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
         propSchema,
         defs,
         visited,
-        depth + 1,
+        depth,
         maxDepth,
         moduleId
       );
@@ -666,6 +902,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;
@@ -698,29 +935,50 @@ function extractHelp(propSchema, maxLength = 1e3) {
   }
   return text;
 }
-var RESERVED_NAMES = /* @__PURE__ */ new Set(["input", "yes", "large_input", "format", "sandbox"]);
+var RESERVED_NAMES = /* @__PURE__ */ new Set([
+  "input",
+  "yes",
+  "large_input",
+  "format",
+  "fields",
+  "sandbox",
+  "verbose",
+  "dry_run",
+  "trace",
+  "stream",
+  "strategy",
+  "approval_timeout",
+  "approval_token"
+]);
 function schemaToCliOptions(schema, maxHelpLength = 1e3) {
   const properties = schema.properties ?? {};
   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 (flagName in flagNames) {
+    if (RESERVED_NAMES.has(propName)) {
       process.stderr.write(
-        `Error: Flag name collision: properties '${propName}' and '${flagNames[flagName]}' both map to '${flagName}'.
+        `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);
     }
-    flagNames[flagName] = propName;
-    if (RESERVED_NAMES.has(propName)) {
+    if (flagName in flagNames) {
       process.stderr.write(
-        `Error: Module schema property '${propName}' conflicts with a reserved CLI option name. Rename the property.
+        `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);
     const isRequired = requiredList.includes(propName);
     const helpBase = extractHelp(propSchema, maxHelpLength);
@@ -728,6 +986,15 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
     const defaultValue = propSchema.default;
     if (typeResult === BOOLEAN_FLAG) {
       const flagBase = propName.replace(/_/g, "-");
+      const noFlag = `--no-${flagBase}`;
+      if (noFlag in flagNames) {
+        process.stderr.write(
+          `Error: Flag name collision: boolean property '${propName}' auto-generates '${noFlag}' which is already used by property '${flagNames[noFlag]}'.
+`
+        );
+        process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
+      }
+      flagNames[noFlag] = propName;
       const defaultVal = propSchema.default ?? false;
       options.push({
         name: propName,
@@ -806,12 +1073,20 @@ function getAnnotation(annotations, key, defaultValue = void 0) {
   const ann = annotations;
   return key in ann ? ann[key] : defaultValue;
 }
+function readTimeoutFromEnv() {
+  const raw = process.env.APCORE_CLI_APPROVAL_TIMEOUT;
+  if (raw === void 0 || raw === "") return void 0;
+  const parsed = parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return void 0;
+  return parsed;
+}
 var CliApprovalHandler = class {
   autoApprove;
   timeout;
-  constructor(autoApprove = false, timeout = 60) {
+  constructor(autoApprove = false, timeout) {
     this.autoApprove = autoApprove;
-    this.timeout = Math.max(1, Math.min(timeout, 3600));
+    const resolved = timeout ?? readTimeoutFromEnv() ?? 60;
+    this.timeout = Math.max(1, Math.min(resolved, 3600));
   }
   async requestApproval(request) {
     const moduleId = request.module_id ?? "unknown";
@@ -822,6 +1097,12 @@ var CliApprovalHandler = class {
     if (envVal === "1") {
       return { status: "approved", approved_by: "env_auto_approve" };
     }
+    if (envVal !== "" && envVal !== "1") {
+      process.stderr.write(
+        `Warning: APCORE_CLI_AUTO_APPROVE is set to '${envVal}', expected '1'. Ignoring.
+`
+      );
+    }
     if (!process.stdin.isTTY) {
       return { status: "rejected", reason: "Non-interactive session without --yes" };
     }
@@ -840,7 +1121,7 @@ var CliApprovalHandler = class {
     return { status: "rejected", reason: "CLI does not support async approval polling" };
   }
 };
-async function checkApproval(moduleDef, autoApprove, timeout = 60) {
+async function checkApproval(moduleDef, autoApprove, timeout) {
   const annotations = moduleDef.annotations;
   let requiresApproval;
   if (moduleDef.requiresApproval !== void 0) {
@@ -868,13 +1149,12 @@ async function checkApproval(moduleDef, autoApprove, timeout = 60) {
     );
   }
   if (!process.stdin.isTTY) {
-    process.stderr.write(
-      `Error: Module '${moduleId}' requires approval but no interactive terminal is available. Use --yes or set APCORE_CLI_AUTO_APPROVE=1 to bypass.
-`
+    throw new ApprovalDeniedError(
+      `Module '${moduleId}' requires approval but no interactive terminal is available. Use --yes or set APCORE_CLI_AUTO_APPROVE=1 to bypass.`
     );
-    process.exit(EXIT_CODES.APPROVAL_DENIED);
   }
-  await promptWithTimeout(moduleDef, timeout);
+  const effectiveTimeout = timeout ?? readTimeoutFromEnv() ?? 60;
+  await promptWithTimeout(moduleDef, effectiveTimeout);
 }
 async function promptWithTimeout(moduleDef, timeout) {
   timeout = Math.max(1, Math.min(timeout, 3600));
@@ -889,8 +1169,8 @@ async function promptWithTimeout(moduleDef, timeout) {
   let timer;
   try {
     const answer = await Promise.race([
-      new Promise((resolve3) => {
-        rl.question("Proceed? [y/N] ", (ans) => resolve3(ans));
+      new Promise((resolve2) => {
+        rl.question("Proceed? [y/N] ", (ans) => resolve2(ans));
       }),
       new Promise((_, reject) => {
         timer = setTimeout(() => {
@@ -905,17 +1185,9 @@ async function promptWithTimeout(moduleDef, timeout) {
     if (normalized === "y" || normalized === "yes") {
       return;
     }
-    process.stderr.write("Error: Approval denied.\n");
-    process.exit(EXIT_CODES.APPROVAL_DENIED);
+    throw new ApprovalDeniedError("Approval denied");
   } catch (err) {
     if (timer) clearTimeout(timer);
-    if (err instanceof ApprovalTimeoutError) {
-      process.stderr.write(
-        `Error: Approval prompt timed out after ${timeout} seconds.
-`
-      );
-      process.exit(EXIT_CODES.APPROVAL_TIMEOUT);
-    }
     throw err;
   } finally {
     rl.close();
@@ -924,6 +1196,34 @@ async function promptWithTimeout(moduleDef, timeout) {
 
 // src/output.ts
 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);
+  return String(value);
+}
 function resolveFormat(explicitFormat) {
   if (explicitFormat !== void 0) {
     return explicitFormat;
@@ -947,7 +1247,7 @@ function formatTable(headers, rows) {
   );
   return [headerLine, sep2, ...dataLines].join("\n") + "\n";
 }
-function formatModuleList(modules, format, filterTags, showDeps = false) {
+async function formatModuleList(modules, format, filterTags, showDeps = false, exposureFilter) {
   if (format === "table") {
     if (modules.length === 0 && filterTags && filterTags.length > 0) {
       process.stdout.write(
@@ -960,13 +1260,18 @@ function formatModuleList(modules, format, filterTags, showDeps = false) {
       process.stdout.write("No modules found.\n");
       return;
     }
-    const headers = showDeps ? ["ID", "Description", "Tags", "Deps"] : ["ID", "Description", "Tags"];
+    const headers = ["ID", "Description", "Tags"];
+    if (showDeps) headers.push("Deps");
+    if (exposureFilter) headers.push("Exposure");
     const rows = modules.map((m) => {
       const base = [m.id, truncate(m.description, 80), (m.tags ?? []).join(", ")];
       if (showDeps) {
         const deps = m.dependencies;
         base.push(String(Array.isArray(deps) ? deps.length : 0));
       }
+      if (exposureFilter) {
+        base.push(exposureFilter.isExposed(m.id ?? "") ? "\u2713" : "\u2014");
+      }
       return base;
     });
     process.stdout.write(formatTable(headers, rows));
@@ -981,9 +1286,23 @@ function formatModuleList(modules, format, filterTags, showDeps = false) {
         const deps = m.dependencies;
         entry.dependency_count = Array.isArray(deps) ? deps.length : 0;
       }
+      if (exposureFilter) {
+        entry.exposed = exposureFilter.isExposed(m.id ?? "");
+      }
       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) {
@@ -997,7 +1316,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}
@@ -1068,6 +1387,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) {
@@ -1101,42 +1430,21 @@ function formatExecResult(result, format, fields) {
       const obj = effective_result;
       const keys = Object.keys(obj);
       const header = keys.map(escapeCsvField).join(",");
-      const row = keys.map((k) => escapeCsvField(String(obj[k]))).join(",");
+      const row = keys.map((k) => escapeCsvField(csvCellString(obj[k]))).join(",");
       process.stdout.write(header + "\n" + row + "\n");
     } else if (Array.isArray(effective_result) && effective_result.length > 0 && typeof effective_result[0] === "object") {
       const keys = Object.keys(effective_result[0]);
       const header = keys.map(escapeCsvField).join(",");
       const rows = effective_result.map((item) => {
         const obj = item;
-        return keys.map((k) => escapeCsvField(String(obj[k]))).join(",");
+        return keys.map((k) => escapeCsvField(csvCellString(obj[k]))).join(",");
       });
       process.stdout.write(header + "\n" + rows.join("\n") + "\n");
     } else {
       process.stdout.write(JSON.stringify(effective_result) + "\n");
     }
   } else if (effective === "yaml") {
-    if (typeof effective_result === "object" && !Array.isArray(effective_result) && effective_result !== null) {
-      const obj = effective_result;
-      const lines = Object.entries(obj).map(([k, v]) => {
-        if (v === null || v === void 0) return `${k}: null`;
-        if (typeof v === "object") return `${k}: ${JSON.stringify(v)}`;
-        return `${k}: ${v}`;
-      });
-      process.stdout.write(lines.join("\n") + "\n");
-    } else if (Array.isArray(effective_result)) {
-      for (const item of effective_result) {
-        if (typeof item === "object" && item !== null) {
-          const obj = item;
-          const lines = Object.entries(obj).map(([k, v]) => `  ${k}: ${v}`);
-          process.stdout.write("- " + lines.join("\n  ") + "\n");
-        } else {
-          process.stdout.write(`- ${item}
-`);
-        }
-      }
-    } else {
-      process.stdout.write(String(effective_result) + "\n");
-    }
+    process.stdout.write(yaml.dump(effective_result, { lineWidth: -1 }));
   } else if (effective === "jsonl") {
     if (Array.isArray(effective_result)) {
       for (const item of effective_result) {
@@ -1159,7 +1467,7 @@ function formatExecResult(result, format, fields) {
   }
 }
 function escapeCsvField(value) {
-  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+  if (value.includes(",") || value.includes('"') || value.includes("\n") || value.includes("\r")) {
     return '"' + value.replace(/"/g, '""') + '"';
   }
   return value;
@@ -1169,7 +1477,9 @@ function formatPreflightResult(result, format) {
   if (resolved === "json" || !process.stdout.isTTY) {
     const payload = {
       valid: result.valid,
-      requires_approval: result.requires_approval,
+      // JSON output key stays snake_case for cross-language CLI contract;
+      // runtime read uses camelCase to match apcore-js PreflightResult.
+      requires_approval: result.requiresApproval,
       checks: result.checks.map((c) => {
         const entry = { check: c.check, passed: c.passed };
         if (c.error !== void 0 && c.error !== null) {
@@ -1220,59 +1530,46 @@ Result: ${tag} (${errors} error(s), ${warnings} warning(s))
 }
 function firstFailedExitCode(result) {
   const checkToExit = {
-    module_id: 2,
-    module_lookup: 44,
-    call_chain: 1,
-    acl: 77,
-    schema: 45,
-    approval: 46,
-    module_preflight: 1
+    module_id: EXIT_CODES.INVALID_CLI_INPUT,
+    module_lookup: EXIT_CODES.MODULE_NOT_FOUND,
+    call_chain: EXIT_CODES.MODULE_EXECUTE_ERROR,
+    acl: EXIT_CODES.ACL_DENIED,
+    schema: EXIT_CODES.SCHEMA_VALIDATION_ERROR,
+    approval: EXIT_CODES.APPROVAL_DENIED,
+    module_preflight: EXIT_CODES.MODULE_EXECUTE_ERROR
   };
   for (const check of result.checks) {
     if (!check.passed) {
-      return checkToExit[check.check] ?? 1;
+      return checkToExit[check.check] ?? EXIT_CODES.MODULE_EXECUTE_ERROR;
     }
   }
-  return 1;
+  return EXIT_CODES.MODULE_EXECUTE_ERROR;
 }
 
-// src/logger.ts
-init_esm_shims();
-var LEVELS = { DEBUG: 0, INFO: 1, WARNING: 2, ERROR: 3 };
-var currentLevel = "WARNING";
-function setLogLevel(level) {
-  const upper = level.toUpperCase();
-  if (upper in LEVELS) {
-    currentLevel = upper;
-  }
-}
-function getLogLevel() {
-  return currentLevel;
-}
-function shouldLog(level) {
-  return LEVELS[level] >= LEVELS[currentLevel];
-}
-function debug(message) {
-  if (shouldLog("DEBUG")) process.stderr.write(`DEBUG: ${message}
-`);
-}
-function info(message) {
-  if (shouldLog("INFO")) process.stderr.write(`INFO: ${message}
-`);
-}
-function warn(message) {
-  if (shouldLog("WARNING")) process.stderr.write(`WARNING: ${message}
-`);
-}
-function error(message) {
-  if (shouldLog("ERROR")) process.stderr.write(`ERROR: ${message}
-`);
-}
+// src/main.ts
+init_logger();
 
 // src/init-cmd.ts
 init_esm_shims();
+init_errors();
 import * as fs from "fs";
 import * as path2 from "path";
+function runFsOp(op, targetPath, fn, partial) {
+  try {
+    return fn();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Error: failed to ${op} ${targetPath}: ${msg}
+`);
+    if (partial && partial.length > 0) {
+      process.stderr.write(
+        `  Partial scaffold left on disk \u2014 you may want to remove: ${partial.join(", ")}
+`
+      );
+    }
+    process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
+  }
+}
 var DECORATOR_TEMPLATE = `import { module } from "apcore-js";
 import { Type } from "@sinclair/typebox";
 
@@ -1296,7 +1593,8 @@ export function {funcName}(): Record<string, unknown> {
   return { status: "ok" };
 }
 `;
-var BINDING_TEMPLATE = `bindings:
+var BINDING_TEMPLATE = `spec_version: "1.0"
+bindings:
   - module_id: "{moduleId}"
     target: "{target}"
     description: "{description}"
@@ -1345,7 +1643,7 @@ function registerInitCommand(cli) {
   });
 }
 function createDecoratorModule(moduleId, _prefix, funcName, description, outputDir) {
-  fs.mkdirSync(outputDir, { recursive: true });
+  runFsOp("create directory", outputDir, () => fs.mkdirSync(outputDir, { recursive: true }));
   const filename = moduleId.replace(/\./g, "_") + ".ts";
   const filepath = path2.join(outputDir, filename);
   const varName = funcName + "Module";
@@ -1355,14 +1653,14 @@ function createDecoratorModule(moduleId, _prefix, funcName, description, outputD
     funcName,
     description
   });
-  fs.writeFileSync(filepath, content);
+  runFsOp("write file", filepath, () => fs.writeFileSync(filepath, content));
   process.stdout.write(`Created ${filepath}
 `);
 }
 function createConventionModule(moduleId, prefix, funcName, description, outputDir) {
   const prefixParts = prefix.split(".");
   const dirPath = prefixParts.length > 1 ? path2.join(outputDir, ...prefixParts.slice(0, -1)) : outputDir;
-  fs.mkdirSync(dirPath, { recursive: true });
+  runFsOp("create directory", dirPath, () => fs.mkdirSync(dirPath, { recursive: true }));
   let filename;
   if (prefixParts.length > 1) {
     filename = prefixParts[prefixParts.length - 1] + ".ts";
@@ -1380,12 +1678,13 @@ function createConventionModule(moduleId, prefix, funcName, description, outputD
     description,
     cliGroupLine
   });
-  fs.writeFileSync(filepath, content);
+  runFsOp("write file", filepath, () => fs.writeFileSync(filepath, content));
   process.stdout.write(`Created ${filepath}
 `);
 }
 function createBindingModule(moduleId, prefix, funcName, description, outputDir) {
-  fs.mkdirSync(outputDir, { recursive: true });
+  const partial = [];
+  runFsOp("create directory", outputDir, () => fs.mkdirSync(outputDir, { recursive: true }));
   const yamlFile = path2.join(outputDir, moduleId.replace(/\./g, "_") + ".binding.yaml");
   const target = `commands.${prefix}:${funcName}`;
   const yamlContent = renderTemplate(BINDING_TEMPLATE, {
@@ -1393,11 +1692,12 @@ function createBindingModule(moduleId, prefix, funcName, description, outputDir)
     target,
     description
   });
-  fs.writeFileSync(yamlFile, yamlContent);
+  runFsOp("write file", yamlFile, () => fs.writeFileSync(yamlFile, yamlContent));
+  partial.push(yamlFile);
   process.stdout.write(`Created ${yamlFile}
 `);
   const baseSrc = "commands";
-  fs.mkdirSync(baseSrc, { recursive: true });
+  runFsOp("create directory", baseSrc, () => fs.mkdirSync(baseSrc, { recursive: true }), partial);
   const srcFile = path2.join(baseSrc, prefix.replace(/\./g, "_") + ".ts");
   if (!fs.existsSync(srcFile)) {
     const srcContent = `export function ${funcName}(): Record<string, unknown> {
@@ -1406,7 +1706,7 @@ function createBindingModule(moduleId, prefix, funcName, description, outputDir)
   return { status: "ok" };
 }
 `;
-    fs.writeFileSync(srcFile, srcContent);
+    runFsOp("write file", srcFile, () => fs.writeFileSync(srcFile, srcContent), partial);
     process.stdout.write(`Created ${srcFile}
 `);
   }
@@ -1420,40 +1720,48 @@ function getDisplay(descriptor) {
   if (display && typeof display === "object" && !Array.isArray(display)) {
     return display;
   }
-  return {};
-}
-function getCliDisplayFields(descriptor) {
-  const display = getDisplay(descriptor);
-  const cli = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
-  const name = cli.alias ?? display.alias ?? descriptor.id;
-  const desc = cli.description ?? descriptor.description;
-  const tags = display.tags ?? descriptor.tags ?? [];
-  return [name, desc, tags];
+  const overlay = lookupBindingDisplay(descriptor.id);
+  return overlay ?? {};
 }
 
 // src/config.ts
 init_esm_shims();
+init_logger();
 import * as fs2 from "fs";
-import yaml from "js-yaml";
+import { createRequire } from "module";
+import yaml2 from "js-yaml";
 var DEFAULTS = {
   "extensions.root": "./extensions",
   "logging.level": "WARNING",
-  "sandbox.enabled": false,
-  "cli.stdin_buffer_limit": 10485760,
-  "cli.auto_approve": false,
   "cli.help_text_max_length": 1e3,
-  // Namespace-mode aliases (apcore >= 0.15.0 Config Bus)
-  "apcore-cli.stdin_buffer_limit": 10485760,
-  "apcore-cli.auto_approve": false,
-  "apcore-cli.help_text_max_length": 1e3,
-  "apcore-cli.logging_level": "WARNING",
   // FE-11 config keys
   "cli.approval_timeout": 60,
   "cli.strategy": "standard",
   "cli.group_depth": 1,
-  "apcore-cli.approval_timeout": 60,
-  "apcore-cli.strategy": "standard",
-  "apcore-cli.group_depth": 1
+  // Exposure filtering (FE-12)
+  "expose.mode": "all",
+  "expose.include": [],
+  "expose.exclude": []
+  // Builtin group visibility (FE-13) — apcli.* keys are NOT in DEFAULTS.
+  // The runtime reads them via resolveObject('apcli') (raw yaml walk) and
+  // does not use the flat-key resolve() path. Python and Rust have no such
+  // entries either. (D11-008 cleanup)
+};
+var NAMESPACE_DEFAULTS = {
+  stdin_buffer_limit: 10485760,
+  auto_approve: false,
+  help_text_max_length: 1e3,
+  logging_level: "WARNING",
+  approval_timeout: 60,
+  strategy: "standard",
+  group_depth: 1,
+  // FE-13 — builtin group visibility configuration
+  apcli: {
+    mode: null,
+    include: [],
+    exclude: [],
+    disable_env: false
+  }
 };
 var NAMESPACE_TO_LEGACY = {
   "apcore-cli.stdin_buffer_limit": "cli.stdin_buffer_limit",
@@ -1466,20 +1774,13 @@ var LEGACY_TO_NAMESPACE = Object.fromEntries(
 );
 function registerConfigNamespace() {
   try {
-    const { Config } = __require("apcore-js");
+    const nodeRequire = createRequire(import.meta.url);
+    const { Config } = nodeRequire("apcore-js");
     if (typeof Config?.registerNamespace === "function") {
       Config.registerNamespace({
         name: "apcore-cli",
         envPrefix: "APCORE_CLI",
-        defaults: {
-          stdin_buffer_limit: 10485760,
-          auto_approve: false,
-          help_text_max_length: 1e3,
-          logging_level: "WARNING",
-          approval_timeout: 60,
-          strategy: "standard",
-          group_depth: 1
-        }
+        defaults: NAMESPACE_DEFAULTS
       });
     }
   } catch {
@@ -1490,6 +1791,13 @@ var ConfigResolver = class {
   configPath;
   fileCache = null;
   fileCacheLoaded = false;
+  /**
+   * Raw parsed yaml root (pre-flatten). Populated alongside `fileCache`
+   * on load. Used by `resolveObject()` to walk nested paths without
+   * invoking `flattenDict` — see FE-13 spec §4.8 M1 note.
+   * `null` when no config file is present or parsing fails.
+   */
+  _rawConfig = null;
   constructor(cliFlags, configPath) {
     this.cliFlags = cliFlags ?? {};
     this.configPath = configPath ?? "apcore.yaml";
@@ -1498,9 +1806,8 @@ var ConfigResolver = class {
    * Resolve a single configuration key across all four tiers.
    */
   resolve(key, cliFlag, envVar) {
-    const flagKey = cliFlag ?? key;
-    if (flagKey in this.cliFlags) {
-      const value = this.cliFlags[flagKey];
+    if (cliFlag !== void 0 && cliFlag in this.cliFlags) {
+      const value = this.cliFlags[cliFlag];
       if (value !== null && value !== void 0) {
         return value;
       }
@@ -1537,6 +1844,44 @@ var ConfigResolver = class {
     }
     return this.fileCache[key];
   }
+  /**
+   * Resolve a configuration key to its raw nested value (FE-13).
+   *
+   * Unlike `resolve()`, this method does NOT flatten the yaml tree — it
+   * walks the dot-separated path directly against the parsed yaml root.
+   * This lets callers retrieve non-leaf structures (booleans, arrays,
+   * objects) such as the `apcli` visibility config, which is naturally
+   * shaped as a nested object in apcore.yaml.
+   *
+   * Semantics:
+   *   - Returns `null` when no config file is loaded or when the path is
+   *     not present / descends into a non-object node (including arrays).
+   *   - Returns the raw value (boolean / array / object / scalar) when the
+   *     full path resolves to a leaf or intermediate node.
+   *
+   * Intentionally DOES NOT consult DEFAULTS, env vars, or CLI flags — it is
+   * strictly a yaml-tree accessor. Scalar `resolve()` semantics are
+   * unaffected.
+   */
+  resolveObject(key) {
+    if (!this.fileCacheLoaded) {
+      this.fileCache = this.loadConfigFile();
+      this.fileCacheLoaded = true;
+    }
+    if (this._rawConfig == null) {
+      return null;
+    }
+    const parts = key.split(".");
+    let cur = this._rawConfig;
+    for (const p of parts) {
+      if (cur != null && typeof cur === "object" && !Array.isArray(cur) && p in cur) {
+        cur = cur[p];
+      } else {
+        return null;
+      }
+    }
+    return cur;
+  }
   /**
    * Load and flatten a YAML config file.
    */
@@ -1548,26 +1893,27 @@ var ConfigResolver = class {
       if (err instanceof Error && "code" in err && err.code === "ENOENT") {
         return null;
       }
-      console.warn(
+      warn(
         `Configuration file '${this.configPath}' is malformed, using defaults.`
       );
       return null;
     }
     let parsed;
     try {
-      parsed = yaml.load(content);
+      parsed = yaml2.load(content);
     } catch {
-      console.warn(
+      warn(
         `Configuration file '${this.configPath}' is malformed, using defaults.`
       );
       return null;
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-      console.warn(
+      warn(
         `Configuration file '${this.configPath}' is malformed, using defaults.`
       );
       return null;
     }
+    this._rawConfig = parsed;
     return this.flattenDict(parsed);
   }
   /**
@@ -1593,95 +1939,89 @@ var ConfigResolver = class {
 // src/shell.ts
 init_esm_shims();
 init_errors();
-import { readFileSync as readFileSync2 } from "fs";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import * as path3 from "path";
 import { spawnSync } from "child_process";
 import { Command, Help, Option } from "commander";
-var __dirname2 = path3.dirname(fileURLToPath2(import.meta.url));
-var SHELL_VERSION = "0.0.0";
-try {
-  const pkg = JSON.parse(readFileSync2(path3.resolve(__dirname2, "../package.json"), "utf-8"));
-  SHELL_VERSION = pkg.version;
-} catch {
-}
 function makeFunctionName(progName) {
   return "_" + progName.replace(/[^a-zA-Z0-9]/g, "_");
 }
 function shellQuote(s) {
   return "'" + s.replace(/'/g, "'\\''") + "'";
 }
-function generateBashCompletion(progName) {
+function enumerateApcliSubcommands(apcliGroup) {
+  if (!apcliGroup) return [];
+  return apcliGroup.commands.filter((c) => !isCmdHidden(c)).map((c) => c.name());
+}
+function enumerateRootCommands(program) {
+  return program.commands.filter((c) => !isCmdHidden(c)).map((c) => c.name());
+}
+function findApcliGroup(program) {
+  return program.commands.find((c) => c.name() === "apcli");
+}
+function isCmdHidden(cmd) {
+  const withHiddenFn = cmd;
+  const withHiddenField = cmd;
+  if (typeof withHiddenFn.hidden === "function") return !!withHiddenFn.hidden();
+  return !!withHiddenField._hidden;
+}
+function generateBashCompletion(progName, program) {
   const fn = makeFunctionName(progName);
   const quoted = shellQuote(progName);
-  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e "process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})" 2>/dev/null`;
-  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const ids=JSON.parse(m).map(x=>x.id);
-const g=new Set(),t=[];
-ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});
-console.log([...g].sort().concat(t.sort()).join(' '))
-" 2>/dev/null`;
-  const groupCmdsCmd = `${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const g=process.env._APCORE_GRP;
-JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
-" 2>/dev/null`;
-  return `${fn}() {
+  const apcliGroup = program ? findApcliGroup(program) : void 0;
+  const apcliVisible = apcliGroup !== void 0 && !isCmdHidden(apcliGroup);
+  const rootCmds = program ? enumerateRootCommands(program).filter(
+    (n) => n !== "apcli" || apcliVisible
+  ) : [];
+  const apcliCmds = apcliVisible ? enumerateApcliSubcommands(apcliGroup) : [];
+  const rootOpts = rootCmds.join(" ");
+  const apcliOpts = apcliCmds.join(" ");
+  let body = `${fn}() {
     local cur prev opts
     COMPREPLY=()
     cur="\${COMP_WORDS[COMP_CWORD]}"
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
     if [[ \${COMP_CWORD} -eq 1 ]]; then
-        opts="completion describe exec init list man"
-        local groups_and_top=$(${groupsAndTopCmd})
-        COMPREPLY=( $(compgen -W "\${opts} \${groups_and_top}" -- \${cur}) )
+        opts="${rootOpts}"
+        COMPREPLY=( $(compgen -W "\${opts}" -- \${cur}) )
         return 0
     fi
-
+`;
+  if (apcliVisible) {
+    body += `
     if [[ \${COMP_CWORD} -eq 2 ]]; then
-        if [[ "\${COMP_WORDS[1]}" == "exec" ]]; then
-            local modules=$(${moduleListCmd})
-            COMPREPLY=( $(compgen -W "\${modules}" -- \${cur}) )
+        if [[ "\${COMP_WORDS[1]}" == "apcli" ]]; then
+            local apcli_cmds="${apcliOpts}"
+            COMPREPLY=( $(compgen -W "\${apcli_cmds}" -- \${cur}) )
             return 0
         fi
-        export _APCORE_GRP="\${COMP_WORDS[1]}"
-        local group_cmds=$(${groupCmdsCmd})
-        COMPREPLY=( $(compgen -W "\${group_cmds}" -- \${cur}) )
-        return 0
     fi
-}
+`;
+  }
+  body += `}
 complete -F ${fn} ${quoted}
 `;
+  return body;
 }
-function generateZshCompletion(progName) {
+function generateZshCompletion(progName, program) {
   const fn = makeFunctionName(progName);
   const quoted = shellQuote(progName);
-  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e "process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})" 2>/dev/null`;
-  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const ids=JSON.parse(m).map(x=>x.id);
-const g=new Set(),t=[];
-ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});
-console.log([...g].sort().concat(t.sort()).join(' '))
-" 2>/dev/null`;
-  const groupCmdsCmd = `${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const g=process.env._APCORE_GRP;
-JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
-" 2>/dev/null`;
+  const apcliGroup = program ? findApcliGroup(program) : void 0;
+  const apcliVisible = apcliGroup !== void 0 && !isCmdHidden(apcliGroup);
+  const rootCmds = program ? enumerateRootCommands(program).filter(
+    (n) => n !== "apcli" || apcliVisible
+  ) : [];
+  const apcliCmds = apcliVisible ? enumerateApcliSubcommands(apcliGroup) : [];
+  const rootEntries = rootCmds.map((n) => `        '${n}:${n}'`).join("\n");
+  const apcliEntries = apcliCmds.map((n) => `        '${n}:${n}'`).join("\n");
   return `#compdef ${progName}
 
 ${fn}() {
     local -a commands
     commands=(
-        'list:List available modules'
-        'describe:Show module metadata and schema'
-        'completion:Generate shell completion script'
-        'init:Scaffolding commands'
-        'man:Generate man page'
-    )
+` + (rootEntries ? rootEntries + "\n" : "") + `    )
+    local -a apcli_cmds
+    apcli_cmds=(
+` + (apcliEntries ? apcliEntries + "\n" : "") + `    )
 
     _arguments -C \\
         '1:command:->command' \\
@@ -1690,22 +2030,11 @@ ${fn}() {
     case "$state" in
         command)
             _describe -t commands '${progName} commands' commands
-            local -a groups_and_top
-            groups_and_top=($(${groupsAndTopCmd}))
-            compadd -a groups_and_top
             ;;
         args)
             case "\${words[1]}" in
-                exec)
-                    local modules
-                    modules=($(${moduleListCmd}))
-                    compadd -a modules
-                    ;;
-                *)
-                    export _APCORE_GRP="\${words[1]}"
-                    local -a group_cmds
-                    group_cmds=($(${groupCmdsCmd}))
-                    compadd -a group_cmds
+                apcli)
+                    _describe -t apcli_cmds '${progName} apcli commands' apcli_cmds
                     ;;
             esac
             ;;
@@ -1715,158 +2044,30 @@ ${fn}() {
 compdef ${fn} ${quoted}
 `;
 }
-function generateFishCompletion(progName) {
+function generateFishCompletion(progName, program) {
   const quoted = shellQuote(progName);
-  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e \\"process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})\\" 2>/dev/null`;
-  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e \\"const m=require('fs').readFileSync('/dev/stdin','utf8');const ids=JSON.parse(m).map(x=>x.id);const g=new Set(),t=[];ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});console.log([...g].sort().concat(t.sort()).join('\\\\n'))\\" 2>/dev/null`;
-  return `# Fish completions for ${progName}
-complete -c ${quoted} -n "__fish_use_subcommand" -a list -d "List available modules"
-complete -c ${quoted} -n "__fish_use_subcommand" -a describe -d "Show module metadata and schema"
-complete -c ${quoted} -n "__fish_use_subcommand" -a completion -d "Generate shell completion script"
-complete -c ${quoted} -n "__fish_use_subcommand" -a init -d "Scaffolding commands"
-complete -c ${quoted} -n "__fish_use_subcommand" -a man -d "Generate man page"
-complete -c ${quoted} -n "__fish_use_subcommand" -a "(${groupsAndTopCmd})" -d "Module group"
-
-complete -c ${quoted} -n "__fish_seen_subcommand_from exec" -a "(${moduleListCmd})"
-
-function __apcore_group_cmds
-    set -l grp (commandline -opc)[2]
-    set -x _APCORE_GRP $grp
-    ${quoted} list --format json 2>/dev/null | node -e "
-const m=require('fs').readFileSync('/dev/stdin','utf8');
-const g=process.env._APCORE_GRP;
-JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
-" 2>/dev/null
-end
-
-# Group subcommand completion \u2014 matches when position 1 is not a builtin
-complete -c ${quoted} -n "not __fish_use_subcommand; and not __fish_seen_subcommand_from list describe completion init man exec" -a "(__apcore_group_cmds)"
-`;
-}
-function buildSynopsis(command, progName, commandName) {
-  if (!command) {
-    return `\\fB${progName} ${commandName}\\fR [OPTIONS]`;
-  }
-  const parts = [`\\fB${progName} ${commandName}\\fR`];
-  for (const opt of command.options) {
-    const flag = opt.long ?? opt.short ?? "";
-    if (opt.isBoolean?.()) {
-      parts.push(`[${flag}]`);
-    } else if (opt.required) {
-      const typeName = (opt.argChoices ? "CHOICE" : "VALUE").toUpperCase();
-      parts.push(`${flag} \\fI${typeName}\\fR`);
-    } else {
-      const typeName = (opt.argChoices ? "CHOICE" : "VALUE").toUpperCase();
-      parts.push(`[${flag} \\fI${typeName}\\fR]`);
-    }
-  }
-  for (const arg of command.registeredArguments ?? []) {
-    const meta = arg.name().toUpperCase();
-    if (arg.required) {
-      parts.push(`\\fI${meta}\\fR`);
-    } else {
-      parts.push(`[\\fI${meta}\\fR]`);
-    }
-  }
-  return parts.join(" ");
-}
-function generateManPage(commandName, command, progName, version = SHELL_VERSION) {
-  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  const title = `${progName}-${commandName}`.toUpperCase();
-  const pkgLabel = `${progName} ${version}`;
-  const manualLabel = `${progName} Manual`;
-  const sections = [];
-  sections.push(`.TH "${title}" "1" "${today}" "${pkgLabel}" "${manualLabel}"`);
-  sections.push(".SH NAME");
-  const desc = command?.description() ?? commandName;
-  const nameDesc = desc.split("\n")[0].replace(/\.$/, "");
-  sections.push(`${progName}-${commandName} \\- ${nameDesc}`);
-  sections.push(".SH SYNOPSIS");
-  sections.push(buildSynopsis(command, progName, commandName));
-  if (command?.description()) {
-    sections.push(".SH DESCRIPTION");
-    sections.push(
-      command.description().replace(/\\/g, "\\\\").replace(/-/g, "\\-")
+  const apcliGroup = program ? findApcliGroup(program) : void 0;
+  const apcliVisible = apcliGroup !== void 0 && !isCmdHidden(apcliGroup);
+  const rootCmds = program ? enumerateRootCommands(program).filter(
+    (n) => n !== "apcli" || apcliVisible
+  ) : [];
+  const apcliCmds = apcliVisible ? enumerateApcliSubcommands(apcliGroup) : [];
+  const lines = [];
+  lines.push(`# Fish completions for ${progName}`);
+  for (const name of rootCmds) {
+    lines.push(
+      `complete -c ${quoted} -n "__fish_use_subcommand" -a ${name} -d "${name}"`
     );
   }
-  if (command && command.options.length > 0) {
-    sections.push(".SH OPTIONS");
-    for (const opt of command.options) {
-      const flag = [opt.short, opt.long].filter(Boolean).join(", ");
-      sections.push(".TP");
-      if (opt.isBoolean?.()) {
-        sections.push(`\\fB${flag}\\fR`);
-      } else {
-        sections.push(`\\fB${flag}\\fR \\fIVALUE\\fR`);
-      }
-      if (opt.description) {
-        sections.push(opt.description);
-      }
-      if (opt.defaultValue !== void 0 && !opt.isBoolean?.()) {
-        sections.push(`Default: ${opt.defaultValue}.`);
-      }
+  if (apcliVisible && apcliCmds.length > 0) {
+    lines.push("");
+    for (const name of apcliCmds) {
+      lines.push(
+        `complete -c ${quoted} -n "__fish_seen_subcommand_from apcli" -a ${name} -d "${name}"`
+      );
     }
   }
-  sections.push(".SH ENVIRONMENT");
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_EXTENSIONS_ROOT\\fR");
-  sections.push(
-    "Path to the apcore extensions directory. Overrides the default \\fI./extensions\\fR."
-  );
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_CLI_AUTO_APPROVE\\fR");
-  sections.push(
-    "Set to \\fB1\\fR to bypass approval prompts for modules that require human-in-the-loop confirmation."
-  );
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_CLI_LOGGING_LEVEL\\fR");
-  sections.push(
-    "CLI-specific logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. Takes priority over \\fBAPCORE_LOGGING_LEVEL\\fR. Default: WARNING."
-  );
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_LOGGING_LEVEL\\fR");
-  sections.push(
-    "Global apcore logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. Used as fallback when \\fBAPCORE_CLI_LOGGING_LEVEL\\fR is not set. Default: WARNING."
-  );
-  sections.push(".TP");
-  sections.push("\\fBAPCORE_AUTH_API_KEY\\fR");
-  sections.push(
-    "API key for authenticating with the apcore registry."
-  );
-  sections.push(".SH EXIT CODES");
-  const exitCodes = [
-    ["0", "Success."],
-    ["1", "Module execution error."],
-    ["2", "Invalid CLI input or missing argument."],
-    ["44", "Module not found, disabled, or failed to load."],
-    ["45", "Input failed JSON Schema validation."],
-    [
-      "46",
-      "Approval denied, timed out, or no interactive terminal available."
-    ],
-    [
-      "47",
-      "Configuration error (extensions directory not found or unreadable)."
-    ],
-    ["48", "Schema contains a circular \\fB$ref\\fR."],
-    ["77", "ACL denied \u2014 insufficient permissions for this module."],
-    ["130", "Execution cancelled by user (SIGINT / Ctrl\\-C)."]
-  ];
-  for (const [code, meaning] of exitCodes) {
-    sections.push(`.TP
-\\fB${code}\\fR
-${meaning}`);
-  }
-  sections.push(".SH SEE ALSO");
-  sections.push(
-    [
-      `\\fB${progName}\\fR(1)`,
-      `\\fB${progName}\\-list\\fR(1)`,
-      `\\fB${progName}\\-describe\\fR(1)`,
-      `\\fB${progName}\\-completion\\fR(1)`
-    ].join(", ")
-  );
-  return sections.join("\n");
+  return lines.join("\n") + "\n";
 }
 function roffEscape(s) {
   return s.replace(/\\/g, "\\\\").replace(/-/g, "\\-").replace(/'/g, "\\(aq");
@@ -2008,10 +2209,13 @@ function configureManHelp(program, progName, version, description, docsUrl2) {
     return "";
   });
 }
-function registerShellCommands(cli, progName = "apcore-cli") {
-  const completionCmd = new Command("completion").description(
-    "Generate a shell completion script and print it to stdout."
-  ).argument("<shell>", "Shell type: bash, zsh, or fish").action((shell) => {
+function findRootProgram(host) {
+  let cur = host;
+  while (cur.parent) cur = cur.parent;
+  return cur;
+}
+function registerCompletionCommand(host) {
+  const completionCmd = new Command("completion").description("Generate a shell completion script and print it to stdout.").argument("<shell>", "Shell type: bash, zsh, or fish").action((shell) => {
     const validShells = ["bash", "zsh", "fish"];
     if (!validShells.includes(shell)) {
       process.stderr.write(
@@ -2020,36 +2224,115 @@ function registerShellCommands(cli, progName = "apcore-cli") {
       );
       process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
-    const resolved = cli.name() || progName;
+    const root = findRootProgram(host);
+    const resolved = root.name() || "apcore-cli";
     const generators = {
-      bash: () => generateBashCompletion(resolved),
-      zsh: () => generateZshCompletion(resolved),
-      fish: () => generateFishCompletion(resolved)
+      bash: () => generateBashCompletion(resolved, root),
+      zsh: () => generateZshCompletion(resolved, root),
+      fish: () => generateFishCompletion(resolved, root)
     };
     process.stdout.write(generators[shell]());
   });
-  cli.addCommand(completionCmd);
-  const manCmd = new Command("man").description("Generate a roff man page for COMMAND and print it to stdout.").argument("<command>", "Command to generate man page for").action((commandName) => {
-    const knownBuiltins = /* @__PURE__ */ new Set(["completion", "describe", "exec", "init", "list", "man"]);
-    const cmd = cli.commands.find((c) => c.name() === commandName) ?? null;
-    if (!cmd && !knownBuiltins.has(commandName)) {
-      process.stderr.write(
-        `Error: Unknown command '${commandName}'.
-`
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-    }
-    const resolved = cli.name() || progName;
-    const roff = generateManPage(commandName, cmd, resolved);
-    process.stdout.write(roff);
-  });
-  cli.addCommand(manCmd);
+  host.addCommand(completionCmd);
 }
 
 // src/discovery.ts
 init_esm_shims();
-init_errors();
 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)) {
@@ -2076,17 +2359,22 @@ function getAnnotationFlag(moduleDef, flag) {
     "readonly": "readonly",
     "streaming": "streaming",
     "cacheable": "cacheable",
-    "idempotent": "idempotent"
+    "idempotent": "idempotent",
+    "paginated": "paginated"
   };
   const attr = map[flag] ?? flag;
   return ann[attr] === true;
 }
-function registerDiscoveryCommands(cli, registry) {
-  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(
+function registerListCommand(apcliGroup, registry, exposureFilter) {
+  const listCmd = new Command2("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--flat", "Show flat list (no grouping).", false).addOption(
+    new Option2("--format <format>", "Output format.").choices(["table", "json", "csv", "yaml", "jsonl", "markdown", "skill"])
+  ).option("-s, --search <query>", "Filter by substring match on ID and description.").addOption(
     new Option2("--status <status>", "Filter by module status.").choices(["enabled", "disabled", "all"]).default("enabled")
   ).option("-a, --annotation <flag>", "Filter by annotation flag (AND logic). Repeatable.", collectAnnotation, []).addOption(
     new Option2("--sort <field>", "Sort order.").choices(["id", "calls", "errors", "latency"]).default("id")
-  ).option("--reverse", "Reverse sort order.", false).option("--deprecated", "Include deprecated modules.", false).option("--deps", "Show dependency count column.", false).action((opts) => {
+  ).option("--reverse", "Reverse sort order.", false).option("--deprecated", "Include deprecated modules.", false).option("--deps", "Show dependency count column.", false).addOption(
+    new Option2("--exposure <mode>", "Filter by exposure status.").choices(["exposed", "hidden", "all"]).default("exposed")
+  ).action((opts) => {
     for (const t of opts.tag) {
       validateTag(t);
     }
@@ -2130,21 +2418,40 @@ function registerDiscoveryCommands(cli, registry) {
       }
     }
     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.
 `
-      );
+        );
+      }
+    } else {
+      modules.sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""));
+      if (opts.reverse) {
+        modules.reverse();
+      }
+    }
+    let showExposureCol = false;
+    if (exposureFilter && opts.exposure !== "all") {
+      if (opts.exposure === "exposed") {
+        modules = modules.filter((m) => exposureFilter.isExposed(m.id ?? ""));
+      } else if (opts.exposure === "hidden") {
+        modules = modules.filter((m) => !exposureFilter.isExposed(m.id ?? ""));
+      }
     }
-    modules.sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""));
-    if (opts.reverse) {
-      modules.reverse();
+    if (opts.exposure === "all" && exposureFilter) {
+      showExposureCol = true;
     }
     const fmt = resolveFormat(opts.format);
     const filterTagsArg = opts.tag.length > 0 ? opts.tag : void 0;
-    formatModuleList(modules, fmt, filterTagsArg, opts.deps);
+    void formatModuleList(modules, fmt, filterTagsArg, opts.deps, showExposureCol ? exposureFilter : void 0);
   });
-  cli.addCommand(listCmd);
-  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) => {
+  apcliGroup.addCommand(listCmd);
+}
+function registerDescribeCommand(apcliGroup, registry) {
+  const describeCmd = new Command2("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").addOption(
+    new Option2("--format <format>", "Output format.").choices(["table", "json", "csv", "yaml", "jsonl", "markdown", "skill"])
+  ).action((moduleId, opts) => {
     validateModuleId(moduleId);
     const moduleDef = registry.getModule(moduleId);
     if (!moduleDef) {
@@ -2155,9 +2462,88 @@ function registerDiscoveryCommands(cli, registry) {
       process.exit(EXIT_CODES.MODULE_NOT_FOUND);
     }
     const fmt = resolveFormat(opts.format);
-    formatModuleDetail(moduleDef, fmt);
+    void formatModuleDetail(moduleDef, fmt);
+  });
+  apcliGroup.addCommand(describeCmd);
+}
+function registerExecCommand(apcliGroup, registry, executor) {
+  const execCmd = new Command2("exec").description("Execute a module by ID with JSON input.").argument("<module-id>", "Module ID to execute").option("--format <format>", "Output format (json, table, csv, yaml, jsonl).").option("--fields <fields>", "Comma-separated dot-paths to select from the result.").option(
+    "--input <json>",
+    "JSON object passed as input to the module. Use '-' to read JSON from stdin."
+  ).option("-y, --yes", "Auto-approve if the module declares requires_approval.", false).option(
+    "--approval-timeout <seconds>",
+    "Seconds to wait for interactive approval.",
+    parseInt
+  ).option("--sandbox", "Run module in an isolated subprocess with restricted env.", false).option("--strategy <name>", "Execution strategy (standard, parallel, sequential, etc.).").option("--trace", "Enable pipeline trace output.", false).option("--dry-run", "Validate inputs without executing the module.", false).option("--stream", "Stream output as JSONL instead of buffering.", false).action(async (moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getModule(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(`Error: Module '${moduleId}' not found.
+`);
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
+    }
+    let merged = {};
+    if (opts.input === "-") {
+      merged = await collectInput("-", {}, false);
+    } else if (opts.input !== void 0) {
+      try {
+        const parsed = JSON.parse(opts.input);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+          process.stderr.write("Error: --input JSON must be an object.\n");
+          process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+        }
+        merged = parsed;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: --input is not valid JSON: ${msg}
+`);
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      }
+    }
+    const startTime = performance.now();
+    try {
+      await checkApproval(moduleDef, opts.yes, opts.approvalTimeout);
+      if (opts.dryRun) {
+        if (executor.validate) {
+          const preflight = await executor.validate(moduleId, merged);
+          formatPreflightResult(preflight, opts.format);
+        } else {
+          process.stdout.write(JSON.stringify({ valid: true }) + "\n");
+        }
+        return;
+      }
+      let result;
+      if (opts.strategy && executor.callWithTrace) {
+        const [res] = await executor.callWithTrace(moduleId, merged, { strategy: opts.strategy });
+        result = res;
+      } else {
+        const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
+        const sandbox = new Sandbox2(opts.sandbox);
+        result = await sandbox.execute(moduleId, merged, executor);
+      }
+      const durationMs = Math.round(performance.now() - startTime);
+      const fmt = resolveFormat(opts.format);
+      formatExecResult(result, fmt, opts.fields);
+      const auditLogger = getAuditLogger();
+      if (auditLogger) {
+        auditLogger.logExecution(moduleId, merged, "success", 0, durationMs);
+      }
+    } catch (err) {
+      const exitCode = exitCodeForError(err);
+      const durationMs = Math.round(performance.now() - startTime);
+      try {
+        const auditLogger = getAuditLogger();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, durationMs);
+        }
+      } catch {
+      }
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : err}
+`);
+      process.exit(exitCode);
+    }
   });
-  cli.addCommand(describeCmd);
+  apcliGroup.addCommand(execCmd);
 }
 function registerValidateCommand(cli, registry, executor) {
   const validateCmd = new Command2("validate").description("Run preflight checks without executing a module.").argument("<module-id>", "Module ID to validate").option("--input <source>", "JSON input file or '-' for stdin.").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
@@ -2171,11 +2557,25 @@ function registerValidateCommand(cli, registry, executor) {
     const merged = opts.input ? await collectInput(opts.input, {}, false) : {};
     if (!executor.validate) {
       process.stderr.write("Error: Executor does not support validate.\n");
-      process.exit(1);
+      process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
+    }
+    try {
+      const preflight = await executor.validate(moduleId, merged);
+      formatPreflightResult(preflight, opts.format);
+      process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+    } catch (err) {
+      const exitCode = exitCodeForError(err);
+      try {
+        const auditLogger = getAuditLogger();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, 0);
+        }
+      } catch {
+      }
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : err}
+`);
+      process.exit(exitCode);
     }
-    const preflight = await executor.validate(moduleId, merged);
-    formatPreflightResult(preflight, opts.format);
-    process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
   });
   cli.addCommand(validateCmd);
 }
@@ -2183,12 +2583,34 @@ function registerValidateCommand(cli, registry, executor) {
 // src/system-cmd.ts
 init_esm_shims();
 import { Command as Command3 } from "commander";
+init_errors();
 async function callSystemModule(executor, moduleId, inputs) {
   if (executor.call) {
     return executor.call(moduleId, inputs);
   }
   return executor.execute(moduleId, inputs);
 }
+function emitResult(jsonPayload, fmt, ttyRender) {
+  if (fmt === "json" || !process.stdout.isTTY) {
+    process.stdout.write(JSON.stringify(jsonPayload, null, 2) + "\n");
+  } else {
+    ttyRender();
+  }
+}
+function emitErrorAndExit(e) {
+  process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+  process.exit(exitCodeForError(e));
+}
+async function requireApprovalForSystemCommand(moduleId, autoApprove) {
+  const syntheticModuleDef = {
+    id: moduleId,
+    name: moduleId,
+    description: `system command: ${moduleId}`,
+    annotations: { requires_approval: true }
+  };
+  await checkApproval(syntheticModuleDef, autoApprove, void 0);
+}
 function formatHealthSummaryTty(result) {
   const summary = result.summary ?? {};
   const modules = result.modules ?? [];
@@ -2277,17 +2699,7 @@ function formatUsageSummaryTty(result) {
 Total: ${totalCalls.toLocaleString()} calls | ${totalErrors.toLocaleString()} errors
 `);
 }
-async function registerSystemCommands(cli, executor) {
-  try {
-    if (executor.validate) {
-      await executor.validate("system.health.summary", {});
-    } else {
-      await callSystemModule(executor, "system.health.summary", { include_healthy: true });
-    }
-  } catch {
-    debug("System modules not available; skipping system command registration.");
-    return;
-  }
+function registerHealthCommand(apcliGroup, executor) {
   const healthCmd = new Command3("health").description("Show module health status. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed health").option("--threshold <number>", "Error rate threshold (default: 0.01).", parseFloat, 0.01).option("--all", "Include healthy modules.", false).option("--errors <count>", "Max recent errors (module detail only).", parseInt, 10).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
@@ -2296,29 +2708,21 @@ async function registerSystemCommands(cli, executor) {
           module_id: moduleId,
           error_limit: opts.errors
         });
-        if (fmt === "json" || !process.stdout.isTTY) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-        } else {
-          formatHealthModuleTty(result);
-        }
+        emitResult(result, fmt, () => formatHealthModuleTty(result));
       } else {
         const result = await callSystemModule(executor, "system.health.summary", {
           error_rate_threshold: opts.threshold,
           include_healthy: opts.all
         });
-        if (fmt === "json" || !process.stdout.isTTY) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-        } else {
-          formatHealthSummaryTty(result);
-        }
+        emitResult(result, fmt, () => formatHealthSummaryTty(result));
       }
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(healthCmd);
+  apcliGroup.addCommand(healthCmd);
+}
+function registerUsageCommand(apcliGroup, executor) {
   const usageCmd = new Command3("usage").description("Show module usage statistics. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed usage").option("--period <period>", "Time window: 1h, 24h, 7d, 30d.", "24h").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
@@ -2333,83 +2737,71 @@ async function registerSystemCommands(cli, executor) {
           period: opts.period
         });
       }
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else if (moduleId) {
-        formatExecResult(result, fmt);
-      } else {
-        formatUsageSummaryTty(result);
-      }
+      emitResult(result, fmt, () => {
+        if (moduleId) {
+          formatExecResult(result, fmt);
+        } else {
+          formatUsageSummaryTty(result);
+        }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(usageCmd);
-  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.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    if (!opts.yes) {
-      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
-    }
+  apcliGroup.addCommand(usageCmd);
+}
+function registerEnableCommand(apcliGroup, executor) {
+  const enableCmd = new Command3("enable").description("Enable a disabled module at runtime.").argument("<module-id>", "Module ID to enable").requiredOption("--reason <reason>", "Reason for enabling (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
+      await requireApprovalForSystemCommand("system.control.toggle_feature", opts.yes);
       const result = await callSystemModule(executor, "system.control.toggle_feature", {
         module_id: moduleId,
         enabled: true,
         reason: opts.reason
       });
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else {
+      emitResult(result, fmt, () => {
         process.stdout.write(`Module '${moduleId}' enabled.
   Reason: ${opts.reason}
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(enableCmd);
-  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.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    if (!opts.yes) {
-      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
-    }
+  apcliGroup.addCommand(enableCmd);
+}
+function registerDisableCommand(apcliGroup, executor) {
+  const disableCmd = new Command3("disable").description("Disable a module at runtime (calls are rejected until re-enabled).").argument("<module-id>", "Module ID to disable").requiredOption("--reason <reason>", "Reason for disabling (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
+      await requireApprovalForSystemCommand("system.control.toggle_feature", opts.yes);
       const result = await callSystemModule(executor, "system.control.toggle_feature", {
         module_id: moduleId,
         enabled: false,
         reason: opts.reason
       });
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else {
+      emitResult(result, fmt, () => {
         process.stdout.write(`Module '${moduleId}' disabled.
   Reason: ${opts.reason}
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(disableCmd);
-  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.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    if (!opts.yes) {
-      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
-    }
+  apcliGroup.addCommand(disableCmd);
+}
+function registerReloadCommand(apcliGroup, executor) {
+  const reloadCmd = new Command3("reload").description("Hot-reload a module from disk.").argument("<module-id>", "Module ID to reload").requiredOption("--reason <reason>", "Reason for reload (required for audit).").option("-y, --yes", "Skip approval prompt (audit D11-B-001 cross-SDK parity).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
+      await requireApprovalForSystemCommand("system.control.reload_module", opts.yes);
       const result = await callSystemModule(executor, "system.control.reload_module", {
         module_id: moduleId,
         reason: opts.reason
       });
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else {
+      emitResult(result, fmt, () => {
         const prev = result.previous_version ?? "?";
         const newVer = result.new_version ?? "?";
         const dur = result.reload_duration_ms ?? "?";
@@ -2419,34 +2811,30 @@ async function registerSystemCommands(cli, executor) {
 `);
         process.stdout.write(`  Duration: ${dur}ms
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(reloadCmd);
+  apcliGroup.addCommand(reloadCmd);
+}
+function registerConfigCommand(apcliGroup, executor) {
   const configGroup = new Command3("config").description("Read or update runtime configuration.");
   const configGetCmd = new Command3("get").description("Read a configuration value by dot-path key.").argument("<key>", "Configuration key (dot-path)").option("--format <format>", "Output format.", "table").action(async (key, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
       const result = await callSystemModule(executor, "system.config.get", { key });
       const value = result?.value ?? result;
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify({ key, value }, null, 2) + "\n");
-      } else {
+      emitResult({ key, value }, fmt, () => {
         process.stdout.write(`${key} = ${JSON.stringify(value)}
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
   configGroup.addCommand(configGetCmd);
-  const configSetCmd = new Command3("set").description("Update a runtime configuration value (requires approval).").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 {
@@ -2455,14 +2843,13 @@ async function registerSystemCommands(cli, executor) {
       parsedValue = value;
     }
     try {
+      await requireApprovalForSystemCommand("system.control.update_config", opts.yes);
       const result = await callSystemModule(executor, "system.control.update_config", {
         key,
         value: parsedValue,
         reason: opts.reason
       });
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else {
+      emitResult(result, fmt, () => {
         const old = result.old_value ?? "?";
         const newVal = result.new_value ?? "?";
         process.stdout.write(`Config updated: ${key}
@@ -2471,20 +2858,40 @@ async function registerSystemCommands(cli, executor) {
 `);
         process.stdout.write(`  Reason: ${opts.reason}
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
   configGroup.addCommand(configSetCmd);
-  cli.addCommand(configGroup);
+  apcliGroup.addCommand(configGroup);
 }
 
 // src/strategy.ts
 init_esm_shims();
 import { Command as Command4, Option as Option3 } from "commander";
+function lookupStrategyInfo(executor, strategyName) {
+  if (typeof executor.describePipeline === "function") {
+    try {
+      const current = executor.describePipeline();
+      if (current && current.name === strategyName) {
+        return { info: current, isCurrent: true };
+      }
+    } catch {
+    }
+  }
+  const ctor = executor.constructor;
+  if (ctor && typeof ctor.listStrategies === "function") {
+    try {
+      const all = ctor.listStrategies();
+      const info = all.find((s) => s.name === strategyName) ?? null;
+      return { info, isCurrent: false };
+    } catch {
+      return { info: null, isCurrent: false };
+    }
+  }
+  return { info: null, isCurrent: false };
+}
 var PRESET_STEPS = {
   standard: [
     "context_creation",
@@ -2543,87 +2950,84 @@ function registerPipelineCommand(cli, executor) {
     new Option3("--strategy <name>", "Strategy to describe (default: standard).").choices(["standard", "internal", "testing", "performance", "minimal"]).default("standard")
   ).option("--format <format>", "Output format.").action((opts) => {
     const fmt = resolveFormat(opts.format);
-    let strategyObj = null;
-    const ex = executor;
-    if (typeof ex._resolve_strategy_name === "function" || typeof ex._resolveStrategyName === "function") {
-      try {
-        const fn = ex._resolve_strategy_name ?? ex._resolveStrategyName;
-        strategyObj = fn(opts.strategy);
-      } catch {
-        strategyObj = null;
-      }
-    }
-    if (!strategyObj) {
-      const steps = PRESET_STEPS[opts.strategy] ?? [];
-      const pureSteps = /* @__PURE__ */ new Set([
-        "context_creation",
-        "call_chain_guard",
-        "module_lookup",
-        "acl_check",
-        "input_validation"
-      ]);
-      const nonRemovable = /* @__PURE__ */ new Set([
-        "context_creation",
-        "module_lookup",
-        "execute",
-        "return_result"
-      ]);
+    const { info, isCurrent } = lookupStrategyInfo(executor, opts.strategy);
+    if (info) {
+      const strategySteps = isCurrent ? executor.currentStrategy?.steps ?? [] : [];
+      const header = `Pipeline: ${info.name} (${info.stepCount} steps)`;
       if (fmt === "json" || !process.stdout.isTTY) {
         const payload = {
-          strategy: opts.strategy,
-          step_count: steps.length,
-          steps: steps.map((s, i) => ({
-            index: i + 1,
-            name: s,
-            pure: pureSteps.has(s),
-            removable: !nonRemovable.has(s)
-          }))
+          strategy: info.name,
+          step_count: info.stepCount,
+          description: info.description,
+          steps: info.stepNames.map((name, i) => {
+            const stepMeta = strategySteps[i];
+            return {
+              index: i + 1,
+              name,
+              pure: stepMeta?.pure ?? false,
+              removable: stepMeta?.removable ?? true,
+              timeout_ms: stepMeta?.timeoutMs ?? null
+            };
+          })
         };
         process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
       } else {
-        process.stdout.write(`Pipeline: ${opts.strategy} (${steps.length} steps)
+        process.stdout.write(`${header}
 
 `);
         process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
 `);
         process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
 `);
-        for (let i = 0; i < steps.length; i++) {
-          const pure = pureSteps.has(steps[i]) ? "yes" : "no";
-          const removable = nonRemovable.has(steps[i]) ? "no" : "yes";
-          process.stdout.write(`  ${String(i + 1).padEnd(4)} ${steps[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} \u2014
+        for (let i = 0; i < info.stepNames.length; i++) {
+          const stepMeta = strategySteps[i];
+          const pure = stepMeta?.pure ? "yes" : "no";
+          const removable = stepMeta?.removable !== false ? "yes" : "no";
+          const timeout = stepMeta?.timeoutMs ? `${stepMeta.timeoutMs}ms` : "\u2014";
+          process.stdout.write(`  ${String(i + 1).padEnd(4)} ${info.stepNames[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} ${timeout}
 `);
         }
       }
       return;
     }
-    const stepsInfo = strategyObj.steps.map((step) => ({
-      name: step.name,
-      pure: step.pure ?? false,
-      removable: step.removable ?? true,
-      timeout_ms: step.timeout_ms ?? null
-    }));
+    const steps = PRESET_STEPS[opts.strategy] ?? [];
+    const pureSteps = /* @__PURE__ */ new Set([
+      "context_creation",
+      "call_chain_guard",
+      "module_lookup",
+      "acl_check",
+      "input_validation"
+    ]);
+    const nonRemovable = /* @__PURE__ */ new Set([
+      "context_creation",
+      "module_lookup",
+      "execute",
+      "return_result"
+    ]);
     if (fmt === "json" || !process.stdout.isTTY) {
       const payload = {
         strategy: opts.strategy,
-        step_count: stepsInfo.length,
-        steps: stepsInfo.map((s, i) => ({ index: i + 1, ...s }))
+        step_count: steps.length,
+        steps: steps.map((s, i) => ({
+          index: i + 1,
+          name: s,
+          pure: pureSteps.has(s),
+          removable: !nonRemovable.has(s)
+        }))
       };
       process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
     } else {
-      process.stdout.write(`Pipeline: ${opts.strategy} (${stepsInfo.length} steps)
+      process.stdout.write(`Pipeline: ${opts.strategy} (${steps.length} steps)
 
 `);
       process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
 `);
       process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
 `);
-      for (let i = 0; i < stepsInfo.length; i++) {
-        const s = stepsInfo[i];
-        const pure = s.pure ? "yes" : "no";
-        const removable = s.removable ? "yes" : "no";
-        const timeout = s.timeout_ms !== null ? `${s.timeout_ms}ms` : "\u2014";
-        process.stdout.write(`  ${String(i + 1).padEnd(4)} ${s.name.padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} ${timeout}
+      for (let i = 0; i < steps.length; i++) {
+        const pure = pureSteps.has(steps[i]) ? "yes" : "no";
+        const removable = nonRemovable.has(steps[i]) ? "no" : "yes";
+        process.stdout.write(`  ${String(i + 1).padEnd(4)} ${steps[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} \u2014
 `);
       }
     }
@@ -2631,333 +3035,596 @@ function registerPipelineCommand(cli, executor) {
   cli.addCommand(pipelineCmd);
 }
 
-// src/cli.ts
+// src/builtin-group.ts
 init_esm_shims();
-import { Command as Command5 } from "commander";
-var BUILTIN_COMMANDS = [
-  "completion",
-  "config",
+init_errors();
+init_logger();
+var ApcliGroupError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ApcliGroupError";
+  }
+};
+var DEFAULT_BUILTIN_GROUP_NAME = "apcli";
+var RESERVED_GROUP_NAMES = /* @__PURE__ */ new Set([DEFAULT_BUILTIN_GROUP_NAME]);
+var _effectiveReservedNames = RESERVED_GROUP_NAMES;
+function getReservedGroupNames() {
+  return _effectiveReservedNames;
+}
+function setReservedGroupNames(names) {
+  _effectiveReservedNames = names;
+}
+var _NAME_REGEX = /^[a-z][a-z0-9_-]*$/;
+function _validateBuiltinGroupName(name) {
+  if (!name || !_NAME_REGEX.test(name)) {
+    throw new ApcliGroupError(
+      `builtinGroupName ${JSON.stringify(name)} must match /^[a-z][a-z0-9_-]*$/ (non-empty, lowercase, alphanumeric + '_' / '-', leading letter).`
+    );
+  }
+}
+var VALID_USER_MODES = /* @__PURE__ */ new Set([
+  "all",
+  "none",
+  "include",
+  "exclude"
+]);
+var APCLI_SUBCOMMAND_NAMES = /* @__PURE__ */ new Set([
+  "list",
   "describe",
-  "describe-pipeline",
-  "disable",
-  "enable",
   "exec",
-  "health",
+  "validate",
   "init",
-  "list",
-  "man",
-  "reload",
+  "health",
   "usage",
-  "validate"
-];
-var LazyModuleGroup = class {
-  registry;
-  executor;
-  helpTextMaxLength;
-  commandCache = /* @__PURE__ */ new Map();
-  /** alias -> canonical module_id (populated lazily) */
-  aliasMap = /* @__PURE__ */ new Map();
-  /** module_id -> descriptor cache (populated during alias map build) */
-  descriptorCache = /* @__PURE__ */ new Map();
-  aliasMapBuilt = false;
-  constructor(registry, executor, helpTextMaxLength = 1e3) {
-    this.registry = registry;
-    this.executor = executor;
-    this.helpTextMaxLength = helpTextMaxLength;
+  "enable",
+  "disable",
+  "reload",
+  "config",
+  "completion",
+  "describe-pipeline"
+]);
+var ApcliGroup = class _ApcliGroup {
+  _mode;
+  _include;
+  _exclude;
+  _disableEnv;
+  _registryInjected;
+  _fromCliConfig;
+  _name;
+  constructor(init) {
+    this._mode = init.mode;
+    this._include = init.include;
+    this._exclude = init.exclude;
+    this._disableEnv = init.disableEnv;
+    this._registryInjected = init.registryInjected;
+    this._fromCliConfig = init.fromCliConfig;
+    this._name = init.name;
   }
   /**
-   * Build alias->module_id map from display overlay metadata.
+   * 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).
    */
-  buildAliasMap() {
-    if (this.aliasMapBuilt) {
-      return;
-    }
-    try {
-      for (const descriptor of this.registry.listModules()) {
-        const moduleId = descriptor.id;
-        this.descriptorCache.set(moduleId, descriptor);
-        const display = getDisplay(descriptor);
-        const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
-        const cliAlias = cliDisplay.alias;
-        if (cliAlias && cliAlias !== moduleId) {
-          this.aliasMap.set(cliAlias, moduleId);
-        }
-      }
-      this.aliasMapBuilt = true;
-    } catch {
-      warn("Failed to build alias map from registry");
+  get name() {
+    return this._name;
+  }
+  /**
+   * Tier 1 constructor — config came from `createCli({ apcli })`.
+   *
+   * A non-auto mode from this tier wins over env var and yaml.
+   */
+  static fromCliConfig(config, opts) {
+    return _ApcliGroup._build(
+      config,
+      opts,
+      /*fromCliConfig*/
+      true
+    );
+  }
+  /**
+   * Tier 3 constructor — config came from `apcore.yaml`.
+   *
+   * Env var (Tier 2) may override the yaml-supplied mode.
+   */
+  static fromYaml(config, opts) {
+    if (config !== null && config !== void 0 && typeof config !== "boolean" && (typeof config !== "object" || Array.isArray(config))) {
+      const got = Array.isArray(config) ? "array" : typeof config;
+      warn(
+        `apcore.yaml apcli has unexpected type ${got}; using auto-detect.`
+      );
+      return _ApcliGroup._build(
+        void 0,
+        opts,
+        /*fromCliConfig*/
+        false
+      );
     }
+    return _ApcliGroup._build(
+      config,
+      opts,
+      /*fromCliConfig*/
+      false
+    );
   }
   /**
-   * List all available command names from the Registry.
+   * Non-panicking Tier 3 factory (A-001 parity with Rust's `try_from_yaml`).
+   * Returns `[instance, null]` on success or `[null, errorMessage]` on invalid input.
+   * Use this in programmatic contexts where throwing/exiting is unwanted.
    */
-  listCommands() {
-    this.buildAliasMap();
-    const reverse = /* @__PURE__ */ new Map();
-    for (const [alias, moduleId] of this.aliasMap) {
-      reverse.set(moduleId, alias);
+  static tryFromYaml(config, opts) {
+    if (config !== null && config !== void 0 && typeof config !== "boolean" && (typeof config !== "object" || Array.isArray(config))) {
+      const got = Array.isArray(config) ? "array" : typeof config;
+      return [
+        null,
+        `apcore.yaml 'apcli:' must be a bool, object, or null; got ${got}`
+      ];
     }
-    const moduleIds = this.registry.listModules().map((m) => m.id);
-    const names = moduleIds.map((mid) => reverse.get(mid) ?? mid);
-    return [...new Set(names)].sort();
+    if (config !== null && config !== void 0 && typeof config === "object" && !Array.isArray(config)) {
+      const mode = config["mode"];
+      if (mode !== void 0 && mode !== null) {
+        const validModes = ["all", "none", "include", "exclude"];
+        if (typeof mode !== "string" || !validModes.includes(mode)) {
+          return [null, `Invalid apcli mode: '${mode}'. Must be one of: all, none, include, exclude.`];
+        }
+      }
+    }
+    return [_ApcliGroup.fromYaml(config, opts), null];
   }
-  /**
-   * Get or lazily build a Commander Command for the given module.
-   */
-  getCommand(cmdName) {
-    if (this.commandCache.has(cmdName)) {
-      return this.commandCache.get(cmdName);
+  // -------------------------------------------------------------------------
+  // Internal builder — shared by both factories
+  // -------------------------------------------------------------------------
+  static _build(config, opts, fromCliConfig) {
+    const name = opts.name ?? DEFAULT_BUILTIN_GROUP_NAME;
+    _validateBuiltinGroupName(name);
+    if (config === true) {
+      return new _ApcliGroup({
+        mode: "all",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig,
+        name
+      });
     }
-    this.buildAliasMap();
-    const moduleId = this.aliasMap.get(cmdName) ?? cmdName;
-    let moduleDef = this.descriptorCache.get(moduleId);
-    if (!moduleDef) {
-      moduleDef = this.registry.getModule(moduleId) ?? void 0;
+    if (config === false) {
+      return new _ApcliGroup({
+        mode: "none",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig,
+        name
+      });
     }
-    if (!moduleDef) {
-      return null;
+    if (config === void 0 || config === null) {
+      return new _ApcliGroup({
+        mode: "auto",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig,
+        name
+      });
     }
-    const cmd = buildModuleCommand(moduleDef, this.executor, this.helpTextMaxLength, cmdName);
-    this.commandCache.set(cmdName, cmd);
-    return cmd;
-  }
-};
-var LazyGroup = class {
-  members;
-  _executor;
-  _helpTextMaxLength;
-  _cmdCache = /* @__PURE__ */ new Map();
-  command;
-  constructor(members, executor, name, helpTextMaxLength = 1e3) {
-    this.members = members;
-    this._executor = executor;
-    this._helpTextMaxLength = helpTextMaxLength;
-    this.command = new Command5(name).description(`${name} commands`);
-    for (const [cmdName, [, descriptor]] of this.members) {
-      const cmd = buildModuleCommand(
-        descriptor,
-        this._executor,
-        this._helpTextMaxLength,
-        cmdName
+    if (typeof config !== "object" || Array.isArray(config)) {
+      process.stderr.write(
+        `Error: apcli config must be a boolean or object; got ${Array.isArray(config) ? "array" : typeof config}.
+`
       );
-      this._cmdCache.set(cmdName, cmd);
-      this.command.addCommand(cmd);
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
-  }
-  listCommands() {
-    return [...this.members.keys()].sort();
-  }
-  getCommand(cmdName) {
-    if (this._cmdCache.has(cmdName)) {
-      return this._cmdCache.get(cmdName);
+    const cfg = config;
+    let mode;
+    if (cfg.mode === void 0 || cfg.mode === null) {
+      mode = "auto";
+    } else if (typeof cfg.mode !== "string") {
+      process.stderr.write(
+        `Error: apcli.mode must be a string; got ${typeof cfg.mode}. Expected one of all|none|include|exclude.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    } else if (!VALID_USER_MODES.has(cfg.mode)) {
+      process.stderr.write(
+        `Error: apcli.mode '${cfg.mode}' is invalid. Expected one of all|none|include|exclude.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    } else {
+      mode = cfg.mode;
     }
-    const entry = this.members.get(cmdName);
-    if (!entry) {
-      return null;
+    const include = _ApcliGroup._normalizeList(cfg.include, "include");
+    const exclude = _ApcliGroup._normalizeList(cfg.exclude, "exclude");
+    const rawDisableEnv = cfg.disableEnv !== void 0 ? cfg.disableEnv : cfg["disable_env"];
+    let disableEnv = false;
+    if (rawDisableEnv !== void 0) {
+      if (typeof rawDisableEnv === "boolean") {
+        disableEnv = rawDisableEnv;
+      } else {
+        warn(
+          `apcli.disable_env must be boolean; got ${typeof rawDisableEnv}. Treating as false.`
+        );
+      }
     }
-    const [, descriptor] = entry;
-    const cmd = buildModuleCommand(
-      descriptor,
-      this._executor,
-      this._helpTextMaxLength,
-      cmdName
-    );
-    this._cmdCache.set(cmdName, cmd);
-    return cmd;
+    return new _ApcliGroup({
+      mode,
+      include,
+      exclude,
+      disableEnv,
+      registryInjected: opts.registryInjected,
+      fromCliConfig,
+      name
+    });
   }
-};
-var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
-  /** groupName -> { cmdName -> [moduleId, descriptor] } */
-  groupMap = /* @__PURE__ */ new Map();
-  /** cmdName -> [moduleId, descriptor] for top-level (ungrouped) modules */
-  topLevelModules = /* @__PURE__ */ new Map();
-  /** Cached LazyGroup instances */
-  groupCache = /* @__PURE__ */ new Map();
-  groupMapBuilt = false;
   /**
-   * Determine (groupName | null, commandName) for a module from its display overlay.
+   * Normalize an include/exclude list. Non-array → warn and return [].
    *
-   * @param groupDepth  Number of dotted segments to consume as the group prefix.
-   *                    Defaults to 1 (e.g., "math.add" → group="math", cmd="add").
-   *                    Set to 2 for multi-level grouping (e.g., "math.trig.sin" →
-   *                    group="math.trig", cmd="sin").
+   * Unknown but well-formed entries emit a WARNING (spec §7 error table,
+   * T-APCLI-25) but are retained in the returned list for forward-compat —
+   * if apcore-cli later adds a subcommand named `foo`, existing configs
+   * continue to work without a config change. At runtime, unknown names
+   * simply never match any registered subcommand.
    */
-  static resolveGroup(moduleId, descriptor, groupDepth = 1) {
-    if (!moduleId) {
-      warn("Empty module_id encountered in resolveGroup");
-      return [null, ""];
-    }
-    const display = getDisplay(descriptor);
-    const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
-    const explicitGroup = cliDisplay.group;
-    if (typeof explicitGroup === "string" && explicitGroup !== "") {
-      return [explicitGroup, cliDisplay.alias ?? moduleId];
-    }
-    if (explicitGroup === "") {
-      return [null, cliDisplay.alias ?? moduleId];
+  static _normalizeList(raw, label) {
+    if (raw === void 0 || raw === null) return [];
+    if (!Array.isArray(raw)) {
+      warn(`apcli.${label} must be a list; got ${typeof raw}. Ignoring.`);
+      return [];
     }
-    const cliName = cliDisplay.alias ?? moduleId;
-    if (cliName.includes(".")) {
-      const parts = cliName.split(".");
-      const depth = Math.max(1, Math.min(groupDepth, parts.length - 1));
-      const group = parts.slice(0, depth).join(".");
-      const cmd = parts.slice(depth).join(".");
-      return [group, cmd];
+    const out = [];
+    for (const entry of raw) {
+      if (typeof entry === "string" && entry.length > 0) {
+        if (!APCLI_SUBCOMMAND_NAMES.has(entry)) {
+          warn(
+            `Unknown apcli subcommand '${entry}' in ${label} list \u2014 ignoring.`
+          );
+        }
+        out.push(entry);
+      } else {
+        warn(`apcli.${label} contains non-string entry; skipping.`);
+      }
     }
-    return [null, cliName];
+    return out;
   }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
   /**
-   * Build the group map from registry modules.
+   * Resolve effective visibility mode after applying tier precedence.
+   *
+   * Returns one of `"all" | "none" | "include" | "exclude"` — never `"auto"`.
+   *
+   * Tier order (spec §4.4):
+   *   1. CliConfig non-auto wins outright.
+   *   2. `APCORE_CLI_APCLI` env var (unless sealed by disableEnv).
+   *   3. yaml non-auto.
+   *   4. Auto-detect from registryInjected.
    */
-  buildGroupMap() {
-    if (this.groupMapBuilt) {
-      return;
+  resolveVisibility() {
+    if (this._fromCliConfig && this._mode !== "auto") {
+      return this._mode;
     }
-    try {
-      this.buildAliasMap();
-      for (const descriptor of this.registry.listModules()) {
-        const moduleId = descriptor.id;
-        const cached = this.descriptorCache.get(moduleId);
-        if (!cached) {
-          continue;
-        }
-        const [group, cmd] = _GroupedModuleGroup.resolveGroup(moduleId, cached);
-        if (group === null) {
-          this.topLevelModules.set(cmd, [moduleId, cached]);
-        } else if (!/^[a-z][a-z0-9_-]*$/.test(group)) {
-          warn(
-            `Module '${moduleId}': group name '${group}' is not shell-safe \u2014 treating as top-level.`
-          );
-          this.topLevelModules.set(cmd, [moduleId, cached]);
-        } else {
-          if (!this.groupMap.has(group)) {
-            this.groupMap.set(group, /* @__PURE__ */ new Map());
-          }
-          this.groupMap.get(group).set(cmd, [moduleId, cached]);
-        }
-      }
-      for (const groupName of this.groupMap.keys()) {
-        if (BUILTIN_COMMANDS.includes(groupName)) {
-          warn(
-            `Group name '${groupName}' collides with a built-in command and will be ignored`
-          );
-        }
+    if (!this._disableEnv) {
+      const envMode = this._parseEnv(process.env.APCORE_CLI_APCLI);
+      if (envMode !== null) {
+        return envMode;
       }
-      this.groupMapBuilt = true;
-    } catch {
-      warn("Failed to build group map");
     }
+    if (this._mode !== "auto") {
+      return this._mode;
+    }
+    return this._registryInjected ? "none" : "all";
   }
   /**
-   * List all available command names: builtins + group names + top-level module names.
+   * True iff `subcommand` passes the include/exclude filter.
+   *
+   * Callers MUST first check {@link resolveVisibility} — this method throws
+   * under modes `"all"` or `"none"` (caller bug per spec §4.6).
    */
-  listCommands() {
-    this.buildGroupMap();
-    const groupNames = [...this.groupMap.keys()].filter(
-      (g) => !BUILTIN_COMMANDS.includes(g)
+  isSubcommandIncluded(subcommand) {
+    const mode = this.resolveVisibility();
+    if (mode === "include") return this._include.includes(subcommand);
+    if (mode === "exclude") return !this._exclude.includes(subcommand);
+    throw new Error(
+      `isSubcommandIncluded called under mode '${mode}'; caller should bypass.`
     );
-    const topNames = [...this.topLevelModules.keys()];
-    return [.../* @__PURE__ */ new Set([...BUILTIN_COMMANDS, ...groupNames, ...topNames])].sort();
   }
+  /** True iff the `apcli` group itself should appear in root `--help`. */
+  isGroupVisible() {
+    return this.resolveVisibility() !== "none";
+  }
+  // -------------------------------------------------------------------------
+  // Env parser (Tier 2) — co-located per spec §4.4
+  // -------------------------------------------------------------------------
   /**
-   * Get a command by name: check builtins -> group cache -> group map -> top-level modules.
+   * Parse APCORE_CLI_APCLI. Case-insensitive.
+   *
+   * - `show` / `1` / `true` → `"all"`
+   * - `hide` / `0` / `false` → `"none"`
+   * - Empty / unset → `null`
+   * - Anything else → warn and return `null`
    */
-  getCommand(cmdName) {
-    this.buildGroupMap();
-    if (this.groupCache.has(cmdName)) {
-      return this.groupCache.get(cmdName).command;
+  _parseEnv(raw) {
+    if (raw === void 0 || raw === "") return null;
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "") return null;
+    if (normalized === "show" || normalized === "1" || normalized === "true") {
+      return "all";
     }
-    if (this.groupMap.has(cmdName)) {
-      const lazyGrp = new LazyGroup(
-        this.groupMap.get(cmdName),
-        this.executor,
-        cmdName,
-        this.helpTextMaxLength
-      );
-      this.groupCache.set(cmdName, lazyGrp);
-      return lazyGrp.command;
+    if (normalized === "hide" || normalized === "0" || normalized === "false") {
+      return "none";
     }
-    if (this.topLevelModules.has(cmdName)) {
-      if (this.commandCache.has(cmdName)) {
-        return this.commandCache.get(cmdName);
-      }
-      const [, descriptor] = this.topLevelModules.get(cmdName);
-      const cmd = buildModuleCommand(
-        descriptor,
-        this.executor,
-        this.helpTextMaxLength,
-        cmdName
+    warn(
+      `Unknown APCORE_CLI_APCLI value '${raw}', ignoring. Expected: show, hide, 1, 0, true, false.`
+    );
+    return null;
+  }
+};
+
+// src/exposure.ts
+init_esm_shims();
+init_logger();
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function compilePattern(pattern) {
+  const sentinel = "\0GLOB\0";
+  const escaped = pattern.replaceAll("**", sentinel);
+  const parts = escaped.split("*");
+  const regexParts = parts.map((p) => {
+    const restored = p.replaceAll(sentinel, "**");
+    return escapeRegex(restored);
+  });
+  let regex = regexParts.join("[^.]*");
+  regex = regex.replaceAll("\\*\\*", ".+");
+  return new RegExp(`^${regex}$`);
+}
+var ExposureFilter = class _ExposureFilter {
+  static VALID_MODES = ["all", "include", "exclude", "none"];
+  _mode;
+  _compiledInclude;
+  _compiledExclude;
+  constructor(mode = "all", include, exclude) {
+    if (!_ExposureFilter.VALID_MODES.includes(mode)) {
+      process.stderr.write(
+        `Warning: Unknown ExposureFilter mode '${mode}' \u2014 defaulting to 'none'. Valid modes: ${_ExposureFilter.VALID_MODES.join(", ")}.
+`
       );
-      this.commandCache.set(cmdName, cmd);
-      return cmd;
+      mode = "none";
     }
-    return null;
+    this._mode = mode;
+    const dedup = (arr) => [...new Set(arr)];
+    this._compiledInclude = dedup(include ?? []).map(compilePattern);
+    this._compiledExclude = dedup(exclude ?? []).map(compilePattern);
   }
-  /** Expose groupMap for testing. */
-  getGroupMap() {
-    return this.groupMap;
+  /** Return true if the module should be exposed as a CLI command. */
+  isExposed(moduleId) {
+    if (this._mode === "all") return true;
+    if (this._mode === "include") {
+      return this._compiledInclude.some((rx) => rx.test(moduleId));
+    }
+    if (this._mode === "exclude") {
+      return !this._compiledExclude.some((rx) => rx.test(moduleId));
+    }
+    return false;
   }
-  /** Expose topLevelModules for testing. */
-  getTopLevelModules() {
-    return this.topLevelModules;
+  /** Partition moduleIds into [exposed, hidden] lists. */
+  filterModules(moduleIds) {
+    const exposed = [];
+    const hidden = [];
+    for (const mid of moduleIds) {
+      (this.isExposed(mid) ? exposed : hidden).push(mid);
+    }
+    return [exposed, hidden];
   }
-  /** Expose groupMapBuilt for testing. */
-  isGroupMapBuilt() {
-    return this.groupMapBuilt;
+  /**
+   * Create an ExposureFilter from a parsed config dict.
+   *
+   * Expected: `{ expose: { mode: "include", include: ["admin.*"] } }`
+   */
+  static fromConfig(config) {
+    const expose = config.expose ?? {};
+    if (typeof expose !== "object" || expose === null || Array.isArray(expose)) {
+      warn("Invalid 'expose' config (expected dict), using mode: all.");
+      return new _ExposureFilter();
+    }
+    const exposeObj = expose;
+    const mode = exposeObj.mode ?? "all";
+    if (!["all", "include", "exclude"].includes(mode)) {
+      throw new Error(
+        `Invalid expose mode: '${mode}'. Must be one of: all, include, exclude.`
+      );
+    }
+    let include = exposeObj.include ?? [];
+    if (!Array.isArray(include)) {
+      warn("Invalid 'expose.include' (expected list), ignoring.");
+      include = [];
+    }
+    let exclude = exposeObj.exclude ?? [];
+    if (!Array.isArray(exclude)) {
+      warn("Invalid 'expose.exclude' (expected list), ignoring.");
+      exclude = [];
+    }
+    const filterList = (arr, label) => {
+      const result = [];
+      for (const p of arr) {
+        if (!p) {
+          warn(`Empty pattern in expose.${label}, skipping.`);
+        } else {
+          result.push(String(p));
+        }
+      }
+      return result;
+    };
+    return new _ExposureFilter(
+      mode,
+      filterList(include, "include"),
+      filterList(exclude, "exclude")
+    );
   }
 };
 
 // src/main.ts
-var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
-var verboseHelp = false;
-function setVerboseHelp(verbose) {
-  verboseHelp = verbose;
+init_audit();
+
+// src/canonical-help.ts
+init_esm_shims();
+function resolveHelpText(cmd, section) {
+  const bag = cmd._helpText;
+  const v = bag?.[section];
+  if (typeof v === "function") return v({ error: false, command: cmd });
+  return v ?? "";
 }
-var docsUrl = null;
-function setDocsUrl(url) {
-  docsUrl = url;
+function uppercasePlaceholders(flags) {
+  return flags.replace(/<([a-zA-Z0-9_-]+)>/g, (_, name) => `<${name.toUpperCase()}>`).replace(/\[([a-zA-Z0-9_-]+)\]/g, (_, name) => `[${name.toUpperCase()}]`);
 }
-function hasVerboseFlag() {
-  return process.argv.includes("--verbose");
+function optionTerm(opt) {
+  const flags = uppercasePlaceholders(opt.flags);
+  if (!opt.short && flags.startsWith("--")) return "    " + flags;
+  return flags;
 }
-var VERSION = "0.0.0";
-try {
-  const pkg = JSON.parse(readFileSync3(path6.resolve(__dirname3, "../package.json"), "utf-8"));
-  VERSION = pkg.version;
-} catch {
+function optionDescription(opt) {
+  let desc = opt.description;
+  const d = opt.defaultValue;
+  if (d !== void 0 && d !== false && d !== "" && d !== null) {
+    desc = `${desc} [default: ${String(d)}]`;
+  }
+  return desc;
 }
-var ERROR_CODE_MAP = {
-  MODULE_NOT_FOUND: 44,
-  MODULE_LOAD_ERROR: 44,
-  MODULE_DISABLED: 44,
-  SCHEMA_VALIDATION_ERROR: 45,
-  SCHEMA_CIRCULAR_REF: 48,
-  APPROVAL_DENIED: 46,
-  APPROVAL_TIMEOUT: 46,
-  APPROVAL_PENDING: 46,
-  CONFIG_NOT_FOUND: 47,
-  CONFIG_INVALID: 47,
-  MODULE_EXECUTE_ERROR: 1,
-  MODULE_TIMEOUT: 1,
-  ACL_DENIED: 77,
-  CONFIG_NAMESPACE_RESERVED: 78,
-  CONFIG_NAMESPACE_DUPLICATE: 78,
-  CONFIG_ENV_PREFIX_CONFLICT: 78,
-  CONFIG_ENV_MAP_CONFLICT: 78,
-  CONFIG_MOUNT_ERROR: 66,
-  CONFIG_BIND_ERROR: 65,
-  ERROR_FORMATTER_DUPLICATE: 70
-};
-function emitErrorJson(e, exitCode) {
-  const err = e instanceof Error ? e : new Error(String(e));
-  const errRecord = err;
-  const code = errRecord.code ?? "UNKNOWN";
-  const payload = {
-    error: true,
-    code,
-    message: err.message,
-    exit_code: exitCode
-  };
+function reorderHelpVersionLast(opts) {
+  const helpOpts = [];
+  const versionOpts = [];
+  const rest = [];
+  for (const o of opts) {
+    if (o.long === "--help") helpOpts.push(o);
+    else if (o.long === "--version") versionOpts.push(o);
+    else rest.push(o);
+  }
+  return [...rest, ...helpOpts, ...versionOpts];
+}
+function canonicalFormatHelp(cmd, helper) {
+  const sections = [];
+  const beforeAll = resolveHelpText(cmd, "beforeAll");
+  if (beforeAll) sections.push(beforeAll);
+  const desc = cmd.description();
+  if (desc) sections.push(desc);
+  const before = resolveHelpText(cmd, "before");
+  if (before) sections.push(before);
+  const visibleOpts = reorderHelpVersionLast(helper.visibleOptions(cmd));
+  const visibleCmds = helper.visibleCommands(cmd);
+  const args = cmd.registeredArguments ?? [];
+  let usage = `Usage: ${cmd.name()}`;
+  if (visibleOpts.length > 0) usage += " [OPTIONS]";
+  for (const a of args) {
+    const n = a.name().toUpperCase();
+    usage += a.required ? ` <${n}>` : ` [${n}]`;
+  }
+  if (visibleCmds.length > 0) usage += " [COMMAND]";
+  sections.push(usage);
+  if (visibleCmds.length > 0) {
+    const terms = visibleCmds.map((c) => c.name());
+    const w = Math.max(...terms.map((t) => t.length));
+    const lines = ["Commands:"];
+    visibleCmds.forEach((sub, i) => {
+      lines.push(`  ${terms[i].padEnd(w)}  ${sub.description()}`);
+    });
+    sections.push(lines.join("\n"));
+  }
+  if (visibleOpts.length > 0) {
+    const terms = visibleOpts.map(optionTerm);
+    const w = Math.max(...terms.map((t) => t.length));
+    const lines = ["Options:"];
+    visibleOpts.forEach((opt, i) => {
+      lines.push(`  ${terms[i].padEnd(w)}  ${optionDescription(opt)}`);
+    });
+    sections.push(lines.join("\n"));
+  }
+  const after = resolveHelpText(cmd, "after");
+  if (after) sections.push(after);
+  const afterAll = resolveHelpText(cmd, "afterAll");
+  if (afterAll) sections.push(afterAll);
+  return sections.join("\n\n") + "\n";
+}
+
+// src/validate.ts
+init_esm_shims();
+init_errors();
+var MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+var MAX_MODULE_ID_LENGTH = 192;
+function validateModuleId(moduleId) {
+  if (moduleId.length > MAX_MODULE_ID_LENGTH) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'. Maximum length is ${MAX_MODULE_ID_LENGTH} characters.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (!MODULE_ID_PATTERN.test(moduleId)) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+}
+
+// src/main.ts
+var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
+var verboseHelp = false;
+function setVerboseHelp(verbose) {
+  verboseHelp = verbose;
+}
+var docsUrl = null;
+function setDocsUrl(url) {
+  docsUrl = url;
+}
+function hasVerboseFlag() {
+  return process.argv.includes("--verbose");
+}
+function resolveIntOption(cliValue, envValue, defaultValue) {
+  if (cliValue !== void 0 && Number.isFinite(cliValue) && cliValue > 0) {
+    return cliValue;
+  }
+  if (envValue !== void 0 && envValue !== "") {
+    const parsed = parseInt(envValue, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+    process.stderr.write(
+      `Warning: invalid integer env value '${envValue}'; using default ${defaultValue}.
+`
+    );
+  }
+  return defaultValue;
+}
+function resolveStringOption(cliValue, envValue) {
+  if (typeof cliValue === "string" && cliValue !== "") {
+    return cliValue;
+  }
+  if (envValue !== void 0 && envValue !== "") {
+    return envValue;
+  }
+  return void 0;
+}
+var VERSION = "0.0.0";
+try {
+  const pkg = JSON.parse(readFileSync3(path5.resolve(__dirname2, "../package.json"), "utf-8"));
+  VERSION = pkg.version;
+} catch {
+}
+function emitErrorJson(e, exitCode) {
+  const err = e instanceof Error ? e : new Error(String(e));
+  const errRecord = err;
+  const code = errRecord.code ?? "UNKNOWN";
+  const payload = {
+    error: true,
+    code,
+    message: err.message,
+    exit_code: exitCode
+  };
   for (const field of ["details", "suggestion", "ai_guidance", "retryable", "user_fixable"]) {
     const val = errRecord[field];
     if (val !== void 0 && val !== null) {
@@ -3001,103 +3668,297 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
   let registry;
   let executor;
   let extraCommands;
+  let app;
+  let expose;
+  let apcliOption;
+  let appVersion;
+  let appDescription;
+  let allowedPrefixes;
+  let builtinGroupName;
   if (typeof extensionsDirOrOpts === "object" && extensionsDirOrOpts !== null) {
     extensionsDir = extensionsDirOrOpts.extensionsDir;
     progName = extensionsDirOrOpts.progName ?? progName;
     verbose = extensionsDirOrOpts.verbose ?? verbose;
+    app = extensionsDirOrOpts.app;
     registry = extensionsDirOrOpts.registry;
     executor = extensionsDirOrOpts.executor;
     extraCommands = extensionsDirOrOpts.extraCommands;
+    expose = extensionsDirOrOpts.expose;
+    apcliOption = extensionsDirOrOpts.apcli;
+    appVersion = extensionsDirOrOpts.version;
+    appDescription = extensionsDirOrOpts.description;
+    builtinGroupName = extensionsDirOrOpts.builtinGroupName;
+    allowedPrefixes = extensionsDirOrOpts.allowedPrefixes;
   } else {
     extensionsDir = extensionsDirOrOpts;
   }
   verboseHelp = verbose;
   registerConfigNamespace();
-  const resolvedProgName = progName ?? path6.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
+  try {
+    const auditLogger = new AuditLogger();
+    setAuditLogger(auditLogger);
+  } catch {
+  }
+  const resolvedProgName = progName ?? path5.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
   const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? "WARNING";
   setLogLevel(cliLogLevel);
-  const program = new Command6(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--commands-dir <path>", "Path to convention-based commands directory").option("--binding <path>", "Path to binding.yaml for display overlay").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
+  if (app && (registry || executor)) {
+    process.stderr.write("Error: app is mutually exclusive with registry/executor\n");
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (app) {
+    registry = app.registry;
+    executor = app.executor;
+  }
   if (executor && !registry) {
-    throw new Error("executor requires registry \u2014 pass both or neither");
+    process.stderr.write("Error: executor requires registry \u2014 pass both or neither\n");
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (executor && typeof executor.setApprovalHandler === "function") {
+    try {
+      const handler = new CliApprovalHandler(
+        /*autoApprove*/
+        false
+      );
+      executor.setApprovalHandler(handler);
+    } catch {
+    }
+  }
+  const registryInjected = registry !== void 0;
+  const program = new Command5(resolvedProgName).exitOverride().helpOption("-h, --help", "Print help").addHelpCommand("help [command]", "Print this message or the help of the given subcommand(s)").description(appDescription ?? `${resolvedProgName} CLI`).option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--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");
+    program.option("--commands-dir <path>", "Path to convention-based commands directory");
+    program.option("--binding <path>", "Path to binding.yaml for display overlay");
+  }
+  let apcliCfg;
+  try {
+    if (apcliOption instanceof ApcliGroup) {
+      if (builtinGroupName !== void 0 && builtinGroupName !== "apcli" && apcliOption.name !== builtinGroupName) {
+        throw new Error(
+          `builtinGroupName=${JSON.stringify(builtinGroupName)} conflicts with the name on the supplied ApcliGroup (${JSON.stringify(apcliOption.name)}). Pass only one.`
+        );
+      }
+      apcliCfg = apcliOption;
+    } else if (apcliOption !== void 0) {
+      apcliCfg = ApcliGroup.fromCliConfig(apcliOption, {
+        registryInjected,
+        name: builtinGroupName
+      });
+    } else {
+      let yamlVal = null;
+      try {
+        const resolver = new ConfigResolver();
+        yamlVal = resolver.resolveObject("apcli");
+      } catch {
+        yamlVal = null;
+      }
+      apcliCfg = ApcliGroup.fromYaml(yamlVal, {
+        registryInjected,
+        name: builtinGroupName
+      });
+    }
+  } catch (e) {
+    process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}
+`);
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  setReservedGroupNames(/* @__PURE__ */ new Set([apcliCfg.name]));
+  const apcliGroup = program.command(apcliCfg.name, { hidden: !apcliCfg.isGroupVisible() }).description("Built-in commands");
   if (registry) {
     program._registry = registry;
     if (executor) {
       program._executor = executor;
-      registerValidateCommand(program, registry, executor);
-      void registerSystemCommands(program, executor);
-      registerPipelineCommand(program, executor);
     }
   } else {
     const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
     void resolvedExtDir;
   }
+  let exposureFilter;
+  try {
+    if (expose instanceof ExposureFilter) {
+      exposureFilter = expose;
+    } else if (typeof expose === "object" && expose !== null) {
+      exposureFilter = ExposureFilter.fromConfig({ expose });
+    } else {
+      exposureFilter = new ExposureFilter();
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Error: invalid 'expose' option \u2014 ${msg}
+`);
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter);
   program.addHelpText("after", [
     "",
-    "Use --help --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"));
-  registerInitCommand(program);
-  configureManHelp(program, resolvedProgName, VERSION);
+  configureManHelp(program, resolvedProgName, appVersion ?? VERSION);
   if (extraCommands && extraCommands.length > 0) {
-    const existingNames = /* @__PURE__ */ new Set([
-      ...BUILTIN_COMMANDS,
-      ...program.commands.map((c) => c.name())
-    ]);
+    const _reservedForExtra = /* @__PURE__ */ new Set([apcliCfg.name]);
     for (const cmd of extraCommands) {
       const cmdName = cmd.name();
-      if (existingNames.has(cmdName)) {
+      if (_reservedForExtra.has(cmdName)) {
         process.stderr.write(
-          `Warning: Extra command '${cmdName}' collides with a built-in command and will be skipped.
+          `Error: extraCommands name '${cmdName}' is reserved
 `
         );
-        continue;
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      }
+      const existing = program.commands.find((c) => c.name() === cmdName);
+      if (existing) {
+        process.stderr.write(
+          `Error: extraCommands name '${cmdName}' collides with an existing command
+`
+        );
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
       }
       program.addCommand(cmd);
-      existingNames.add(cmdName);
     }
   }
   program.hook("preAction", async (thisCommand) => {
     const opts = thisCommand.opts();
     const commandsDir = opts.commandsDir;
     const bindingPath = opts.binding;
-    await applyToolkitIntegration(commandsDir, bindingPath);
+    await applyToolkitIntegration(commandsDir, bindingPath, { allowedPrefixes });
   });
   return program;
 }
-async function applyToolkitIntegration(commandsDir, bindingPath) {
+var _ALWAYS_REGISTERED = /* @__PURE__ */ new Set(["exec"]);
+function _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter) {
+  const emitUnwiredError = () => {
+    process.stderr.write(
+      "Error: no apcore-js registry wired. In standalone mode, pass --extensions-dir <path> to enable module discovery.\n"
+    );
+    process.exit(EXIT_CODES.CONFIG_INVALID);
+  };
+  const effectiveRegistry = registry ?? {
+    listModules: () => emitUnwiredError(),
+    getModule: () => emitUnwiredError()
+  };
+  const TABLE = [
+    { name: "list", requiresExecutor: false, register: (g) => registerListCommand(g, effectiveRegistry, exposureFilter) },
+    { name: "describe", requiresExecutor: false, register: (g) => registerDescribeCommand(g, effectiveRegistry) },
+    { name: "exec", requiresExecutor: true, register: (g, _r, ex) => registerExecCommand(g, effectiveRegistry, ex) },
+    { name: "validate", requiresExecutor: true, register: (g, _r, ex) => registerValidateCommand(g, effectiveRegistry, ex) },
+    { name: "init", requiresExecutor: false, register: (g) => registerInitCommand(g) },
+    { name: "health", requiresExecutor: true, register: (g, _r, ex) => registerHealthCommand(g, ex) },
+    { name: "usage", requiresExecutor: true, register: (g, _r, ex) => registerUsageCommand(g, ex) },
+    { name: "enable", requiresExecutor: true, register: (g, _r, ex) => registerEnableCommand(g, ex) },
+    { name: "disable", requiresExecutor: true, register: (g, _r, ex) => registerDisableCommand(g, ex) },
+    { name: "reload", requiresExecutor: true, register: (g, _r, ex) => registerReloadCommand(g, ex) },
+    { name: "config", requiresExecutor: true, register: (g, _r, ex) => registerConfigCommand(g, ex) },
+    { name: "completion", requiresExecutor: false, register: (g) => registerCompletionCommand(g) },
+    { name: "describe-pipeline", requiresExecutor: true, register: (g, _r, ex) => registerPipelineCommand(g, ex) }
+  ];
+  const mode = apcliCfg.resolveVisibility();
+  for (const entry of TABLE) {
+    let shouldRegister;
+    if (mode === "all" || mode === "none") {
+      shouldRegister = true;
+    } else {
+      shouldRegister = _ALWAYS_REGISTERED.has(entry.name) || apcliCfg.isSubcommandIncluded(entry.name);
+    }
+    if (!shouldRegister) continue;
+    if (entry.requiresExecutor && !executor) {
+      if (_ALWAYS_REGISTERED.has(entry.name)) {
+        warn(
+          `apcli.${entry.name} is in _ALWAYS_REGISTERED but no executor is wired \u2014 subcommand unavailable. Pass executor to createCli() or avoid ${entry.name} invocations.`
+        );
+      }
+      continue;
+    }
+    entry.register(apcliGroup, registry, executor);
+  }
+}
+var bindingDisplayMap = /* @__PURE__ */ new Map();
+function lookupBindingDisplay(moduleId) {
+  return bindingDisplayMap.get(moduleId);
+}
+async function applyToolkitIntegration(commandsDir, bindingPath, options = {}) {
   if (!commandsDir && !bindingPath) {
     return;
   }
+  let toolkit;
   try {
     const toolkitModule = "apcore-toolkit";
-    const toolkit = await import(
+    toolkit = await import(
       /* @vite-ignore */
       toolkitModule
     );
-    if (commandsDir) {
-      console.warn("Convention scanning not yet available in TypeScript toolkit");
+  } catch {
+    warn("apcore-toolkit not installed \u2014 toolkit features unavailable");
+    return;
+  }
+  if (commandsDir) {
+    warn("Convention scanning not available in the TypeScript toolkit");
+  }
+  if (bindingPath) {
+    try {
+      await loadBindingDisplayOverlay(toolkit, bindingPath, options.allowedPrefixes);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warn(`apcore-toolkit: failed to load binding '${bindingPath}': ${msg}`);
+    }
+  }
+}
+async function loadBindingDisplayOverlay(toolkit, bindingPath, allowedPrefixes) {
+  const BindingLoaderCtor = toolkit.BindingLoader;
+  const DisplayResolverCtor = toolkit.DisplayResolver;
+  if (!BindingLoaderCtor || !DisplayResolverCtor) {
+    return;
+  }
+  const loader = new BindingLoaderCtor();
+  const scanned = loader.load(bindingPath);
+  const resolver = new DisplayResolverCtor();
+  const resolved = resolver.resolve(scanned, { bindingPath });
+  const prefixes = allowedPrefixes && allowedPrefixes.length > 0 ? allowedPrefixes : null;
+  const isTargetAllowed = (target) => {
+    if (!prefixes) return true;
+    if (typeof target !== "string" || target.length === 0) return true;
+    return prefixes.some((p) => target.startsWith(p));
+  };
+  for (const mod of resolved) {
+    if (!mod || typeof mod !== "object") continue;
+    const entry = mod;
+    const id = typeof entry.moduleId === "string" ? entry.moduleId : null;
+    if (!id) continue;
+    if (!isTargetAllowed(entry.target)) {
+      warn(
+        `apcore-toolkit: dropped binding entry '${id}' \u2014 target '${String(entry.target)}' is outside allowedPrefixes`
+      );
+      continue;
     }
-    if (bindingPath) {
-      const resolver = new toolkit.DisplayResolver();
-      void resolver;
+    const meta = entry.metadata ?? {};
+    const display = meta.display;
+    if (display && typeof display === "object" && !Array.isArray(display)) {
+      bindingDisplayMap.set(id, display);
     }
-  } catch {
-    console.warn("apcore-toolkit not installed \u2014 toolkit features unavailable");
   }
 }
 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 (error2) {
-    if (error2 instanceof CommanderError) {
-      process.exit(error2.exitCode);
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      process.exit(error.exitCode);
     }
-    const code = exitCodeForError(error2);
-    if (error2 instanceof Error) {
-      process.stderr.write(`Error: ${error2.message}
+    const code = exitCodeForError(error);
+    if (error instanceof Error) {
+      process.stderr.write(`Error: ${error.message}
 `);
     }
     process.exit(code);
@@ -3120,7 +3981,7 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
     }
     schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
   }
-  const cmd = new Command6(effectiveCmdName).description(cmdHelp);
+  const cmd = new Command5(effectiveCmdName).description(cmdHelp);
   const inputOpt = new Option4("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
   const yesOpt = new Option4("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
   const largeInputOpt = new Option4("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
@@ -3168,30 +4029,6 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
   if (footerParts.length > 0) {
     cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
   }
-  const reservedNames = /* @__PURE__ */ new Set([
-    "input",
-    "yes",
-    "largeInput",
-    "format",
-    "fields",
-    "sandbox",
-    "verbose",
-    "dryRun",
-    "trace",
-    "stream",
-    "strategy",
-    "approvalTimeout",
-    "approvalToken"
-  ]);
-  for (const opt of schemaOptions) {
-    if (reservedNames.has(opt.name)) {
-      process.stderr.write(
-        `Error: Module '${moduleId}' schema property '${opt.name}' conflicts with a reserved CLI option name. Rename the property.
-`
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-    }
-  }
   for (const opt of schemaOptions) {
     if (opt.parseArg) {
       cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
@@ -3209,8 +4046,12 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
     const dryRun = options.dryRun;
     const traceFlag = options.trace;
     const streamFlag = options.stream;
-    const strategyName = options.strategy;
-    const approvalTimeout = options.approvalTimeout ?? 60;
+    const strategyName = resolveStringOption(options.strategy, process.env.APCORE_CLI_STRATEGY);
+    const approvalTimeout = resolveIntOption(
+      options.approvalTimeout,
+      process.env.APCORE_CLI_APPROVAL_TIMEOUT,
+      60
+    );
     const approvalToken = options.approvalToken;
     const schemaKwargs = {};
     const builtinKeys = /* @__PURE__ */ new Set([
@@ -3234,6 +4075,7 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
       }
     }
     let merged = {};
+    const startTime = performance.now();
     try {
       merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
       const reconverted = reconvertEnumValues(merged, schemaOptions);
@@ -3241,7 +4083,7 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
       if (dryRun) {
         if (!executor.validate) {
           process.stderr.write("Error: Executor does not support validate.\n");
-          process.exit(1);
+          process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
         }
         const preflight = await executor.validate(moduleId, merged);
         formatPreflightResult(preflight, outputFormat);
@@ -3283,7 +4125,6 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
         merged._approval_token = approvalToken;
       }
       await checkApproval(moduleDef, autoApprove, approvalTimeout);
-      const startTime = performance.now();
       if (streamFlag) {
         if (resolveFormat(outputFormat) === "table") {
           process.stderr.write("Warning: Streaming mode always outputs JSONL; --format table is ignored.\n");
@@ -3324,22 +4165,17 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
           strategyName ? { strategy: strategyName } : void 0
         );
         const durationMs2 = Math.round(performance.now() - startTime);
-        const { getAuditLogger: getAuditLogger3 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-        const auditLogger2 = getAuditLogger3();
-        if (auditLogger2) {
-          auditLogger2.logExecution(moduleId, merged, "success", 0, durationMs2);
-        }
         const resolved = resolveFormat(outputFormat);
         if (resolved === "json" || !process.stdout.isTTY) {
           const traceData = {
-            strategy: trace.strategy_name,
-            total_duration_ms: trace.total_duration_ms,
+            strategy: trace.strategyName,
+            total_duration_ms: trace.totalDurationMs,
             success: trace.success,
             steps: trace.steps.map((s) => ({
               name: s.name,
-              duration_ms: s.duration_ms,
+              duration_ms: s.durationMs,
               skipped: s.skipped,
-              ...s.skipped ? { skip_reason: s.skip_reason } : {}
+              ...s.skipped ? { skip_reason: s.skipReason ?? null } : {}
             }))
           };
           let output;
@@ -3354,20 +4190,25 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
           const stepCount = trace.steps.length;
           process.stderr.write(
             `
-Pipeline Trace (strategy: ${trace.strategy_name}, ${stepCount} steps, ${trace.total_duration_ms.toFixed(1)}ms)
+Pipeline Trace (strategy: ${trace.strategyName}, ${stepCount} steps, ${trace.totalDurationMs.toFixed(1)}ms)
 `
           );
           for (const s of trace.steps) {
             if (s.skipped) {
-              const reason = s.skip_reason ?? "n/a";
+              const reason = s.skipReason ?? "n/a";
               process.stderr.write(`  \u25CB ${s.name.padEnd(24)} ${"\u2014".padStart(8)}  skipped (${reason})
 `);
             } else {
-              process.stderr.write(`  \u2713 ${s.name.padEnd(24)} ${(s.duration_ms.toFixed(1) + "ms").padStart(8)}
+              process.stderr.write(`  \u2713 ${s.name.padEnd(24)} ${(s.durationMs.toFixed(1) + "ms").padStart(8)}
 `);
             }
           }
         }
+        const { getAuditLogger: getAL2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+        const al2 = getAL2();
+        if (al2) {
+          al2.logExecution(moduleId, merged, "success", 0, durationMs2);
+        }
         return;
       }
       let result;
@@ -3388,21 +4229,20 @@ Pipeline Trace (strategy: ${trace.strategy_name}, ${stepCount} steps, ${trace.to
         result = await sandbox.execute(moduleId, merged, executor);
       }
       const durationMs = Math.round(performance.now() - startTime);
+      formatExecResult(result, outputFormat, outputFields);
       const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
       const auditLogger = getAuditLogger2();
       if (auditLogger) {
         auditLogger.logExecution(moduleId, merged, "success", 0, durationMs);
       }
-      formatExecResult(result, outputFormat, outputFields);
     } catch (err) {
-      const errRecord = err;
-      const errorCode = typeof errRecord?.code === "string" ? errRecord.code : void 0;
-      const exitCode = errorCode && errorCode in ERROR_CODE_MAP ? ERROR_CODE_MAP[errorCode] : exitCodeForError(err);
+      const exitCode = exitCodeForError(err);
+      const durationMs = Math.round(performance.now() - startTime);
       try {
         const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
         const auditLogger = getAuditLogger2();
         if (auditLogger) {
-          auditLogger.logExecution(moduleId, merged, "error", exitCode, 0);
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, durationMs);
         }
       } catch {
       }
@@ -3416,22 +4256,6 @@ Pipeline Trace (strategy: ${trace.strategy_name}, ${stepCount} steps, ${trace.to
   });
   return cmd;
 }
-function validateModuleId(moduleId) {
-  if (moduleId.length > 128) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/.test(moduleId)) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-}
 async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
   const cliKwargsNonNull = {};
   for (const [k, v] of Object.entries(cliKwargs)) {
@@ -3442,45 +4266,57 @@ async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
   if (!stdinFlag) {
     return cliKwargsNonNull;
   }
+  let raw;
+  let source;
   if (stdinFlag === "-") {
-    const raw = await readStdin();
-    const rawSize = Buffer.byteLength(raw, "utf-8");
-    if (rawSize > 10485760 && !largeInput) {
-      process.stderr.write(
-        "Error: STDIN input exceeds 10MB limit. Use --large-input to override.\n"
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-    }
-    if (!raw) {
-      return cliKwargsNonNull;
-    }
-    let stdinData;
+    raw = await readStdin();
+    source = "STDIN";
+  } else {
+    source = `file '${stdinFlag}'`;
     try {
-      stdinData = JSON.parse(raw);
-    } catch {
-      process.stderr.write(
-        "Error: STDIN does not contain valid JSON.\n"
-      );
+      raw = readFileSync3(stdinFlag, "utf-8");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Error: Could not read input ${source}: ${msg}
+`);
       process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
-    if (typeof stdinData !== "object" || stdinData === null || Array.isArray(stdinData)) {
-      process.stderr.write(
-        `Error: STDIN JSON must be an object, got ${Array.isArray(stdinData) ? "array" : typeof stdinData}.
+  }
+  const rawSize = Buffer.byteLength(raw, "utf-8");
+  if (rawSize > 10485760 && !largeInput) {
+    process.stderr.write(
+      `Error: ${source} input exceeds 10MB limit. Use --large-input to override.
 `
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-    }
-    return { ...stdinData, ...cliKwargsNonNull };
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
   }
-  return cliKwargsNonNull;
+  if (!raw) {
+    return cliKwargsNonNull;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    process.stderr.write(`Error: ${source} does not contain valid JSON.
+`);
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    process.stderr.write(
+      `Error: ${source} JSON must be an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  return { ...parsed, ...cliKwargsNonNull };
 }
 function readStdin() {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve2, reject) => {
     const chunks = [];
     const onData = (chunk) => chunks.push(chunk);
     const onEnd = () => {
       cleanup();
-      resolve3(Buffer.concat(chunks).toString("utf-8"));
+      resolve2(Buffer.concat(chunks).toString("utf-8"));
     };
     const onError = (err) => {
       cleanup();
@@ -3518,62 +4354,375 @@ function reconvertEnumValues(kwargs, options) {
   return result;
 }
 
+// src/cli.ts
+init_esm_shims();
+import { Command as Command6 } from "commander";
+init_logger();
+init_errors();
+function assertNotReserved(kind, name, moduleId) {
+  if (!getReservedGroupNames().has(name)) return;
+  let msg;
+  if (kind === "group") {
+    msg = `Error: Module '${moduleId}': display.cli.group '${name}' is reserved. Use a different CLI alias or set display.cli.group to another value.
+`;
+  } else if (kind === "auto-group") {
+    msg = `Error: Module '${moduleId}': auto-group '${name}' is reserved. Rename the module id or set display.cli.group to another value.
+`;
+  } else {
+    msg = `Error: Module '${moduleId}': top-level CLI name '${name}' is reserved. Use a different CLI alias.
+`;
+  }
+  process.stderr.write(msg);
+  process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+}
+var LazyModuleGroup = class {
+  registry;
+  executor;
+  helpTextMaxLength;
+  commandCache = /* @__PURE__ */ new Map();
+  /** alias -> canonical module_id (populated lazily) */
+  aliasMap = /* @__PURE__ */ new Map();
+  /** module_id -> descriptor cache (populated during alias map build) */
+  descriptorCache = /* @__PURE__ */ new Map();
+  aliasMapBuilt = false;
+  constructor(registry, executor, helpTextMaxLength = 1e3) {
+    this.registry = registry;
+    this.executor = executor;
+    this.helpTextMaxLength = helpTextMaxLength;
+  }
+  /**
+   * Build alias->module_id map from display overlay metadata.
+   */
+  buildAliasMap() {
+    if (this.aliasMapBuilt) {
+      return;
+    }
+    try {
+      for (const descriptor of this.registry.listModules()) {
+        const moduleId = descriptor.id;
+        this.descriptorCache.set(moduleId, descriptor);
+        const display = getDisplay(descriptor);
+        const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+        const cliAlias = cliDisplay.alias;
+        if (cliAlias && cliAlias !== moduleId) {
+          this.aliasMap.set(cliAlias, moduleId);
+        }
+      }
+      this.aliasMapBuilt = true;
+    } catch {
+      warn("Failed to build alias map from registry");
+    }
+  }
+  /**
+   * List all available command names from the Registry.
+   */
+  listCommands() {
+    this.buildAliasMap();
+    const reverse = /* @__PURE__ */ new Map();
+    for (const [alias, moduleId] of this.aliasMap) {
+      reverse.set(moduleId, alias);
+    }
+    const moduleIds = this.registry.listModules().map((m) => m.id);
+    const names = moduleIds.map((mid) => reverse.get(mid) ?? mid);
+    return [...new Set(names)].sort();
+  }
+  /**
+   * Get or lazily build a Commander Command for the given module.
+   */
+  getCommand(cmdName) {
+    if (this.commandCache.has(cmdName)) {
+      return this.commandCache.get(cmdName);
+    }
+    this.buildAliasMap();
+    const moduleId = this.aliasMap.get(cmdName) ?? cmdName;
+    let moduleDef = this.descriptorCache.get(moduleId);
+    if (!moduleDef) {
+      moduleDef = this.registry.getModule(moduleId) ?? void 0;
+    }
+    if (!moduleDef) {
+      return null;
+    }
+    const cmd = buildModuleCommand(moduleDef, this.executor, this.helpTextMaxLength, cmdName);
+    this.commandCache.set(cmdName, cmd);
+    return cmd;
+  }
+};
+var LazyGroup = class {
+  members;
+  _executor;
+  _helpTextMaxLength;
+  _cmdCache = /* @__PURE__ */ new Map();
+  command;
+  constructor(members, executor, name, helpTextMaxLength = 1e3) {
+    this.members = members;
+    this._executor = executor;
+    this._helpTextMaxLength = helpTextMaxLength;
+    this.command = new Command6(name).description(`${name} commands`);
+    for (const [cmdName, [, descriptor]] of this.members) {
+      const cmd = buildModuleCommand(
+        descriptor,
+        this._executor,
+        this._helpTextMaxLength,
+        cmdName
+      );
+      this._cmdCache.set(cmdName, cmd);
+      this.command.addCommand(cmd);
+    }
+  }
+  listCommands() {
+    return [...this.members.keys()].sort();
+  }
+  getCommand(cmdName) {
+    if (this._cmdCache.has(cmdName)) {
+      return this._cmdCache.get(cmdName);
+    }
+    const entry = this.members.get(cmdName);
+    if (!entry) {
+      return null;
+    }
+    const [, descriptor] = entry;
+    const cmd = buildModuleCommand(
+      descriptor,
+      this._executor,
+      this._helpTextMaxLength,
+      cmdName
+    );
+    this._cmdCache.set(cmdName, cmd);
+    return cmd;
+  }
+};
+var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
+  /** groupName -> { cmdName -> [moduleId, descriptor] } */
+  groupMap = /* @__PURE__ */ new Map();
+  /** cmdName -> [moduleId, descriptor] for top-level (ungrouped) modules */
+  topLevelModules = /* @__PURE__ */ new Map();
+  /** Cached LazyGroup instances */
+  groupCache = /* @__PURE__ */ new Map();
+  groupMapBuilt = false;
+  /** Exposure filter (FE-12) — controls which modules appear as CLI commands */
+  exposureFilter;
+  /** Effective group depth (CLAUDE.md v0.6.0): constructor arg > APCORE_CLI_GROUP_DEPTH env > 1. */
+  groupDepth;
+  constructor(registry, executor, helpTextMaxLength = 1e3, exposureFilter, groupDepth) {
+    super(registry, executor, helpTextMaxLength);
+    this.exposureFilter = exposureFilter ?? new ExposureFilter();
+    this.groupDepth = _GroupedModuleGroup.resolveGroupDepth(groupDepth);
+  }
+  /**
+   * Resolve group depth from constructor arg > APCORE_CLI_GROUP_DEPTH env > default 1.
+   * Invalid env values (non-integer, non-positive) fall through to the default.
+   */
+  static resolveGroupDepth(explicit) {
+    if (explicit !== void 0 && Number.isFinite(explicit) && explicit > 0) {
+      return Math.floor(explicit);
+    }
+    const raw = process.env.APCORE_CLI_GROUP_DEPTH;
+    if (raw !== void 0 && raw !== "") {
+      const parsed = parseInt(raw, 10);
+      if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed;
+      }
+    }
+    return 1;
+  }
+  /**
+   * Determine (groupName | null, commandName) for a module from its display overlay.
+   *
+   * @param groupDepth  Number of dotted segments to consume as the group prefix.
+   *                    Defaults to 1 (e.g., "math.add" → group="math", cmd="add").
+   *                    Set to 2 for multi-level grouping (e.g., "math.trig.sin" →
+   *                    group="math.trig", cmd="sin").
+   */
+  static resolveGroup(moduleId, descriptor, groupDepth = 1) {
+    if (!moduleId) {
+      warn("Empty module_id encountered in resolveGroup");
+      return [null, ""];
+    }
+    const display = getDisplay(descriptor);
+    const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+    const explicitGroup = cliDisplay.group;
+    if (typeof explicitGroup === "string" && explicitGroup !== "") {
+      return [explicitGroup, cliDisplay.alias ?? moduleId];
+    }
+    if (explicitGroup === "") {
+      return [null, cliDisplay.alias ?? moduleId];
+    }
+    const cliName = cliDisplay.alias ?? moduleId;
+    if (cliName.includes(".")) {
+      const parts = cliName.split(".");
+      const depth = Math.max(1, Math.min(groupDepth, parts.length - 1));
+      const group = parts.slice(0, depth).join(".");
+      const cmd = parts.slice(depth).join(".");
+      return [group, cmd];
+    }
+    return [null, cliName];
+  }
+  /**
+   * Build the group map from registry modules.
+   *
+   * FE-13: hard-fails with exit 2 when a module resolves to the reserved
+   * `apcli` namespace in any of three ways — explicit `display.cli.group`,
+   * auto-grouped dotted prefix, or top-level alias/id. See spec §4.10.
+   */
+  buildGroupMap() {
+    if (this.groupMapBuilt) {
+      return;
+    }
+    this.buildAliasMap();
+    for (const descriptor of this.registry.listModules()) {
+      const moduleId = descriptor.id;
+      const cached = this.descriptorCache.get(moduleId);
+      if (!cached) {
+        continue;
+      }
+      if (!this.exposureFilter.isExposed(moduleId)) {
+        continue;
+      }
+      const display = getDisplay(cached);
+      const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+      const explicitGroup = typeof cliDisplay.group === "string" && cliDisplay.group !== "" ? cliDisplay.group : void 0;
+      if (explicitGroup !== void 0) {
+        assertNotReserved("group", explicitGroup, moduleId);
+      }
+      const [group, cmd] = _GroupedModuleGroup.resolveGroup(moduleId, cached, this.groupDepth);
+      if (group !== null && explicitGroup === void 0) {
+        assertNotReserved("auto-group", group, moduleId);
+      }
+      if (group === null) {
+        assertNotReserved("top-level", cmd, moduleId);
+        this.topLevelModules.set(cmd, [moduleId, cached]);
+      } else if (!/^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)*$/.test(group)) {
+        warn(
+          `Module '${moduleId}': group name '${group}' is not shell-safe \u2014 treating as top-level.`
+        );
+        this.topLevelModules.set(cmd, [moduleId, cached]);
+      } else {
+        if (!this.groupMap.has(group)) {
+          this.groupMap.set(group, /* @__PURE__ */ new Map());
+        }
+        this.groupMap.get(group).set(cmd, [moduleId, cached]);
+      }
+    }
+    this.groupMapBuilt = true;
+  }
+  /**
+   * List all available command names: group names + top-level module names.
+   *
+   * FE-13: the built-in subcommand list is no longer folded in here — those
+   * commands live under the `apcli` prefix and are registered directly by
+   * `createCli`.
+   */
+  listCommands() {
+    this.buildGroupMap();
+    const reserved = getReservedGroupNames();
+    const groupNames = [...this.groupMap.keys()].filter(
+      (g) => !reserved.has(g)
+    );
+    const topNames = [...this.topLevelModules.keys()];
+    return [.../* @__PURE__ */ new Set([...groupNames, ...topNames])].sort();
+  }
+  /**
+   * Get a command by name: check builtins -> group cache -> group map -> top-level modules.
+   */
+  getCommand(cmdName) {
+    this.buildGroupMap();
+    if (this.groupCache.has(cmdName)) {
+      return this.groupCache.get(cmdName).command;
+    }
+    if (this.groupMap.has(cmdName)) {
+      const lazyGrp = new LazyGroup(
+        this.groupMap.get(cmdName),
+        this.executor,
+        cmdName,
+        this.helpTextMaxLength
+      );
+      this.groupCache.set(cmdName, lazyGrp);
+      return lazyGrp.command;
+    }
+    if (this.topLevelModules.has(cmdName)) {
+      if (this.commandCache.has(cmdName)) {
+        return this.commandCache.get(cmdName);
+      }
+      const [, descriptor] = this.topLevelModules.get(cmdName);
+      const cmd = buildModuleCommand(
+        descriptor,
+        this.executor,
+        this.helpTextMaxLength,
+        cmdName
+      );
+      this.commandCache.set(cmdName, cmd);
+      return cmd;
+    }
+    return null;
+  }
+  /** Expose groupMap for testing. */
+  getGroupMap() {
+    return this.groupMap;
+  }
+  /** Expose topLevelModules for testing. */
+  getTopLevelModules() {
+    return this.topLevelModules;
+  }
+  /** Expose groupMapBuilt for testing. */
+  isGroupMapBuilt() {
+    return this.groupMapBuilt;
+  }
+};
+
 // src/index.ts
 init_errors();
+init_logger();
 init_security();
 export {
+  ApcliGroup,
+  ApcliGroupError,
   ApprovalDeniedError,
   ApprovalTimeoutError,
   AuditLogger,
   AuthProvider,
   AuthenticationError,
-  BUILTIN_COMMANDS,
   CliApprovalHandler,
   ConfigDecryptionError,
   ConfigEncryptor,
   ConfigResolver,
   DEFAULTS,
   EXIT_CODES,
+  ExposureFilter,
   GroupedModuleGroup,
   LazyGroup,
   LazyModuleGroup,
   ModuleExecutionError,
   ModuleNotFoundError,
+  RESERVED_GROUP_NAMES,
   Sandbox,
   SchemaValidationError,
   applyToolkitIntegration,
   buildModuleCommand,
-  buildProgramManPage,
   checkApproval,
   collectInput,
   configureManHelp,
   createCli,
-  debug,
-  docsUrl,
-  emitErrorJson,
-  emitErrorTty,
-  error,
   exitCodeForError,
-  extractHelp,
-  firstFailedExitCode,
   formatExecResult,
   formatModuleDetail,
   formatModuleList,
-  formatPreflightResult,
   getAuditLogger,
-  getCliDisplayFields,
-  getDisplay,
   getLogLevel,
-  info,
   main,
-  mapType,
   reconvertEnumValues,
+  registerCompletionCommand,
+  registerConfigCommand,
   registerConfigNamespace,
-  registerDiscoveryCommands,
+  registerDescribeCommand,
+  registerDisableCommand,
+  registerEnableCommand,
+  registerExecCommand,
+  registerHealthCommand,
   registerInitCommand,
+  registerListCommand,
   registerPipelineCommand,
-  registerShellCommands,
-  registerSystemCommands,
+  registerReloadCommand,
+  registerUsageCommand,
   registerValidateCommand,
   resolveFormat,
   resolveRefs,
@@ -3582,9 +4731,6 @@ export {
   setDocsUrl,
   setLogLevel,
   setVerboseHelp,
-  truncate,
-  validateModuleId,
-  verboseHelp,
-  warn
+  validateModuleId
 };
 //# sourceMappingURL=index.js.map