apcore-cli 0.6.0 → 0.7.0

package/dist/bin/apcore-cli.js

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
+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;
 };
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // node_modules/.pnpm/tsup@8.5.1_postcss@8.5.8_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js
 import path from "path";
@@ -48,6 +47,8 @@ function exitCodeForError(error) {
       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,
@@ -62,6 +63,7 @@ function exitCodeForError(error) {
       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
@@ -127,6 +129,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,
@@ -147,38 +151,635 @@ var init_errors = __esm({
   }
 });
 
-// bin/apcore-cli.ts
-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 path4 from "path";
-import { Command as Command6, CommanderError, Option as Option4 } from "commander";
+// src/security/sandbox.ts
+var sandbox_exports = {};
+__export(sandbox_exports, {
+  Sandbox: () => Sandbox,
+  runSandboxRunner: () => runSandboxRunner
+});
+async function runSandboxRunner(moduleId) {
+  const extensionsRoot = process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
+  const apcore = await import("apcore-js").catch(() => {
+    process.stderr.write(
+      "sandbox runner: apcore-js is not available in the sandboxed environment.\n"
+    );
+    process.exit(1);
+  });
+  if (!apcore) return;
+  let inputJson = "";
+  for await (const chunk of process.stdin) {
+    inputJson += chunk.toString();
+  }
+  let inputData;
+  try {
+    inputData = JSON.parse(inputJson);
+  } catch {
+    process.stderr.write("sandbox runner: failed to parse stdin as JSON.\n");
+    process.exit(1);
+    return;
+  }
+  const registry = new apcore.Registry({ extensionsDir: extensionsRoot });
+  await registry.discover();
+  const executor = new apcore.Executor({ registry });
+  try {
+    const result = await executor.call(moduleId, inputData);
+    process.stdout.write(JSON.stringify(result));
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`sandbox runner error: ${err}
+`);
+    process.exit(1);
+  }
+}
+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;
+      timeoutSeconds;
+      constructor(enabled = false, timeoutSeconds = 300) {
+        this.enabled = enabled;
+        this.timeoutSeconds = timeoutSeconds;
+      }
+      /**
+       * Execute a module, optionally inside a sandboxed subprocess.
+       */
+      async execute(moduleId, inputData, executor) {
+        if (!this.enabled) {
+          return executor.execute(moduleId, inputData);
+        }
+        return this._sandboxedExecute(moduleId, inputData);
+      }
+      async _sandboxedExecute(moduleId, inputData) {
+        const { spawn } = await import("child_process");
+        const { tmpdir } = await import("os");
+        const { join: join3 } = await import("path");
+        const { mkdtempSync, rmSync } = await import("fs");
+        const tmpDir = mkdtempSync(join3(tmpdir(), "apcore_sandbox_"));
+        const 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;
+          }
+          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.`
+              )
+            );
+          }, 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}`));
+          });
+        });
+      }
+    };
+  }
+});
 
 // src/ref-resolver.ts
-init_esm_shims();
-init_errors();
+function resolveRefs(schema, maxDepth = 32, moduleId = "") {
+  const cloned = structuredClone(schema);
+  const defs = cloned.$defs ?? cloned.definitions ?? {};
+  const result = resolveNode(
+    cloned,
+    defs,
+    /* @__PURE__ */ new Set(),
+    0,
+    maxDepth,
+    moduleId
+  );
+  delete result.$defs;
+  delete result.definitions;
+  return result;
+}
+function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
+  if (typeof node !== "object" || node === null || Array.isArray(node)) {
+    return node;
+  }
+  const obj = node;
+  if ("$ref" in obj) {
+    const refPath = obj.$ref;
+    if (depth >= maxDepth) {
+      process.stderr.write(
+        `Error: $ref resolution depth exceeded maximum of ${maxDepth} for module '${moduleId}'.
+`
+      );
+      process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
+    }
+    if (visited.has(refPath)) {
+      process.stderr.write(
+        `Error: Circular $ref detected in schema for module '${moduleId}' at path '${refPath}'.
+`
+      );
+      process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
+    }
+    const parts = refPath.split("/");
+    const key = parts[parts.length - 1];
+    if (!(key in defs)) {
+      process.stderr.write(
+        `Error: Unresolvable $ref '${refPath}' in schema for module '${moduleId}'.
+`
+      );
+      process.exit(EXIT_CODES.SCHEMA_VALIDATION_ERROR);
+    }
+    const newVisited = new Set(visited);
+    newVisited.add(refPath);
+    return resolveNode(defs[key], defs, newVisited, depth + 1, maxDepth, moduleId);
+  }
+  if ("allOf" in obj && Array.isArray(obj.allOf)) {
+    const merged = {
+      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,
+        defs,
+        visited,
+        depth + 1,
+        maxDepth,
+        moduleId
+      );
+      if (resolved.properties) {
+        Object.assign(
+          merged.properties,
+          resolved.properties
+        );
+      }
+      if (Array.isArray(resolved.required)) {
+        merged.required.push(...resolved.required);
+      }
+    }
+    merged.required = [...new Set(merged.required)];
+    for (const [k, v] of Object.entries(obj)) {
+      if (k !== "allOf" && !(k in merged)) {
+        merged[k] = v;
+      }
+    }
+    return merged;
+  }
+  for (const keyword of ["anyOf", "oneOf"]) {
+    if (keyword in obj && Array.isArray(obj[keyword])) {
+      const merged = {
+        properties: {},
+        required: []
+      };
+      const allRequiredSets = [];
+      for (const subSchema of obj[keyword]) {
+        const resolved = resolveNode(
+          subSchema,
+          defs,
+          visited,
+          depth + 1,
+          maxDepth,
+          moduleId
+        );
+        if (resolved.properties) {
+          Object.assign(
+            merged.properties,
+            resolved.properties
+          );
+        }
+        if (Array.isArray(resolved.required)) {
+          allRequiredSets.push(new Set(resolved.required));
+        }
+      }
+      if (allRequiredSets.length > 0) {
+        let intersection = allRequiredSets[0];
+        for (let i = 1; i < allRequiredSets.length; i++) {
+          intersection = new Set(
+            [...intersection].filter((x) => allRequiredSets[i].has(x))
+          );
+        }
+        merged.required = [...intersection];
+      } else {
+        merged.required = [];
+      }
+      for (const [k, v] of Object.entries(obj)) {
+        if (k !== keyword && !(k in merged)) {
+          merged[k] = v;
+        }
+      }
+      return merged;
+    }
+  }
+  if ("properties" in obj && typeof obj.properties === "object" && obj.properties !== null) {
+    const props = obj.properties;
+    for (const [propName, propSchema] of Object.entries(props)) {
+      props[propName] = resolveNode(
+        propSchema,
+        defs,
+        visited,
+        depth + 1,
+        maxDepth,
+        moduleId
+      );
+    }
+  }
+  return obj;
+}
+var init_ref_resolver = __esm({
+  "src/ref-resolver.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+  }
+});
 
 // src/schema-parser.ts
-init_esm_shims();
-init_errors();
+function mapType(propName, propSchema) {
+  const schemaType = propSchema.type;
+  if (schemaType === "string" && (propName.endsWith("_file") || propSchema["x-cli-file"] === true)) {
+    return "file";
+  }
+  const typeMap = {
+    string: "string",
+    integer: "int",
+    number: "float",
+    boolean: BOOLEAN_FLAG,
+    object: "string",
+    array: "string"
+  };
+  if (!schemaType) {
+    return "string";
+  }
+  return typeMap[schemaType] ?? "string";
+}
+function extractHelp(propSchema, maxLength = 1e3) {
+  let text = propSchema["x-llm-description"];
+  if (!text) {
+    text = propSchema.description;
+  }
+  if (!text) {
+    return void 0;
+  }
+  if (maxLength > 0 && text.length > maxLength) {
+    return text.slice(0, maxLength - 3) + "...";
+  }
+  return text;
+}
+function schemaToCliOptions(schema, maxHelpLength = 1e3) {
+  const properties = schema.properties ?? {};
+  const requiredList = schema.required ?? [];
+  const options = [];
+  const flagNames = {};
+  for (const [propName, propSchema] of Object.entries(properties)) {
+    const flagName = "--" + propName.replace(/_/g, "-");
+    if (RESERVED_NAMES.has(propName)) {
+      process.stderr.write(
+        `Error: Module schema property '${propName}' conflicts with a reserved CLI option name. Rename the property.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    if (flagName in flagNames) {
+      process.stderr.write(
+        `Error: Flag name collision: properties '${propName}' and '${flagNames[flagName]}' both map to '${flagName}'.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    flagNames[flagName] = propName;
+    const typeResult = mapType(propName, propSchema);
+    const isRequired = requiredList.includes(propName);
+    const helpBase = extractHelp(propSchema, maxHelpLength);
+    const helpText = isRequired ? (helpBase ? helpBase + " " : "") + "[required]" : helpBase ?? "";
+    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: isRequired,
+        isBooleanFlag: true
+      });
+    } else if ("enum" in propSchema && Array.isArray(propSchema.enum)) {
+      const enumValues = propSchema.enum;
+      if (enumValues.length === 0) {
+        options.push({
+          name: propName,
+          flags: `${flagName} <value>`,
+          description: helpText,
+          defaultValue,
+          required: isRequired
+        });
+      } else {
+        const stringValues = enumValues.map(String);
+        const enumOriginalTypes = {};
+        for (const v of enumValues) {
+          if (typeof v === "number" && Number.isInteger(v)) {
+            enumOriginalTypes[String(v)] = "int";
+          } else if (typeof v === "number") {
+            enumOriginalTypes[String(v)] = "float";
+          } else if (typeof v === "boolean") {
+            enumOriginalTypes[String(v)] = "bool";
+          }
+        }
+        options.push({
+          name: propName,
+          flags: `${flagName} <value>`,
+          description: helpText,
+          defaultValue: defaultValue !== void 0 ? String(defaultValue) : void 0,
+          required: isRequired,
+          choices: stringValues,
+          enumOriginalTypes: Object.keys(enumOriginalTypes).length > 0 ? enumOriginalTypes : void 0
+        });
+      }
+    } else {
+      let parseArg;
+      if (typeResult === "int") {
+        parseArg = (v) => {
+          const n = parseInt(v, 10);
+          if (isNaN(n)) throw new Error(`Invalid integer: ${v}`);
+          return n;
+        };
+      } else if (typeResult === "float") {
+        parseArg = (v) => {
+          const n = parseFloat(v);
+          if (isNaN(n)) throw new Error(`Invalid number: ${v}`);
+          return n;
+        };
+      }
+      options.push({
+        name: propName,
+        flags: `${flagName} <value>`,
+        description: helpText,
+        defaultValue,
+        required: isRequired,
+        parseArg
+      });
+    }
+  }
+  return options;
+}
+var BOOLEAN_FLAG, RESERVED_NAMES;
+var init_schema_parser = __esm({
+  "src/schema-parser.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    BOOLEAN_FLAG = /* @__PURE__ */ Symbol("BOOLEAN_FLAG");
+    RESERVED_NAMES = /* @__PURE__ */ new Set([
+      "input",
+      "yes",
+      "large_input",
+      "format",
+      "fields",
+      "sandbox",
+      "verbose",
+      "dry_run",
+      "trace",
+      "stream",
+      "strategy",
+      "approval_timeout",
+      "approval_token"
+    ]);
+  }
+});
 
 // src/approval.ts
