apcore-cli 0.5.0 → 0.7.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,
@@ -142,6 +141,7 @@ var init_errors = __esm({
       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,
@@ -150,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(path5) {
+        this.logPath = path5 ?? _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 {
         }
       }
@@ -202,14 +247,20 @@ 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() {
@@ -235,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();
@@ -253,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.
@@ -290,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}'.`
@@ -305,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() {
+      // 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 = os2.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([
@@ -324,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 = os2.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");
       }
     };
   }
@@ -370,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();
@@ -384,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.
@@ -401,20 +543,37 @@ 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_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_OUTPUT_SIZE_LIMIT = 64 * 1024 * 1024;
     Sandbox = class {
       enabled;
-      constructor(enabled = false) {
+      timeoutSeconds;
+      constructor(enabled = false, timeoutSeconds = 300) {
         this.enabled = enabled;
+        this.timeoutSeconds = timeoutSeconds;
       }
       /**
        * Execute a module, optionally inside a sandboxed subprocess.
@@ -423,63 +582,77 @@ 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: join3 } = await import("path");
+        const { mkdtempSync, rmSync } = await import("fs");
+        const tmpDir = mkdtempSync(join3(tmpdir(), "apcore_sandbox_"));
+        const env = buildSandboxEnv(tmpDir);
+        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 totalBytes = 0;
+        let sizeExceeded = false;
+        child.stdout.on("data", (chunk) => {
+          totalBytes += chunk.length;
+          if (totalBytes > SANDBOX_OUTPUT_SIZE_LIMIT) {
+            sizeExceeded = true;
+            child.kill("SIGKILL");
+            return;
           }
-        }
-        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.`
+          stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+          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.`
+              )
             );
-          }
-          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 {
-          }
-        }
+          }, this.timeoutSeconds * 1e3);
+          child.on("close", (code) => {
+            clearTimeout(timer);
+            try {
+              rmSync(tmpDir, { recursive: true, force: true });
+            } catch {
+            }
+            if (sizeExceeded) {
+              reject(new ModuleExecutionError(`Sandbox module '${moduleId}' output exceeded 64MiB 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}`));
+          });
+        });
       }
     };
   }
@@ -512,10 +685,10 @@ init_esm_shims();
 // src/main.ts
 init_esm_shims();
 init_errors();
-import { readFileSync as readFileSync3 } from "fs";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import * as path6 from "path";
-import { Command as Command2, CommanderError, Option as Option2 } from "commander";
+import { readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import * as path4 from "path";
+import { Command as Command5, CommanderError, Option as Option4 } from "commander";
 
 // src/ref-resolver.ts
 init_esm_shims();
@@ -574,6 +747,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,
@@ -697,7 +876,21 @@ 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 ?? [];
@@ -705,21 +898,21 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
   const flagNames = {};
   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);
     }
-    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);
     }
+    flagNames[flagName] = propName;
     const typeResult = mapType(propName, propSchema);
     const isRequired = requiredList.includes(propName);
     const helpBase = extractHelp(propSchema, maxHelpLength);
@@ -727,13 +920,22 @@ 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.INVALID_CLI_INPUT);
+      }
+      flagNames[noFlag] = propName;
       const defaultVal = propSchema.default ?? false;
       options.push({
         name: propName,
         flags: `--${flagBase}, --no-${flagBase}`,
         description: helpText,
         defaultValue: defaultVal,
-        required: false,
+        required: isRequired,
         isBooleanFlag: true
       });
     } else if ("enum" in propSchema && Array.isArray(propSchema.enum)) {
@@ -744,7 +946,7 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
           flags: `${flagName} <value>`,
           description: helpText,
           defaultValue,
-          required: false
+          required: isRequired
         });
       } else {
         const stringValues = enumValues.map(String);
@@ -763,7 +965,7 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
           flags: `${flagName} <value>`,
           description: helpText,
           defaultValue: defaultValue !== void 0 ? String(defaultValue) : void 0,
-          required: false,
+          required: isRequired,
           choices: stringValues,
           enumOriginalTypes: Object.keys(enumOriginalTypes).length > 0 ? enumOriginalTypes : void 0
         });
@@ -788,7 +990,7 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
         flags: `${flagName} <value>`,
         description: helpText,
         defaultValue,
-        required: false,
+        required: isRequired,
         parseArg
       });
     }
@@ -805,7 +1007,55 @@ function getAnnotation(annotations, key, defaultValue = void 0) {
   const ann = annotations;
   return key in ann ? ann[key] : defaultValue;
 }
-async function checkApproval(moduleDef, autoApprove) {
+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) {
+    this.autoApprove = autoApprove;
+    const resolved = timeout ?? readTimeoutFromEnv() ?? 60;
+    this.timeout = Math.max(1, Math.min(resolved, 3600));
+  }
+  async requestApproval(request) {
+    const moduleId = request.module_id ?? "unknown";
+    if (this.autoApprove) {
+      return { status: "approved", approved_by: "auto_approve" };
+    }
+    const envVal = process.env.APCORE_CLI_AUTO_APPROVE ?? "";
+    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" };
+    }
+    const annotations = request.annotations;
+    const extra = annotations?.extra ?? {};
+    const message = extra.approval_message ?? `Module '${moduleId}' requires approval to execute.`;
+    process.stderr.write(message + "\n");
+    try {
+      await promptWithTimeout({ id: moduleId }, this.timeout);
+      return { status: "approved", approved_by: "tty_user" };
+    } catch {
+      return { status: "rejected", reason: "User rejected or timed out" };
+    }
+  }
+  async checkApproval(_approvalId) {
+    return { status: "rejected", reason: "CLI does not support async approval polling" };
+  }
+};
+async function checkApproval(moduleDef, autoApprove, timeout) {
   const annotations = moduleDef.annotations;
   let requiresApproval;
   if (moduleDef.requiresApproval !== void 0) {
@@ -833,13 +1083,12 @@ async function checkApproval(moduleDef, autoApprove) {
     );
   }
   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, 60);
+  const effectiveTimeout = timeout ?? readTimeoutFromEnv() ?? 60;
+  await promptWithTimeout(moduleDef, effectiveTimeout);
 }
 async function promptWithTimeout(moduleDef, timeout) {
   timeout = Math.max(1, Math.min(timeout, 3600));
@@ -854,8 +1103,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(() => {
@@ -870,17 +1119,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();
@@ -889,6 +1130,13 @@ async function promptWithTimeout(moduleDef, timeout) {
 
 // src/output.ts
 init_esm_shims();
+init_errors();
+import yaml from "js-yaml";
+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;
@@ -912,7 +1160,7 @@ function formatTable(headers, rows) {
   );
   return [headerLine, sep2, ...dataLines].join("\n") + "\n";
 }
-function formatModuleList(modules, format, filterTags) {
+function formatModuleList(modules, format, filterTags, showDeps = false, exposureFilter) {
   if (format === "table") {
     if (modules.length === 0 && filterTags && filterTags.length > 0) {
       process.stdout.write(
@@ -926,18 +1174,36 @@ function formatModuleList(modules, format, filterTags) {
       return;
     }
     const headers = ["ID", "Description", "Tags"];
-    const rows = modules.map((m) => [
-      m.id,
-      truncate(m.description, 80),
-      (m.tags ?? []).join(", ")
-    ]);
+    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));
   } else if (format === "json") {
-    const result = modules.map((m) => ({
-      id: m.id,
-      description: m.description,
-      tags: m.tags ?? []
-    }));
+    const result = modules.map((m) => {
+      const entry = {
+        id: m.id,
+        description: m.description,
+        tags: m.tags ?? []
+      };
+      if (showDeps) {
+        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");
   }
 }
@@ -1025,62 +1291,177 @@ Tags: ${tags.join(", ")}
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
   }
 }
-function formatExecResult(result, format) {
+function selectFields(result, fields) {
+  const selected = {};
+  for (const f of fields.split(",")) {
+    const key = f.trim();
+    let val = result;
+    for (const part of key.split(".")) {
+      if (val && typeof val === "object" && !Array.isArray(val)) {
+        val = val[part];
+      } else {
+        val = void 0;
+        break;
+      }
+    }
+    selected[key] = val;
+  }
+  return selected;
+}
+function formatExecResult(result, format, fields) {
   if (result === null || result === void 0) {
     return;
   }
+  let effective_result = result;
+  if (fields && typeof result === "object" && !Array.isArray(result) && result !== null) {
+    effective_result = selectFields(result, fields);
+  }
   const effective = resolveFormat(format);
-  if (effective === "table" && typeof result === "object" && !Array.isArray(result)) {
-    const entries = Object.entries(result);
+  if (effective === "csv") {
+    if (typeof effective_result === "object" && !Array.isArray(effective_result) && effective_result !== null) {
+      const obj = effective_result;
+      const keys = Object.keys(obj);
+      const header = keys.map(escapeCsvField).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(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") {
+    process.stdout.write(yaml.dump(effective_result, { lineWidth: -1 }));
+  } else if (effective === "jsonl") {
+    if (Array.isArray(effective_result)) {
+      for (const item of effective_result) {
+        process.stdout.write(JSON.stringify(item) + "\n");
+      }
+    } else {
+      process.stdout.write(JSON.stringify(effective_result) + "\n");
+    }
+  } else if (effective === "table" && typeof effective_result === "object" && !Array.isArray(effective_result)) {
+    const entries = Object.entries(effective_result);
     const headers = ["Key", "Value"];
     const rows = entries.map(([k, v]) => [String(k), String(v)]);
     process.stdout.write(formatTable(headers, rows));
-  } else if (typeof result === "object") {
-    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-  } else if (typeof result === "string") {
-    process.stdout.write(result + "\n");
+  } else if (typeof effective_result === "object") {
+    process.stdout.write(JSON.stringify(effective_result, null, 2) + "\n");
+  } else if (typeof effective_result === "string") {
+    process.stdout.write(effective_result + "\n");
   } else {
-    process.stdout.write(String(result) + "\n");
+    process.stdout.write(String(effective_result) + "\n");
   }
 }
-
-// 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 escapeCsvField(value) {
+  if (value.includes(",") || value.includes('"') || value.includes("\n") || value.includes("\r")) {
+    return '"' + value.replace(/"/g, '""') + '"';
   }
+  return value;
 }
-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 formatPreflightResult(result, format) {
+  const resolved = resolveFormat(format);
+  if (resolved === "json" || !process.stdout.isTTY) {
+    const payload = {
+      valid: result.valid,
+      // 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) {
+          entry.error = c.error;
+        }
+        if (c.warnings && c.warnings.length > 0) {
+          entry.warnings = c.warnings;
+        }
+        return entry;
+      })
+    };
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  } else {
+    for (const c of result.checks) {
+      const hasWarnings = (c.warnings?.length ?? 0) > 0;
+      let sym;
+      if (c.passed && hasWarnings) {
+        sym = "\u26A0";
+      } else if (c.passed) {
+        sym = "\u2713";
+      } else if (c.passed === false) {
+        sym = "\u2717";
+      } else {
+        sym = "\u25CB";
+      }
+      let status = `  ${sym} ${c.check.padEnd(20)}`;
+      if (c.error) {
+        const detail = typeof c.error === "object" ? JSON.stringify(c.error) : String(c.error);
+        status += ` ${detail}`;
+      } else if (c.passed && !hasWarnings) {
+        status += " OK";
+      } else if (!c.passed) {
+        status += " Skipped";
+      }
+      process.stdout.write(status + "\n");
+      for (const w of c.warnings ?? []) {
+        process.stdout.write(`    Warning: ${w}
 `);
-}
-function warn(message) {
-  if (shouldLog("WARNING")) process.stderr.write(`WARNING: ${message}
+      }
+    }
+    const errors = result.checks.filter((c) => !c.passed).length;
+    const warnings = result.checks.reduce((sum, c) => sum + (c.warnings?.length ?? 0), 0);
+    const tag = result.valid ? "PASS" : "FAIL";
+    process.stdout.write(`
+Result: ${tag} (${errors} error(s), ${warnings} warning(s))
 `);
+  }
 }
-function error(message) {
-  if (shouldLog("ERROR")) process.stderr.write(`ERROR: ${message}
-`);
+function firstFailedExitCode(result) {
+  const checkToExit = {
+    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] ?? EXIT_CODES.MODULE_EXECUTE_ERROR;
+    }
+  }
+  return EXIT_CODES.MODULE_EXECUTE_ERROR;
 }
 
+// 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";
 
@@ -1104,7 +1485,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}"
@@ -1153,7 +1535,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";
@@ -1163,14 +1545,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";
@@ -1188,12 +1570,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, {
@@ -1201,11 +1584,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> {
@@ -1214,7 +1598,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}
 `);
   }
@@ -1228,33 +1612,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,
+  // 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",
@@ -1267,17 +1666,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"
-        }
+        defaults: NAMESPACE_DEFAULTS
       });
     }
   } catch {
@@ -1288,6 +1683,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";
@@ -1296,9 +1698,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;
       }
@@ -1335,6 +1736,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.
    */
@@ -1346,26 +1785,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);
   }
   /**
@@ -1391,95 +1831,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' \\
@@ -1488,22 +1922,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
             ;;
@@ -1513,158 +1936,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]`);
-    }
+  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}"`
+    );
   }
-  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]`);
+  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}"`
+      );
     }
   }
-  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, "\\-")
-    );
-  }
-  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}.`);
-      }
-    }
-  }
-  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");
@@ -1806,10 +2101,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(
@@ -1818,34 +2116,1164 @@ 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)) {
+  host.addCommand(completionCmd);
+}
+
+// src/discovery.ts
+init_esm_shims();
+import { Command as Command2, Option as Option2 } from "commander";
+init_errors();
+init_audit();
+var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
+function validateTag(tag) {
+  if (!TAG_PATTERN.test(tag)) {
+    process.stderr.write(
+      `Error: Invalid tag format: '${tag}'. Tags must match [a-z][a-z0-9_-]*.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+}
+function collectTag(value, previous) {
+  return previous.concat([value]);
+}
+function collectAnnotation(value, previous) {
+  return previous.concat([value]);
+}
+function getAnnotationFlag(moduleDef, flag) {
+  const annotations = moduleDef.annotations;
+  if (!annotations || typeof annotations !== "object") return false;
+  const ann = annotations;
+  const map = {
+    "destructive": "destructive",
+    "requires-approval": "requires_approval",
+    "readonly": "readonly",
+    "streaming": "streaming",
+    "cacheable": "cacheable",
+    "idempotent": "idempotent",
+    "paginated": "paginated"
+  };
+  const attr = map[flag] ?? flag;
+  return ann[attr] === true;
+}
+function registerListCommand(apcliGroup, registry, exposureFilter) {
+  const listCmd = new Command2("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--flat", "Show flat list (no grouping).", false).option("--format <format>", "Output format.", void 0).option("-s, --search <query>", "Filter by substring match on ID and description.").addOption(
+    new Option2("--status <status>", "Filter by module status.").choices(["enabled", "disabled", "all"]).default("enabled")
+  ).option("-a, --annotation <flag>", "Filter by annotation flag (AND logic). Repeatable.", collectAnnotation, []).addOption(
+    new Option2("--sort <field>", "Sort order.").choices(["id", "calls", "errors", "latency"]).default("id")
+  ).option("--reverse", "Reverse sort order.", false).option("--deprecated", "Include deprecated modules.", false).option("--deps", "Show dependency count column.", false).addOption(
+    new Option2("--exposure <mode>", "Filter by exposure status.").choices(["exposed", "hidden", "all"]).default("exposed")
+  ).action((opts) => {
+    for (const t of opts.tag) {
+      validateTag(t);
+    }
+    let modules = [];
+    for (const m of registry.listModules()) {
+      modules.push(m);
+    }
+    if (opts.tag.length > 0) {
+      const filterTags = new Set(opts.tag);
+      modules = modules.filter((m) => {
+        const mTags = m.tags ?? [];
+        return [...filterTags].every((t) => mTags.includes(t));
+      });
+    }
+    if (opts.search) {
+      const query = opts.search.toLowerCase();
+      modules = modules.filter(
+        (m) => (m.id ?? "").toLowerCase().includes(query) || (m.description ?? "").toLowerCase().includes(query)
+      );
+    }
+    if (opts.status === "enabled") {
+      modules = modules.filter((m) => {
+        const enabled = m.enabled;
+        return enabled !== false;
+      });
+    } else if (opts.status === "disabled") {
+      modules = modules.filter((m) => {
+        const enabled = m.enabled;
+        return enabled === false;
+      });
+    }
+    if (!opts.deprecated) {
+      modules = modules.filter((m) => {
+        const deprecated = m.deprecated;
+        return deprecated !== true;
+      });
+    }
+    if (opts.annotation.length > 0) {
+      for (const annFlag of opts.annotation) {
+        modules = modules.filter((m) => getAnnotationFlag(m, annFlag));
+      }
+    }
+    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.
+`
+      );
+    }
+    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 ?? ""));
+      }
+    }
+    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, showExposureCol ? exposureFilter : void 0);
+  });
+  apcliGroup.addCommand(listCmd);
+}
+function registerDescribeCommand(apcliGroup, registry) {
+  const describeCmd = new Command2("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").option("--format <format>", "Output format.", void 0).action((moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getModule(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(
+        `Error: Module '${moduleId}' not found.
+`
+      );
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
+    }
+    const fmt = resolveFormat(opts.format);
+    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);
+    }
+  });
+  apcliGroup.addCommand(execCmd);
+}
+function registerValidateCommand(cli, registry, executor) {
+  const validateCmd = new Command2("validate").description("Run preflight checks without executing a module.").argument("<module-id>", "Module ID to validate").option("--input <source>", "JSON input file or '-' for stdin.").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getModule(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(`Error: Module '${moduleId}' not found.
+`);
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
+    }
+    const merged = opts.input ? await collectInput(opts.input, {}, false) : {};
+    if (!executor.validate) {
+      process.stderr.write("Error: Executor does not support validate.\n");
+      process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
+    }
+    try {
+      const preflight = await executor.validate(moduleId, merged);
+      formatPreflightResult(preflight, opts.format);
+      process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+    } catch (err) {
+      const exitCode = exitCodeForError(err);
+      try {
+        const auditLogger = getAuditLogger();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, 0);
+        }
+      } catch {
+      }
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : err}
+`);
+      process.exit(exitCode);
+    }
+  });
+  cli.addCommand(validateCmd);
+}
+
+// src/system-cmd.ts
+init_esm_shims();
+init_errors();
+import { Command as Command3 } from "commander";
+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));
+}
+function formatHealthSummaryTty(result) {
+  const summary = result.summary ?? {};
+  const modules = result.modules ?? [];
+  if (modules.length === 0) {
+    process.stdout.write("No modules found.\n");
+    return;
+  }
+  const total = summary.total_modules ?? modules.length;
+  process.stdout.write(`Health Overview (${total} modules)
+
+`);
+  process.stdout.write(`  ${"Module".padEnd(28)} ${"Status".padEnd(12)} ${"Error Rate".padEnd(12)} Top Error
+`);
+  process.stdout.write(`  ${"-".repeat(28)} ${"-".repeat(12)} ${"-".repeat(12)} ${"-".repeat(20)}
+`);
+  for (const m of modules) {
+    const top = m.top_error;
+    const topStr = top ? `${top.code} (${top.count ?? "?"})` : "\u2014";
+    const rate = `${((m.error_rate ?? 0) * 100).toFixed(1)}%`;
+    process.stdout.write(
+      `  ${String(m.module_id).padEnd(28)} ${String(m.status).padEnd(12)} ${rate.padEnd(12)} ${topStr}
+`
+    );
+  }
+  const parts = [];
+  for (const key of ["healthy", "degraded", "error"]) {
+    const count = summary[key];
+    if (count) parts.push(`${count} ${key}`);
+  }
+  process.stdout.write(`
+Summary: ${parts.join(", ") || "no data"}
+`);
+}
+function formatHealthModuleTty(result) {
+  process.stdout.write(`Module: ${result.module_id ?? "?"}
+`);
+  process.stdout.write(`Status: ${result.status ?? "unknown"}
+`);
+  const total = result.total_calls ?? 0;
+  const errors = result.error_count ?? 0;
+  const rate = result.error_rate ?? 0;
+  const avg = result.avg_latency_ms ?? 0;
+  const p99 = result.p99_latency_ms ?? 0;
+  process.stdout.write(`Calls: ${total.toLocaleString()} total | ${errors.toLocaleString()} errors | ${(rate * 100).toFixed(1)}% error rate
+`);
+  process.stdout.write(`Latency: ${avg.toFixed(0)}ms avg | ${p99.toFixed(0)}ms p99
+`);
+  const recent = result.recent_errors ?? [];
+  if (recent.length > 0) {
+    process.stdout.write(`
+Recent Errors (top ${recent.length}):
+`);
+    for (const e of recent) {
+      const count = e.count ?? "?";
+      const last = e.last_occurred ?? "?";
+      process.stdout.write(`  ${String(e.code ?? "?").padEnd(24)} x${count}  (last: ${last})
+`);
+    }
+  }
+}
+function formatUsageSummaryTty(result) {
+  const modules = result.modules ?? [];
+  const period = result.period ?? "?";
+  if (modules.length === 0) {
+    process.stdout.write(`No usage data for period ${period}.
+`);
+    return;
+  }
+  process.stdout.write(`Usage Summary (last ${period})
+
+`);
+  process.stdout.write(`  ${"Module".padEnd(24)} ${"Calls".padStart(8)} ${"Errors".padStart(8)} ${"Avg Latency".padStart(12)} ${"Trend".padStart(10)}
+`);
+  process.stdout.write(`  ${"-".repeat(24)} ${"-".repeat(8)} ${"-".repeat(8)} ${"-".repeat(12)} ${"-".repeat(10)}
+`);
+  for (const m of modules) {
+    const avg = `${(m.avg_latency_ms ?? 0).toFixed(0)}ms`;
+    process.stdout.write(
+      `  ${String(m.module_id).padEnd(24)} ${String(m.call_count ?? 0).padStart(8)} ${String(m.error_count ?? 0).padStart(8)} ${avg.padStart(12)} ${String(m.trend ?? "").padStart(10)}
+`
+    );
+  }
+  const totalCalls = result.total_calls ?? modules.reduce((s, m) => s + (m.call_count ?? 0), 0);
+  const totalErrors = result.total_errors ?? modules.reduce((s, m) => s + (m.error_count ?? 0), 0);
+  process.stdout.write(`
+Total: ${totalCalls.toLocaleString()} calls | ${totalErrors.toLocaleString()} errors
+`);
+}
+function registerHealthCommand(apcliGroup, executor) {
+  const healthCmd = new Command3("health").description("Show module health status. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed health").option("--threshold <number>", "Error rate threshold (default: 0.01).", parseFloat, 0.01).option("--all", "Include healthy modules.", false).option("--errors <count>", "Max recent errors (module detail only).", parseInt, 10).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      if (moduleId) {
+        const result = await callSystemModule(executor, "system.health.module", {
+          module_id: moduleId,
+          error_limit: opts.errors
+        });
+        emitResult(result, fmt, () => formatHealthModuleTty(result));
+      } else {
+        const result = await callSystemModule(executor, "system.health.summary", {
+          error_rate_threshold: opts.threshold,
+          include_healthy: opts.all
+        });
+        emitResult(result, fmt, () => formatHealthSummaryTty(result));
+      }
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(healthCmd);
+}
+function registerUsageCommand(apcliGroup, executor) {
+  const usageCmd = new Command3("usage").description("Show module usage statistics. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed usage").option("--period <period>", "Time window: 1h, 24h, 7d, 30d.", "24h").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      let result;
+      if (moduleId) {
+        result = await callSystemModule(executor, "system.usage.module", {
+          module_id: moduleId,
+          period: opts.period
+        });
+      } else {
+        result = await callSystemModule(executor, "system.usage.summary", {
+          period: opts.period
+        });
+      }
+      emitResult(result, fmt, () => {
+        if (moduleId) {
+          formatExecResult(result, fmt);
+        } else {
+          formatUsageSummaryTty(result);
+        }
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(usageCmd);
+}
+function registerEnableCommand(apcliGroup, executor) {
+  const enableCmd = new Command3("enable").description("Enable a disabled module at runtime.").argument("<module-id>", "Module ID to enable").requiredOption("--reason <reason>", "Reason for enabling (required for audit).").option("-y, --yes", "Signal explicit intent (forwarded to server-side approval gate).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      const result = await callSystemModule(executor, "system.control.toggle_feature", {
+        module_id: moduleId,
+        enabled: true,
+        reason: opts.reason
+      });
+      emitResult(result, fmt, () => {
+        process.stdout.write(`Module '${moduleId}' enabled.
+  Reason: ${opts.reason}
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(enableCmd);
+}
+function registerDisableCommand(apcliGroup, executor) {
+  const disableCmd = new Command3("disable").description("Disable a module at runtime (calls are rejected until re-enabled).").argument("<module-id>", "Module ID to disable").requiredOption("--reason <reason>", "Reason for disabling (required for audit).").option("-y, --yes", "Signal explicit intent (forwarded to server-side approval gate).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      const result = await callSystemModule(executor, "system.control.toggle_feature", {
+        module_id: moduleId,
+        enabled: false,
+        reason: opts.reason
+      });
+      emitResult(result, fmt, () => {
+        process.stdout.write(`Module '${moduleId}' disabled.
+  Reason: ${opts.reason}
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(disableCmd);
+}
+function registerReloadCommand(apcliGroup, executor) {
+  const reloadCmd = new Command3("reload").description("Hot-reload a module from disk.").argument("<module-id>", "Module ID to reload").requiredOption("--reason <reason>", "Reason for reload (required for audit).").option("-y, --yes", "Signal explicit intent (forwarded to server-side approval gate).", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      const result = await callSystemModule(executor, "system.control.reload_module", {
+        module_id: moduleId,
+        reason: opts.reason
+      });
+      emitResult(result, fmt, () => {
+        const prev = result.previous_version ?? "?";
+        const newVer = result.new_version ?? "?";
+        const dur = result.reload_duration_ms ?? "?";
+        process.stdout.write(`Module '${moduleId}' reloaded.
+`);
+        process.stdout.write(`  Version: ${prev} -> ${newVer}
+`);
+        process.stdout.write(`  Duration: ${dur}ms
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  apcliGroup.addCommand(reloadCmd);
+}
+function registerConfigCommand(apcliGroup, executor) {
+  const configGroup = new Command3("config").description("Read or update runtime configuration.");
+  const configGetCmd = new Command3("get").description("Read a configuration value by dot-path key.").argument("<key>", "Configuration key (dot-path)").option("--format <format>", "Output format.", "table").action(async (key, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      const result = await callSystemModule(executor, "system.config.get", { key });
+      const value = result?.value ?? result;
+      emitResult({ key, value }, fmt, () => {
+        process.stdout.write(`${key} = ${JSON.stringify(value)}
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  configGroup.addCommand(configGetCmd);
+  const configSetCmd = new Command3("set").description("Update a runtime configuration value (audit-logged; server-side approval gate applies).").argument("<key>", "Configuration key (dot-path)").argument("<value>", "New value").requiredOption("--reason <reason>", "Reason for config change (required for audit).").option("--format <format>", "Output format.").action(async (key, value, opts) => {
+    const fmt = resolveFormat(opts.format);
+    let parsedValue;
+    try {
+      parsedValue = JSON.parse(value);
+    } catch {
+      parsedValue = value;
+    }
+    try {
+      const result = await callSystemModule(executor, "system.control.update_config", {
+        key,
+        value: parsedValue,
+        reason: opts.reason
+      });
+      emitResult(result, fmt, () => {
+        const old = result.old_value ?? "?";
+        const newVal = result.new_value ?? "?";
+        process.stdout.write(`Config updated: ${key}
+`);
+        process.stdout.write(`  ${JSON.stringify(old)} -> ${JSON.stringify(newVal)}
+`);
+        process.stdout.write(`  Reason: ${opts.reason}
+`);
+      });
+    } catch (e) {
+      emitErrorAndExit(e);
+    }
+  });
+  configGroup.addCommand(configSetCmd);
+  apcliGroup.addCommand(configGroup);
+}
+
+// src/strategy.ts
+init_esm_shims();
+import { Command as 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",
+    "call_chain_guard",
+    "module_lookup",
+    "acl_check",
+    "approval_gate",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  internal: [
+    "context_creation",
+    "call_chain_guard",
+    "module_lookup",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  testing: [
+    "context_creation",
+    "module_lookup",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  performance: [
+    "context_creation",
+    "call_chain_guard",
+    "module_lookup",
+    "acl_check",
+    "approval_gate",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "return_result"
+  ],
+  minimal: [
+    "context_creation",
+    "module_lookup",
+    "execute",
+    "return_result"
+  ]
+};
+function registerPipelineCommand(cli, executor) {
+  const pipelineCmd = new Command4("describe-pipeline").description("Show the execution pipeline steps for a strategy.").addOption(
+    new Option3("--strategy <name>", "Strategy to describe (default: standard).").choices(["standard", "internal", "testing", "performance", "minimal"]).default("standard")
+  ).option("--format <format>", "Output format.").action((opts) => {
+    const fmt = resolveFormat(opts.format);
+    const { info, isCurrent } = lookupStrategyInfo(executor, opts.strategy);
+    if (info) {
+      const strategySteps = isCurrent ? executor.currentStrategy?.steps ?? [] : [];
+      const header = `Pipeline: ${info.name} (${info.stepCount} steps)`;
+      if (fmt === "json" || !process.stdout.isTTY) {
+        const payload = {
+          strategy: info.name,
+          step_count: info.stepCount,
+          description: info.description,
+          steps: info.stepNames.map((name, i) => {
+            const stepMeta = strategySteps[i];
+            return {
+              index: i + 1,
+              name,
+              pure: stepMeta?.pure ?? false,
+              removable: stepMeta?.removable ?? true,
+              timeout_ms: stepMeta?.timeoutMs ?? null
+            };
+          })
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+      } else {
+        process.stdout.write(`${header}
+
+`);
+        process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
+`);
+        process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
+`);
+        for (let i = 0; i < info.stepNames.length; i++) {
+          const stepMeta = strategySteps[i];
+          const pure = stepMeta?.pure ? "yes" : "no";
+          const removable = stepMeta?.removable !== false ? "yes" : "no";
+          const timeout = stepMeta?.timeoutMs ? `${stepMeta.timeoutMs}ms` : "\u2014";
+          process.stdout.write(`  ${String(i + 1).padEnd(4)} ${info.stepNames[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} ${timeout}
+`);
+        }
+      }
+      return;
+    }
+    const steps = PRESET_STEPS[opts.strategy] ?? [];
+    const pureSteps = /* @__PURE__ */ new Set([
+      "context_creation",
+      "call_chain_guard",
+      "module_lookup",
+      "acl_check",
+      "input_validation"
+    ]);
+    const nonRemovable = /* @__PURE__ */ new Set([
+      "context_creation",
+      "module_lookup",
+      "execute",
+      "return_result"
+    ]);
+    if (fmt === "json" || !process.stdout.isTTY) {
+      const payload = {
+        strategy: opts.strategy,
+        step_count: steps.length,
+        steps: steps.map((s, i) => ({
+          index: i + 1,
+          name: s,
+          pure: pureSteps.has(s),
+          removable: !nonRemovable.has(s)
+        }))
+      };
+      process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    } else {
+      process.stdout.write(`Pipeline: ${opts.strategy} (${steps.length} steps)
+
+`);
+      process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
+`);
+      process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
+`);
+      for (let i = 0; i < steps.length; i++) {
+        const pure = pureSteps.has(steps[i]) ? "yes" : "no";
+        const removable = nonRemovable.has(steps[i]) ? "no" : "yes";
+        process.stdout.write(`  ${String(i + 1).padEnd(4)} ${steps[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} \u2014
+`);
+      }
+    }
+  });
+  cli.addCommand(pipelineCmd);
+}
+
+// src/builtin-group.ts
+init_esm_shims();
+init_errors();
+init_logger();
+var RESERVED_GROUP_NAMES = /* @__PURE__ */ new Set(["apcli"]);
+var VALID_USER_MODES = /* @__PURE__ */ new Set([
+  "all",
+  "none",
+  "include",
+  "exclude"
+]);
+var APCLI_SUBCOMMAND_NAMES = /* @__PURE__ */ new Set([
+  "list",
+  "describe",
+  "exec",
+  "validate",
+  "init",
+  "health",
+  "usage",
+  "enable",
+  "disable",
+  "reload",
+  "config",
+  "completion",
+  "describe-pipeline"
+]);
+var ApcliGroup = class _ApcliGroup {
+  _mode;
+  _include;
+  _exclude;
+  _disableEnv;
+  _registryInjected;
+  _fromCliConfig;
+  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;
+  }
+  /**
+   * 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) {
+    return _ApcliGroup._build(
+      config,
+      opts,
+      /*fromCliConfig*/
+      false
+    );
+  }
+  /**
+   * Non-panicking Tier 3 factory (A-001 parity with Rust's `try_from_yaml`).
+   * Returns `[instance, null]` on success or `[null, errorMessage]` on invalid input.
+   * Use this in programmatic contexts where throwing/exiting is unwanted.
+   */
+  static tryFromYaml(config, opts) {
+    if (config !== null && config !== void 0 && typeof config !== "boolean" && typeof config !== "object") {
+      return [null, `apcore.yaml 'apcli:' must be a bool, object, or null; got ${typeof config}`];
+    }
+    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];
+  }
+  // -------------------------------------------------------------------------
+  // Internal builder — shared by both factories
+  // -------------------------------------------------------------------------
+  static _build(config, opts, fromCliConfig) {
+    if (config === true) {
+      return new _ApcliGroup({
+        mode: "all",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig
+      });
+    }
+    if (config === false) {
+      return new _ApcliGroup({
+        mode: "none",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig
+      });
+    }
+    if (config === void 0 || config === null) {
+      return new _ApcliGroup({
+        mode: "auto",
+        include: [],
+        exclude: [],
+        disableEnv: false,
+        registryInjected: opts.registryInjected,
+        fromCliConfig
+      });
+    }
+    if (typeof config !== "object" || Array.isArray(config)) {
+      process.stderr.write(
+        `Error: apcli config must be a boolean or object; got ${Array.isArray(config) ? "array" : typeof config}.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    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: Unknown command '${commandName}'.
+        `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 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.`
+        );
+      }
+    }
+    return new _ApcliGroup({
+      mode,
+      include,
+      exclude,
+      disableEnv,
+      registryInjected: opts.registryInjected,
+      fromCliConfig
+    });
+  }
+  /**
+   * Normalize an include/exclude list. Non-array → warn and return [].
+   *
+   * Unknown but well-formed entries emit a WARNING (spec §7 error table,
+   * T-APCLI-25) but are retained in the returned list for forward-compat —
+   * if apcore-cli later adds a subcommand named `foo`, existing configs
+   * continue to work without a config change. At runtime, unknown names
+   * simply never match any registered subcommand.
+   */
+  static _normalizeList(raw, label) {
+    if (raw === void 0 || raw === null) return [];
+    if (!Array.isArray(raw)) {
+      warn(`apcli.${label} must be a list; got ${typeof raw}. Ignoring.`);
+      return [];
+    }
+    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 out;
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  resolveVisibility() {
+    if (this._fromCliConfig && this._mode !== "auto") {
+      return this._mode;
+    }
+    if (!this._disableEnv) {
+      const envMode = this._parseEnv(process.env.APCORE_CLI_APCLI);
+      if (envMode !== null) {
+        return envMode;
+      }
+    }
+    if (this._mode !== "auto") {
+      return this._mode;
+    }
+    return this._registryInjected ? "none" : "all";
+  }
+  /**
+   * 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).
+   */
+  isSubcommandIncluded(subcommand) {
+    const mode = this.resolveVisibility();
+    if (mode === "include") return this._include.includes(subcommand);
+    if (mode === "exclude") return !this._exclude.includes(subcommand);
+    throw new Error(
+      `isSubcommandIncluded called under mode '${mode}'; caller should bypass.`
+    );
+  }
+  /** True iff the `apcli` group itself should appear in root `--help`. */
+  isGroupVisible() {
+    return this.resolveVisibility() !== "none";
+  }
+  // -------------------------------------------------------------------------
+  // Env parser (Tier 2) — co-located per spec §4.4
+  // -------------------------------------------------------------------------
+  /**
+   * Parse APCORE_CLI_APCLI. Case-insensitive.
+   *
+   * - `show` / `1` / `true` → `"all"`
+   * - `hide` / `0` / `false` → `"none"`
+   * - Empty / unset → `null`
+   * - Anything else → warn and return `null`
+   */
+  _parseEnv(raw) {
+    if (raw === void 0 || raw === "") return null;
+    const normalized = raw.toLowerCase();
+    if (normalized === "show" || normalized === "1" || normalized === "true") {
+      return "all";
+    }
+    if (normalized === "hide" || normalized === "0" || normalized === "false") {
+      return "none";
     }
-    const resolved = cli.name() || progName;
-    const roff = generateManPage(commandName, cmd, resolved);
-    process.stdout.write(roff);
+    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);
   });
-  cli.addCommand(manCmd);
+  let regex = regexParts.join("[^.]*");
+  regex = regex.replaceAll("\\*\\*", ".+");
+  return new RegExp(`^${regex}$`);
+}
+var ExposureFilter = class _ExposureFilter {
+  static VALID_MODES = ["all", "include", "exclude", "none"];
+  _mode;
+  _compiledInclude;
+  _compiledExclude;
+  constructor(mode = "all", include, exclude) {
+    if (!_ExposureFilter.VALID_MODES.includes(mode)) {
+      process.stderr.write(
+        `Warning: Unknown ExposureFilter mode '${mode}' \u2014 defaulting to 'none'. Valid modes: ${_ExposureFilter.VALID_MODES.join(", ")}.
+`
+      );
+      mode = "none";
+    }
+    this._mode = mode;
+    const dedup = (arr) => [...new Set(arr)];
+    this._compiledInclude = dedup(include ?? []).map(compilePattern);
+    this._compiledExclude = dedup(exclude ?? []).map(compilePattern);
+  }
+  /** Return true if the module should be exposed as a CLI command. */
+  isExposed(moduleId) {
+    if (this._mode === "all") return true;
+    if (this._mode === "include") {
+      return this._compiledInclude.some((rx) => rx.test(moduleId));
+    }
+    if (this._mode === "exclude") {
+      return !this._compiledExclude.some((rx) => rx.test(moduleId));
+    }
+    return false;
+  }
+  /** Partition moduleIds into [exposed, hidden] lists. */
+  filterModules(moduleIds) {
+    const exposed = [];
+    const hidden = [];
+    for (const mid of moduleIds) {
+      (this.isExposed(mid) ? exposed : hidden).push(mid);
+    }
+    return [exposed, hidden];
+  }
+  /**
+   * Create an ExposureFilter from a parsed config dict.
+   *
+   * Expected: `{ expose: { mode: "include", include: ["admin.*"] } }`
+   */
+  static fromConfig(config) {
+    const expose = config.expose ?? {};
+    if (typeof expose !== "object" || expose === null || Array.isArray(expose)) {
+      warn("Invalid 'expose' config (expected dict), using mode: all.");
+      return new _ExposureFilter();
+    }
+    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
+init_audit();
+
+// src/canonical-help.ts
+init_esm_shims();
+function resolveHelpText(cmd, section) {
+  const bag = cmd._helpText;
+  const v = bag?.[section];
+  if (typeof v === "function") return v({ error: false, command: cmd });
+  return v ?? "";
+}
+function uppercasePlaceholders(flags) {
+  return flags.replace(/<([a-zA-Z0-9_-]+)>/g, (_, name) => `<${name.toUpperCase()}>`).replace(/\[([a-zA-Z0-9_-]+)\]/g, (_, name) => `[${name.toUpperCase()}]`);
+}
+function optionTerm(opt) {
+  const flags = uppercasePlaceholders(opt.flags);
+  if (!opt.short && flags.startsWith("--")) return "    " + flags;
+  return flags;
+}
+function optionDescription(opt) {
+  let desc = opt.description;
+  const d = opt.defaultValue;
+  if (d !== void 0 && d !== false && d !== "" && d !== null) {
+    desc = `${desc} [default: ${String(d)}]`;
+  }
+  return desc;
+}
+function reorderHelpVersionLast(opts) {
+  const helpOpts = [];
+  const versionOpts = [];
+  const rest = [];
+  for (const o of opts) {
+    if (o.long === "--help") helpOpts.push(o);
+    else if (o.long === "--version") versionOpts.push(o);
+    else rest.push(o);
+  }
+  return [...rest, ...helpOpts, ...versionOpts];
+}
+function canonicalFormatHelp(cmd, helper) {
+  const sections = [];
+  const beforeAll = resolveHelpText(cmd, "beforeAll");
+  if (beforeAll) sections.push(beforeAll);
+  const desc = cmd.description();
+  if (desc) sections.push(desc);
+  const before = resolveHelpText(cmd, "before");
+  if (before) sections.push(before);
+  const visibleOpts = reorderHelpVersionLast(helper.visibleOptions(cmd));
+  const visibleCmds = helper.visibleCommands(cmd);
+  const args = cmd.registeredArguments ?? [];
+  let usage = `Usage: ${cmd.name()}`;
+  if (visibleOpts.length > 0) usage += " [OPTIONS]";
+  for (const a of args) {
+    const n = a.name().toUpperCase();
+    usage += a.required ? ` <${n}>` : ` [${n}]`;
+  }
+  if (visibleCmds.length > 0) usage += " [COMMAND]";
+  sections.push(usage);
+  if (visibleCmds.length > 0) {
+    const terms = visibleCmds.map((c) => c.name());
+    const w = Math.max(...terms.map((t) => t.length));
+    const lines = ["Commands:"];
+    visibleCmds.forEach((sub, i) => {
+      lines.push(`  ${terms[i].padEnd(w)}  ${sub.description()}`);
+    });
+    sections.push(lines.join("\n"));
+  }
+  if (visibleOpts.length > 0) {
+    const terms = visibleOpts.map(optionTerm);
+    const w = Math.max(...terms.map((t) => t.length));
+    const lines = ["Options:"];
+    visibleOpts.forEach((opt, i) => {
+      lines.push(`  ${terms[i].padEnd(w)}  ${optionDescription(opt)}`);
+    });
+    sections.push(lines.join("\n"));
+  }
+  const after = resolveHelpText(cmd, "after");
+  if (after) sections.push(after);
+  const afterAll = resolveHelpText(cmd, "afterAll");
+  if (afterAll) sections.push(afterAll);
+  return sections.join("\n\n") + "\n";
 }
 
 // src/main.ts
-var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
+var __dirname2 = path4.dirname(fileURLToPath2(import.meta.url));
 var verboseHelp = false;
 function setVerboseHelp(verbose) {
   verboseHelp = verbose;
@@ -1857,28 +3285,225 @@ function setDocsUrl(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(path6.resolve(__dirname3, "../package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync2(path4.resolve(__dirname2, "../package.json"), "utf-8"));
   VERSION = pkg.version;
 } catch {
 }
-function createCli(extensionsDir, progName, verbose = false) {
+function emitErrorJson(e, exitCode) {
+  const err = e instanceof Error ? e : new Error(String(e));
+  const errRecord = err;
+  const code = errRecord.code ?? "UNKNOWN";
+  const payload = {
+    error: true,
+    code,
+    message: err.message,
+    exit_code: exitCode
+  };
+  for (const field of ["details", "suggestion", "ai_guidance", "retryable", "user_fixable"]) {
+    const val = errRecord[field];
+    if (val !== void 0 && val !== null) {
+      payload[field] = val;
+    }
+  }
+  process.stderr.write(JSON.stringify(payload) + "\n");
+}
+function emitErrorTty(e, exitCode) {
+  const err = e instanceof Error ? e : new Error(String(e));
+  const errRecord = err;
+  const code = errRecord.code;
+  const header = code ? `Error [${code}]: ${err.message}` : `Error: ${err.message}`;
+  process.stderr.write(header + "\n");
+  const details = errRecord.details;
+  if (details && typeof details === "object" && !Array.isArray(details)) {
+    process.stderr.write("\n  Details:\n");
+    for (const [k, v] of Object.entries(details)) {
+      process.stderr.write(`    ${k}: ${v}
+`);
+    }
+  }
+  const suggestion = errRecord.suggestion;
+  if (suggestion) {
+    process.stderr.write(`
+  Suggestion: ${suggestion}
+`);
+  }
+  const retryable = errRecord.retryable;
+  if (retryable !== void 0 && retryable !== null) {
+    const label = retryable ? "Yes" : "No (same input will fail again)";
+    process.stderr.write(`  Retryable: ${label}
+`);
+  }
+  process.stderr.write(`
+  Exit code: ${exitCode}
+`);
+}
+function createCli(extensionsDirOrOpts, progName, verbose = false) {
+  let extensionsDir;
+  let registry;
+  let executor;
+  let extraCommands;
+  let app;
+  let expose;
+  let apcliOption;
+  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;
+  } 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 ?? path4.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
   const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? "WARNING";
   setLogLevel(cliLogLevel);
-  const program = new Command2(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--commands-dir <path>", "Path to convention-based commands directory").option("--binding <path>", "Path to binding.yaml for display overlay").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
-  const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
-  void resolvedExtDir;
+  if (app && (registry || executor)) {
+    process.stderr.write("Error: app is mutually exclusive with registry/executor\n");
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (app) {
+    registry = app.registry;
+    executor = app.executor;
+  }
+  if (executor && !registry) {
+    process.stderr.write("Error: executor requires registry \u2014 pass both or neither\n");
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (executor && typeof executor.setApprovalHandler === "function") {
+    try {
+      const handler = new CliApprovalHandler(
+        /*autoApprove*/
+        false
+      );
+      executor.setApprovalHandler(handler);
+    } catch {
+    }
+  }
+  const registryInjected = registry !== void 0;
+  const program = new Command5(resolvedProgName).exitOverride().version(VERSION, "-V, --version", "Print version").helpOption("-h, --help", "Print help").addHelpCommand("help [command]", "Print this message or the help of the given subcommand(s)").description("apcore CLI \u2014 execute apcore modules from the command line").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
+  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;
+  if (apcliOption instanceof ApcliGroup) {
+    apcliCfg = apcliOption;
+  } else if (apcliOption !== void 0) {
+    apcliCfg = ApcliGroup.fromCliConfig(apcliOption, { registryInjected });
+  } else {
+    let yamlVal = null;
+    try {
+      const resolver = new ConfigResolver();
+      yamlVal = resolver.resolveObject("apcli");
+    } catch {
+      yamlVal = null;
+    }
+    apcliCfg = ApcliGroup.fromYaml(yamlVal, { registryInjected });
+  }
+  const apcliGroup = program.command("apcli", { hidden: !apcliCfg.isGroupVisible() }).description("apcore-cli built-in commands");
+  if (registry) {
+    program._registry = registry;
+    if (executor) {
+      program._executor = executor;
+    }
+  } else {
+    const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
+    void resolvedExtDir;
+  }
+  let exposureFilter;
+  try {
+    if (expose instanceof ExposureFilter) {
+      exposureFilter = expose;
+    } else if (typeof expose === "object" && expose !== null) {
+      exposureFilter = ExposureFilter.fromConfig({ expose });
+    } else {
+      exposureFilter = new ExposureFilter();
+    }
+  } 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);
+  _registerDeprecationShims(program, apcliGroup, registryInjected, resolvedProgName);
   program.addHelpText("after", [
     "",
     "Use --help --verbose to show all options (including built-in apcore options).",
     "Use --help --man to display a formatted man page."
   ].join("\n"));
-  registerInitCommand(program);
   configureManHelp(program, resolvedProgName, VERSION);
+  if (extraCommands && extraCommands.length > 0) {
+    for (const cmd of extraCommands) {
+      const cmdName = cmd.name();
+      if (RESERVED_GROUP_NAMES.has(cmdName)) {
+        process.stderr.write(
+          `Error: extraCommands name '${cmdName}' is reserved
+`
+        );
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      }
+      const existing = program.commands.find((c) => c.name() === cmdName);
+      if (existing) {
+        const isShim = existing.__isDeprecationShim === true;
+        if (isShim) {
+          warn(
+            `extraCommands '${cmdName}' overrides the deprecation shim for the same name. The shim will be removed.`
+          );
+          const cmds = program.commands;
+          const idx = cmds.indexOf(existing);
+          if (idx >= 0) cmds.splice(idx, 1);
+        } else {
+          process.stderr.write(
+            `Error: extraCommands name '${cmdName}' collides with an existing command
+`
+          );
+          process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+        }
+      }
+      program.addCommand(cmd);
+    }
+  }
   program.hook("preAction", async (thisCommand) => {
     const opts = thisCommand.opts();
     const commandsDir = opts.commandsDir;
@@ -1887,25 +3512,146 @@ function createCli(extensionsDir, progName, verbose = false) {
   });
   return program;
 }
+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 _DEPRECATED_ROOT_COMMANDS = [
+  "list",
+  "describe",
+  "exec",
+  "init",
+  "validate",
+  "health",
+  "usage",
+  "enable",
+  "disable",
+  "reload",
+  "config",
+  "completion",
+  "describe-pipeline"
+];
+function _registerDeprecationShims(root, apcliGroup, registryInjected, cliName) {
+  if (registryInjected) return;
+  for (const name of _DEPRECATED_ROOT_COMMANDS) {
+    const apcliSub = apcliGroup.commands.find((c) => c.name() === name);
+    if (!apcliSub) continue;
+    if (root.commands.some((c) => c.name() === name)) continue;
+    const shim = root.command(name).description(`[DEPRECATED] Use '${cliName} apcli ${name}' instead.`).allowUnknownOption(true).allowExcessArguments(true).helpOption(false);
+    shim.__isDeprecationShim = true;
+    shim.action(async function() {
+      process.stderr.write(
+        `WARNING: '${name}' as a root-level command is deprecated. Use '${cliName} apcli ${name}' instead.
+         Will be removed in v0.8. See: https://aiperceivable.github.io/apcore-cli/features/builtin-group/#11-migration
+`
+      );
+      const tail = _collectShimForwardArgs(this);
+      await apcliSub.parseAsync(tail, { from: "user" });
+    });
+  }
+}
+function _collectShimForwardArgs(shim) {
+  const shimArgs = (shim.args ?? []).slice();
+  if (shimArgs.length > 0) return shimArgs;
+  const shimName = shim.name();
+  const idx = process.argv.indexOf(shimName);
+  if (idx < 0) return [];
+  return process.argv.slice(idx + 1);
+}
+var bindingDisplayMap = /* @__PURE__ */ new Map();
+function lookupBindingDisplay(moduleId) {
+  return bindingDisplayMap.get(moduleId);
+}
 async function applyToolkitIntegration(commandsDir, bindingPath) {
   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);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warn(`apcore-toolkit: failed to load binding '${bindingPath}': ${msg}`);
     }
-    if (bindingPath) {
-      const resolver = new toolkit.DisplayResolver();
-      void resolver;
+  }
+}
+async function loadBindingDisplayOverlay(toolkit, bindingPath) {
+  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 });
+  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;
+    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) {
@@ -1913,13 +3659,13 @@ function main(progName) {
   const program = createCli(void 0, progName, verboseHelp);
   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);
@@ -1942,23 +3688,44 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
     }
     schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
   }
-  const cmd = new Command2(effectiveCmdName).description(cmdHelp);
-  const inputOpt = new Option2("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
-  const yesOpt = new Option2("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
-  const largeInputOpt = new Option2("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
-  const formatOpt = new Option2("--format <format>", "Set output format: 'json' for machine-readable, 'table' for human-readable");
-  const sandboxOpt = new Option2("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
+  const cmd = new Command5(effectiveCmdName).description(cmdHelp);
+  const inputOpt = new Option4("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
+  const yesOpt = new Option4("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
+  const largeInputOpt = new Option4("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
+  const formatOpt = new Option4("--format <format>", "Output format: json, table, csv, yaml, jsonl.").choices(["json", "table", "csv", "yaml", "jsonl"]);
+  const fieldsOpt = new Option4("--fields <fields>", "Comma-separated dot-paths to select from the result (e.g., 'status,data.count').");
+  const sandboxOpt = new Option4("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
+  const dryRunOpt = new Option4("--dry-run", "Run preflight checks without executing the module. Shows validation results.").default(false);
+  const traceOpt = new Option4("--trace", "Show execution pipeline trace with per-step timing after the result.").default(false);
+  const streamOpt = new Option4("--stream", "Stream module output as JSONL (one JSON object per line, flushed immediately).").default(false);
+  const strategyOpt = new Option4("--strategy <name>", "Execution pipeline strategy: standard (default), internal, testing, performance.").choices(["standard", "internal", "testing", "performance", "minimal"]);
+  const approvalTimeoutOpt = new Option4("--approval-timeout <seconds>", "Override approval prompt timeout in seconds (default: 60).").argParser(parseInt);
+  const approvalTokenOpt = new Option4("--approval-token <token>", "Resume a pending approval with the given token (for async approval flows).");
   if (!verbose) {
     inputOpt.hideHelp();
     yesOpt.hideHelp();
     largeInputOpt.hideHelp();
     formatOpt.hideHelp();
+    fieldsOpt.hideHelp();
+    dryRunOpt.hideHelp();
+    traceOpt.hideHelp();
+    streamOpt.hideHelp();
+    strategyOpt.hideHelp();
+    approvalTimeoutOpt.hideHelp();
+    approvalTokenOpt.hideHelp();
   }
   cmd.addOption(inputOpt);
   cmd.addOption(yesOpt);
   cmd.addOption(largeInputOpt);
   cmd.addOption(formatOpt);
+  cmd.addOption(fieldsOpt);
   cmd.addOption(sandboxOpt);
+  cmd.addOption(dryRunOpt);
+  cmd.addOption(traceOpt);
+  cmd.addOption(streamOpt);
+  cmd.addOption(strategyOpt);
+  cmd.addOption(approvalTimeoutOpt);
+  cmd.addOption(approvalTokenOpt);
   const footerParts = [];
   if (!verbose) {
     footerParts.push("Use --verbose to show all options (including built-in apcore options).");
@@ -1981,49 +3748,225 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
     const autoApprove = options.yes;
     const largeInput = options.largeInput;
     const outputFormat = options.format;
+    const outputFields = options.fields;
     const sandboxEnabled = options.sandbox;
+    const dryRun = options.dryRun;
+    const traceFlag = options.trace;
+    const streamFlag = options.stream;
+    const strategyName = resolveStringOption(options.strategy, process.env.APCORE_CLI_STRATEGY);
+    const approvalTimeout = resolveIntOption(
+      options.approvalTimeout,
+      process.env.APCORE_CLI_APPROVAL_TIMEOUT,
+      60
+    );
+    const approvalToken = options.approvalToken;
     const schemaKwargs = {};
-    const builtinKeys = /* @__PURE__ */ new Set(["input", "yes", "largeInput", "format", "sandbox", "verbose"]);
+    const builtinKeys = /* @__PURE__ */ new Set([
+      "input",
+      "yes",
+      "largeInput",
+      "format",
+      "fields",
+      "sandbox",
+      "verbose",
+      "dryRun",
+      "trace",
+      "stream",
+      "strategy",
+      "approvalTimeout",
+      "approvalToken"
+    ]);
     for (const [k, v] of Object.entries(options)) {
       if (!builtinKeys.has(k)) {
         schemaKwargs[k] = v;
       }
     }
+    let merged = {};
+    const startTime = performance.now();
     try {
-      const merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
+      merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
       const reconverted = reconvertEnumValues(merged, schemaOptions);
-      await checkApproval(moduleDef, autoApprove);
-      const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
-      const sandbox = new Sandbox2(sandboxEnabled);
-      const startTime = performance.now();
-      const result = await sandbox.execute(moduleId, reconverted, executor);
+      merged = reconverted;
+      if (dryRun) {
+        if (!executor.validate) {
+          process.stderr.write("Error: Executor does not support validate.\n");
+          process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
+        }
+        const preflight = await executor.validate(moduleId, merged);
+        formatPreflightResult(preflight, outputFormat);
+        if (traceFlag) {
+          const pureSteps = /* @__PURE__ */ new Set([
+            "context_creation",
+            "call_chain_guard",
+            "module_lookup",
+            "acl_check",
+            "input_validation"
+          ]);
+          const allSteps = [
+            "context_creation",
+            "call_chain_guard",
+            "module_lookup",
+            "acl_check",
+            "approval_gate",
+            "middleware_before",
+            "input_validation",
+            "execute",
+            "output_validation",
+            "middleware_after",
+            "return_result"
+          ];
+          process.stderr.write("\nPipeline preview (dry-run):\n");
+          for (const s of allSteps) {
+            if (pureSteps.has(s)) {
+              process.stderr.write(`  \u2713 ${s.padEnd(24)} (pure \u2014 would execute)
+`);
+            } else {
+              process.stderr.write(`  \u25CB ${s.padEnd(24)} (impure \u2014 skipped in dry-run)
+`);
+            }
+          }
+        }
+        process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+      }
+      if (approvalToken) {
+        merged._approval_token = approvalToken;
+      }
+      await checkApproval(moduleDef, autoApprove, approvalTimeout);
+      if (streamFlag) {
+        if (resolveFormat(outputFormat) === "table") {
+          process.stderr.write("Warning: Streaming mode always outputs JSONL; --format table is ignored.\n");
+        }
+        const annotations = moduleDef.annotations;
+        const isStreaming = annotations?.streaming === true;
+        if (!isStreaming) {
+          process.stderr.write(
+            `Warning: Module '${moduleId}' does not declare streaming support. Falling back to standard execution.
+`
+          );
+        }
+        if (isStreaming && executor.stream) {
+          let chunks = 0;
+          for await (const chunk of executor.stream(moduleId, merged)) {
+            chunks++;
+            process.stdout.write(JSON.stringify(chunk) + "\n");
+            if (process.stderr.isTTY) {
+              process.stderr.write(`\rStreaming ${moduleId}... (${chunks} chunks)`);
+            }
+          }
+          if (process.stderr.isTTY) {
+            process.stderr.write("\n");
+          }
+          const durationMs2 = Math.round(performance.now() - startTime);
+          const { getAuditLogger: getAuditLogger3 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+          const auditLogger2 = getAuditLogger3();
+          if (auditLogger2) {
+            auditLogger2.logExecution(moduleId, merged, "success", 0, durationMs2);
+          }
+          return;
+        }
+      }
+      if (traceFlag && executor.callWithTrace) {
+        const [result2, trace] = await executor.callWithTrace(
+          moduleId,
+          merged,
+          strategyName ? { strategy: strategyName } : void 0
+        );
+        const durationMs2 = Math.round(performance.now() - startTime);
+        const resolved = resolveFormat(outputFormat);
+        if (resolved === "json" || !process.stdout.isTTY) {
+          const traceData = {
+            strategy: trace.strategyName,
+            total_duration_ms: trace.totalDurationMs,
+            success: trace.success,
+            steps: trace.steps.map((s) => ({
+              name: s.name,
+              duration_ms: s.durationMs,
+              skipped: s.skipped,
+              ...s.skipped ? { skip_reason: s.skipReason ?? null } : {}
+            }))
+          };
+          let output;
+          if (typeof result2 === "object" && result2 !== null && !Array.isArray(result2)) {
+            output = { ...result2, _trace: traceData };
+          } else {
+            output = { result: result2, _trace: traceData };
+          }
+          process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+        } else {
+          formatExecResult(result2, outputFormat, outputFields);
+          const stepCount = trace.steps.length;
+          process.stderr.write(
+            `
+Pipeline Trace (strategy: ${trace.strategyName}, ${stepCount} steps, ${trace.totalDurationMs.toFixed(1)}ms)
+`
+          );
+          for (const s of trace.steps) {
+            if (s.skipped) {
+              const reason = s.skipReason ?? "n/a";
+              process.stderr.write(`  \u25CB ${s.name.padEnd(24)} ${"\u2014".padStart(8)}  skipped (${reason})
+`);
+            } else {
+              process.stderr.write(`  \u2713 ${s.name.padEnd(24)} ${(s.durationMs.toFixed(1) + "ms").padStart(8)}
+`);
+            }
+          }
+        }
+        const { getAuditLogger: getAL2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+        const al2 = getAL2();
+        if (al2) {
+          al2.logExecution(moduleId, merged, "success", 0, durationMs2);
+        }
+        return;
+      }
+      let result;
+      if (strategyName && executor.callWithTrace) {
+        const [res] = await executor.callWithTrace(
+          moduleId,
+          merged,
+          { strategy: strategyName }
+        );
+        result = res;
+        if (strategyName !== "standard" && process.stderr.isTTY) {
+          process.stderr.write(`Warning: Using '${strategyName}' strategy.
+`);
+        }
+      } else {
+        const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
+        const sandbox = new Sandbox2(sandboxEnabled);
+        result = await sandbox.execute(moduleId, merged, executor);
+      }
       const durationMs = Math.round(performance.now() - startTime);
+      formatExecResult(result, outputFormat, outputFields);
       const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
       const auditLogger = getAuditLogger2();
       if (auditLogger) {
-        auditLogger.logExecution(moduleId, reconverted, "success", 0, durationMs);
+        auditLogger.logExecution(moduleId, merged, "success", 0, durationMs);
       }
-      formatExecResult(result, outputFormat);
     } catch (err) {
-      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-      const auditLogger = getAuditLogger2();
-      const code = exitCodeForError(err);
-      if (auditLogger) {
-        auditLogger.logExecution(moduleId, {}, "error", code, 0);
+      const exitCode = exitCodeForError(err);
+      const durationMs = Math.round(performance.now() - startTime);
+      try {
+        const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+        const auditLogger = getAuditLogger2();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, durationMs);
+        }
+      } catch {
       }
-      if (err instanceof Error) {
-        process.stderr.write(`Error: ${err.message}
-`);
+      if (outputFormat === "json" || !process.stderr.isTTY) {
+        emitErrorJson(err, exitCode);
+      } else {
+        emitErrorTty(err, exitCode);
       }
-      process.exit(code);
+      process.exit(exitCode);
     }
   });
   return cmd;
 }
 function validateModuleId(moduleId) {
-  if (moduleId.length > 128) {
+  if (moduleId.length > 192) {
     process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.
+      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 192 characters.
 `
     );
     process.exit(EXIT_CODES.INVALID_CLI_INPUT);
@@ -2046,45 +3989,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 = readFileSync2(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);
+  }
+  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 cliKwargsNonNull;
+  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();
@@ -2124,8 +4079,25 @@ function reconvertEnumValues(kwargs, options) {
 
 // src/cli.ts
 init_esm_shims();
-import { Command as Command3 } from "commander";
-var BUILTIN_COMMANDS = ["completion", "describe", "exec", "init", "list", "man"];
+import { Command as Command6 } from "commander";
+init_logger();
+init_errors();
+function assertNotReserved(kind, name, moduleId) {
+  if (!RESERVED_GROUP_NAMES.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;
@@ -2208,7 +4180,7 @@ var LazyGroup = class {
     this.members = members;
     this._executor = executor;
     this._helpTextMaxLength = helpTextMaxLength;
-    this.command = new Command3(name).description(`${name} commands`);
+    this.command = new Command6(name).description(`${name} commands`);
     for (const [cmdName, [, descriptor]] of this.members) {
       const cmd = buildModuleCommand(
         descriptor,
@@ -2250,10 +4222,41 @@ var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
   /** 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) {
+  static resolveGroup(moduleId, descriptor, groupDepth = 1) {
     if (!moduleId) {
       warn("Empty module_id encountered in resolveGroup");
       return [null, ""];
@@ -2269,65 +4272,76 @@ var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
     }
     const cliName = cliDisplay.alias ?? moduleId;
     if (cliName.includes(".")) {
-      const dotIdx = cliName.indexOf(".");
-      const group = cliName.substring(0, dotIdx);
-      const cmd = cliName.substring(dotIdx + 1);
+      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;
     }
-    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]);
-        }
+    this.buildAliasMap();
+    for (const descriptor of this.registry.listModules()) {
+      const moduleId = descriptor.id;
+      const cached = this.descriptorCache.get(moduleId);
+      if (!cached) {
+        continue;
       }
-      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.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;
-    } catch {
-      warn("Failed to build group map");
     }
+    this.groupMapBuilt = true;
   }
   /**
-   * List all available command names: builtins + group names + top-level module names.
+   * 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 groupNames = [...this.groupMap.keys()].filter(
-      (g) => !BUILTIN_COMMANDS.includes(g)
+      (g) => !RESERVED_GROUP_NAMES.has(g)
     );
     const topNames = [...this.topLevelModules.keys()];
-    return [.../* @__PURE__ */ new Set([...BUILTIN_COMMANDS, ...groupNames, ...topNames])].sort();
+    return [.../* @__PURE__ */ new Set([...groupNames, ...topNames])].sort();
   }
   /**
    * Get a command by name: check builtins -> group cache -> group map -> top-level modules.
@@ -2377,119 +4391,66 @@ var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
   }
 };
 
-// src/discovery.ts
-init_esm_shims();
-init_errors();
-import { Command as Command4 } from "commander";
-var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
-function validateTag(tag) {
-  if (!TAG_PATTERN.test(tag)) {
-    process.stderr.write(
-      `Error: Invalid tag format: '${tag}'. Tags must match [a-z][a-z0-9_-]*.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-}
-function collectTag(value, previous) {
-  return previous.concat([value]);
-}
-function registerDiscoveryCommands(cli, registry) {
-  const listCmd = new Command4("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--format <format>", "Output format.", void 0).action((opts) => {
-    for (const t of opts.tag) {
-      validateTag(t);
-    }
-    const modules = [];
-    for (const m of registry.listModules()) {
-      modules.push(m);
-    }
-    let filtered = modules;
-    if (opts.tag.length > 0) {
-      const filterTags = new Set(opts.tag);
-      filtered = modules.filter((m) => {
-        const mTags = m.tags ?? [];
-        return [...filterTags].every((t) => mTags.includes(t));
-      });
-    }
-    const fmt = resolveFormat(opts.format);
-    formatModuleList(filtered, fmt, opts.tag.length > 0 ? opts.tag : void 0);
-  });
-  cli.addCommand(listCmd);
-  const describeCmd = new Command4("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").option("--format <format>", "Output format.", void 0).action((moduleId, opts) => {
-    validateModuleId(moduleId);
-    const moduleDef = registry.getModule(moduleId);
-    if (!moduleDef) {
-      process.stderr.write(
-        `Error: Module '${moduleId}' not found.
-`
-      );
-      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
-    }
-    const fmt = resolveFormat(opts.format);
-    formatModuleDetail(moduleDef, fmt);
-  });
-  cli.addCommand(describeCmd);
-}
-
 // src/index.ts
 init_errors();
+init_logger();
 init_security();
 export {
+  ApcliGroup,
   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,
-  error,
+  emitErrorJson,
+  emitErrorTty,
   exitCodeForError,
-  extractHelp,
   formatExecResult,
-  formatModuleDetail,
-  formatModuleList,
   getAuditLogger,
-  getCliDisplayFields,
-  getDisplay,
   getLogLevel,
-  info,
   main,
-  mapType,
   reconvertEnumValues,
+  registerCompletionCommand,
+  registerConfigCommand,
   registerConfigNamespace,
-  registerDiscoveryCommands,
+  registerDescribeCommand,
+  registerDisableCommand,
+  registerEnableCommand,
+  registerExecCommand,
+  registerHealthCommand,
   registerInitCommand,
-  registerShellCommands,
-  resolveFormat,
+  registerListCommand,
+  registerPipelineCommand,
+  registerReloadCommand,
+  registerUsageCommand,
+  registerValidateCommand,
   resolveRefs,
   schemaToCliOptions,
   setAuditLogger,
   setDocsUrl,
   setLogLevel,
   setVerboseHelp,
-  truncate,
-  validateModuleId,
-  verboseHelp,
-  warn
+  validateModuleId
 };
 //# sourceMappingURL=index.js.map