-init_esm_shims();
-init_errors();
 import * as readline from "readline";
+function getAnnotation(annotations, key, defaultValue = void 0) {
+  if (!annotations || typeof annotations !== "object") return defaultValue;
+  const ann = annotations;
+  return key in ann ? ann[key] : defaultValue;
+}
+function readTimeoutFromEnv() {
+  const raw = process.env.APCORE_CLI_APPROVAL_TIMEOUT;
+  if (raw === void 0 || raw === "") return void 0;
+  const parsed = parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return void 0;
+  return parsed;
+}
+async function checkApproval(moduleDef, autoApprove, timeout) {
+  const annotations = moduleDef.annotations;
+  let requiresApproval;
+  if (moduleDef.requiresApproval !== void 0) {
+    requiresApproval = moduleDef.requiresApproval;
+  } else if (annotations) {
+    requiresApproval = getAnnotation(annotations, "requires_approval", false) === true;
+  } else {
+    return;
+  }
+  if (!requiresApproval) {
+    return;
+  }
+  const moduleId = moduleDef.id;
+  if (autoApprove) {
+    return;
+  }
+  const envVal = process.env.APCORE_CLI_AUTO_APPROVE ?? "";
+  if (envVal === "1") {
+    return;
+  }
+  if (envVal !== "" && envVal !== "1") {
+    process.stderr.write(
+      `Warning: APCORE_CLI_AUTO_APPROVE is set to '${envVal}', expected '1'. Ignoring.
+`
+    );
+  }
+  if (!process.stdin.isTTY) {
+    throw new ApprovalDeniedError(
+      `Module '${moduleId}' requires approval but no interactive terminal is available. Use --yes or set APCORE_CLI_AUTO_APPROVE=1 to bypass.`
+    );
+  }
+  const effectiveTimeout = timeout ?? readTimeoutFromEnv() ?? 60;
+  await promptWithTimeout(moduleDef, effectiveTimeout);
+}
+async function promptWithTimeout(moduleDef, timeout) {
+  timeout = Math.max(1, Math.min(timeout, 3600));
+  const moduleId = moduleDef.id;
+  const annotations = moduleDef.annotations;
+  const message = (annotations ? getAnnotation(annotations, "approval_message") : void 0) ?? `Module '${moduleId}' requires approval to execute.`;
+  process.stderr.write(message + "\n");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  let timer;
+  try {
+    const answer = await Promise.race([
+      new Promise((resolve2) => {
+        rl.question("Proceed? [y/N] ", (ans) => resolve2(ans));
+      }),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new ApprovalTimeoutError(
+            `Approval prompt timed out after ${timeout} seconds.`
+          ));
+        }, timeout * 1e3);
+      })
+    ]);
+    if (timer) clearTimeout(timer);
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === "y" || normalized === "yes") {
+      return;
+    }
+    throw new ApprovalDeniedError("Approval denied");
+  } catch (err) {
+    if (timer) clearTimeout(timer);
+    throw err;
+  } finally {
+    rl.close();
+  }
+}
+var CliApprovalHandler;
+var init_approval = __esm({
+  "src/approval.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    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" };
+      }
+    };
+  }
+});
 
 // src/output.ts
-init_esm_shims();
+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;
   }
   return process.stdout.isTTY ? "table" : "json";
 }
+function truncate(text, maxLength = 80) {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return text.slice(0, maxLength - 3) + "...";
+}
 function formatTable(headers, rows) {
   const colWidths = headers.map(
     (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
@@ -190,6 +791,137 @@ function formatTable(headers, rows) {
   );
   return [headerLine, sep2, ...dataLines].join("\n") + "\n";
 }
+function formatModuleList(modules, format, filterTags, showDeps = false, exposureFilter) {
+  if (format === "table") {
+    if (modules.length === 0 && filterTags && filterTags.length > 0) {
+      process.stdout.write(
+        `No modules found matching tags: ${filterTags.join(", ")}.
+`
+      );
+      return;
+    }
+    if (modules.length === 0) {
+      process.stdout.write("No modules found.\n");
+      return;
+    }
+    const headers = ["ID", "Description", "Tags"];
+    if (showDeps) headers.push("Deps");
+    if (exposureFilter) headers.push("Exposure");
+    const rows = modules.map((m) => {
+      const base = [m.id, truncate(m.description, 80), (m.tags ?? []).join(", ")];
+      if (showDeps) {
+        const deps = m.dependencies;
+        base.push(String(Array.isArray(deps) ? deps.length : 0));
+      }
+      if (exposureFilter) {
+        base.push(exposureFilter.isExposed(m.id ?? "") ? "\u2713" : "\u2014");
+      }
+      return base;
+    });
+    process.stdout.write(formatTable(headers, rows));
+  } else if (format === "json") {
+    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");
+  }
+}
+function annotationsToDict(annotations) {
+  if (!annotations) return null;
+  if (typeof annotations !== "object" || Array.isArray(annotations)) return null;
+  const result = {};
+  for (const [k, v] of Object.entries(annotations)) {
+    if (v !== null && v !== void 0 && v !== false && v !== 0 && !(Array.isArray(v) && v.length === 0)) {
+      result[k] = v;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+function formatModuleDetail(moduleDef, format) {
+  if (format === "table") {
+    process.stdout.write(`
+Module: ${moduleDef.id}
+`);
+    process.stdout.write(`
+Description:
+  ${moduleDef.description}
+`);
+    if (moduleDef.inputSchema && Object.keys(moduleDef.inputSchema).length > 0) {
+      process.stdout.write("\nInput Schema:\n");
+      process.stdout.write(JSON.stringify(moduleDef.inputSchema, null, 2) + "\n");
+    }
+    if (moduleDef.outputSchema && Object.keys(moduleDef.outputSchema).length > 0) {
+      process.stdout.write("\nOutput Schema:\n");
+      process.stdout.write(JSON.stringify(moduleDef.outputSchema, null, 2) + "\n");
+    }
+    const annDict = annotationsToDict(
+      moduleDef.annotations
+    );
+    if (annDict) {
+      process.stdout.write("\nAnnotations:\n");
+      for (const [k, v] of Object.entries(annDict)) {
+        process.stdout.write(`  ${k}: ${v}
+`);
+      }
+    }
+    const metadata = moduleDef.metadata;
+    if (metadata) {
+      const xFields = {};
+      for (const [k, v] of Object.entries(metadata)) {
+        if (k.startsWith("x-") || k.startsWith("x_")) {
+          xFields[k] = v;
+        }
+      }
+      if (Object.keys(xFields).length > 0) {
+        process.stdout.write("\nExtension Metadata:\n");
+        for (const [k, v] of Object.entries(xFields)) {
+          process.stdout.write(`  ${k}: ${v}
+`);
+        }
+      }
+    }
+    const tags = moduleDef.tags ?? [];
+    if (tags.length > 0) {
+      process.stdout.write(`
+Tags: ${tags.join(", ")}
+`);
+    }
+  } else if (format === "json") {
+    const result = {
+      id: moduleDef.id,
+      description: moduleDef.description
+    };
+    if (moduleDef.inputSchema) result.input_schema = moduleDef.inputSchema;
+    if (moduleDef.outputSchema) result.output_schema = moduleDef.outputSchema;
+    const annDict = annotationsToDict(
+      moduleDef.annotations
+    );
+    if (annDict) result.annotations = annDict;
+    const tags = moduleDef.tags ?? [];
+    if (tags.length > 0) result.tags = tags;
+    const metadata = moduleDef.metadata;
+    if (metadata) {
+      for (const [k, v] of Object.entries(metadata)) {
+        if (k.startsWith("x-") || k.startsWith("x_")) {
+          result[k] = v;
+        }
+      }
+    }
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+}
 function selectFields(result, fields) {
   const selected = {};
   for (const f of fields.split(",")) {
@@ -221,42 +953,21 @@ function formatExecResult(result, format, fields) {
       const obj = effective_result;
       const keys = Object.keys(obj);
       const header = keys.map(escapeCsvField).join(",");
-      const row = keys.map((k) => escapeCsvField(String(obj[k]))).join(",");
+      const row = keys.map((k) => escapeCsvField(csvCellString(obj[k]))).join(",");
       process.stdout.write(header + "\n" + row + "\n");
     } else if (Array.isArray(effective_result) && effective_result.length > 0 && typeof effective_result[0] === "object") {
       const keys = Object.keys(effective_result[0]);
       const header = keys.map(escapeCsvField).join(",");
       const rows = effective_result.map((item) => {
         const obj = item;
-        return keys.map((k) => escapeCsvField(String(obj[k]))).join(",");
+        return keys.map((k) => escapeCsvField(csvCellString(obj[k]))).join(",");
       });
       process.stdout.write(header + "\n" + rows.join("\n") + "\n");
     } else {
       process.stdout.write(JSON.stringify(effective_result) + "\n");
     }
   } else if (effective === "yaml") {
-    if (typeof effective_result === "object" && !Array.isArray(effective_result) && effective_result !== null) {
-      const obj = effective_result;
-      const lines = Object.entries(obj).map(([k, v]) => {
-        if (v === null || v === void 0) return `${k}: null`;
-        if (typeof v === "object") return `${k}: ${JSON.stringify(v)}`;
-        return `${k}: ${v}`;
-      });
-      process.stdout.write(lines.join("\n") + "\n");
-    } else if (Array.isArray(effective_result)) {
-      for (const item of effective_result) {
-        if (typeof item === "object" && item !== null) {
-          const obj = item;
-          const lines = Object.entries(obj).map(([k, v]) => `  ${k}: ${v}`);
-          process.stdout.write("- " + lines.join("\n  ") + "\n");
-        } else {
-          process.stdout.write(`- ${item}
-`);
-        }
-      }
-    } else {
-      process.stdout.write(String(effective_result) + "\n");
-    }
+    process.stdout.write(yaml.dump(effective_result, { lineWidth: -1 }));
   } else if (effective === "jsonl") {
     if (Array.isArray(effective_result)) {
       for (const item of effective_result) {
@@ -279,7 +990,7 @@ function formatExecResult(result, format, fields) {
   }
 }
 function escapeCsvField(value) {
-  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+  if (value.includes(",") || value.includes('"') || value.includes("\n") || value.includes("\r")) {
     return '"' + value.replace(/"/g, '""') + '"';
   }
   return value;
@@ -289,7 +1000,9 @@ function formatPreflightResult(result, format) {
   if (resolved === "json" || !process.stdout.isTTY) {
     const payload = {
       valid: result.valid,
-      requires_approval: result.requires_approval,
+      // JSON output key stays snake_case for cross-language CLI contract;
+      // runtime read uses camelCase to match apcore-js PreflightResult.
+      requires_approval: result.requiresApproval,
       checks: result.checks.map((c) => {
         const entry = { check: c.check, passed: c.passed };
         if (c.error !== void 0 && c.error !== null) {
@@ -340,26 +1053,30 @@ Result: ${tag} (${errors} error(s), ${warnings} warning(s))
 }
 function firstFailedExitCode(result) {
   const checkToExit = {
-    module_id: 2,
-    module_lookup: 44,
-    call_chain: 1,
-    acl: 77,
-    schema: 45,
-    approval: 46,
-    module_preflight: 1
+    module_id: EXIT_CODES.INVALID_CLI_INPUT,
+    module_lookup: EXIT_CODES.MODULE_NOT_FOUND,
+    call_chain: EXIT_CODES.MODULE_EXECUTE_ERROR,
+    acl: EXIT_CODES.ACL_DENIED,
+    schema: EXIT_CODES.SCHEMA_VALIDATION_ERROR,
+    approval: EXIT_CODES.APPROVAL_DENIED,
+    module_preflight: EXIT_CODES.MODULE_EXECUTE_ERROR
   };
   for (const check of result.checks) {
     if (!check.passed) {
-      return checkToExit[check.check] ?? 1;
+      return checkToExit[check.check] ?? EXIT_CODES.MODULE_EXECUTE_ERROR;
     }
   }
-  return 1;
+  return EXIT_CODES.MODULE_EXECUTE_ERROR;
 }
+var init_output = __esm({
+  "src/output.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+  }
+});
 
 // 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) {
@@ -369,44 +1086,39 @@ function setLogLevel(level) {
 function shouldLog(level) {
   return LEVELS[level] >= LEVELS[currentLevel];
 }
-function debug(message) {
-  if (shouldLog("DEBUG")) process.stderr.write(`DEBUG: ${message}
+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/init-cmd.ts
-init_esm_shims();
 import * as fs from "fs";
 import * as path2 from "path";
-var DECORATOR_TEMPLATE = `import { module } from "apcore-js";
-import { Type } from "@sinclair/typebox";
-
-export const {varName} = module({
-  id: "{moduleId}",
-  description: "{description}",
-  inputSchema: Type.Object({}),
-  outputSchema: Type.Object({ status: Type.String() }),
-  execute: (_inputs) => {
-    // TODO: implement
-    return { status: "ok" };
-  },
-});
-`;
-var CONVENTION_TEMPLATE = `/**
- * {description}
- */
-{cliGroupLine}
-export function {funcName}(): Record<string, unknown> {
-  // TODO: implement
-  return { status: "ok" };
+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 BINDING_TEMPLATE = `bindings:
-  - module_id: "{moduleId}"
-    target: "{target}"
-    description: "{description}"
-    auto_schema: true
-`;
 function renderTemplate(template, context) {
   let result = template;
   for (const [key, value] of Object.entries(context)) {
@@ -450,7 +1162,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";
@@ -460,14 +1172,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";
@@ -485,12 +1197,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, {
@@ -498,11 +1211,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> {
@@ -511,69 +1225,421 @@ 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}
 `);
   }
 }
+var DECORATOR_TEMPLATE, CONVENTION_TEMPLATE, BINDING_TEMPLATE;
+var init_init_cmd = __esm({
+  "src/init-cmd.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    DECORATOR_TEMPLATE = `import { module } from "apcore-js";
+import { Type } from "@sinclair/typebox";
+
+export const {varName} = module({
+  id: "{moduleId}",
+  description: "{description}",
+  inputSchema: Type.Object({}),
+  outputSchema: Type.Object({ status: Type.String() }),
+  execute: (_inputs) => {
+    // TODO: implement
+    return { status: "ok" };
+  },
+});
+`;
+    CONVENTION_TEMPLATE = `/**
+ * {description}
+ */
+{cliGroupLine}
+export function {funcName}(): Record<string, unknown> {
+  // TODO: implement
+  return { status: "ok" };
+}
+`;
+    BINDING_TEMPLATE = `spec_version: "1.0"
+bindings:
+  - module_id: "{moduleId}"
+    target: "{target}"
+    description: "{description}"
+    auto_schema: true
+`;
+  }
+});
 
 // src/display-helpers.ts
-init_esm_shims();
+function getDisplay(descriptor) {
+  const metadata = descriptor.metadata ?? {};
+  const display = metadata.display;
+  if (display && typeof display === "object" && !Array.isArray(display)) {
+    return display;
+  }
+  const overlay = lookupBindingDisplay(descriptor.id);
+  return overlay ?? {};
+}
+var init_display_helpers = __esm({
+  "src/display-helpers.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_main();
+  }
+});
 
 // src/config.ts
-init_esm_shims();
 import * as fs2 from "fs";
-import yaml from "js-yaml";
-var NAMESPACE_TO_LEGACY = {
-  "apcore-cli.stdin_buffer_limit": "cli.stdin_buffer_limit",
-  "apcore-cli.auto_approve": "cli.auto_approve",
-  "apcore-cli.help_text_max_length": "cli.help_text_max_length",
-  "apcore-cli.logging_level": "logging.level"
-};
-var LEGACY_TO_NAMESPACE = Object.fromEntries(
-  Object.entries(NAMESPACE_TO_LEGACY).map(([k, v]) => [v, k])
-);
+import { createRequire } from "module";
+import yaml2 from "js-yaml";
 function registerConfigNamespace() {
   try {
-    const { Config } = __require("apcore-js");
+    const nodeRequire = createRequire(import.meta.url);
+    const { Config } = nodeRequire("apcore-js");
     if (typeof Config?.registerNamespace === "function") {
       Config.registerNamespace({
         name: "apcore-cli",
         envPrefix: "APCORE_CLI",
-        defaults: {
-          stdin_buffer_limit: 10485760,
-          auto_approve: false,
-          help_text_max_length: 1e3,
-          logging_level: "WARNING",
-          approval_timeout: 60,
-          strategy: "standard",
-          group_depth: 1
-        }
+        defaults: NAMESPACE_DEFAULTS
       });
     }
   } catch {
   }
 }
+var DEFAULTS, NAMESPACE_DEFAULTS, NAMESPACE_TO_LEGACY, LEGACY_TO_NAMESPACE, ConfigResolver;
+var init_config = __esm({
+  "src/config.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_logger();
+    DEFAULTS = {
+      "extensions.root": "./extensions",
+      "logging.level": "WARNING",
+      "cli.help_text_max_length": 1e3,
+      // 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)
+    };
+    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
+      }
+    };
+    NAMESPACE_TO_LEGACY = {
+      "apcore-cli.stdin_buffer_limit": "cli.stdin_buffer_limit",
+      "apcore-cli.auto_approve": "cli.auto_approve",
+      "apcore-cli.help_text_max_length": "cli.help_text_max_length",
+      "apcore-cli.logging_level": "logging.level"
+    };
+    LEGACY_TO_NAMESPACE = Object.fromEntries(
+      Object.entries(NAMESPACE_TO_LEGACY).map(([k, v]) => [v, k])
+    );
+    ConfigResolver = class {
+      cliFlags;
+      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";
+      }
+      /**
+       * Resolve a single configuration key across all four tiers.
+       */
+      resolve(key, cliFlag, envVar) {
+        if (cliFlag !== void 0 && cliFlag in this.cliFlags) {
+          const value = this.cliFlags[cliFlag];
+          if (value !== null && value !== void 0) {
+            return value;
+          }
+        }
+        if (envVar) {
+          const envValue = process.env[envVar];
+          if (envValue !== void 0 && envValue !== "") {
+            return envValue;
+          }
+        }
+        const fileValue = this.resolveFromFile(key);
+        if (fileValue !== void 0) {
+          return fileValue;
+        }
+        const altKey = NAMESPACE_TO_LEGACY[key] ?? LEGACY_TO_NAMESPACE[key];
+        if (altKey) {
+          const altFileValue = this.resolveFromFile(altKey);
+          if (altFileValue !== void 0) {
+            return altFileValue;
+          }
+        }
+        return DEFAULTS[key];
+      }
+      /**
+       * Load a value from the config file using a dot-separated key path.
+       */
+      resolveFromFile(key) {
+        if (!this.fileCacheLoaded) {
+          this.fileCache = this.loadConfigFile();
+          this.fileCacheLoaded = true;
+        }
+        if (this.fileCache === null) {
+          return void 0;
+        }
+        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.
+       */
+      loadConfigFile() {
+        let content;
+        try {
+          content = fs2.readFileSync(this.configPath, "utf-8");
+        } catch (err) {
+          if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return null;
+          }
+          warn(
+            `Configuration file '${this.configPath}' is malformed, using defaults.`
+          );
+          return null;
+        }
+        let parsed;
+        try {
+          parsed = yaml2.load(content);
+        } catch {
+          warn(
+            `Configuration file '${this.configPath}' is malformed, using defaults.`
+          );
+          return null;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+          warn(
+            `Configuration file '${this.configPath}' is malformed, using defaults.`
+          );
+          return null;
+        }
+        this._rawConfig = parsed;
+        return this.flattenDict(parsed);
+      }
+      /**
+       * Flatten nested dict to dot-notation keys.
+       */
+      flattenDict(d, prefix = "") {
+        const result = {};
+        for (const [key, value] of Object.entries(d)) {
+          const fullKey = prefix ? `${prefix}.${key}` : key;
+          if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            Object.assign(
+              result,
+              this.flattenDict(value, fullKey)
+            );
+          } else {
+            result[fullKey] = value;
+          }
+        }
+        return result;
+      }
+    };
+  }
+});
 
 // 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 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 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="${rootOpts}"
+        COMPREPLY=( $(compgen -W "\${opts}" -- \${cur}) )
+        return 0
+    fi
+`;
+  if (apcliVisible) {
+    body += `
+    if [[ \${COMP_CWORD} -eq 2 ]]; then
+        if [[ "\${COMP_WORDS[1]}" == "apcli" ]]; then
+            local apcli_cmds="${apcliOpts}"
+            COMPREPLY=( $(compgen -W "\${apcli_cmds}" -- \${cur}) )
+            return 0
+        fi
+    fi
+`;
+  }
+  body += `}
+complete -F ${fn} ${quoted}
+`;
+  return body;
+}
+function generateZshCompletion(progName, program) {
+  const fn = makeFunctionName(progName);
+  const quoted = shellQuote(progName);
+  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=(
+` + (rootEntries ? rootEntries + "\n" : "") + `    )
+    local -a apcli_cmds
+    apcli_cmds=(
+` + (apcliEntries ? apcliEntries + "\n" : "") + `    )
+
+    _arguments -C \\
+        '1:command:->command' \\
+        '*::arg:->args'
+
+    case "$state" in
+        command)
+            _describe -t commands '${progName} commands' commands
+            ;;
+        args)
+            case "\${words[1]}" in
+                apcli)
+                    _describe -t apcli_cmds '${progName} apcli commands' apcli_cmds
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+compdef ${fn} ${quoted}
+`;
+}
+function generateFishCompletion(progName, program) {
+  const quoted = shellQuote(progName);
+  const apcliGroup = program ? findApcliGroup(program) : void 0;
+  const apcliVisible = apcliGroup !== void 0 && !isCmdHidden(apcliGroup);
+  const rootCmds = program ? enumerateRootCommands(program).filter(
+    (n) => n !== "apcli" || apcliVisible
+  ) : [];
+  const apcliCmds = apcliVisible ? enumerateApcliSubcommands(apcliGroup) : [];
+  const lines = [];
+  lines.push(`# Fish completions for ${progName}`);
+  for (const name of rootCmds) {
+    lines.push(
+      `complete -c ${quoted} -n "__fish_use_subcommand" -a ${name} -d "${name}"`
+    );
+  }
+  if (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 lines.join("\n") + "\n";
 }
 function roffEscape(s) {
   return s.replace(/\\/g, "\\\\").replace(/-/g, "\\-").replace(/'/g, "\\(aq");
 }
-function buildProgramManPage(program, progName, version, description, docsUrl) {
+function buildProgramManPage(program, progName, version, description, docsUrl2) {
   const help = new Help();
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const s = [];
@@ -663,18 +1729,18 @@ ${meaning}`);
   }
   s.push(".SH SEE ALSO");
   s.push(`\\fB${progName} \\-\\-help \\-\\-verbose\\fR for full option list.`);
-  if (docsUrl) {
+  if (docsUrl2) {
     s.push(`.PP
-Full documentation at \\fI${roffEscape(docsUrl)}\\fR`);
+Full documentation at \\fI${roffEscape(docsUrl2)}\\fR`);
   }
   return s.join("\n");
 }
-function configureManHelp(program, progName, version, description, docsUrl) {
+function configureManHelp(program, progName, version, description, docsUrl2) {
   const manOpt = new Option("--man", "Output man page in roff format (use with --help)").hideHelp();
   program.addOption(manOpt);
   program.addHelpText("beforeAll", () => {
     if (program.opts().man) {
-      const roff = buildProgramManPage(program, progName, version, description, docsUrl) + "\n";
+      const roff = buildProgramManPage(program, progName, version, description, docsUrl2) + "\n";
       if (process.stdout.isTTY) {
         const pagers = [
           { cmd: "mandoc", args: ["-a"] },
@@ -710,119 +1776,777 @@ function configureManHelp(program, progName, version, description, docsUrl) {
     return "";
   });
 }
-
-// src/discovery.ts
-init_esm_shims();
-init_errors();
-import { Command as Command2, Option as Option2 } from "commander";
-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(1);
+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(
+        `Error: Unknown shell '${shell}'. Expected: bash, zsh, or fish.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
     }
-    const preflight = await executor.validate(moduleId, merged);
-    formatPreflightResult(preflight, opts.format);
-    process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+    const root = findRootProgram(host);
+    const resolved = root.name() || "apcore-cli";
+    const generators = {
+      bash: () => generateBashCompletion(resolved, root),
+      zsh: () => generateZshCompletion(resolved, root),
+      fish: () => generateFishCompletion(resolved, root)
+    };
+    process.stdout.write(generators[shell]());
   });
-  cli.addCommand(validateCmd);
-}
-
-// src/system-cmd.ts
-init_esm_shims();
-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);
+  host.addCommand(completionCmd);
 }
-function formatHealthSummaryTty(result) {
-  const summary = result.summary ?? {};
-  const modules = result.modules ?? [];
-  if (modules.length === 0) {
-    process.stdout.write("No modules found.\n");
-    return;
+var init_shell = __esm({
+  "src/shell.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
   }
-  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"}
-`);
+// 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 path3 from "path";
+function setAuditLogger(auditLogger) {
+  _auditLogger = auditLogger;
 }
-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 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;
 }
-function formatUsageSummaryTty(result) {
-  const modules = result.modules ?? [];
-  const period = result.period ?? "?";
-  if (modules.length === 0) {
-    process.stdout.write(`No usage data for period ${period}.
-`);
-    return;
+var _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 = path3.join(
+        os.homedir(),
+        ".apcore-cli",
+        "audit.jsonl"
+      );
+      logPath;
+      writeFailureWarned = false;
+      constructor(path5) {
+        this.logPath = path5 ?? _AuditLogger.DEFAULT_PATH;
+        this.ensureDirectory();
+      }
+      ensureDirectory() {
+        const dir = path3.dirname(this.logPath);
+        try {
+          fs3.mkdirSync(dir, { recursive: true });
+          try {
+            fs3.chmodSync(dir, 448);
+          } catch {
+          }
+        } catch {
+        }
+      }
+      logExecution(moduleId, inputData, status, exitCode, durationMs) {
+        const entry = {
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          user: this.getUser(),
+          module_id: moduleId,
+          input_hash: this.hashInput(inputData),
+          status,
+          exit_code: exitCode,
+          duration_ms: durationMs
+        };
+        try {
+          fs3.appendFileSync(this.logPath, JSON.stringify(entry) + "\n");
+          try {
+            fs3.chmodSync(this.logPath, 384);
+          } catch {
+          }
+        } catch (err) {
+          if (!this.writeFailureWarned) {
+            this.writeFailureWarned = true;
+            warn(`Could not write audit log: ${err}`);
+          }
+        }
+      }
+      hashInput(inputData) {
+        const salt = crypto.randomBytes(16);
+        const payload = JSON.stringify(canonicalizeForHash(inputData));
+        return crypto.createHash("sha256").update(Buffer.concat([salt, Buffer.from(payload, "utf-8")])).digest("hex");
+      }
+      getUser() {
+        try {
+          return os.userInfo().username;
+        } catch {
+          return process.env.USER ?? process.env.USERNAME ?? "unknown";
+        }
+      }
+    };
   }
-  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(
+// src/security/config-encryptor.ts
+import * as crypto2 from "crypto";
+import * as os2 from "os";
+async function getKeytar() {
+  if (keytarModule) return keytarModule;
+  try {
+    keytarModule = await import("keytar");
+    return keytarModule;
+  } catch {
+    return null;
+  }
+}
+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();
+        if (keytar) {
+          try {
+            await keytar.setPassword(_ConfigEncryptor.SERVICE_NAME, key, value);
+            return `keyring:${key}`;
+          } 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.`
+            );
+          }
+        }
+        warn("OS keyring unavailable. Using file-based encryption.");
+        const ciphertext = this.aesEncrypt(value);
+        return `enc:v2:${ciphertext.toString("base64")}`;
+      }
+      /**
+       * Retrieve and decrypt a configuration value.
+       */
+      async retrieve(configValue, key) {
+        if (configValue.startsWith("keyring:")) {
+          const keytar = await getKeytar();
+          if (!keytar) {
+            throw new ConfigDecryptionError(
+              `Keyring module not available to retrieve '${key}'.`
+            );
+          }
+          try {
+            const refKey = configValue.slice("keyring:".length);
+            const result = await keytar.getPassword(
+              _ConfigEncryptor.SERVICE_NAME,
+              refKey
+            );
+            if (result === null || result === void 0) {
+              throw new ConfigDecryptionError(
+                `Keyring entry not found for '${refKey}'.`
+              );
+            }
+            return result;
+          } catch (err) {
+            if (err instanceof ConfigDecryptionError) throw err;
+            throw new ConfigDecryptionError(
+              `Failed to retrieve from keyring: ${err}`
+            );
+          }
+        }
+        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 data = Buffer.from(configValue.slice("enc:".length), "base64");
+          try {
+            return this.aesDecryptV1(data);
+          } catch {
+            throw new ConfigDecryptionError(
+              `Failed to decrypt configuration value '${key}'. Re-configure with 'apcore-cli config set ${key}'.`
+            );
+          }
+        }
+        return configValue;
+      }
+      // 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 material = `${hostname2}:${username}`;
+        return crypto2.pbkdf2Sync(material, salt, PBKDF2_ITERATIONS, 32, "sha256");
+      }
+      aesEncrypt(plaintext) {
+        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([
+          cipher.update(plaintext, "utf-8"),
+          cipher.final()
+        ]);
+        const tag = cipher.getAuthTag();
+        return Buffer.concat([salt, nonce, tag, ct]);
+      }
+      aesDecrypt(data) {
+        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 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");
+      }
+    };
+  }
+});
+
+// src/security/auth.ts
+var AuthProvider;
+var init_auth = __esm({
+  "src/security/auth.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    init_config_encryptor();
+    AuthProvider = class {
+      config;
+      encryptor;
+      constructor(config, encryptor) {
+        this.config = config;
+        this.encryptor = encryptor ?? new ConfigEncryptor();
+      }
+      /**
+       * Retrieve the API key from the configured sources.
+       * Handles keyring: and enc: prefixes via ConfigEncryptor.
+       */
+      async getApiKey() {
+        const result = this.config.resolve(
+          "auth.api_key",
+          "--api-key",
+          "APCORE_AUTH_API_KEY"
+        );
+        if (result === null || result === void 0) {
+          return null;
+        }
+        const strResult = String(result);
+        if (strResult.startsWith("keyring:") || strResult.startsWith("enc:")) {
+          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();
+        if (!key) {
+          throw new AuthenticationError(
+            "Remote registry requires authentication. Set --api-key, APCORE_AUTH_API_KEY, or auth.api_key in config."
+          );
+        }
+        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.
+       */
+      handleResponse(statusCode) {
+        if (statusCode === 401 || statusCode === 403) {
+          throw new AuthenticationError(
+            "Authentication failed. Verify your API key."
+          );
+        }
+      }
+    };
+  }
+});
+
+// src/security/index.ts
+var security_exports = {};
+__export(security_exports, {
+  AuditLogger: () => AuditLogger,
+  AuthProvider: () => AuthProvider,
+  ConfigEncryptor: () => ConfigEncryptor,
+  Sandbox: () => Sandbox,
+  getAuditLogger: () => getAuditLogger,
+  setAuditLogger: () => setAuditLogger
+});
+var init_security = __esm({
+  "src/security/index.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_audit();
+    init_auth();
+    init_config_encryptor();
+    init_sandbox();
+  }
+});
+
+// src/discovery.ts
+import { Command as Command2, Option as Option2 } from "commander";
+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);
+}
+var TAG_PATTERN;
+var init_discovery = __esm({
+  "src/discovery.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_approval();
+    init_errors();
+    init_main();
+    init_output();
+    init_audit();
+    TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
+  }
+});
+
+// src/system-cmd.ts
+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)}
 `
     );
@@ -833,17 +2557,7 @@ function formatUsageSummaryTty(result) {
 Total: ${totalCalls.toLocaleString()} calls | ${totalErrors.toLocaleString()} errors
 `);
 }
-async function registerSystemCommands(cli, executor) {
-  try {
-    if (executor.validate) {
-      await executor.validate("system.health.summary", {});
-    } else {
-      await callSystemModule(executor, "system.health.summary", { include_healthy: true });
-    }
-  } catch {
-    debug("System modules not available; skipping system command registration.");
-    return;
-  }
+function registerHealthCommand(apcliGroup, executor) {
   const healthCmd = new Command3("health").description("Show module health status. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed health").option("--threshold <number>", "Error rate threshold (default: 0.01).", parseFloat, 0.01).option("--all", "Include healthy modules.", false).option("--errors <count>", "Max recent errors (module detail only).", parseInt, 10).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
@@ -852,29 +2566,21 @@ async function registerSystemCommands(cli, executor) {
           module_id: moduleId,
           error_limit: opts.errors
         });
-        if (fmt === "json" || !process.stdout.isTTY) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-        } else {
-          formatHealthModuleTty(result);
-        }
+        emitResult(result, fmt, () => formatHealthModuleTty(result));
       } else {
         const result = await callSystemModule(executor, "system.health.summary", {
           error_rate_threshold: opts.threshold,
           include_healthy: opts.all
         });
-        if (fmt === "json" || !process.stdout.isTTY) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-        } else {
-          formatHealthSummaryTty(result);
-        }
+        emitResult(result, fmt, () => formatHealthSummaryTty(result));
       }
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(healthCmd);
+  apcliGroup.addCommand(healthCmd);
+}
+function registerUsageCommand(apcliGroup, executor) {
   const usageCmd = new Command3("usage").description("Show module usage statistics. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed usage").option("--period <period>", "Time window: 1h, 24h, 7d, 30d.", "24h").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
@@ -889,24 +2595,21 @@ async function registerSystemCommands(cli, executor) {
           period: opts.period
         });
       }
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else if (moduleId) {
-        formatExecResult(result, fmt);
-      } else {
-        formatUsageSummaryTty(result);
-      }
+      emitResult(result, fmt, () => {
+        if (moduleId) {
+          formatExecResult(result, fmt);
+        } else {
+          formatUsageSummaryTty(result);
+        }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(usageCmd);
-  const enableCmd = new Command3("enable").description("Enable a disabled module at runtime.").argument("<module-id>", "Module ID to enable").requiredOption("--reason <reason>", "Reason for enabling (required for audit).").option("-y, --yes", "Skip approval prompt.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    if (!opts.yes) {
-      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
-    }
+  apcliGroup.addCommand(usageCmd);
+}
+function registerEnableCommand(apcliGroup, executor) {
+  const enableCmd = new Command3("enable").description("Enable a disabled module at runtime.").argument("<module-id>", "Module ID to enable").requiredOption("--reason <reason>", "Reason for enabling (required for audit).").option("-y, --yes", "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", {
@@ -914,24 +2617,19 @@ async function registerSystemCommands(cli, executor) {
         enabled: true,
         reason: opts.reason
       });
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else {
+      emitResult(result, fmt, () => {
         process.stdout.write(`Module '${moduleId}' enabled.
   Reason: ${opts.reason}
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(enableCmd);
-  const disableCmd = new Command3("disable").description("Disable a module at runtime (calls are rejected until re-enabled).").argument("<module-id>", "Module ID to disable").requiredOption("--reason <reason>", "Reason for disabling (required for audit).").option("-y, --yes", "Skip approval prompt.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    if (!opts.yes) {
-      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
-    }
+  apcliGroup.addCommand(enableCmd);
+}
+function registerDisableCommand(apcliGroup, executor) {
+  const disableCmd = new Command3("disable").description("Disable a module at runtime (calls are rejected until re-enabled).").argument("<module-id>", "Module ID to disable").requiredOption("--reason <reason>", "Reason for disabling (required for audit).").option("-y, --yes", "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", {
@@ -939,33 +2637,26 @@ async function registerSystemCommands(cli, executor) {
         enabled: false,
         reason: opts.reason
       });
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else {
+      emitResult(result, fmt, () => {
         process.stdout.write(`Module '${moduleId}' disabled.
   Reason: ${opts.reason}
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(disableCmd);
-  const reloadCmd = new Command3("reload").description("Hot-reload a module from disk.").argument("<module-id>", "Module ID to reload").requiredOption("--reason <reason>", "Reason for reload (required for audit).").option("-y, --yes", "Skip approval prompt.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
-    if (!opts.yes) {
-      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
-    }
+  apcliGroup.addCommand(disableCmd);
+}
+function registerReloadCommand(apcliGroup, executor) {
+  const reloadCmd = new Command3("reload").description("Hot-reload a module from disk.").argument("<module-id>", "Module ID to reload").requiredOption("--reason <reason>", "Reason for reload (required for audit).").option("-y, --yes", "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
       });
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else {
+      emitResult(result, fmt, () => {
         const prev = result.previous_version ?? "?";
         const newVer = result.new_version ?? "?";
         const dur = result.reload_duration_ms ?? "?";
@@ -975,34 +2666,30 @@ async function registerSystemCommands(cli, executor) {
 `);
         process.stdout.write(`  Duration: ${dur}ms
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
-  cli.addCommand(reloadCmd);
+  apcliGroup.addCommand(reloadCmd);
+}
+function registerConfigCommand(apcliGroup, executor) {
   const configGroup = new Command3("config").description("Read or update runtime configuration.");
   const configGetCmd = new Command3("get").description("Read a configuration value by dot-path key.").argument("<key>", "Configuration key (dot-path)").option("--format <format>", "Output format.", "table").action(async (key, opts) => {
     const fmt = resolveFormat(opts.format);
     try {
       const result = await callSystemModule(executor, "system.config.get", { key });
       const value = result?.value ?? result;
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify({ key, value }, null, 2) + "\n");
-      } else {
+      emitResult({ key, value }, fmt, () => {
         process.stdout.write(`${key} = ${JSON.stringify(value)}
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
   configGroup.addCommand(configGetCmd);
-  const configSetCmd = new Command3("set").description("Update a runtime configuration value (requires approval).").argument("<key>", "Configuration key (dot-path)").argument("<value>", "New value").requiredOption("--reason <reason>", "Reason for config change (required for audit).").option("--format <format>", "Output format.").action(async (key, value, opts) => {
+  const configSetCmd = new Command3("set").description("Update a runtime configuration value (audit-logged; 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 {
@@ -1016,9 +2703,7 @@ async function registerSystemCommands(cli, executor) {
         value: parsedValue,
         reason: opts.reason
       });
-      if (fmt === "json" || !process.stdout.isTTY) {
-        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-      } else {
+      emitResult(result, fmt, () => {
         const old = result.old_value ?? "?";
         const newVal = result.new_value ?? "?";
         process.stdout.write(`Config updated: ${key}
@@ -1027,257 +2712,915 @@ async function registerSystemCommands(cli, executor) {
 `);
         process.stdout.write(`  Reason: ${opts.reason}
 `);
-      }
+      });
     } catch (e) {
-      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
-`);
-      process.exit(1);
+      emitErrorAndExit(e);
     }
   });
   configGroup.addCommand(configSetCmd);
-  cli.addCommand(configGroup);
+  apcliGroup.addCommand(configGroup);
 }
+var init_system_cmd = __esm({
+  "src/system-cmd.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    init_output();
+  }
+});
 
 // src/strategy.ts
-init_esm_shims();
 import { Command as Command4, Option as Option3 } from "commander";
-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 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 };
+}
 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);
-    let strategyObj = null;
-    const ex = executor;
-    if (typeof ex._resolve_strategy_name === "function" || typeof ex._resolveStrategyName === "function") {
-      try {
-        const fn = ex._resolve_strategy_name ?? ex._resolveStrategyName;
-        strategyObj = fn(opts.strategy);
-      } catch {
-        strategyObj = null;
-      }
-    }
-    if (!strategyObj) {
-      const steps = PRESET_STEPS[opts.strategy] ?? [];
-      const pureSteps = /* @__PURE__ */ new Set([
-        "context_creation",
-        "call_chain_guard",
-        "module_lookup",
-        "acl_check",
-        "input_validation"
-      ]);
-      const nonRemovable = /* @__PURE__ */ new Set([
-        "context_creation",
-        "module_lookup",
-        "execute",
-        "return_result"
-      ]);
+    const { info, isCurrent } = lookupStrategyInfo(executor, opts.strategy);
+    if (info) {
+      const strategySteps = isCurrent ? executor.currentStrategy?.steps ?? [] : [];
+      const header = `Pipeline: ${info.name} (${info.stepCount} steps)`;
       if (fmt === "json" || !process.stdout.isTTY) {
         const payload = {
-          strategy: opts.strategy,
-          step_count: steps.length,
-          steps: steps.map((s, i) => ({
-            index: i + 1,
-            name: s,
-            pure: pureSteps.has(s),
-            removable: !nonRemovable.has(s)
-          }))
+          strategy: info.name,
+          step_count: info.stepCount,
+          description: info.description,
+          steps: info.stepNames.map((name, i) => {
+            const stepMeta = strategySteps[i];
+            return {
+              index: i + 1,
+              name,
+              pure: stepMeta?.pure ?? false,
+              removable: stepMeta?.removable ?? true,
+              timeout_ms: stepMeta?.timeoutMs ?? null
+            };
+          })
         };
         process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
       } else {
-        process.stdout.write(`Pipeline: ${opts.strategy} (${steps.length} steps)
+        process.stdout.write(`${header}
 
 `);
         process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
 `);
         process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
 `);
-        for (let i = 0; i < steps.length; i++) {
-          const pure = pureSteps.has(steps[i]) ? "yes" : "no";
-          const removable = nonRemovable.has(steps[i]) ? "no" : "yes";
-          process.stdout.write(`  ${String(i + 1).padEnd(4)} ${steps[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} \u2014
+        for (let i = 0; i < info.stepNames.length; i++) {
+          const stepMeta = strategySteps[i];
+          const pure = stepMeta?.pure ? "yes" : "no";
+          const removable = stepMeta?.removable !== false ? "yes" : "no";
+          const timeout = stepMeta?.timeoutMs ? `${stepMeta.timeoutMs}ms` : "\u2014";
+          process.stdout.write(`  ${String(i + 1).padEnd(4)} ${info.stepNames[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} ${timeout}
 `);
         }
       }
       return;
     }
-    const stepsInfo = strategyObj.steps.map((step) => ({
-      name: step.name,
-      pure: step.pure ?? false,
-      removable: step.removable ?? true,
-      timeout_ms: step.timeout_ms ?? null
-    }));
+    const steps = PRESET_STEPS[opts.strategy] ?? [];
+    const pureSteps = /* @__PURE__ */ new Set([
+      "context_creation",
+      "call_chain_guard",
+      "module_lookup",
+      "acl_check",
+      "input_validation"
+    ]);
+    const nonRemovable = /* @__PURE__ */ new Set([
+      "context_creation",
+      "module_lookup",
+      "execute",
+      "return_result"
+    ]);
     if (fmt === "json" || !process.stdout.isTTY) {
       const payload = {
         strategy: opts.strategy,
-        step_count: stepsInfo.length,
-        steps: stepsInfo.map((s, i) => ({ index: i + 1, ...s }))
+        step_count: steps.length,
+        steps: steps.map((s, i) => ({
+          index: i + 1,
+          name: s,
+          pure: pureSteps.has(s),
+          removable: !nonRemovable.has(s)
+        }))
       };
       process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
     } else {
-      process.stdout.write(`Pipeline: ${opts.strategy} (${stepsInfo.length} steps)
+      process.stdout.write(`Pipeline: ${opts.strategy} (${steps.length} steps)
 
 `);
       process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
 `);
       process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
 `);
-      for (let i = 0; i < stepsInfo.length; i++) {
-        const s = stepsInfo[i];
-        const pure = s.pure ? "yes" : "no";
-        const removable = s.removable ? "yes" : "no";
-        const timeout = s.timeout_ms !== null ? `${s.timeout_ms}ms` : "\u2014";
-        process.stdout.write(`  ${String(i + 1).padEnd(4)} ${s.name.padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} ${timeout}
+      for (let i = 0; i < steps.length; i++) {
+        const pure = pureSteps.has(steps[i]) ? "yes" : "no";
+        const removable = nonRemovable.has(steps[i]) ? "no" : "yes";
+        process.stdout.write(`  ${String(i + 1).padEnd(4)} ${steps[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} \u2014
 `);
       }
-    }
+    }
+  });
+  cli.addCommand(pipelineCmd);
+}
+var PRESET_STEPS;
+var init_strategy = __esm({
+  "src/strategy.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_output();
+    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"
+      ]
+    };
+  }
+});
+
+// src/builtin-group.ts
+var RESERVED_GROUP_NAMES, VALID_USER_MODES, APCLI_SUBCOMMAND_NAMES, ApcliGroup;
+var init_builtin_group = __esm({
+  "src/builtin-group.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    init_logger();
+    RESERVED_GROUP_NAMES = /* @__PURE__ */ new Set(["apcli"]);
+    VALID_USER_MODES = /* @__PURE__ */ new Set([
+      "all",
+      "none",
+      "include",
+      "exclude"
+    ]);
+    APCLI_SUBCOMMAND_NAMES = /* @__PURE__ */ new Set([
+      "list",
+      "describe",
+      "exec",
+      "validate",
+      "init",
+      "health",
+      "usage",
+      "enable",
+      "disable",
+      "reload",
+      "config",
+      "completion",
+      "describe-pipeline"
+    ]);
+    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: 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";
+        }
+        warn(
+          `Unknown APCORE_CLI_APCLI value '${raw}', ignoring. Expected: show, hide, 1, 0, true, false.`
+        );
+        return null;
+      }
+    };
+  }
+});
+
+// src/exposure.ts
+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(pipelineCmd);
+  let regex = regexParts.join("[^.]*");
+  regex = regex.replaceAll("\\*\\*", ".+");
+  return new RegExp(`^${regex}$`);
 }
+var ExposureFilter;
+var init_exposure = __esm({
+  "src/exposure.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_logger();
+    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/cli.ts
-init_esm_shims();
-import { Command as Command5 } from "commander";
-var BUILTIN_COMMANDS = [
-  "completion",
-  "config",
-  "describe",
-  "describe-pipeline",
-  "disable",
-  "enable",
-  "exec",
-  "health",
-  "init",
-  "list",
-  "man",
-  "reload",
-  "usage",
-  "validate"
-];
+// src/canonical-help.ts
+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";
+}
+var init_canonical_help = __esm({
+  "src/canonical-help.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
 
 // src/main.ts
-var __dirname3 = path4.dirname(fileURLToPath3(import.meta.url));
-var verboseHelp = false;
+var main_exports = {};
+__export(main_exports, {
+  applyToolkitIntegration: () => applyToolkitIntegration,
+  buildModuleCommand: () => buildModuleCommand,
+  clearBindingDisplayMap: () => clearBindingDisplayMap,
+  collectInput: () => collectInput,
+  createCli: () => createCli,
+  docsUrl: () => docsUrl,
+  emitErrorJson: () => emitErrorJson,
+  emitErrorTty: () => emitErrorTty,
+  lookupBindingDisplay: () => lookupBindingDisplay,
+  main: () => main,
+  reconvertEnumValues: () => reconvertEnumValues,
+  resolveIntOption: () => resolveIntOption,
+  resolveStringOption: () => resolveStringOption,
+  setDocsUrl: () => setDocsUrl,
+  setVerboseHelp: () => setVerboseHelp,
+  validateModuleId: () => validateModuleId,
+  verboseHelp: () => verboseHelp
+});
+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";
+function setVerboseHelp(verbose) {
+  verboseHelp = verbose;
+}
+function setDocsUrl(url) {
+  docsUrl = url;
+}
 function hasVerboseFlag() {
   return process.argv.includes("--verbose");
 }
-var VERSION = "0.0.0";
-try {
-  const pkg = JSON.parse(readFileSync3(path4.resolve(__dirname3, "../package.json"), "utf-8"));
-  VERSION = pkg.version;
-} catch {
+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;
+}
+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();
+  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 Command6(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--commands-dir <path>", "Path to convention-based commands directory").option("--binding <path>", "Path to binding.yaml for display overlay").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
+  if (app && (registry || executor)) {
+    process.stderr.write("Error: app is mutually exclusive with registry/executor\n");
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (app) {
+    registry = app.registry;
+    executor = app.executor;
+  }
   if (executor && !registry) {
-    throw new Error("executor requires registry \u2014 pass both or neither");
+    process.stderr.write("Error: executor requires registry \u2014 pass both or neither\n");
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (executor && typeof executor.setApprovalHandler === "function") {
+    try {
+      const handler = new CliApprovalHandler(
+        /*autoApprove*/
+        false
+      );
+      executor.setApprovalHandler(handler);
+    } catch {
+    }
+  }
+  const registryInjected = registry !== void 0;
+  const program = new Command5(resolvedProgName).exitOverride().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;
-      registerValidateCommand(program, registry, executor);
-      void registerSystemCommands(program, executor);
-      registerPipelineCommand(program, executor);
     }
   } else {
     const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
     void resolvedExtDir;
   }
+  let exposureFilter;
+  try {
+    if (expose instanceof ExposureFilter) {
+      exposureFilter = expose;
+    } else if (typeof expose === "object" && expose !== null) {
+      exposureFilter = ExposureFilter.fromConfig({ expose });
+    } else {
+      exposureFilter = new ExposureFilter();
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Error: invalid 'expose' option \u2014 ${msg}
+`);
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter);
+  _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) {
-    const existingNames = /* @__PURE__ */ new Set([
-      ...BUILTIN_COMMANDS,
-      ...program.commands.map((c) => c.name())
-    ]);
     for (const cmd of extraCommands) {
       const cmdName = cmd.name();
-      if (existingNames.has(cmdName)) {
+      if (RESERVED_GROUP_NAMES.has(cmdName)) {
         process.stderr.write(
-          `Warning: Extra command '${cmdName}' collides with a built-in command and will be skipped.
+          `Error: extraCommands name '${cmdName}' is reserved
 `
         );
-        continue;
+        process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      }
+      const existing = program.commands.find((c) => c.name() === cmdName);
+      if (existing) {
+        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);
-      existingNames.add(cmdName);
     }
   }
   program.hook("preAction", async (thisCommand) => {
@@ -1288,25 +3631,132 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
   });
   return program;
 }
+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);
+  }
+}
+function _registerDeprecationShims(root, apcliGroup, registryInjected, cliName) {
+  if (registryInjected) return;
+  for (const name of _DEPRECATED_ROOT_COMMANDS) {
+    const apcliSub = apcliGroup.commands.find((c) => c.name() === name);
+    if (!apcliSub) continue;
+    if (root.commands.some((c) => c.name() === name)) continue;
+    const shim = root.command(name).description(`[DEPRECATED] Use '${cliName} apcli ${name}' instead.`).allowUnknownOption(true).allowExcessArguments(true).helpOption(false);
+    shim.__isDeprecationShim = true;
+    shim.action(async function() {
+      process.stderr.write(
+        `WARNING: '${name}' as a root-level command is deprecated. Use '${cliName} apcli ${name}' instead.
+         Will be removed in v0.8. See: https://aiperceivable.github.io/apcore-cli/features/builtin-group/#11-migration
+`
+      );
+      const tail = _collectShimForwardArgs(this);
+      await apcliSub.parseAsync(tail, { from: "user" });
+    });
+  }
+}
+function _collectShimForwardArgs(shim) {
+  const shimArgs = (shim.args ?? []).slice();
+  if (shimArgs.length > 0) return shimArgs;
+  const shimName = shim.name();
+  const idx = process.argv.indexOf(shimName);
+  if (idx < 0) return [];
+  return process.argv.slice(idx + 1);
+}
+function lookupBindingDisplay(moduleId) {
+  return bindingDisplayMap.get(moduleId);
+}
+function clearBindingDisplayMap() {
+  bindingDisplayMap.clear();
+}
 async function applyToolkitIntegration(commandsDir, bindingPath) {
   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) {
@@ -1326,10 +3776,302 @@ function main(progName) {
     process.exit(code);
   }
 }
+function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName, verbose = verboseHelp) {
+  const moduleId = moduleDef.id;
+  let resolvedSchema = {};
+  let schemaOptions = [];
+  const display = getDisplay(moduleDef);
+  const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+  const effectiveCmdName = cmdName ?? cliDisplay.alias ?? moduleId;
+  const cmdHelp = cliDisplay.description ?? moduleDef.description;
+  const inputSchema = moduleDef.inputSchema;
+  if (inputSchema && typeof inputSchema === "object" && inputSchema.properties) {
+    try {
+      resolvedSchema = resolveRefs(inputSchema, 32, moduleId);
+    } catch {
+      resolvedSchema = inputSchema;
+    }
+    schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
+  }
+  const cmd = new Command5(effectiveCmdName).description(cmdHelp);
+  const inputOpt = new Option4("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
+  const yesOpt = new Option4("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
+  const largeInputOpt = new Option4("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
+  const formatOpt = new Option4("--format <format>", "Output format: json, table, csv, yaml, jsonl.").choices(["json", "table", "csv", "yaml", "jsonl"]);
+  const fieldsOpt = new Option4("--fields <fields>", "Comma-separated dot-paths to select from the result (e.g., 'status,data.count').");
+  const sandboxOpt = new Option4("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
+  const dryRunOpt = new Option4("--dry-run", "Run preflight checks without executing the module. Shows validation results.").default(false);
+  const traceOpt = new Option4("--trace", "Show execution pipeline trace with per-step timing after the result.").default(false);
+  const streamOpt = new Option4("--stream", "Stream module output as JSONL (one JSON object per line, flushed immediately).").default(false);
+  const strategyOpt = new Option4("--strategy <name>", "Execution pipeline strategy: standard (default), internal, testing, performance.").choices(["standard", "internal", "testing", "performance", "minimal"]);
+  const approvalTimeoutOpt = new Option4("--approval-timeout <seconds>", "Override approval prompt timeout in seconds (default: 60).").argParser(parseInt);
+  const approvalTokenOpt = new Option4("--approval-token <token>", "Resume a pending approval with the given token (for async approval flows).");
+  if (!verbose) {
+    inputOpt.hideHelp();
+    yesOpt.hideHelp();
+    largeInputOpt.hideHelp();
+    formatOpt.hideHelp();
+    fieldsOpt.hideHelp();
+    dryRunOpt.hideHelp();
+    traceOpt.hideHelp();
+    streamOpt.hideHelp();
+    strategyOpt.hideHelp();
+    approvalTimeoutOpt.hideHelp();
+    approvalTokenOpt.hideHelp();
+  }
+  cmd.addOption(inputOpt);
+  cmd.addOption(yesOpt);
+  cmd.addOption(largeInputOpt);
+  cmd.addOption(formatOpt);
+  cmd.addOption(fieldsOpt);
+  cmd.addOption(sandboxOpt);
+  cmd.addOption(dryRunOpt);
+  cmd.addOption(traceOpt);
+  cmd.addOption(streamOpt);
+  cmd.addOption(strategyOpt);
+  cmd.addOption(approvalTimeoutOpt);
+  cmd.addOption(approvalTokenOpt);
+  const footerParts = [];
+  if (!verbose) {
+    footerParts.push("Use --verbose to show all options (including built-in apcore options).");
+  }
+  if (docsUrl) {
+    footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);
+  }
+  if (footerParts.length > 0) {
+    cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
+  }
+  for (const opt of schemaOptions) {
+    if (opt.parseArg) {
+      cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
+    } else {
+      cmd.option(opt.flags, opt.description, opt.defaultValue);
+    }
+  }
+  cmd.action(async (options) => {
+    const stdinFlag = options.input;
+    const autoApprove = options.yes;
+    const largeInput = options.largeInput;
+    const outputFormat = options.format;
+    const outputFields = options.fields;
+    const sandboxEnabled = options.sandbox;
+    const dryRun = options.dryRun;
+    const traceFlag = options.trace;
+    const streamFlag = options.stream;
+    const strategyName = resolveStringOption(options.strategy, process.env.APCORE_CLI_STRATEGY);
+    const approvalTimeout = resolveIntOption(
+      options.approvalTimeout,
+      process.env.APCORE_CLI_APPROVAL_TIMEOUT,
+      60
+    );
+    const approvalToken = options.approvalToken;
+    const schemaKwargs = {};
+    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 {
+      merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
+      const reconverted = reconvertEnumValues(merged, schemaOptions);
+      merged = reconverted;
+      if (dryRun) {
+        if (!executor.validate) {
+          process.stderr.write("Error: Executor does not support validate.\n");
+          process.exit(EXIT_CODES.MODULE_EXECUTE_ERROR);
+        }
+        const preflight = await executor.validate(moduleId, merged);
+        formatPreflightResult(preflight, outputFormat);
+        if (traceFlag) {
+          const pureSteps = /* @__PURE__ */ new Set([
+            "context_creation",
+            "call_chain_guard",
+            "module_lookup",
+            "acl_check",
+            "input_validation"
+          ]);
+          const allSteps = [
+            "context_creation",
+            "call_chain_guard",
+            "module_lookup",
+            "acl_check",
+            "approval_gate",
+            "middleware_before",
+            "input_validation",
+            "execute",
+            "output_validation",
+            "middleware_after",
+            "return_result"
+          ];
+          process.stderr.write("\nPipeline preview (dry-run):\n");
+          for (const s of allSteps) {
+            if (pureSteps.has(s)) {
+              process.stderr.write(`  \u2713 ${s.padEnd(24)} (pure \u2014 would execute)
+`);
+            } else {
+              process.stderr.write(`  \u25CB ${s.padEnd(24)} (impure \u2014 skipped in dry-run)
+`);
+            }
+          }
+        }
+        process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+      }
+      if (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, merged, "success", 0, durationMs);
+      }
+    } catch (err) {
+      const exitCode = exitCodeForError(err);
+      const durationMs = Math.round(performance.now() - startTime);
+      try {
+        const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+        const auditLogger = getAuditLogger2();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, durationMs);
+        }
+      } catch {
+      }
+      if (outputFormat === "json" || !process.stderr.isTTY) {
+        emitErrorJson(err, exitCode);
+      } else {
+        emitErrorTty(err, exitCode);
+      }
+      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);
@@ -1352,45 +4094,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);
   }
-  return cliKwargsNonNull;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    process.stderr.write(
+      `Error: ${source} JSON must be an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  return { ...parsed, ...cliKwargsNonNull };
 }
 function readStdin() {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve2, reject) => {
     const chunks = [];
     const onData = (chunk) => chunks.push(chunk);
     const onEnd = () => {
       cleanup();
-      resolve3(Buffer.concat(chunks).toString("utf-8"));
+      resolve2(Buffer.concat(chunks).toString("utf-8"));
     };
     const onError = (err) => {
       cleanup();
@@ -1407,7 +4161,97 @@ function readStdin() {
     process.stdin.resume();
   });
 }
+function reconvertEnumValues(kwargs, options) {
+  const result = { ...kwargs };
+  for (const opt of options) {
+    if (!opt.enumOriginalTypes) continue;
+    const paramName = opt.name;
+    if (!(paramName in result) || result[paramName] === null || result[paramName] === void 0) {
+      continue;
+    }
+    const strVal = String(result[paramName]);
+    const origType = opt.enumOriginalTypes[strVal];
+    if (origType === "int") {
+      result[paramName] = parseInt(strVal, 10);
+    } else if (origType === "float") {
+      result[paramName] = parseFloat(strVal);
+    } else if (origType === "bool") {
+      result[paramName] = strVal.toLowerCase() === "true";
+    }
+  }
+  return result;
+}
+var __dirname2, verboseHelp, docsUrl, VERSION, _ALWAYS_REGISTERED, _DEPRECATED_ROOT_COMMANDS, bindingDisplayMap;
+var init_main = __esm({
+  "src/main.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    init_ref_resolver();
+    init_schema_parser();
+    init_approval();
+    init_output();
+    init_logger();
+    init_init_cmd();
+    init_display_helpers();
+    init_config();
+    init_approval();
+    init_shell();
+    init_discovery();
+    init_system_cmd();
+    init_strategy();
+    init_builtin_group();
+    init_exposure();
+    init_audit();
+    init_canonical_help();
+    __dirname2 = path4.dirname(fileURLToPath2(import.meta.url));
+    verboseHelp = false;
+    docsUrl = null;
+    VERSION = "0.0.0";
+    try {
+      const pkg = JSON.parse(readFileSync2(path4.resolve(__dirname2, "../package.json"), "utf-8"));
+      VERSION = pkg.version;
+    } catch {
+    }
+    _ALWAYS_REGISTERED = /* @__PURE__ */ new Set(["exec"]);
+    _DEPRECATED_ROOT_COMMANDS = [
+      "list",
+      "describe",
+      "exec",
+      "init",
+      "validate",
+      "health",
+      "usage",
+      "enable",
+      "disable",
+      "reload",
+      "config",
+      "completion",
+      "describe-pipeline"
+    ];
+    bindingDisplayMap = /* @__PURE__ */ new Map();
+  }
+});
 
 // bin/apcore-cli.ts
-main("apcore-cli");
+init_esm_shims();
+var sandboxIdx = process.argv.indexOf("--internal-sandbox-runner");
+if (sandboxIdx !== -1) {
+  const moduleId = process.argv[sandboxIdx + 1];
+  if (!moduleId) {
+    process.stderr.write("--internal-sandbox-runner requires a module_id argument.\n");
+    process.exit(1);
+  }
+  Promise.resolve().then(() => (init_sandbox(), sandbox_exports)).then(({ runSandboxRunner: runSandboxRunner2 }) => {
+    runSandboxRunner2(moduleId).catch((err) => {
+      process.stderr.write(`sandbox runner fatal: ${err}
+`);
+      process.exit(1);
+    });
+  });
+} else {
+  Promise.resolve().then(() => (init_main(), main_exports)).then(({ main: main2 }) => {
+    main2("apcore-cli");
+  });
+}
 //# sourceMappingURL=apcore-cli.js.map