@kb-labs/cli-commands 2.94.0 → 2.96.0

package/dist/index.js

@@ -5,25 +5,20 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { promises, existsSync } from 'fs';
 import { createHash } from 'crypto';
 import path from 'path';
+import { DiagnosticCollector, readMarketplaceLock, computeManifestIntegrity } from '@kb-labs/core-discovery';
 import { parse } from 'yaml';
 import { glob } from 'glob';
 import { defineSystemCommand, defineSystemCommandGroup } from '@kb-labs/shared-command-kit';
-import { createRegistry, formatDiagnosticReport } from '@kb-labs/core-registry';
-import { readMarketplaceLock, DiagnosticCollector } from '@kb-labs/core-discovery';
+import { createRegistry as createRegistry$1, formatDiagnosticReport } from '@kb-labs/core-registry';
+import { createRequire } from 'module';
 import { platform, platformSync } from '@kb-labs/core-runtime';
+import { getLogLevel, colors } from '@kb-labs/cli-runtime';
+import { access, readFile } from 'fs/promises';
 import { CredentialsManager } from '@kb-labs/cli-runtime/gateway';
-import Ajv from 'ajv';
-import { createRequire } from 'module';
-import { colors, getLogLevel } from '@kb-labs/cli-runtime';
+import os from 'os';
 
 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;
 };
@@ -43,34 +38,24 @@ function validateManifests(manifests) {
     if (result.success) {
       validated.push(result.data);
     } else {
-      const errorWithIndex = new z.ZodError([
-        ...result.error.issues.map((issue) => ({
-          ...issue,
-          path: [`[${i}]`, ...issue.path]
-        }))
-      ]);
-      errors.push(errorWithIndex);
+      errors.push(
+        new z.ZodError(
+          result.error.issues.map((issue) => ({ ...issue, path: [`[${i}]`, ...issue.path] }))
+        )
+      );
     }
   }
-  if (errors.length === 0) {
-    return { success: true, data: validated };
-  }
-  return { success: false, errors };
+  return errors.length === 0 ? { success: true, data: validated } : { success: false, errors };
 }
-function normalizeManifest(manifest, packageName, namespace) {
-  const normalized = { ...manifest };
-  if (!normalized.namespace && normalized.group) {
-    normalized.namespace = normalized.group;
-  } else if (!normalized.namespace && namespace) {
-    normalized.namespace = namespace;
-  }
-  if (!normalized.group && normalized.namespace) {
-    normalized.group = normalized.namespace;
-  }
-  if (!normalized.package) {
-    normalized.package = packageName;
-  }
-  return normalized;
+function normalizeManifest(manifest, packageName) {
+  const segs = manifest.segments;
+  return {
+    ...manifest,
+    id: segs[segs.length - 1] ?? "",
+    group: segs[0] ?? "",
+    subgroup: segs.length >= 3 ? segs[1] : void 0,
+    package: manifest.package ?? packageName
+  };
 }
 var semverPattern, FlagDefinitionSchema, EngineSchema, CommandManifestSchema;
 var init_schema = __esm({
@@ -85,62 +70,37 @@ var init_schema = __esm({
       choices: z.array(z.string()).optional(),
       required: z.boolean().optional()
     }).refine(
-      (data) => {
-        if (data.choices && data.type !== "string") {
-          return false;
-        }
-        return true;
-      },
+      (data) => !(data.choices && data.type !== "string"),
       { message: "Choices are only allowed for string type flags" }
     );
     EngineSchema = z.object({
       node: z.string().optional(),
-      // e.g., ">=18", "^18.0.0"
       kbCli: z.string().optional(),
-      // e.g., "^1.5.0"
       module: z.enum(["esm", "cjs"]).optional()
     }).optional();
     CommandManifestSchema = z.object({
       manifestVersion: z.literal("1.0"),
-      // Legacy fields (still supported)
-      id: z.string().min(1).regex(/^[a-z0-9-]+:[a-z0-9-]+(?:[:a-z0-9-]+)*$/, 'Command ID must be in format "namespace:command"'),
-      aliases: z.array(z.string()).optional(),
+      segments: z.array(z.string().min(1)).min(1),
+      id: z.string().min(1),
       group: z.string().min(1),
+      subgroup: z.string().optional(),
+      aliases: z.array(z.string()).optional(),
+      category: z.string().optional(),
       describe: z.string().min(1),
       longDescription: z.string().optional(),
       requires: z.array(z.string()).optional(),
-      // Package names with optional semver
       flags: z.array(FlagDefinitionSchema).optional(),
       examples: z.array(z.string()).optional(),
       loader: z.any(),
-      // Function validation happens at runtime
-      // New fields (optional for backward compatibility)
       package: z.string().optional(),
-      // Full package name
-      namespace: z.string().optional(),
-      // Derived from id if not provided
       engine: EngineSchema,
       permissions: z.array(z.string()).optional(),
-      // e.g., ["fs.read", "git.read", "net.fetch"]
       telemetry: z.enum(["opt-in", "off"]).optional(),
       manifestV2: z.any().optional(),
-      // Full ManifestV3 for sandbox execution
-      // Internal flags for auto-generated commands
-      isSetup: z.boolean().optional(),
-      // Auto-generated setup command
-      isSetupRollback: z.boolean().optional(),
-      // Auto-generated setup rollback command
-      pkgRoot: z.string().optional()
-      // Package root path for handler resolution
+      pkgRoot: z.string().optional(),
+      _synthetic: z.boolean().optional(),
+      operationType: z.enum(["read", "mutate", "execute", "analyze"]).optional()
     }).refine(
-      (data) => {
-        if (data.namespace && data.group && data.namespace !== data.group) {
-          return false;
-        }
-        return true;
-      },
-      { message: "namespace must match group" }
-    ).refine(
       (data) => {
         if (data.requires) {
           for (const req2 of data.requires) {
@@ -168,6 +128,7 @@ __export(discover_exports, {
   __test: () => __test,
   discoverManifests: () => discoverManifests,
   discoverManifestsByNamespace: () => discoverManifestsByNamespace,
+  loadConfig: () => loadConfig,
   resetInProcCache: () => resetInProcCache
 });
 function createManifestV3Loader(commandId) {
@@ -198,9 +159,11 @@ function createUnavailableManifest(pkgName, error) {
   const group = (seg || pkgName).replace(/-cli$/, "");
   const short = seg || pkgName;
   const requires = missing ? [missing] : [];
+  const unavailableId = `manifest:${short}`;
   const manifest = {
     manifestVersion: "1.0",
-    id: `${group}:manifest:${short}`,
+    segments: [group, unavailableId],
+    id: unavailableId,
     group,
     describe: `Commands from ${pkgName} are unavailable`,
     requires,
@@ -218,14 +181,6 @@ function createUnavailableManifest(pkgName, error) {
 function resetInProcCache() {
   inProcDiscoveryCache = null;
 }
-async function computeManifestHash(manifestPath) {
-  try {
-    const content = await promises.readFile(manifestPath, "utf8");
-    return createHash("sha256").update(content).digest("hex");
-  } catch {
-    return "unknown";
-  }
-}
 async function computeLockfileHash(cwd) {
   const lockfilePath = path.join(cwd, "pnpm-lock.yaml");
   try {
@@ -331,8 +286,12 @@ async function loadManifest(manifestPath, pkgName, pkgRoot) {
   const mod = await import(fileUrl);
   const modTyped = mod;
   const rawManifest = modTyped.manifest || modTyped.default;
-  if (!rawManifest || typeof rawManifest !== "object" || rawManifest.schema !== "kb.plugin/3") {
-    throw new Error(`Unsupported manifest format in ${pkgName}. Only kb.plugin/3 schema is supported.`);
+  if (!rawManifest || typeof rawManifest !== "object") {
+    throw new Error(`No manifest export found in ${pkgName}`);
+  }
+  const schema = rawManifest.schema;
+  if (schema !== "kb.plugin/3") {
+    throw new NonPluginManifestError(pkgName, typeof schema === "string" ? schema : String(schema ?? "unknown"));
   }
   const manifest = rawManifest;
   const namespace = getNamespaceFromManifest(manifest, pkgName);
@@ -343,20 +302,23 @@ async function loadManifest(manifestPath, pkgName, pkgRoot) {
     log("warn", `ManifestV3 ${manifest.id || pkgName} has no CLI commands or setup entry`);
   }
   const commandManifests = cliCommands.map((cmd) => {
-    const commandId = cmd.id;
+    const segments = cmd.path.trim().split(/\s+/).filter(Boolean);
+    const commandId = segments[segments.length - 1] ?? namespace;
     const commandManifest = {
       manifestVersion: "1.0",
+      segments,
       id: commandId,
-      group: cmd.group || namespace,
-      subgroup: cmd.subgroup,
+      group: segments[0] ?? namespace,
+      subgroup: segments.length >= 3 ? segments[1] : void 0,
+      category: cmd.category,
       describe: cmd.describe || "",
       longDescription: cmd.longDescription,
       aliases: cmd.aliases,
       flags: cmd.flags,
       examples: cmd.examples,
-      loader: createManifestV3Loader(commandId),
+      loader: createManifestV3Loader(cmd.path),
       package: pkgName,
-      namespace: cmd.group || namespace
+      operationType: cmd.operationType
     };
     commandManifest.manifestV2 = manifest;
     commandManifest.pkgRoot = baseRoot;
@@ -370,7 +332,7 @@ async function loadManifest(manifestPath, pkgName, pkgRoot) {
     log("warn", `ManifestV3 validation warnings for ${pkgName}: ${errorMessages}`);
   }
   return (validation.success ? validation.data : commandManifests).map(
-    (m) => normalizeManifest(m, pkgName, namespace)
+    (m) => normalizeManifest(m, pkgName)
   );
 }
 async function readPackageJson(pkgPath) {
@@ -441,10 +403,11 @@ function validateUniqueIds(manifests, pkgName) {
   const ids = /* @__PURE__ */ new Set();
   const aliases = /* @__PURE__ */ new Set();
   for (const m of manifests) {
-    if (ids.has(m.id)) {
+    const key = m.segments.join("/");
+    if (ids.has(key)) {
       throw new Error(`Duplicate command ID "${m.id}" in package ${pkgName}`);
     }
-    ids.add(m.id);
+    ids.add(key);
     if (m.aliases) {
       for (const alias of m.aliases) {
         if (aliases.has(alias) || ids.has(alias)) {
@@ -537,6 +500,10 @@ async function loadManifestsForPackages(packageInfos, source, scope) {
       log("debug", `[plugins][perf] ${pkgName} failed after ${pkgTime}ms`);
       const errMsg = err instanceof Error ? err.message : String(err);
       const errCode = err.code ?? "UNKNOWN";
+      if (err instanceof NonPluginManifestError) {
+        log("debug", `[plugins] ${pkgName} skipped: ${err.message}`);
+        return null;
+      }
       log("warn", JSON.stringify({
         code: "DISCOVERY_MANIFEST_LOAD_FAIL",
         packageName: pkgName,
@@ -707,6 +674,10 @@ async function discoverNodeModules(cwd) {
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
         const errCode = err.code ?? "UNKNOWN";
+        if (err instanceof NonPluginManifestError) {
+          log("debug", `[plugins] ${pkgName} skipped: ${err.message}`);
+          return null;
+        }
         log("warn", JSON.stringify({
           code: "DISCOVERY_MANIFEST_LOAD_FAIL",
           packageName: pkgName,
@@ -796,6 +767,10 @@ async function loadCache(cwd, roots) {
       log("debug", "Cache invalidated: Node version changed");
       return null;
     }
+    if ((cache.discoveryVersion ?? 0) !== DISCOVERY_VERSION) {
+      log("debug", `Cache invalidated: discovery logic changed (${cache.discoveryVersion ?? 0} \u2192 ${DISCOVERY_VERSION})`);
+      return null;
+    }
     const currentCliVersion = process.env.CLI_VERSION || "0.1.0";
     if (cache.cliVersion !== currentCliVersion) {
       log("debug", "Cache invalidated: CLI version changed");
@@ -849,7 +824,7 @@ async function loadCache(cwd, roots) {
     return null;
   }
 }
-async function isPackageCacheStale(entry, options) {
+async function isPackageCacheStale(entry) {
   const manifestFsPath = entry.manifestPath.split("/").join(path.sep);
   const pkgJsonPath = path.join(entry.result.pkgRoot.split("/").join(path.sep), PACKAGE_JSON);
   try {
@@ -862,26 +837,23 @@ async function isPackageCacheStale(entry, options) {
     log("debug", `Package cache invalidated: missing package.json for ${entry.result.packageName} (${error instanceof Error ? error.message : "unknown"})`);
     return true;
   }
-  let manifestStat;
+  let manifestMtimeChanged = false;
   try {
-    manifestStat = await promises.stat(manifestFsPath);
-    if (manifestStat.mtimeMs !== entry.manifestMtime) {
-      log("debug", `Package cache invalidated: manifest mtime changed for ${entry.result.packageName}`);
-      return true;
-    }
+    const manifestStat = await promises.stat(manifestFsPath);
+    manifestMtimeChanged = manifestStat.mtimeMs !== entry.manifestMtime;
   } catch (error) {
     log("debug", `Package cache invalidated: manifest deleted for ${entry.result.packageName} (${error instanceof Error ? error.message : "unknown"})`);
     return true;
   }
-  if (options.validateHash) {
+  if (manifestMtimeChanged) {
     try {
-      const currentHash = await computeManifestHash(manifestFsPath);
+      const currentHash = await computeManifestIntegrity(manifestFsPath);
       if (currentHash !== entry.manifestHash) {
-        log("debug", `Package cache invalidated: manifest hash changed for ${entry.result.packageName}`);
+        log("debug", `Package cache invalidated: manifest content changed for ${entry.result.packageName}`);
         return true;
       }
     } catch (error) {
-      log("debug", `Package cache hash validation failed for ${entry.result.packageName}: ${error instanceof Error ? error.message : "unknown"}`);
+      log("debug", `Package cache hash check failed for ${entry.result.packageName}: ${error instanceof Error ? error.message : "unknown"}`);
       return true;
     }
   }
@@ -900,7 +872,7 @@ async function saveCache(cwd, results, roots) {
       continue;
     }
     try {
-      const manifestHash = await computeManifestHash(result.manifestPath);
+      const manifestHash = await computeManifestIntegrity(result.manifestPath);
       const pkgJsonPath = path.join(result.pkgRoot.split("/").join(path.sep), PACKAGE_JSON);
       const pkgStat = await promises.stat(pkgJsonPath);
       const pkg = await readPackageJson(pkgJsonPath);
@@ -955,6 +927,7 @@ async function saveCache(cwd, results, roots) {
   const cache = {
     version: process.version,
     cliVersion: process.env.CLI_VERSION || "0.1.0",
+    discoveryVersion: DISCOVERY_VERSION,
     timestamp: now,
     ttlMs: DISK_CACHE_TTL_MS,
     stateHash: stateHasher.digest("hex"),
@@ -1002,11 +975,10 @@ async function discoverManifests(cwd, noCache = false, options = {}) {
       const freshResults = [];
       const cacheAge = Date.now() - cached.timestamp;
       const ttlMs = cached.ttlMs ?? DISK_CACHE_TTL_MS;
-      const enforceHashValidation = cacheAge >= ttlMs;
-      log("debug", `[plugins][cache] hit age=${cacheAge}ms ttl=${ttlMs}ms validateHash=${enforceHashValidation}`);
+      log("debug", `[plugins][cache] hit age=${cacheAge}ms ttl=${ttlMs}ms`);
       let staleCount = 0;
       for (const entry of Object.values(cached.packages)) {
-        const stale = await isPackageCacheStale(entry, { validateHash: enforceHashValidation });
+        const stale = await isPackageCacheStale(entry);
         if (!stale) {
           freshResults.push(entry.result);
         } else {
@@ -1073,7 +1045,19 @@ async function discoverManifests(cwd, noCache = false, options = {}) {
       if (projectWorkspace.length > 0) {
         log("info", `Discovered ${projectWorkspace.length} project workspace packages with CLI manifests`);
       }
-    } catch {
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const isMissingYaml = msg.includes("ENOENT") || msg.includes("no such file");
+      if (isMissingYaml) {
+        log("debug", `[plugins][discover] no pnpm-workspace.yaml at projectRoot=${roots.projectRoot} \u2014 skipping project workspace scan`);
+      } else {
+        log("warn", JSON.stringify({
+          code: "PROJECT_WORKSPACE_DISCOVERY_FAILED",
+          projectRoot: roots.projectRoot,
+          error: msg,
+          hint: "Project workspace plugins may be missing from CLI discovery"
+        }));
+      }
     }
   }
   const dedupStart = Date.now();
@@ -1099,27 +1083,26 @@ async function discoverManifestsByNamespace(cwd, namespace, noCache = false) {
   const allResults = await discoverManifests(cwd, noCache);
   return allResults.filter((result) => {
     return result.manifests.some((m) => {
-      const manifestNamespace = m.namespace || m.group;
-      return manifestNamespace === namespace;
+      return m.group === namespace;
     });
   });
 }
-var DEBUG_MODE, log, __test, PACKAGE_JSON, MANIFEST_LOAD_TIMEOUT, IN_PROC_CACHE_TTL_MS, DISK_CACHE_TTL_MS, inProcDiscoveryCache;
+var DISCOVERY_VERSION, DEBUG_MODE, log, __test, NonPluginManifestError, PACKAGE_JSON, MANIFEST_LOAD_TIMEOUT, IN_PROC_CACHE_TTL_MS, DISK_CACHE_TTL_MS, inProcDiscoveryCache;
 var init_discover = __esm({
   "src/registry/discover.ts"() {
     init_path();
     init_schema();
+    DISCOVERY_VERSION = 2;
     DEBUG_MODE = process.env.DEBUG_SANDBOX === "1" || process.env.NODE_ENV === "development";
     log = (level, message, fields) => {
       if (!DEBUG_MODE) {
         return;
       }
       const prefix = level === "error" ? "\u2717" : level === "warn" ? "\u26A0" : level === "info" ? "\u2139" : "\u{1F50D}";
-      const logFn = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
       if (fields) {
-        logFn(`${prefix} [discover] ${message}`, fields);
+        console.error(`${prefix} [discover] ${message}`, fields);
       } else {
-        logFn(`${prefix} [discover] ${message}`);
+        console.error(`${prefix} [discover] ${message}`);
       }
     };
     __test = {
@@ -1127,6 +1110,14 @@ var init_discover = __esm({
       createManifestV3Loader
       // resetInProcCache is exported directly (not via __test) since it's part of the public API
     };
+    NonPluginManifestError = class extends Error {
+      schema;
+      constructor(pkgName, schema) {
+        super(`${pkgName} uses manifest schema "${schema}", not kb.plugin/3 \u2014 skipping`);
+        this.name = "NonPluginManifestError";
+        this.schema = schema;
+      }
+    };
     PACKAGE_JSON = "package.json";
     MANIFEST_LOAD_TIMEOUT = 1500;
     IN_PROC_CACHE_TTL_MS = 6e4;
@@ -1135,420 +1126,511 @@ var init_discover = __esm({
   }
 });
 
-// src/registry/service.ts
-function manifestToCommand(registered) {
-  return {
-    name: registered.manifest.id,
-    category: registered.manifest.group,
-    describe: registered.manifest.describe,
-    longDescription: registered.manifest.longDescription,
-    aliases: registered.manifest.aliases || [],
-    flags: registered.manifest.flags,
-    examples: registered.manifest.examples,
-    async run() {
-      throw new Error(`Command ${registered.manifest.id} should be executed via plugin-executor, not via legacy run() path.`);
-    }
-  };
+// src/registry/trie-router.ts
+function makeNode() {
+  return { children: /* @__PURE__ */ new Map() };
 }
-function buildCanonicalId(manifest) {
-  const { id, group, subgroup } = manifest;
-  if (group && subgroup) {
-    return `${group}:${subgroup}:${id}`;
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from(
+    { length: m + 1 },
+    (_, i) => Array.from({ length: n + 1 }, (__, j) => i === 0 ? j : j === 0 ? i : 0)
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (a[i - 1] === b[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1];
+      } else {
+        dp[i][j] = 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      }
+    }
   }
-  if (group) {
-    return `${group}:${id}`;
+  return dp[m][n];
+}
+function findDeep(node, targetSegments, prefix) {
+  const results = [];
+  function dfs(current, path6) {
+    if (current.command) {
+      if (targetSegments.length <= path6.length) {
+        const tail = path6.slice(path6.length - targetSegments.length);
+        const matches = tail.every((seg, i) => seg === targetSegments[i]);
+        if (matches) {
+          results.push(path6.join(" "));
+        }
+      }
+    }
+    for (const [key, child] of current.children) {
+      dfs(child, [...path6, key]);
+    }
   }
-  return id;
+  dfs(node, [...prefix]);
+  return results;
 }
-var InMemoryRegistry = class {
-  // System commands (in-process): key = any registered name/alias
-  systemCommands = /* @__PURE__ */ new Map();
-  // Plugin commands: key = canonicalId only
-  pluginByCanonical = /* @__PURE__ */ new Map();
-  // Alias → canonicalId: covers all user-input variants that resolve to a plugin
-  pluginAliases = /* @__PURE__ */ new Map();
-  // Legacy unified collection for backward compatibility (display/get)
-  byName = /* @__PURE__ */ new Map();
-  groups = /* @__PURE__ */ new Map();
-  // manifests: any key → RegisteredCommand (for listing/lookup; still stores multi-key for compat)
-  manifests = /* @__PURE__ */ new Map();
-  partial = false;
-  // ─── System command registration ────────────────────────────────────────
-  register(cmd) {
-    this.systemCommands.set(cmd.name, cmd);
-    this.byName.set(cmd.name, cmd);
-    for (const a of cmd.aliases || []) {
-      this.systemCommands.set(a, cmd);
-      this.byName.set(a, cmd);
+var TrieRouter = class {
+  root = makeNode();
+  /**
+   * Insert a plugin command into the trie.
+   *
+   * Enforces 1-manifest-1-namespace: the first packageName to register any command
+   * under a top-level group becomes the owner. Subsequent packages with a different
+   * packageName are rejected (collides: true) — the caller is responsible for warning
+   * and marking the command as shadowed.
+   *
+   * Returns { collides: false } on success, or { collides: true, ownerPackage } on conflict.
+   */
+  insertCommand(segments, cmd) {
+    if (segments.length === 0) {
+      return { collides: false };
+    }
+    const incoming = cmd.packageName ?? "__unknown__";
+    const topSeg = segments[0];
+    if (!this.root.children.has(topSeg)) {
+      this.root.children.set(topSeg, makeNode());
+    }
+    const groupNode = this.root.children.get(topSeg);
+    if (groupNode.ownerPackage === void 0) {
+      groupNode.ownerPackage = incoming;
+    } else if (groupNode.ownerPackage !== incoming) {
+      return { collides: true, ownerPackage: groupNode.ownerPackage };
+    }
+    let node = groupNode;
+    for (const seg of segments.slice(1)) {
+      if (!node.children.has(seg)) {
+        node.children.set(seg, makeNode());
+      }
+      node = node.children.get(seg);
     }
+    node.command = cmd;
+    return { collides: false };
   }
-  registerGroup(group) {
-    this.groups.set(group.name, group);
-    this.byName.set(group.name, group);
+  insertSystemCommand(cmd) {
+    const segments = [cmd.name];
+    let node = this.root;
+    for (const seg of segments) {
+      if (!node.children.has(seg)) {
+        node.children.set(seg, makeNode());
+      }
+      node = node.children.get(seg);
+    }
+    node.systemCommand = cmd;
+    for (const alias of cmd.aliases ?? []) {
+      let aliasNode = this.root;
+      if (!aliasNode.children.has(alias)) {
+        aliasNode.children.set(alias, makeNode());
+      }
+      aliasNode = aliasNode.children.get(alias);
+      aliasNode.systemCommand = cmd;
+    }
+  }
+  insertSystemGroup(group) {
+    let groupNode = this.root;
+    if (!groupNode.children.has(group.name)) {
+      groupNode.children.set(group.name, makeNode());
+    }
+    groupNode = groupNode.children.get(group.name);
+    groupNode.systemGroup = group;
+    groupNode.groupDescribe = group.describe;
     for (const cmd of group.commands) {
-      this.systemCommands.set(cmd.name, cmd);
-      const fullName = `${group.name} ${cmd.name}`;
-      this.systemCommands.set(fullName, cmd);
-      this.byName.set(fullName, cmd);
-      for (const alias of cmd.aliases || []) {
-        this.systemCommands.set(alias, cmd);
-        this.byName.set(alias, cmd);
+      let cmdNode = groupNode;
+      if (!cmdNode.children.has(cmd.name)) {
+        cmdNode.children.set(cmd.name, makeNode());
+      }
+      cmdNode = cmdNode.children.get(cmd.name);
+      cmdNode.systemCommand = cmd;
+      for (const alias of cmd.aliases ?? []) {
+        let aliasNode = groupNode;
+        if (!aliasNode.children.has(alias)) {
+          aliasNode.children.set(alias, makeNode());
+        }
+        aliasNode = aliasNode.children.get(alias);
+        aliasNode.systemCommand = cmd;
       }
     }
-    if (group.subgroups) {
-      for (const sub of group.subgroups) {
-        const subName = `${group.name} ${sub.name}`;
-        this.groups.set(subName, sub);
-        this.byName.set(subName, sub);
-        for (const cmd of sub.commands) {
-          const fullName = `${group.name} ${sub.name} ${cmd.name}`;
-          this.systemCommands.set(fullName, cmd);
-          this.byName.set(fullName, cmd);
-          for (const alias of cmd.aliases || []) {
-            this.systemCommands.set(alias, cmd);
-            this.byName.set(alias, cmd);
-          }
+    for (const sub of group.subgroups ?? []) {
+      let subNode = groupNode;
+      if (!subNode.children.has(sub.name)) {
+        subNode.children.set(sub.name, makeNode());
+      }
+      subNode = subNode.children.get(sub.name);
+      subNode.systemGroup = sub;
+      subNode.groupDescribe = sub.describe;
+      for (const cmd of sub.commands) {
+        let cmdNode = subNode;
+        if (!cmdNode.children.has(cmd.name)) {
+          cmdNode.children.set(cmd.name, makeNode());
         }
+        cmdNode = cmdNode.children.get(cmd.name);
+        cmdNode.systemCommand = cmd;
       }
     }
   }
-  // ─── Plugin command registration ────────────────────────────────────────
-  registerManifest(cmd) {
-    const canonicalId = buildCanonicalId(cmd.manifest);
-    const collisionKey = this._findSystemCollision(cmd.manifest, canonicalId);
-    if (collisionKey) {
-      console.warn(`[registry] Plugin command "${canonicalId}" collides with system command "${collisionKey}". System command takes priority.`);
-      cmd.shadowed = true;
+  getGroupDescribe(segments) {
+    let node = this.root;
+    for (const seg of segments) {
+      const child = node.children.get(seg);
+      if (!child) {
+        return void 0;
+      }
+      node = child;
     }
-    const collisionAliases = /* @__PURE__ */ new Set();
-    for (const alias of cmd.manifest.aliases || []) {
-      if (this.systemCommands.has(alias)) {
-        console.warn(`[registry] Plugin alias "${alias}" collides with system command. System command takes priority.`);
-        collisionAliases.add(alias);
+    return node.groupDescribe;
+  }
+  setGroupDescribe(segments, describe) {
+    let node = this.root;
+    for (const seg of segments) {
+      if (!node.children.has(seg)) {
+        node.children.set(seg, makeNode());
       }
+      node = node.children.get(seg);
     }
-    this.pluginByCanonical.set(canonicalId, cmd);
-    this.manifests.set(canonicalId, cmd);
-    this.manifests.set(cmd.manifest.id, cmd);
-    if (cmd.shadowed) {
-      return;
+    if (!node.groupDescribe) {
+      node.groupDescribe = describe;
     }
-    this._registerPluginAliases(cmd, canonicalId, collisionAliases);
-    const commandAdapter = manifestToCommand(cmd);
-    this.byName.set(canonicalId, commandAdapter);
-    const spaceCanonical = canonicalId.replace(/:/g, " ");
-    this.byName.set(spaceCanonical, commandAdapter);
-    this._registerSyntheticGroups(cmd, commandAdapter);
   }
-  /**
-   * Check whether any system command already owns the canonical id or its parts.
-   * Returns the colliding key if found, null otherwise.
-   */
-  _findSystemCollision(manifest, canonicalId) {
-    if (this.systemCommands.has(canonicalId)) {
-      return canonicalId;
+  resolve(tokens) {
+    if (tokens.length === 0) {
+      return {
+        type: "group",
+        segments: [],
+        childKeys: [...this.root.children.keys()]
+      };
+    }
+    let node = this.root;
+    let i = 0;
+    while (i < tokens.length) {
+      const tok = tokens[i];
+      const child = node.children.get(tok);
+      if (!child) {
+        return this._notFound(node, tokens, i);
+      }
+      node = child;
+      i++;
+      if (node.command && i < tokens.length) {
+        return { type: "command", command: node.command, rest: tokens.slice(i) };
+      }
+      if (node.systemCommand && i < tokens.length) {
+        return { type: "system-cmd", cmd: node.systemCommand, rest: tokens.slice(i) };
+      }
     }
-    const space = canonicalId.replace(/:/g, " ");
-    if (this.systemCommands.has(space)) {
-      return space;
+    if (node.command) {
+      return { type: "command", command: node.command, rest: [] };
     }
-    return null;
+    if (node.systemCommand) {
+      return { type: "system-cmd", cmd: node.systemCommand, rest: [] };
+    }
+    if (node.systemGroup) {
+      return { type: "system-group", group: node.systemGroup, rest: [] };
+    }
+    if (node.children.size > 0 || node.groupDescribe !== void 0) {
+      const segs = tokens.slice(0, i);
+      return {
+        type: "group",
+        segments: segs,
+        describe: node.groupDescribe,
+        childKeys: [...node.children.keys()]
+      };
+    }
+    return { type: "not-found", input: tokens, suggestions: [] };
   }
-  /**
-   * Register all lookup aliases for a plugin command.
-   *
-   * Priority (what beats what) is handled in resolveToCanonical at query time.
-   * Here we just build the mapping.
-   *
-   * Aliases registered:
-   *   - canonicalId itself        ("marketplace:plugins:list")
-   *   - bare id                   ("list")         ← low priority, may clash
-   *   - 2-part shorthand          ("marketplace:list", "marketplace list")
-   *   - manifest.aliases[]        (user-defined aliases, except collisions)
-   */
-  _registerPluginAliases(cmd, canonicalId, collisionAliases) {
-    const { id, group, subgroup } = cmd.manifest;
-    const register = (key) => {
-      if (!this.systemCommands.has(key) && !this.systemCommands.has(key.replace(/:/g, " "))) {
-        if (!this.pluginAliases.has(key)) {
-          this.pluginAliases.set(key, canonicalId);
-          this.manifests.set(key, cmd);
-        }
+  complete(tokens) {
+    if (tokens.length === 0) {
+      return [...this.root.children.keys()];
+    }
+    let node = this.root;
+    for (let i = 0; i < tokens.length - 1; i++) {
+      const child = node.children.get(tokens[i]);
+      if (!child) {
+        return [];
       }
-    };
-    this.pluginAliases.set(canonicalId, canonicalId);
-    const spaceCanonical = canonicalId.replace(/:/g, " ");
-    this.pluginAliases.set(spaceCanonical, canonicalId);
-    this.manifests.set(spaceCanonical, cmd);
-    if (group && subgroup) {
-      const twoPartColon = `${group}:${id}`;
-      const twoPartSpace = `${group} ${id}`;
-      register(twoPartColon);
-      register(twoPartSpace);
-      this.manifests.set(twoPartColon, cmd);
-      this.manifests.set(twoPartSpace, cmd);
-      const fullPath = `${group} ${subgroup} ${id}`;
-      this.pluginAliases.set(fullPath, canonicalId);
-      this.manifests.set(fullPath, cmd);
-      const colonPath = `${group}:${subgroup}:${id}`;
-      this.pluginAliases.set(colonPath, canonicalId);
-      this.manifests.set(colonPath, cmd);
-    } else if (group) {
-      const colonName = `${group}:${id}`;
-      const spaceName = `${group} ${id}`;
-      this.pluginAliases.set(colonName, canonicalId);
-      this.pluginAliases.set(spaceName, canonicalId);
-      this.manifests.set(colonName, cmd);
-      this.manifests.set(spaceName, cmd);
-    }
-    register(id);
-    for (const alias of cmd.manifest.aliases || []) {
-      if (!collisionAliases.has(alias)) {
-        register(alias);
+      node = child;
+    }
+    const partial = tokens[tokens.length - 1] ?? "";
+    const results = [];
+    const prefix = tokens.slice(0, tokens.length - 1);
+    for (const [key] of node.children) {
+      if (key.startsWith(partial)) {
+        results.push([...prefix, key].join(" "));
       }
     }
+    return results;
   }
   /**
-   * Register synthetic subgroups for help display.
+   * List all leaf plugin commands under a given node path.
    */
-  _registerSyntheticGroups(cmd, commandAdapter) {
-    const { id, group, subgroup } = cmd.manifest;
-    if (group && subgroup) {
-      const subgroupKey = `${group} ${subgroup}`;
-      if (!this.groups.has(subgroupKey)) {
-        this.groups.set(subgroupKey, {
-          name: subgroupKey,
-          describe: subgroup,
-          commands: []
-        });
-        this.byName.set(subgroupKey, this.groups.get(subgroupKey));
+  listUnder(segments) {
+    let node = this.root;
+    for (const seg of segments) {
+      const child = node.children.get(seg);
+      if (!child) {
+        return [];
       }
-      this.groups.get(subgroupKey).commands.push(commandAdapter);
-      const twoPartSpace = `${group} ${id}`;
-      if (!this.byName.has(twoPartSpace)) {
-        this.byName.set(twoPartSpace, commandAdapter);
+      node = child;
+    }
+    const results = [];
+    this._collectCommands(node, results);
+    return results;
+  }
+  /**
+   * Get exact command at path.
+   */
+  getAt(segments) {
+    let node = this.root;
+    for (const seg of segments) {
+      const child = node.children.get(seg);
+      if (!child) {
+        return null;
       }
-      const twoPartColon = `${group}:${id}`;
-      if (!this.byName.has(twoPartColon)) {
-        this.byName.set(twoPartColon, commandAdapter);
+      node = child;
+    }
+    return node.command ?? null;
+  }
+  /**
+   * List top-level system groups and standalone system commands (depth=1 nodes).
+   */
+  listSystemTopLevel() {
+    const results = [];
+    for (const [name, node] of this.root.children) {
+      if (node.systemGroup) {
+        results.push({ name, describe: node.systemGroup.describe, isGroup: true });
+      } else if (node.systemCommand) {
+        results.push({ name, describe: node.systemCommand.describe, isGroup: false });
       }
-      const fullPath = `${group} ${subgroup} ${id}`;
-      this.byName.set(fullPath, commandAdapter);
-    } else if (group) {
-      const fullName = `${group} ${id}`;
-      const colonName = `${group}:${id}`;
-      this.byName.set(fullName, commandAdapter);
-      this.byName.set(colonName, commandAdapter);
     }
+    return results;
   }
-  // ─── Resolution ──────────────────────────────────────────────────────────
   /**
-   * Resolve any user input to its canonical plugin ID.
-   *
-   * Returns canonicalId if found in plugin aliases, undefined otherwise.
+   * Collect all plugin commands reachable from node.
    */
-  resolveToCanonical(input) {
-    if (this.pluginAliases.has(input)) {
-      return this.pluginAliases.get(input);
+  listAll() {
+    const results = [];
+    this._collectCommands(this.root, results);
+    return results;
+  }
+  _collectCommands(node, out) {
+    if (node.command) {
+      out.push(node.command);
+    }
+    for (const child of node.children.values()) {
+      this._collectCommands(child, out);
     }
-    const converted = input.includes(":") ? input.replace(/:/g, " ") : input.replace(/ /g, ":");
-    if (this.pluginAliases.has(converted)) {
-      return this.pluginAliases.get(converted);
+  }
+  _notFound(node, tokens, failIdx) {
+    const failToken = tokens[failIdx];
+    const prefix = tokens.slice(0, failIdx);
+    const siblings = [...node.children.keys()];
+    const fuzzy = siblings.map((s) => ({ s, d: levenshtein(failToken, s) })).filter(({ d }) => d <= 2).sort((a, b) => a.d - b.d).map(({ s }) => [...prefix, s, ...tokens.slice(failIdx + 1)].join(" "));
+    if (fuzzy.length === 1) {
+      return { type: "not-found", input: tokens, suggestions: fuzzy };
+    }
+    if (fuzzy.length > 1) {
+      return { type: "ambiguous", input: tokens, candidates: fuzzy };
+    }
+    const remaining = tokens.slice(failIdx);
+    const deep = findDeep(node, remaining, prefix);
+    if (deep.length === 0) {
+      return { type: "not-found", input: tokens, suggestions: [] };
+    }
+    if (deep.length === 1) {
+      return { type: "not-found", input: tokens, suggestions: deep };
     }
-    return void 0;
+    return { type: "ambiguous", input: tokens, candidates: deep };
   }
-  // ─── Public API ──────────────────────────────────────────────────────────
-  markPartial(partial) {
-    this.partial = partial;
+};
+
+// src/registry/archetype-flags.ts
+var outputFlag = { name: "output", type: "string", choices: ["json", "table", "csv"], description: "Output format" };
+var dryRunFlag = { name: "dry-run", type: "boolean", description: "Show what would happen without executing" };
+var yesFlag = { name: "yes", type: "boolean", alias: "y", description: "Skip confirmation prompts" };
+var waitFlag = { name: "wait", type: "boolean", description: "Block until execution completes" };
+var watchFlag = { name: "watch", type: "boolean", description: "Stream events as NDJSON" };
+var timeoutFlag = { name: "timeout", type: "string", description: "Max wait time (e.g. 30s, 5m)" };
+var limitFlag = { name: "limit", type: "number", description: "Max results to return" };
+var offsetFlag = { name: "offset", type: "number", description: "Offset for pagination" };
+var formatFlag = { name: "format", type: "string", choices: ["json", "text", "md"], description: "Output format" };
+var streamFlag = { name: "stream", type: "boolean", description: "Stream output progressively" };
+var schemaFlag = {
+  name: "schema",
+  type: "boolean",
+  description: "Output JSON Schema for this command (flags, types, examples)"
+};
+var ARCHETYPE_FLAGS = {
+  read: [outputFlag, limitFlag, offsetFlag],
+  mutate: [outputFlag, dryRunFlag, yesFlag],
+  execute: [outputFlag, waitFlag, watchFlag, timeoutFlag, yesFlag],
+  analyze: [outputFlag, formatFlag, streamFlag]
+};
+function getArchetypeFlags(operationType, existing = []) {
+  const toInject = ARCHETYPE_FLAGS[operationType] ?? [];
+  const existingNames = new Set(existing.map((f) => f.name));
+  return toInject.filter((f) => !existingNames.has(f.name));
+}
+
+// src/registry/service.ts
+var RESERVED_NAMESPACES = /* @__PURE__ */ new Set(["__complete", "__internal"]);
+var MAX_PATH_DEPTH = 6;
+function validateSegments(segs) {
+  if (segs.length === 0) {
+    return "empty path \u2014 segments must not be empty";
   }
-  isPartial() {
-    return this.partial;
+  if (segs.length > MAX_PATH_DEPTH) {
+    return `path too deep: ${segs.length} segments (max ${MAX_PATH_DEPTH})`;
   }
-  getManifest(id) {
-    return this.manifests.get(id);
+  if (RESERVED_NAMESPACES.has(segs[0])) {
+    return `"${segs[0]}" is a reserved namespace`;
   }
-  listManifests() {
-    const unique = /* @__PURE__ */ new Set();
-    for (const cmd of this.pluginByCanonical.values()) {
-      unique.add(cmd);
-    }
-    return Array.from(unique);
+  return null;
+}
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  },
+  child: () => noopLogger
+};
+var TrieBackedRegistry = class {
+  systemRouter = new TrieRouter();
+  pluginRouter = new TrieRouter();
+  partial = false;
+  logger = noopLogger;
+  // ─── Logger ────────────────────────────────────────────────────────────────
+  setLogger(logger) {
+    this.logger = logger;
   }
-  has(name) {
-    return this.byName.has(name) || this.pluginAliases.has(name);
+  // ─── Registration ──────────────────────────────────────────────────────────
+  register(cmd) {
+    this.systemRouter.insertSystemCommand(cmd);
   }
-  /**
-   * Get command with type information for secure routing.
-   *
-   * System commands ALWAYS win — checked first before any plugin lookup.
-   * Returns type='system' for system commands (in-process execution).
-   * Returns type='plugin' for plugin commands (subprocess execution).
-   */
-  getWithType(nameOrPath) {
-    const normalized = typeof nameOrPath === "string" ? nameOrPath : nameOrPath.join(" ");
-    if (this.systemCommands.has(normalized)) {
-      return { cmd: this.systemCommands.get(normalized), type: "system" };
-    }
-    const colonVariant = normalized.replace(/ /g, ":");
-    if (this.systemCommands.has(colonVariant)) {
-      return { cmd: this.systemCommands.get(colonVariant), type: "system" };
-    }
-    if (this.groups.has(normalized)) {
-      return { cmd: this.groups.get(normalized), type: "system" };
-    }
-    const canonicalId = this.resolveToCanonical(normalized);
-    if (canonicalId) {
-      const pluginCmd = this.pluginByCanonical.get(canonicalId);
-      if (pluginCmd && !pluginCmd.shadowed) {
-        const cmd2 = this.byName.get(canonicalId) ?? this.byName.get(normalized);
-        if (cmd2) {
-          return { cmd: cmd2, type: "plugin" };
-        }
+  registerGroup(group) {
+    this.systemRouter.insertSystemGroup(group);
+    if (group.subgroups) {
+      for (const sub of group.subgroups) {
+        this.systemRouter.setGroupDescribe([group.name, sub.name], sub.describe ?? "");
       }
     }
-    const cmd = this.get(nameOrPath);
-    if (!cmd) {
-      return void 0;
-    }
-    if ("commands" in cmd) {
-      return { cmd, type: "system" };
+  }
+  registerManifest(cmd) {
+    if (cmd.manifest._synthetic) {
+      return;
     }
-    if (this.systemCommands.has(normalized) || this.systemCommands.has(colonVariant)) {
-      return { cmd, type: "system" };
+    const segs = cmd.manifest.segments;
+    const pkg = cmd.packageName ?? "unknown";
+    const validationError = validateSegments(segs);
+    if (validationError) {
+      this.logger.warn(`[registry] Plugin "${pkg}" skipped: ${validationError} (path: "${segs.join(" ")}")`);
+      cmd.shadowed = true;
+      return;
     }
-    const manifestCmd = this.getManifestCommand(normalized);
-    if (manifestCmd && !manifestCmd.shadowed) {
-      return { cmd, type: "plugin" };
+    const sysResult = this.systemRouter.resolve([...segs]);
+    if (sysResult.type === "system-cmd" || sysResult.type === "system-group") {
+      this.logger.warn(`[registry] Plugin "${pkg}" tried to register "${segs.join(" ")}" but it collides with a system command. Command will be shadowed.`);
+      cmd.shadowed = true;
+      return;
     }
-    return { cmd, type: "system" };
-  }
-  get(nameOrPath) {
-    if (typeof nameOrPath === "string") {
-      if (this.byName.has(nameOrPath)) {
-        return this.byName.get(nameOrPath);
-      }
-      if (nameOrPath.includes(":")) {
-        const spaceKey = nameOrPath.replace(/:/g, " ");
-        if (this.byName.has(spaceKey)) {
-          return this.byName.get(spaceKey);
-        }
-        const parts = nameOrPath.split(":");
-        if (parts.length === 2) {
-          const spaceKey2 = parts.join(" ");
-          if (this.byName.has(spaceKey2)) {
-            return this.byName.get(spaceKey2);
-          }
-        }
+    if (cmd.manifest.operationType) {
+      const injected = getArchetypeFlags(cmd.manifest.operationType, cmd.manifest.flags ?? []);
+      if (injected.length > 0) {
+        cmd.manifest.flags = [...cmd.manifest.flags ?? [], ...injected];
       }
     }
-    const key = Array.isArray(nameOrPath) ? nameOrPath.join(" ") : nameOrPath;
-    if (this.byName.has(key)) {
-      return this.byName.get(key);
+    if (cmd.manifest.operationType && !cmd.manifest.flags?.some((f) => f.name === "schema")) {
+      cmd.manifest.flags = [...cmd.manifest.flags ?? [], schemaFlag];
+    }
+    const result = this.pluginRouter.insertCommand(segs, cmd);
+    if (result.collides) {
+      this.logger.warn(
+        `[registry] Plugin "${pkg}" tried to register "${segs.join(" ")}" but namespace "${segs[0]}" is owned by "${result.ownerPackage ?? "unknown"}". Command will be shadowed.`
+      );
+      cmd.shadowed = true;
+      return;
     }
-    if (Array.isArray(nameOrPath) && nameOrPath.length === 1 && nameOrPath[0]?.includes(":")) {
-      if (this.byName.has(nameOrPath[0])) {
-        return this.byName.get(nameOrPath[0]);
+    for (const alias of cmd.manifest.aliases ?? []) {
+      const aliasSegs = alias.trim().split(/\s+/).filter(Boolean);
+      if (aliasSegs.length === 0) {
+        continue;
       }
-      const [group, command] = nameOrPath[0].split(":");
-      const legacyKey = `${group} ${command}`;
-      if (this.byName.has(legacyKey)) {
-        return this.byName.get(legacyKey);
+      const aliasValidationError = validateSegments(aliasSegs);
+      if (aliasValidationError) {
+        this.logger.warn(`[registry] Plugin "${pkg}" alias "${alias}" skipped: ${aliasValidationError}`);
+        continue;
       }
-    }
-    if (Array.isArray(nameOrPath)) {
-      const dot = nameOrPath.join(".");
-      if (this.byName.has(dot)) {
-        return this.byName.get(dot);
+      const aliasSysResult = this.systemRouter.resolve([...aliasSegs]);
+      if (aliasSysResult.type === "system-cmd" || aliasSysResult.type === "system-group") {
+        this.logger.warn(`[registry] Plugin "${pkg}" alias "${alias}" collides with a system command and will be skipped.`);
+        continue;
+      }
+      const aliasResult = this.pluginRouter.insertCommand(aliasSegs, cmd);
+      if (aliasResult.collides) {
+        this.logger.warn(
+          `[registry] Plugin "${pkg}" alias "${alias}" conflicts with namespace "${aliasSegs[0]}" owned by "${aliasResult.ownerPackage ?? "unknown"}". Alias skipped.`
+        );
       }
     }
-    if (Array.isArray(nameOrPath) && nameOrPath.length >= 2) {
-      const [groupPrefix, ...cmdParts] = nameOrPath;
-      const cmdName = cmdParts.join(" ");
-      for (const group of this.groups.values()) {
-        if (group.name === groupPrefix || group.name.startsWith(groupPrefix + ":")) {
-          const fullName = `${group.name} ${cmdName}`;
-          if (this.byName.has(fullName)) {
-            return this.byName.get(fullName);
-          }
-        }
+    const v3 = cmd.manifest.manifestV2;
+    if (v3?.cli?.groupMeta) {
+      for (const meta of v3.cli.groupMeta) {
+        const metaSegs = meta.path.trim().split(/\s+/).filter(Boolean);
+        this.pluginRouter.setGroupDescribe(metaSegs, meta.describe);
       }
     }
-    return void 0;
   }
-  list() {
-    const commands = /* @__PURE__ */ new Set();
-    for (const value of this.byName.values()) {
-      if ("run" in value) {
-        commands.add(value);
+  // ─── Resolution ────────────────────────────────────────────────────────────
+  resolve(tokens) {
+    if (tokens.length > 0) {
+      const sysResult = this.systemRouter.resolve(tokens);
+      if (sysResult.type !== "not-found") {
+        return sysResult;
       }
     }
-    return Array.from(commands);
+    return this.pluginRouter.resolve(tokens);
   }
-  listGroups() {
-    return Array.from(this.groups.values());
+  // ─── Tab completion ─────────────────────────────────────────────────────────
+  complete(tokens) {
+    const sysCompletions = this.systemRouter.complete(tokens);
+    const pluginCompletions = this.pluginRouter.complete(tokens);
+    return [.../* @__PURE__ */ new Set([...sysCompletions, ...pluginCompletions])];
   }
-  getGroupsByPrefix(prefix) {
-    const result = [];
-    for (const group of this.groups.values()) {
-      if (group.name === prefix || group.name.startsWith(prefix + ":")) {
-        result.push(group);
-      }
-    }
-    return result;
+  // ─── Query ──────────────────────────────────────────────────────────────────
+  listSystemTopLevel() {
+    return this.systemRouter.listSystemTopLevel();
   }
-  getCommandsByGroupPrefix(prefix) {
-    const result = [];
-    for (const group of this.groups.values()) {
-      if (group.name === prefix || group.name.startsWith(prefix + ":")) {
-        result.push(...group.commands);
-      }
-    }
-    return result;
+  getPluginGroupDescribe(segments) {
+    return this.pluginRouter.getGroupDescribe(segments);
   }
-  listProductGroups() {
-    const groups = /* @__PURE__ */ new Map();
-    for (const cmd of this.listManifests()) {
-      const groupName = cmd.manifest.group;
-      if (!groups.has(groupName)) {
-        groups.set(groupName, {
-          name: groupName,
-          describe: cmd.manifest.group,
-          commands: []
-        });
-      }
-      groups.get(groupName).commands.push(cmd);
-    }
-    return Array.from(groups.values());
+  listCommands() {
+    return this.pluginRouter.listAll();
   }
-  getCommandsByGroup(group) {
-    return this.listManifests().filter((cmd) => cmd.manifest.group === group).sort((a, b) => a.manifest.id.localeCompare(b.manifest.id));
+  listCommandsUnder(segments) {
+    return this.pluginRouter.listUnder(segments);
   }
-  getManifestCommand(idOrAlias) {
-    if (this.manifests.has(idOrAlias)) {
-      return this.manifests.get(idOrAlias);
-    }
-    const canonicalId = this.resolveToCanonical(idOrAlias);
-    if (canonicalId) {
-      return this.pluginByCanonical.get(canonicalId);
-    }
-    for (const cmd of this.pluginByCanonical.values()) {
-      if (cmd.manifest.aliases?.includes(idOrAlias)) {
-        return cmd;
-      }
-      if (cmd.manifest.id.replace(/:/g, " ") === idOrAlias) {
-        return cmd;
-      }
-    }
-    return void 0;
+  getCommandAt(segments) {
+    return this.pluginRouter.getAt(segments);
+  }
+  // ─── Partial loading state ─────────────────────────────────────────────────
+  markPartial(v) {
+    this.partial = v;
+  }
+  isPartial() {
+    return this.partial;
+  }
+  // ─── Diagnostics ──────────────────────────────────────────────────────────
+  getDiagnostics() {
+    return {
+      systemCommandCount: this.systemRouter.listAll().length,
+      systemGroupCount: 0,
+      pluginCommandCount: this.pluginRouter.listAll().length,
+      partialLoad: this.partial
+    };
   }
 };
-var registry = new InMemoryRegistry();
-function findCommand(nameOrPath) {
-  return registry.get(nameOrPath);
-}
-function findCommandWithType(nameOrPath) {
-  return registry.getWithType(nameOrPath);
+function createRegistry() {
+  return new TrieBackedRegistry();
 }
+var registry = new TrieBackedRegistry();
 
 // src/utils/generate-examples.ts
 function generateExamples(commandName, productName, cases) {
@@ -1663,7 +1745,7 @@ var health = defineSystemCommand({
     finishEvent: "HEALTH_FINISHED"
   },
   async handler(ctx, _argv, _flags) {
-    const cliApi = await createRegistry({
+    const cliApi = await createRegistry$1({
       cache: { ttlMs: 5e3 }
     });
     try {
@@ -1701,7 +1783,7 @@ var health = defineSystemCommand({
         status: result.healthStatus,
         error: result.error
       };
-      console.log(JSON.stringify(jsonOutput, null, 2));
+      ctx.ui?.json?.(jsonOutput);
     } else {
       if (result.error) {
         ctx.ui.error("System Health", {
@@ -1752,81 +1834,739 @@ var health = defineSystemCommand({
   }
 });
 init_discover();
-var diag = defineSystemCommand({
-  name: "diag",
-  description: "Comprehensive system diagnostics (plugins, cache, environment, versions)",
-  category: "info",
-  examples: generateExamples("diag", "kb", [
-    { flags: {} },
-    { flags: { json: true } }
-  ]),
-  flags: {
-    json: { type: "boolean", description: "Output in JSON format" }
-  },
-  analytics: {
-    command: "diag",
-    startEvent: "DIAG_STARTED",
-    finishEvent: "DIAG_FINISHED"
-  },
-  // eslint-disable-next-line sonarjs/cognitive-complexity -- Comprehensive diagnostic checks across multiple system components
-  async handler(ctx, _argv, _flags) {
-    const cwd = getContextCwd(ctx);
-    const diagnostics = [];
-    const nodeVersion = process.version;
-    const cliVersion = process.env.CLI_VERSION || process.env.CLI_VERSION || "0.1.0";
-    const platform11 = process.platform;
-    const arch = process.arch;
-    diagnostics.push({
-      category: "environment",
-      status: "ok",
-      message: `Node ${nodeVersion}, CLI ${cliVersion}, ${platform11}/${arch}`,
-      details: { nodeVersion, cliVersion, platform: platform11, arch }
-    });
-    try {
-      const platformRoot = process.env.KB_PLATFORM_ROOT;
-      const projectRoot = process.env.KB_PROJECT_ROOT;
-      const discovered = await discoverManifests(cwd, false, { platformRoot, projectRoot });
-      const manifests = registry.listManifests();
-      const enabled = manifests.filter((m) => m.available && !m.shadowed).length;
-      const disabled = manifests.filter((m) => !m.available).length;
-      const shadowed = manifests.filter((m) => m.shadowed).length;
-      diagnostics.push({
-        category: "marketplace",
-        status: disabled > 0 ? "warning" : "ok",
-        message: `Found ${discovered.length} packages, ${enabled} enabled, ${disabled} unavailable, ${shadowed} shadowed`,
-        details: {
-          packages: discovered.length,
-          enabled,
-          disabled,
-          shadowed,
-          totalCommands: manifests.length
-        }
-      });
-    } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err);
-      diagnostics.push({
-        category: "marketplace",
-        status: "error",
-        message: `Discovery failed: ${errMsg}`,
-        details: { error: errMsg }
-      });
+var req = createRequire(import.meta.url);
+var __filename$1 = fileURLToPath(import.meta.url);
+var __dirname$1 = path.dirname(__filename$1);
+function resolveFromCwd(spec, cwd) {
+  const cliRoot = path.resolve(__dirname$1, "../../..");
+  let monorepoRoot = cwd;
+  while (monorepoRoot !== path.dirname(monorepoRoot)) {
+    if (existsSync(path.join(monorepoRoot, "pnpm-workspace.yaml"))) {
+      break;
     }
-    try {
-      const cachePath = path.join(cwd, ".kb", "cache", "cli-manifests.json");
-      const cacheExists = await promises.access(cachePath).then(() => true).catch(() => false);
-      if (cacheExists) {
-        const cache = JSON.parse(await promises.readFile(cachePath, "utf8"));
-        const age = Date.now() - (cache.timestamp || 0);
-        const ageHours = Math.floor(age / (1e3 * 60 * 60));
-        diagnostics.push({
+    monorepoRoot = path.dirname(monorepoRoot);
+  }
+  const pathsToTry = [
+    cwd,
+    // Current working directory (user's project)
+    cliRoot,
+    // CLI installation directory
+    monorepoRoot,
+    // Monorepo root (if found)
+    path.join(monorepoRoot, "../kb-labs-cli"),
+    // Explicit kb-labs-cli path
+    path.join(monorepoRoot, "../kb-labs-mind")
+    // Explicit kb-labs-mind path
+  ].filter(Boolean);
+  for (const searchPath of pathsToTry) {
+    try {
+      return req.resolve(spec, { paths: [searchPath] });
+    } catch (_e) {
+    }
+  }
+  throw new Error(`Cannot resolve ${spec} from any of: ${pathsToTry.join(", ")}`);
+}
+function checkRequires(manifest, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  if (!manifest.requires || manifest.requires.length === 0) {
+    return { available: true };
+  }
+  let isInMonorepo = false;
+  let monorepoRoot = cwd;
+  while (monorepoRoot !== path.dirname(monorepoRoot)) {
+    if (existsSync(path.join(monorepoRoot, "pnpm-workspace.yaml"))) {
+      isInMonorepo = true;
+      break;
+    }
+    monorepoRoot = path.dirname(monorepoRoot);
+  }
+  for (const dep of manifest.requires) {
+    try {
+      const resolved = resolveFromCwd(dep, cwd);
+      if (!resolved.includes("node_modules")) {
+        continue;
+      }
+    } catch (err) {
+      if (isInMonorepo) {
+        continue;
+      }
+      const errorMessage = (err instanceof Error ? err.message : "") || "";
+      const hasExportsError = errorMessage.includes("exports") || errorMessage.includes("main");
+      if (hasExportsError || errorMessage.includes("Cannot resolve")) {
+        const parts = dep.startsWith("@") ? dep.slice(1).split("/") : [dep];
+        if (parts.length === 0) {
+          continue;
+        }
+        const scope = parts.length >= 2 ? parts[0] : "";
+        const packageName = parts.length >= 2 ? parts[1] : parts[0];
+        if (!packageName) {
+          continue;
+        }
+        const cliRoot = path.resolve(__dirname$1, "../../..");
+        const packagePath = scope ? path.join(cliRoot, "node_modules", "@" + scope, packageName, "package.json") : path.join(cliRoot, "node_modules", packageName, "package.json");
+        if (existsSync(packagePath)) {
+          continue;
+        }
+      }
+      const isKbLabsPackage = dep.startsWith("@kb-labs/");
+      const hint = isKbLabsPackage ? `Run: pnpm add ${dep}` : `Run: npm install ${dep}`;
+      return {
+        available: false,
+        reason: `Missing dependency: ${dep}`,
+        hint
+      };
+    }
+  }
+  return { available: true };
+}
+function validateManifestStructure(manifest) {
+  if (manifest.manifestVersion !== "1.0") {
+    throw new Error(
+      `Unsupported manifestVersion "${manifest.manifestVersion}" in ${manifest.segments?.join(" ") ?? manifest.id} (expected "1.0")`
+    );
+  }
+  if (!Array.isArray(manifest.segments) || manifest.segments.length === 0) {
+    throw new Error(`Missing or empty segments in manifest ${manifest.id}`);
+  }
+  if (!manifest.describe) {
+    throw new Error(`Missing describe in manifest ${manifest.segments.join(" ")}`);
+  }
+  if (!manifest.loader && !manifest.manifestV2) {
+    throw new Error(`Command ${manifest.segments.join(" ")} must have either loader or manifestV2`);
+  }
+  if (manifest.flags) {
+    for (const flag of manifest.flags) {
+      if (!flag.name || !flag.type) {
+        throw new Error(`Invalid flag in ${manifest.segments.join(" ")}: missing name or type`);
+      }
+      if (flag.alias && flag.alias.length !== 1) {
+        throw new Error(`Flag "${flag.name}" in ${manifest.segments.join(" ")}: alias must be a single character`);
+      }
+      if (flag.choices && flag.type !== "string") {
+        throw new Error(
+          `Flag "${flag.name}" in ${manifest.segments.join(" ")}: choices only allowed for string type`
+        );
+      }
+    }
+  }
+}
+var SOURCE_PRIORITY = {
+  builtin: 4,
+  workspace: 3,
+  linked: 2,
+  node_modules: 1
+};
+function getSourcePriority(source) {
+  return SOURCE_PRIORITY[source] ?? 0;
+}
+function preflightManifests(discoveryResults, logger) {
+  const log3 = logger ?? platform.logger;
+  const logLevel = getLogLevel();
+  const valid = [];
+  const skipped = [];
+  for (const result of discoveryResults) {
+    const allowed = [];
+    for (const manifest of result.manifests) {
+      try {
+        validateManifestStructure(manifest);
+        allowed.push(manifest);
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : "Validation failed";
+        const id = manifest?.segments?.join(" ") ?? manifest?.id ?? result.packageName ?? "unknown";
+        skipped.push({ id, source: result.source, reason });
+        log3.warn(`Preflight skipped manifest ${id}: ${reason}`);
+        if (logLevel === "debug") {
+          process.stderr.write(`[debug][preflight] skipped ${id} (${result.source}): ${reason}
+`);
+        }
+      }
+    }
+    if (allowed.length > 0) {
+      valid.push({ ...result, manifests: allowed });
+    }
+  }
+  return { valid, skipped };
+}
+async function registerManifests(discoveryResults, registry2, options = {}) {
+  const log3 = options.logger ?? platform.logger;
+  const registered = [];
+  const skipped = [];
+  const globalIds = /* @__PURE__ */ new Map();
+  const logLevel = getLogLevel();
+  let collisions = 0;
+  let errors = 0;
+  const sorted = [...discoveryResults].sort((a, b) => {
+    return getSourcePriority(b.source) - getSourcePriority(a.source);
+  });
+  for (const result of sorted) {
+    for (const manifest of result.manifests) {
+      const manifestId = manifest.segments?.join(" ") ?? manifest.id ?? "unknown";
+      try {
+        try {
+          validateManifestStructure(manifest);
+        } catch (err) {
+          throw new Error(`Validation failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const availability = checkRequires(manifest, {
+          cwd: options.cwd ?? result.pkgRoot
+        });
+        const cmd = {
+          manifest,
+          v3Manifest: manifest.manifestV2,
+          available: availability.available,
+          unavailableReason: availability.available ? void 0 : availability.reason,
+          hint: availability.available ? void 0 : availability.hint,
+          source: result.source,
+          shadowed: false,
+          pkgRoot: result.pkgRoot,
+          packageName: result.packageName
+        };
+        try {
+          const manifestModule = await import(result.manifestPath);
+          if (typeof manifestModule.init === "function") {
+            await manifestModule.init({
+              cwd: result.pkgRoot,
+              package: result.packageName,
+              manifest: cmd.manifest
+            });
+          }
+          if (typeof manifestModule.register === "function") {
+            await manifestModule.register({
+              registry: registry2,
+              command: cmd,
+              cwd: result.pkgRoot,
+              package: result.packageName
+            });
+          }
+          if (typeof manifestModule.dispose === "function") {
+            cmd._disposeHook = manifestModule.dispose;
+          }
+        } catch (hookError) {
+          const hookMsg = hookError instanceof Error ? hookError.message : String(hookError);
+          log3.debug(`Lifecycle hooks unavailable for ${manifestId}: ${hookMsg}`);
+        }
+        const canonicalKey = manifest.segments.join(":");
+        const existing = globalIds.get(canonicalKey);
+        if (existing) {
+          if (existing.source === result.source && existing.source === "workspace") {
+            collisions++;
+            throw new Error(
+              `Command path collision: "${manifestId}" exported by multiple workspace packages.`
+            );
+          }
+          const existPri = getSourcePriority(existing.source);
+          const curPri = getSourcePriority(result.source);
+          if (curPri > existPri) {
+            existing.shadowed = true;
+            globalIds.set(canonicalKey, cmd);
+            if (logLevel === "info" || logLevel === "debug") {
+              log3.info(`${canonicalKey} from ${result.source} shadows ${existing.source} version`);
+            }
+          } else {
+            cmd.shadowed = true;
+            if (logLevel === "info" || logLevel === "debug") {
+              log3.info(`${canonicalKey} from ${result.source} shadowed by ${existing.source} version`);
+            }
+          }
+        } else {
+          globalIds.set(canonicalKey, cmd);
+        }
+        if (!cmd.shadowed) {
+          registry2.registerManifest(cmd);
+          registered.push(cmd);
+        }
+      } catch (error) {
+        errors++;
+        const reason = error instanceof Error ? error.message : String(error);
+        skipped.push({ id: manifestId, source: result.source, reason });
+        log3.error(`Skipped manifest ${manifestId} (${result.source}): ${reason}`);
+      }
+    }
+  }
+  if (skipped.length > 0) {
+    log3.warn(`Skipped ${skipped.length} manifest(s) during registration`);
+    for (const skip of skipped) {
+      log3.warn(`  \u2022 ${skip.id} [${skip.source}] \u2192 ${skip.reason}`);
+    }
+  }
+  return { registered, skipped, collisions, errors };
+}
+async function disposeAllPlugins(registry2, logger) {
+  const log3 = logger ?? platform.logger;
+  const manifests = registry2.listCommands();
+  const disposePromises = [];
+  for (const cmd of manifests) {
+    const disposeHook = cmd._disposeHook;
+    if (typeof disposeHook === "function") {
+      disposePromises.push(
+        Promise.resolve(disposeHook()).catch((err) => {
+          log3.warn(`Dispose hook failed for ${cmd.manifest.segments.join(" ")}: ${err instanceof Error ? err.message : String(err)}`);
+        })
+      );
+    }
+  }
+  await Promise.allSettled(disposePromises);
+}
+
+// src/commands/system/diag.ts
+init_schema();
+function stageToChainItem(stage) {
+  const statusMap = {
+    ok: "success",
+    error: "error",
+    warning: "warning",
+    info: "info"
+  };
+  const sections = [
+    { items: [stage.message] },
+    ...stage.remediation ? [{ header: "Fix", items: [stage.remediation] }] : []
+  ];
+  return {
+    title: stage.stage,
+    status: statusMap[stage.status],
+    summary: { code: stage.code },
+    sections
+  };
+}
+async function tryLoadManifestForTrace(manifestPath, pkgName) {
+  try {
+    const mod = await import(pathToFileURL(manifestPath).href);
+    const raw = mod.manifest ?? mod.default;
+    if (!raw || typeof raw !== "object") {
+      return {
+        code: "NO_EXPORT",
+        message: "No manifest export \u2014 add: export { manifest } or export default manifest"
+      };
+    }
+    const schema = raw.schema;
+    if (schema !== "kb.plugin/3") {
+      return {
+        code: "WRONG_SCHEMA",
+        foundSchema: String(schema ?? "undefined"),
+        message: `schema must be "kb.plugin/3", found "${String(schema ?? "undefined")}"`
+      };
+    }
+    const cliCmds = raw.cli?.commands ?? [];
+    if (!Array.isArray(cliCmds) || cliCmds.length === 0) {
+      return {
+        code: "VALIDATION_FAILED",
+        message: "cli.commands is empty \u2014 no commands to register",
+        validationErrors: [{ field: "cli.commands", message: "Must contain at least one command" }]
+      };
+    }
+    const mapped = cliCmds.map((cmd) => {
+      const segments = (cmd.path ?? "").trim().split(/\s+/).filter(Boolean);
+      return {
+        manifestVersion: "1.0",
+        segments,
+        id: segments[segments.length - 1] ?? "unknown",
+        group: segments[0] ?? "unknown",
+        describe: cmd.describe ?? "",
+        loader: async () => {
+          throw new Error("trace-only");
+        },
+        flags: cmd.flags,
+        aliases: cmd.aliases,
+        operationType: cmd.operationType,
+        package: pkgName
+      };
+    });
+    const result = validateManifests(mapped);
+    if (!result.success) {
+      const errors = result.errors.flatMap(
+        (e) => e.issues.map((i) => ({ field: i.path.join(".") || "(root)", message: i.message }))
+      );
+      return {
+        code: "VALIDATION_FAILED",
+        message: `${errors.length} validation error(s)`,
+        validationErrors: errors
+      };
+    }
+    return null;
+  } catch (err) {
+    return {
+      code: "LOAD_ERROR",
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function matchesTopSegment(result, topSegment) {
+  if (result.manifests.some((m) => m.group === topSegment)) {
+    return true;
+  }
+  const last = result.packageName.split("/").pop() ?? "";
+  return last.replace(/-entry$|-cli$/, "") === topSegment;
+}
+function findLockEntry(installed, topSegment) {
+  return Object.entries(installed).find(([key]) => {
+    const last = key.split("/").pop() ?? "";
+    return last.replace(/-entry$|-cli$/, "") === topSegment || last === topSegment;
+  });
+}
+async function runContextStage(ctx) {
+  return {
+    stage: "context",
+    status: "info",
+    code: "CONTEXT",
+    message: `cwd=${ctx.cwd}  KB_PLATFORM_ROOT=${ctx.platformRoot ?? "(not set)"}  KB_PROJECT_ROOT=${ctx.projectRoot ?? "(not set)"}`,
+    details: {
+      cwd: ctx.cwd,
+      platformRoot: ctx.platformRoot ?? null,
+      projectRoot: ctx.projectRoot ?? null,
+      execPath: process.execPath
+    }
+  };
+}
+async function runRegistryStage(ctx) {
+  const result = registry.resolve(ctx.segments);
+  if (result.type === "command") {
+    const cmd = result.command;
+    if (cmd.shadowed) {
+      const owner = registry.listCommands().find((c) => c.manifest.segments[0] === ctx.segments[0] && !c.shadowed)?.packageName;
+      return {
+        stage: "registry",
+        status: "warning",
+        code: "SHADOWED_BY",
+        message: `Command found but shadowed by ${owner ?? "another package"}`,
+        details: { ownerPackage: owner ?? null, shadowedPackage: cmd.packageName ?? null }
+      };
+    }
+    if (!cmd.available) {
+      return {
+        stage: "registry",
+        status: "error",
+        code: "REQUIRES_MISSING",
+        message: cmd.unavailableReason ?? "Command unavailable",
+        remediation: cmd.hint,
+        details: { package: cmd.packageName ?? null, source: cmd.source }
+      };
+    }
+    return {
+      stage: "registry",
+      status: "ok",
+      code: "REGISTRY_OK",
+      message: `Command registered and available`,
+      details: { package: cmd.packageName ?? null, source: cmd.source },
+      enrich: { registryOk: true }
+    };
+  }
+  if (result.type === "group") {
+    return {
+      stage: "registry",
+      status: "warning",
+      code: "GROUP_EXISTS_LEAF_MISSING",
+      message: `Group "${ctx.segments[0]}" exists but leaf "${ctx.segments.slice(1).join(" ")}" not found`,
+      details: { availableChildren: result.childKeys }
+    };
+  }
+  const shadowedMatch = registry.listCommands().find((c) => c.manifest.segments.join(" ") === ctx.segments.join(" ") && c.shadowed);
+  if (shadowedMatch) {
+    const owner = registry.listCommands().find((c) => c.manifest.segments[0] === ctx.segments[0] && !c.shadowed)?.packageName;
+    return {
+      stage: "registry",
+      status: "warning",
+      code: "SHADOWED_BY",
+      message: `Command is shadowed by ${owner ?? "another package"}`,
+      details: { ownerPackage: owner ?? null, shadowedPackage: shadowedMatch.packageName ?? null }
+    };
+  }
+  return {
+    stage: "registry",
+    status: "info",
+    code: "REGISTRY_NOT_FOUND",
+    message: "Command not in registry"
+  };
+}
+async function runDiscoveryStage(ctx) {
+  resetInProcCache();
+  const opts = { platformRoot: ctx.platformRoot, projectRoot: ctx.projectRoot };
+  const discovered = await discoverManifests(ctx.cwd, true, opts);
+  const [topSegment] = ctx.segments;
+  const result = discovered.find((r) => matchesTopSegment(r, topSegment ?? ""));
+  if (!result) {
+    const { block: blocklist = [] } = await loadConfig(ctx.cwd);
+    const blocked = blocklist.some((b) => b === topSegment || b.includes(`/${topSegment ?? ""}`));
+    if (blocked) {
+      return {
+        stage: "discovery",
+        status: "error",
+        code: "PLUGIN_BLOCKLISTED",
+        message: `Plugin "${topSegment}" is in plugins.block in .kb/kb.config.json`,
+        remediation: "Remove it from plugins.block in .kb/kb.config.json"
+      };
+    }
+    return {
+      stage: "discovery",
+      status: "info",
+      code: "NOT_IN_DISCOVERY",
+      message: `No package found for group "${topSegment}" in workspace or node_modules`
+    };
+  }
+  if (result.manifests.every((m) => m._synthetic)) {
+    const distPath = path.join(result.pkgRoot, "dist");
+    const distExists = await access(distPath).then(() => true).catch(() => false);
+    const loadErr = await tryLoadManifestForTrace(result.manifestPath, result.packageName);
+    const stageCode = loadErr?.code === "WRONG_SCHEMA" ? "WRONG_SCHEMA" : loadErr?.code === "VALIDATION_FAILED" ? "MANIFEST_VALIDATION_FAILED" : "MANIFEST_LOAD_FAILED";
+    return {
+      stage: "discovery",
+      status: "error",
+      code: stageCode,
+      message: loadErr ? loadErr.message : "Manifest failed to load (timeout or import error)",
+      remediation: !distExists ? `pnpm --filter ${result.packageName} build` : "Fix the error in your manifest.ts",
+      details: {
+        manifestPath: result.manifestPath,
+        distExists,
+        error: loadErr?.message ?? null,
+        foundSchema: loadErr?.foundSchema ?? null,
+        validationErrors: loadErr?.validationErrors ?? null
+      },
+      enrich: { discoveryResult: result }
+    };
+  }
+  const { skipped } = preflightManifests([result]);
+  if (skipped.length > 0) {
+    return {
+      stage: "discovery",
+      status: "error",
+      code: "MANIFEST_STRUCT_INVALID",
+      message: `Manifest loaded but ${skipped.length} command(s) failed structural validation`,
+      remediation: "Fix the errors in your manifest.ts",
+      details: {
+        failures: skipped.map((s) => ({ command: s.id, reason: s.reason }))
+      }
+    };
+  }
+  const commandPath = ctx.segments.join(" ");
+  const found = result.manifests.filter((m) => !m._synthetic).find((m) => m.segments.join(" ") === commandPath);
+  if (!found) {
+    const availablePaths = result.manifests.filter((m) => !m._synthetic).map((m) => m.segments.join(" ")).sort();
+    return {
+      stage: "discovery",
+      status: "warning",
+      code: "COMMAND_PATH_MISSING",
+      message: `Package found but command path "${commandPath}" is not defined in manifest`,
+      remediation: `Check command path in manifest.ts. Available (${availablePaths.length}): ${availablePaths.slice(0, 5).join(", ")}${availablePaths.length > 5 ? ` \u2026 and ${availablePaths.length - 5} more` : ""}`,
+      details: { availablePaths, packageName: result.packageName }
+    };
+  }
+  return {
+    stage: "discovery",
+    status: "ok",
+    code: "MANIFEST_OK",
+    message: `Manifest loaded and command "${commandPath}" is defined`,
+    details: { manifestPath: result.manifestPath, packageName: result.packageName },
+    enrich: { discoveryResult: result }
+  };
+}
+async function runLockStage(ctx) {
+  const collector = new DiagnosticCollector();
+  const lock = await readMarketplaceLock(ctx.cwd, collector);
+  if (!lock) {
+    const status = ctx.registryOk ? "info" : "warning";
+    return {
+      stage: "lock",
+      status,
+      code: "NO_LOCK",
+      message: ctx.registryOk ? "No marketplace.lock \u2014 plugin is available from workspace (normal in dev mode)" : "No marketplace.lock found \u2014 plugin may not be installed"
+    };
+  }
+  const [topSegment] = ctx.segments;
+  const entry = findLockEntry(lock.installed, topSegment ?? "");
+  if (!entry) {
+    if (ctx.registryOk) {
+      return {
+        stage: "lock",
+        status: "info",
+        code: "NOT_IN_MARKETPLACE",
+        message: `"${topSegment}" is not installed via marketplace \u2014 it runs from the workspace (normal in dev mode)`
+      };
+    }
+    return {
+      stage: "lock",
+      status: "warning",
+      code: "NOT_IN_LOCK",
+      message: `"${topSegment}" not found in marketplace.lock`,
+      remediation: `kb marketplace install ${topSegment}`
+    };
+  }
+  const [key, data] = entry;
+  if (data.enabled === false) {
+    return {
+      stage: "lock",
+      status: "error",
+      code: "PLUGIN_DISABLED",
+      message: `Package "${key}" is installed but disabled`,
+      remediation: `kb marketplace plugins enable ${key}`,
+      details: { key, version: data.version }
+    };
+  }
+  return {
+    stage: "lock",
+    status: "ok",
+    code: "PLUGIN_ENABLED",
+    message: `"${key}" is installed and enabled`,
+    details: { key, version: data.version, resolvedPath: data.resolvedPath },
+    enrich: { lockEntry: entry }
+  };
+}
+async function runFilesystemStage(ctx) {
+  if (!ctx.lockEntry) {
+    return {
+      stage: "filesystem",
+      status: "info",
+      code: "FS_SKIP",
+      message: "Skipped \u2014 no lock entry to verify"
+    };
+  }
+  const [, data] = ctx.lockEntry;
+  if (!data.resolvedPath) {
+    return {
+      stage: "filesystem",
+      status: "info",
+      code: "FS_NO_PATH",
+      message: "Lock entry has no resolvedPath to check"
+    };
+  }
+  try {
+    await access(data.resolvedPath);
+    return {
+      stage: "filesystem",
+      status: "ok",
+      code: "PATH_EXISTS",
+      message: `Package path exists at ${data.resolvedPath}`
+    };
+  } catch {
+    return {
+      stage: "filesystem",
+      status: "error",
+      code: "PATH_MISSING",
+      message: `Package path does not exist: ${data.resolvedPath}`,
+      remediation: "pnpm install",
+      details: { resolvedPath: data.resolvedPath }
+    };
+  }
+}
+var STAGE_RUNNERS = [
+  runContextStage,
+  runRegistryStage,
+  runDiscoveryStage,
+  runLockStage,
+  runFilesystemStage
+];
+async function runTrace(ctx) {
+  const stages = [];
+  for (const run of STAGE_RUNNERS) {
+    const { enrich, ...stage } = await run(ctx);
+    stages.push(stage);
+    if (enrich) {
+      Object.assign(ctx, enrich);
+    }
+  }
+  const failing = stages.find((s) => s.status === "error") ?? stages.find((s) => s.status === "warning");
+  return {
+    ok: !stages.some((s) => s.status === "error" || s.status === "warning"),
+    command: ctx.segments.join(" "),
+    stages,
+    verdict: failing ? { rootCause: failing.code, remediation: failing.remediation } : { rootCause: "NONE" }
+  };
+}
+var diag = defineSystemCommand({
+  name: "diag",
+  description: "Comprehensive system diagnostics (plugins, cache, environment, versions)",
+  category: "info",
+  examples: generateExamples("diag", "kb", [
+    { flags: {} },
+    { flags: { json: true } },
+    { flags: { command: "workflow run" } }
+  ]),
+  flags: {
+    json: { type: "boolean", description: "Output in JSON format" },
+    command: { type: "string", description: 'Trace a specific command through the discovery pipeline (e.g. "workflow run")' }
+  },
+  analytics: {
+    command: "diag",
+    startEvent: "DIAG_STARTED",
+    finishEvent: "DIAG_FINISHED"
+  },
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  async handler(ctx, _argv, flags) {
+    const cwd = getContextCwd(ctx);
+    const platformRoot = process.env.KB_PLATFORM_ROOT;
+    const projectRoot = process.env.KB_PROJECT_ROOT;
+    if (flags.command) {
+      const segments = flags.command.trim().split(/\s+/).filter(Boolean);
+      const traceCtx = { cwd, segments, platformRoot, projectRoot };
+      return runTrace(traceCtx);
+    }
+    const diagnostics = [];
+    diagnostics.push({
+      category: "environment",
+      status: "ok",
+      message: `Node ${process.version}, CLI ${process.env.CLI_VERSION ?? "0.1.0"}, ${process.platform}/${process.arch}`,
+      details: {
+        nodeVersion: process.version,
+        cliVersion: process.env.CLI_VERSION ?? "0.1.0",
+        platform: process.platform,
+        arch: process.arch
+      }
+    });
+    let discovered = [];
+    try {
+      discovered = await discoverManifests(cwd, false, { platformRoot, projectRoot });
+      const allCommands = registry.listCommands();
+      const enabled = allCommands.filter((m) => m.available && !m.shadowed).length;
+      const disabled = allCommands.filter((m) => !m.available && !m.shadowed).length;
+      const shadowed = allCommands.filter((m) => m.shadowed).length;
+      diagnostics.push({
+        category: "marketplace",
+        status: disabled > 0 ? "warning" : "ok",
+        message: `Found ${discovered.length} packages, ${enabled} enabled, ${disabled} unavailable, ${shadowed} shadowed`,
+        details: { packages: discovered.length, enabled, disabled, shadowed, totalCommands: allCommands.length }
+      });
+      for (const cmd of allCommands.filter((m) => !m.available && !m.shadowed)) {
+        diagnostics.push({
+          category: "unavailable-command",
+          status: "warning",
+          message: `${cmd.manifest.segments.join(" ")}: ${cmd.unavailableReason ?? "unavailable"}`,
+          code: "REQUIRES_MISSING",
+          remediation: cmd.hint,
+          details: { source: cmd.source, package: cmd.packageName ?? null }
+        });
+      }
+      for (const result of discovered) {
+        for (const manifest of result.manifests) {
+          if (manifest._synthetic) {
+            diagnostics.push({
+              category: "manifest-load-failure",
+              status: "error",
+              message: `${result.packageName}: manifest failed to load`,
+              code: "MANIFEST_LOAD_FAILED",
+              remediation: `pnpm --filter ${result.packageName} build`,
+              details: { source: result.source, manifestPath: result.manifestPath }
+            });
+          }
+        }
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      diagnostics.push({
+        category: "marketplace",
+        status: "error",
+        message: `Discovery failed: ${errMsg}`,
+        details: { error: errMsg }
+      });
+    }
+    try {
+      const cachePath = path.join(cwd, ".kb", "cache", "cli-manifests.json");
+      const cacheExists = await access(cachePath).then(() => true).catch(() => false);
+      if (cacheExists) {
+        const cache = JSON.parse(await readFile(cachePath, "utf8"));
+        const ageHours = Math.floor((Date.now() - (cache.timestamp ?? 0)) / (1e3 * 60 * 60));
+        diagnostics.push({
           category: "cache",
           status: "ok",
-          message: `Cache exists, ${ageHours}h old, ${Object.keys(cache.packages || {}).length} packages cached`,
-          details: {
-            exists: true,
-            ageHours,
-            packages: Object.keys(cache.packages || {}).length
-          }
+          message: `Cache exists, ${ageHours}h old, ${Object.keys(cache.packages ?? {}).length} packages cached`,
+          details: { exists: true, ageHours, packages: Object.keys(cache.packages ?? {}).length }
         });
       } else {
         diagnostics.push({
@@ -1846,7 +2586,20 @@ var diag = defineSystemCommand({
       });
     }
     try {
-      const lock = await readMarketplaceLock(cwd, new DiagnosticCollector());
+      const collector = new DiagnosticCollector();
+      const lock = await readMarketplaceLock(cwd, collector);
+      for (const event of collector.getEvents()) {
+        if (event.severity === "error" || event.severity === "warning") {
+          diagnostics.push({
+            category: "lock-event",
+            status: event.severity === "error" ? "error" : "warning",
+            message: event.message,
+            code: event.code,
+            remediation: event.remediation,
+            details: event.context
+          });
+        }
+      }
       if (lock) {
         const entries = Object.entries(lock.installed);
         const enabledCount = entries.filter(([, e]) => e.enabled !== false).length;
@@ -1873,42 +2626,25 @@ var diag = defineSystemCommand({
         details: { error: errMsg }
       });
     }
-    const versionIssues = [];
     try {
-      const manifests = registry.listManifests();
-      for (const cmd of manifests) {
+      const cliVersion = process.env.CLI_VERSION ?? "0.1.0";
+      const versionIssues = [];
+      for (const cmd of registry.listCommands()) {
         const required = cmd.manifest.engine?.kbCli;
         if (required) {
-          const requiredParts = required.replace("^", "").split(".");
-          const currentParts = cliVersion.split(".");
-          if (requiredParts[0] && currentParts[0]) {
-            const requiredMajor = parseInt(requiredParts[0], 10);
-            const currentMajor = parseInt(currentParts[0], 10);
-            if (!isNaN(requiredMajor) && !isNaN(currentMajor) && currentMajor < requiredMajor) {
-              versionIssues.push({
-                plugin: cmd.manifest.package || cmd.manifest.group,
-                required,
-                current: cliVersion
-              });
-            }
+          const requiredMajor = parseInt(required.replace("^", "").split(".")[0] ?? "0", 10);
+          const currentMajor = parseInt(cliVersion.split(".")[0] ?? "0", 10);
+          if (!isNaN(requiredMajor) && !isNaN(currentMajor) && currentMajor < requiredMajor) {
+            versionIssues.push({ plugin: cmd.manifest.package ?? cmd.manifest.group, required, current: cliVersion });
           }
         }
       }
-      if (versionIssues.length > 0) {
-        diagnostics.push({
-          category: "versions",
-          status: "warning",
-          message: `${versionIssues.length} plugin(s) require newer CLI version`,
-          details: { issues: versionIssues }
-        });
-      } else {
-        diagnostics.push({
-          category: "versions",
-          status: "ok",
-          message: "All plugins compatible with current CLI version",
-          details: { issues: [] }
-        });
-      }
+      diagnostics.push({
+        category: "versions",
+        status: versionIssues.length > 0 ? "warning" : "ok",
+        message: versionIssues.length > 0 ? `${versionIssues.length} plugin(s) require newer CLI version` : "All plugins compatible with current CLI version",
+        details: { issues: versionIssues }
+      });
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
       diagnostics.push({
@@ -1925,68 +2661,75 @@ var diag = defineSystemCommand({
       errors: diagnostics.filter((d) => d.status === "error").length
     };
     ctx.platform?.logger?.info("Diag command completed", summary);
-    return {
-      ok: summary.errors === 0,
-      diagnostics,
-      summary
-    };
+    return { ok: summary.errors === 0, diagnostics, summary };
   },
-  // eslint-disable-next-line sonarjs/cognitive-complexity -- Complex formatting logic for diagnostic output with multiple display modes
+  // eslint-disable-next-line sonarjs/cognitive-complexity
   formatter(result, ctx, flags) {
     if (flags.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      const hasErrors = result.summary.errors > 0;
-      const hasWarnings = result.summary.warnings > 0;
-      const summaryItems = [
-        `${safeColors.bold("Total Checks")}: ${result.summary.total}`,
-        `${safeColors.success("OK")}: ${result.summary.ok}`,
-        `${safeColors.warning("Warnings")}: ${result.summary.warnings}`,
-        `${safeColors.error("Errors")}: ${result.summary.errors}`
-      ];
-      const diagItems = [];
-      for (const diag2 of result.diagnostics) {
-        const icon = diag2.status === "ok" ? safeSymbols.success : diag2.status === "warning" ? safeSymbols.warning : safeSymbols.error;
-        const colorize = diag2.status === "ok" ? safeColors.success : diag2.status === "warning" ? safeColors.warning : safeColors.error;
-        diagItems.push(`${icon} ${colorize(safeColors.bold(diag2.category))}: ${diag2.message}`);
-        if (diag2.status === "warning" && Array.isArray(diag2.details?.issues)) {
-          for (const issue of diag2.details.issues) {
-            diagItems.push(
-              `   ${safeColors.warning(`\u2192 ${issue.plugin}: requires ${issue.required}, found ${issue.current}`)}`
-            );
-          }
+      ctx.ui?.json?.(result);
+      return;
+    }
+    if ("stages" in result) {
+      const trace = result;
+      const verdictStatus = trace.ok ? "success" : "error";
+      const verdictMsg = trace.ok ? "Command is fully operational" : `Root cause: ${trace.verdict.rootCause}`;
+      ctx.ui.chain([
+        ...trace.stages.map(stageToChainItem),
+        {
+          title: "verdict",
+          status: verdictStatus,
+          summary: { rootCause: trace.verdict.rootCause },
+          sections: [
+            { items: [verdictMsg] },
+            ...trace.verdict.remediation ? [{ header: "Fix", items: [trace.verdict.remediation] }] : []
+          ]
         }
+      ]);
+      return;
+    }
+    const base = result;
+    const hasErrors = base.summary.errors > 0;
+    const hasWarnings = base.summary.warnings > 0;
+    const summaryItems = [
+      `${safeColors.bold("Total Checks")}: ${base.summary.total}`,
+      `${safeColors.success("OK")}: ${base.summary.ok}`,
+      `${safeColors.warning("Warnings")}: ${base.summary.warnings}`,
+      `${safeColors.error("Errors")}: ${base.summary.errors}`
+    ];
+    const diagItems = [];
+    for (const diag2 of base.diagnostics) {
+      const icon = diag2.status === "ok" ? safeSymbols.success : diag2.status === "warning" ? safeSymbols.warning : safeSymbols.error;
+      const colorize = diag2.status === "ok" ? safeColors.success : diag2.status === "warning" ? safeColors.warning : safeColors.error;
+      diagItems.push(`${icon} ${colorize(safeColors.bold(diag2.category))}: ${diag2.message}`);
+      if (diag2.remediation) {
+        diagItems.push(`   ${safeColors.muted(`\u2192 Fix: ${diag2.remediation}`)}`);
       }
-      const nextSteps = [];
-      if (hasErrors) {
-        nextSteps.push(`kb marketplace doctor  ${safeColors.muted("Diagnose plugin issues")}`);
-      }
-      if (hasWarnings) {
-        nextSteps.push(`kb marketplace list  ${safeColors.muted("List all plugins")}`);
-      }
-      nextSteps.push(`kb diagnose  ${safeColors.muted("Quick environment check")}`);
-      const sections = [
-        {
-          header: "Summary",
-          items: summaryItems
-        },
-        {
-          header: "Details",
-          items: diagItems
-        },
-        {
-          header: "Next Steps",
-          items: nextSteps
+      if (diag2.status === "warning" && Array.isArray(diag2.details?.issues)) {
+        for (const issue of diag2.details.issues) {
+          diagItems.push(`   ${safeColors.warning(`\u2192 ${issue.plugin}: requires ${issue.required}, found ${issue.current}`)}`);
         }
-      ];
-      if (hasErrors) {
-        ctx.ui.error("System Diagnostics", { sections });
-      } else if (hasWarnings) {
-        ctx.ui.warn("System Diagnostics", { sections });
-      } else {
-        ctx.ui.success("System Diagnostics", { sections });
       }
     }
+    const nextSteps = [];
+    if (hasErrors) {
+      nextSteps.push(`kb marketplace doctor  ${safeColors.muted("Diagnose plugin issues")}`);
+    }
+    if (hasWarnings) {
+      nextSteps.push(`kb marketplace list  ${safeColors.muted("List all plugins")}`);
+    }
+    nextSteps.push(`kb diag --command <name>  ${safeColors.muted("Trace a specific command")}`);
+    const sections = [
+      { header: "Summary", items: summaryItems },
+      { header: "Details", items: diagItems },
+      { header: "Next Steps", items: nextSteps }
+    ];
+    if (hasErrors) {
+      ctx.ui.error("System Diagnostics", { sections });
+    } else if (hasWarnings) {
+      ctx.ui.warn("System Diagnostics", { sections });
+    } else {
+      ctx.ui.success("System Diagnostics", { sections });
+    }
   }
 });
 var registryDiagnostics = defineSystemCommand({
@@ -2005,7 +2748,7 @@ var registryDiagnostics = defineSystemCommand({
   },
   async handler(ctx, _argv, flags) {
     const cwd = getContextCwd(ctx);
-    const registry2 = await createRegistry({ root: cwd });
+    const registry2 = await createRegistry$1({ root: cwd });
     if (flags.refresh) {
       await registry2.refresh();
     }
@@ -2029,128 +2772,6 @@ var registryDiagnostics = defineSystemCommand({
     }
   }
 });
-
-// src/registry/plugins-state.ts
-init_discover();
-async function clearCache(cwd, options) {
-  const cleared = [];
-  const cacheDir = path.join(cwd, ".kb", "cache");
-  try {
-    const entries = await promises.readdir(cacheDir);
-    for (const entry of entries) {
-      if (entry.includes("manifest") || entry.includes("plugin")) {
-        const entryPath = path.join(cacheDir, entry);
-        await promises.unlink(entryPath);
-        cleared.push(entry);
-      }
-    }
-  } catch {
-  }
-  const manifestsCachePath = path.join(cwd, ".kb", "marketplace.manifests.json");
-  try {
-    await promises.unlink(manifestsCachePath);
-    cleared.push("marketplace.manifests.json");
-  } catch {
-  }
-  const cliManifestsPath = path.join(cwd, ".kb", "cache", "cli-manifests.json");
-  try {
-    await promises.unlink(cliManifestsPath);
-    if (!cleared.includes("cli-manifests.json")) {
-      cleared.push("cli-manifests.json");
-    }
-  } catch {
-  }
-  resetInProcCache();
-  const modulesCleared = [];
-  if (options?.deep) {
-    try {
-      const cache = __require.cache;
-      for (const key in cache) {
-        if (key.includes("plugin") || key.includes("manifest") || key.includes("@kb-labs")) {
-          delete cache[key];
-          modulesCleared.push(key);
-        }
-      }
-    } catch {
-    }
-  }
-  return {
-    files: cleared,
-    ...options?.deep ? { modules: modulesCleared } : {}
-  };
-}
-var pluginsCacheClear = defineSystemCommand({
-  name: "clear-cache",
-  description: "Clear CLI plugin discovery cache",
-  category: "marketplace",
-  examples: ["kb marketplace clear-cache", "kb marketplace clear-cache --deep"],
-  flags: {
-    deep: { type: "boolean", description: "Also clear Node.js module cache" },
-    json: { type: "boolean", description: "Output in JSON format" }
-  },
-  analytics: {
-    command: "marketplace:clear-cache",
-    startEvent: "MARKETPLACE_CACHE_CLEAR_STARTED",
-    finishEvent: "MARKETPLACE_CACHE_CLEAR_FINISHED"
-  },
-  async handler(ctx, _argv, flags) {
-    const deep = flags.deep;
-    const cwd = getContextCwd(ctx);
-    const result = await clearCache(cwd, { deep });
-    ctx.platform?.logger?.info("Cache cleared", {
-      filesCount: result.files.length,
-      modulesCount: result.modules?.length || 0,
-      deep
-    });
-    if (flags.json) {
-      const jsonResult = {
-        ok: true,
-        action: "cache:clear",
-        files: result.files,
-        modules: result.modules,
-        count: result.files.length,
-        modulesCount: result.modules?.length || 0
-      };
-      console.log(JSON.stringify(jsonResult, null, 2));
-      return jsonResult;
-    }
-    const files = result.files ?? [];
-    const modules = result.modules ?? [];
-    const sections = [];
-    if (files.length > 0) {
-      sections.push({
-        header: "Cache Files",
-        items: files.map((f) => `\u2713 ${f}`)
-      });
-    } else {
-      sections.push({
-        items: ["No cache files found"]
-      });
-    }
-    if (deep && modules.length > 0) {
-      sections.push({
-        header: "Node Modules",
-        items: [`Cleared ${modules.length} module(s) from cache`]
-      });
-    }
-    sections.push({
-      header: "Summary",
-      items: [`Removed ${files.length} file(s)${deep ? ` and ${modules.length} module(s)` : ""}`]
-    });
-    ctx.ui.success("", {
-      title: "\u{1F5D1}\uFE0F  Cache Management",
-      sections
-    });
-    return {
-      ok: true,
-      action: "cache:clear",
-      files: result.files,
-      modules: result.modules,
-      count: result.files.length,
-      modulesCount: result.modules?.length || 0
-    };
-  }
-});
 var docsGenerateCliReference = defineSystemCommand({
   name: "generate-cli-reference",
   description: "Generate CLI reference documentation from command registry",
@@ -2172,21 +2793,20 @@ var docsGenerateCliReference = defineSystemCommand({
   async handler(ctx, argv, flags) {
     const cwd = getContextCwd(ctx);
     const outputPath = flags.output || path.join(cwd, "CLI-REFERENCE.md");
-    const commands = registry.list();
-    const productGroups = registry.listProductGroups();
+    const registeredCommands2 = registry.listCommands();
     ctx.platform?.logger?.info("Generating CLI reference", {
-      commands: commands.length,
-      products: productGroups.length,
+      commands: registeredCommands2.length,
       output: outputPath
     });
     const groups = /* @__PURE__ */ new Map();
-    for (const cmd of commands) {
-      const group = cmd.category || "other";
+    for (const cmd of registeredCommands2) {
+      const group = cmd.manifest.group || "other";
       if (!groups.has(group)) {
         groups.set(group, []);
       }
       groups.get(group).push(cmd);
     }
+    const commands = registeredCommands2;
     const lines = [];
     lines.push("# KB Labs CLI Reference\n");
     lines.push(`Generated: ${(/* @__PURE__ */ new Date()).toISOString()}
@@ -2202,21 +2822,24 @@ var docsGenerateCliReference = defineSystemCommand({
     }
     lines.push("\n---\n");
     for (const groupName of sortedGroups) {
-      const cmds = groups.get(groupName).sort((a, b) => a.name.localeCompare(b.name));
+      const cmds = groups.get(groupName).sort(
+        (a, b) => a.manifest.segments.join(" ").localeCompare(b.manifest.segments.join(" "))
+      );
       lines.push(`## ${groupName}
 `);
       for (const cmd of cmds) {
-        lines.push(`### \`kb ${cmd.name}\`
+        const displayPath = cmd.manifest.segments.join(" ");
+        lines.push(`### \`kb ${displayPath}\`
 `);
-        lines.push(`${cmd.describe || "No description"}
+        lines.push(`${cmd.manifest.describe || "No description"}
 `);
-        if (cmd.longDescription) {
-          lines.push(`${cmd.longDescription}
+        if (cmd.manifest.longDescription) {
+          lines.push(`${cmd.manifest.longDescription}
 `);
         }
-        if (cmd.flags && cmd.flags.length > 0) {
+        if (cmd.manifest.flags && cmd.manifest.flags.length > 0) {
           lines.push("**Flags:**\n");
-          for (const flag of cmd.flags) {
+          for (const flag of cmd.manifest.flags) {
             const alias = flag.alias ? ` (-${flag.alias})` : "";
             const required = flag.required ? " **(required)**" : "";
             const defaultVal = flag.default !== void 0 ? ` (default: \`${flag.default}\`)` : "";
@@ -2225,16 +2848,16 @@ var docsGenerateCliReference = defineSystemCommand({
           }
           lines.push("");
         }
-        if (cmd.examples && cmd.examples.length > 0) {
+        if (cmd.manifest.examples && cmd.manifest.examples.length > 0) {
           lines.push("**Examples:**\n");
           lines.push("```bash");
-          for (const example of cmd.examples) {
+          for (const example of cmd.manifest.examples) {
             lines.push(example);
           }
           lines.push("```\n");
         }
-        if (cmd.aliases && cmd.aliases.length > 0) {
-          lines.push(`**Aliases:** ${cmd.aliases.map((a) => `\`${a}\``).join(", ")}
+        if (cmd.manifest.aliases && cmd.manifest.aliases.length > 0) {
+          lines.push(`**Aliases:** ${cmd.manifest.aliases.map((a) => `\`${a}\``).join(", ")}
 `);
         }
         lines.push("---\n");
@@ -3178,6 +3801,7 @@ var authLogin = defineSystemCommand({
     "client-secret": { type: "string", description: "Client Secret from service account registration" },
     json: { type: "boolean", description: "Output in JSON format" }
   },
+  // eslint-disable-next-line sonarjs/cognitive-complexity
   async handler(ctx, _argv, flags) {
     const gatewayUrl = flags["gateway-url"];
     const clientId = flags["client-id"];
@@ -3219,23 +3843,43 @@ var authLogin = defineSystemCommand({
       return { ok: false, error: msg, gatewayUrl, expiresIn: 0 };
     }
     const tokenData = await tokenResponse.json();
+    let handle;
+    let namespaceId;
+    try {
+      const meRes = await fetch(`${gatewayUrl}/auth/me`, {
+        headers: { Authorization: `Bearer ${tokenData.accessToken}` }
+      });
+      if (meRes.ok) {
+        const profile = await meRes.json();
+        handle = profile.handle;
+        namespaceId = profile.namespaceId;
+      }
+    } catch {
+    }
     const credentialsManager = new CredentialsManager();
     const expiresAt = Date.now() + tokenData.expiresIn * 1e3;
     await credentialsManager.save({
       gatewayUrl,
       accessToken: tokenData.accessToken,
       refreshToken: tokenData.refreshToken,
-      expiresAt
+      expiresAt,
+      handle,
+      namespaceId
     });
     if (flags.json) {
       ctx.ui?.json({
         ok: true,
         gatewayUrl,
-        expiresIn: tokenData.expiresIn
+        expiresIn: tokenData.expiresIn,
+        ...handle ? { handle } : {}
       });
     } else {
       ctx.ui?.write?.(`Authenticated with Gateway at ${gatewayUrl}
 `);
+      if (handle) {
+        ctx.ui?.write?.(`Handle: ${handle}
+`);
+      }
       ctx.ui?.write?.(`Token expires in ${Math.floor(tokenData.expiresIn / 60)} minutes (auto-refresh enabled).
 `);
     }
@@ -3345,6 +3989,7 @@ var authCreateServiceAccount = defineSystemCommand({
     "namespace-id": { type: "string", description: "Namespace ID (1-64 chars)" },
     json: { type: "boolean", description: "Output in JSON format" }
   },
+  // eslint-disable-next-line sonarjs/cognitive-complexity
   async handler(ctx, _argv, flags) {
     const gatewayUrl = flags["gateway-url"];
     const name = flags.name;
@@ -3472,9 +4117,10 @@ var platformSyncCommand = defineSystemCommand({
       sync: result
     };
   },
+  // eslint-disable-next-line sonarjs/cognitive-complexity
   formatter(result, ctx, flags) {
     if (flags.json) {
-      console.log(JSON.stringify(result.sync ?? result, null, 2));
+      ctx.ui?.json?.(result.sync ?? result);
       return;
     }
     const sync = result.sync;
@@ -3518,35 +4164,308 @@ var platformSyncCommand = defineSystemCommand({
         items: sync.missing.map((id) => `\u2022 ${id}`)
       });
     }
-    if (sync.mismatched.length) {
-      sections.push({
-        header: "Integrity mismatch",
-        items: sync.mismatched.map((id) => `\u2022 ${id}`)
-      });
+    if (sync.mismatched.length) {
+      sections.push({
+        header: "Integrity mismatch",
+        items: sync.mismatched.map((id) => `\u2022 ${id}`)
+      });
+    }
+    if (sync.errors.length) {
+      sections.push({
+        header: "Errors",
+        items: sync.errors.map((e) => `\u2022 ${e.packageId}: ${e.message}`)
+      });
+    }
+    const nextSteps = [];
+    if (!sync.ok) {
+      if (sync.missing.length && sync.mode === "validate") {
+        nextSteps.push("kb platform provision --mode reconcile   Install missing packages");
+      }
+      if (sync.mismatched.length) {
+        nextSteps.push("kb marketplace install <pkg>             Re-install mismatched packages");
+      }
+    }
+    if (nextSteps.length) {
+      sections.push({ header: "Next Steps", items: nextSteps });
+    }
+    if (sync.ok) {
+      ctx.ui.success("Platform Sync", { sections });
+    } else {
+      ctx.ui.error("Platform Sync", { sections });
+    }
+  }
+});
+var webhookProvision = defineSystemCommand({
+  name: "provision",
+  description: "Provision (or rotate) a webhook secret",
+  longDescription: "Generates a new webhook secret for a plugin+event combination and registers it with the Gateway. On first call: creates the secret. On subsequent calls: rotates it (old secret valid for 24h). The secret is shown once \u2014 save it immediately.",
+  category: "webhook",
+  examples: [
+    "kb webhook provision --plugin @kb-labs/rollout --event alert",
+    "kb webhook provision --plugin @kb-labs/rollout --event alert --instance prod",
+    "kb webhook provision --plugin @kb-labs/rollout --event alert --json"
+  ],
+  flags: {
+    plugin: { type: "string", description: "Plugin ID (e.g. @kb-labs/rollout)" },
+    event: { type: "string", description: "Webhook event name declared in the plugin manifest" },
+    instance: { type: "string", description: "Instance ID for multi-instance webhooks (optional)" },
+    json: { type: "boolean", description: "Output in JSON format" }
+  },
+  async handler(ctx, _argv, flags) {
+    const pluginId = flags.plugin;
+    const event = flags.event;
+    if (!pluginId) {
+      const msg = "--plugin is required";
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
+    }
+    if (!event) {
+      const msg = "--event is required";
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
+    }
+    const credentialsManager = new CredentialsManager();
+    const credentials = await credentialsManager.load();
+    if (!credentials) {
+      const msg = 'Not authenticated. Run "kb auth login" first.';
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
+    }
+    const url = `${credentials.gatewayUrl}/api/v1/webhooks/provision`;
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${credentials.accessToken}`
+        },
+        body: JSON.stringify({
+          pluginId,
+          event,
+          ...flags.instance ? { instanceId: flags.instance } : {}
+        })
+      });
+    } catch (err) {
+      const msg = `Cannot reach Gateway at ${credentials.gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`;
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      let detail = "";
+      try {
+        detail = JSON.parse(body)?.message ?? body;
+      } catch {
+        detail = body;
+      }
+      const msg = `Provision failed (HTTP ${response.status})${detail ? ": " + detail : ""}`;
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
+    }
+    const data = await response.json();
+    if (flags.json) {
+      ctx.ui?.json({ ok: true, url: data.url, secret: data.secret, rotated: data.rotated });
+    } else {
+      ctx.ui?.write?.(data.rotated ? "\u27F3  Secret rotated (old secret valid for 24h grace period)\n" : "\u2713  Webhook provisioned\n");
+      ctx.ui?.write?.(`URL:    ${data.url}
+`);
+      ctx.ui?.write?.(`Secret: ${data.secret}
+`);
+      ctx.ui?.write?.("\n\u26A0  Save the secret now \u2014 it will not be shown again.\n");
+    }
+    return { ok: true, url: data.url, rotated: data.rotated };
+  }
+});
+var webhookList = defineSystemCommand({
+  name: "list",
+  description: "List declared webhook endpoints",
+  longDescription: "Lists all webhook endpoints declared in installed plugin manifests. Shows provisioned status (whether a secret has been set) for each endpoint.",
+  category: "webhook",
+  examples: [
+    "kb webhook list",
+    "kb webhook list --plugin @kb-labs/rollout",
+    "kb webhook list --json"
+  ],
+  flags: {
+    plugin: { type: "string", description: "Filter by plugin ID" },
+    json: { type: "boolean", description: "Output in JSON format" }
+  },
+  async handler(ctx, _argv, flags) {
+    const credentialsManager = new CredentialsManager();
+    const credentials = await credentialsManager.load();
+    if (!credentials) {
+      const msg = 'Not authenticated. Run "kb auth login" first.';
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
+    }
+    const qs = flags.plugin ? `?pluginId=${encodeURIComponent(flags.plugin)}` : "";
+    const url = `${credentials.gatewayUrl}/api/v1/webhooks${qs}`;
+    let response;
+    try {
+      response = await fetch(url, {
+        headers: { Authorization: `Bearer ${credentials.accessToken}` }
+      });
+    } catch (err) {
+      const msg = `Cannot reach Gateway at ${credentials.gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`;
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      const msg = `List failed (HTTP ${response.status}): ${body}`;
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
+    }
+    const data = await response.json();
+    const webhooks = data.webhooks ?? [];
+    if (flags.json) {
+      ctx.ui?.json({ ok: true, webhooks });
+    } else {
+      if (webhooks.length === 0) {
+        ctx.ui?.write?.("No webhook endpoints found.\n");
+      } else {
+        const pluginWidth = Math.max(6, ...webhooks.map((w) => w.pluginId.length));
+        const eventWidth = Math.max(5, ...webhooks.map((w) => w.event.length));
+        ctx.ui?.write?.(
+          `${"PLUGIN".padEnd(pluginWidth)}  ${"EVENT".padEnd(eventWidth)}  MULTI  PROVISIONED
+`
+        );
+        ctx.ui?.write?.(`${"\u2500".repeat(pluginWidth)}  ${"\u2500".repeat(eventWidth)}  \u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+`);
+        for (const w of webhooks) {
+          ctx.ui?.write?.(
+            `${w.pluginId.padEnd(pluginWidth)}  ${w.event.padEnd(eventWidth)}  ${w.multi ? "yes  " : "no   "}  ${w.provisioned ? "yes" : "no"}
+`
+          );
+        }
+        ctx.ui?.write?.(`
+${webhooks.length} webhook(s)
+`);
+      }
+    }
+    return { ok: true, webhooks };
+  }
+});
+var webhookRevoke = defineSystemCommand({
+  name: "revoke",
+  description: "Revoke a provisioned webhook secret",
+  longDescription: 'Deletes the webhook secret for a plugin+event combination. Any subsequent deliveries with the old secret are immediately rejected (no grace period). Use "kb webhook provision" to create a new secret afterwards.',
+  category: "webhook",
+  examples: [
+    "kb webhook revoke --plugin @kb-labs/rollout --event alert",
+    "kb webhook revoke --plugin @kb-labs/rollout --event alert --instance prod",
+    "kb webhook revoke --plugin @kb-labs/rollout --event alert --json"
+  ],
+  flags: {
+    plugin: { type: "string", description: "Plugin ID (e.g. @kb-labs/rollout)" },
+    event: { type: "string", description: "Webhook event name" },
+    instance: { type: "string", description: "Instance ID for multi-instance webhooks (optional)" },
+    json: { type: "boolean", description: "Output in JSON format" }
+  },
+  async handler(ctx, _argv, flags) {
+    const pluginId = flags.plugin;
+    const event = flags.event;
+    if (!pluginId) {
+      const msg = "--plugin is required";
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
     }
-    if (sync.errors.length) {
-      sections.push({
-        header: "Errors",
-        items: sync.errors.map((e) => `\u2022 ${e.packageId}: ${e.message}`)
-      });
+    if (!event) {
+      const msg = "--event is required";
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
     }
-    const nextSteps = [];
-    if (!sync.ok) {
-      if (sync.missing.length && sync.mode === "validate") {
-        nextSteps.push("kb platform provision --mode reconcile   Install missing packages");
+    const credentialsManager = new CredentialsManager();
+    const credentials = await credentialsManager.load();
+    if (!credentials) {
+      const msg = 'Not authenticated. Run "kb auth login" first.';
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
       }
-      if (sync.mismatched.length) {
-        nextSteps.push("kb marketplace install <pkg>             Re-install mismatched packages");
+      return { ok: false, error: msg };
+    }
+    const segments = [
+      encodeURIComponent(pluginId),
+      encodeURIComponent(event),
+      ...flags.instance ? [encodeURIComponent(flags.instance)] : []
+    ].join("/");
+    const url = `${credentials.gatewayUrl}/api/v1/webhooks/${segments}`;
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${credentials.accessToken}` }
+      });
+    } catch (err) {
+      const msg = `Cannot reach Gateway at ${credentials.gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`;
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
       }
+      return { ok: false, error: msg };
     }
-    if (nextSteps.length) {
-      sections.push({ header: "Next Steps", items: nextSteps });
+    if (!response.ok && response.status !== 404) {
+      const body = await response.text().catch(() => "");
+      const msg = `Revoke failed (HTTP ${response.status}): ${body}`;
+      if (flags.json) {
+        ctx.ui?.json({ ok: false, error: msg });
+      } else {
+        ctx.ui?.error?.(msg);
+      }
+      return { ok: false, error: msg };
     }
-    if (sync.ok) {
-      ctx.ui.success("Platform Sync", { sections });
+    const label = flags.instance ? `${pluginId}/${event}/${flags.instance}` : `${pluginId}/${event}`;
+    if (flags.json) {
+      ctx.ui?.json({ ok: true, revoked: label });
     } else {
-      ctx.ui.error("Platform Sync", { sections });
+      ctx.ui?.write?.(`\u2713  Webhook revoked: ${label}
+`);
     }
+    return { ok: true };
   }
 });
 
@@ -3557,9 +4476,6 @@ var infoGroup = defineSystemCommandGroup("info", "System information commands",
   health,
   diag
 ]);
-var marketplaceGroup = defineSystemCommandGroup("marketplace", "Marketplace management commands", [
-  pluginsCacheClear
-]);
 var docsGroup = defineSystemCommandGroup("docs", "Documentation generation commands", [
   docsGenerateCliReference
 ]);
@@ -3584,442 +4500,260 @@ var authGroup = defineSystemCommandGroup("auth", "Gateway authentication command
 var platformGroup = defineSystemCommandGroup("platform", "Platform lifecycle commands", [
   platformSyncCommand
 ]);
-var req = createRequire(import.meta.url);
-var __filename$1 = fileURLToPath(import.meta.url);
-var __dirname$1 = path.dirname(__filename$1);
-function resolveFromCwd(spec, cwd) {
-  const cliRoot = path.resolve(__dirname$1, "../../..");
-  let monorepoRoot = cwd;
-  while (monorepoRoot !== path.dirname(monorepoRoot)) {
-    if (existsSync(path.join(monorepoRoot, "pnpm-workspace.yaml"))) {
-      break;
-    }
-    monorepoRoot = path.dirname(monorepoRoot);
-  }
-  const pathsToTry = [
-    cwd,
-    // Current working directory (user's project)
-    cliRoot,
-    // CLI installation directory
-    monorepoRoot,
-    // Monorepo root (if found)
-    path.join(monorepoRoot, "../kb-labs-cli"),
-    // Explicit kb-labs-cli path
-    path.join(monorepoRoot, "../kb-labs-mind")
-    // Explicit kb-labs-mind path
-  ].filter(Boolean);
-  for (const searchPath of pathsToTry) {
-    try {
-      return req.resolve(spec, { paths: [searchPath] });
-    } catch (_e) {
-    }
+var webhookGroup = defineSystemCommandGroup("webhook", "Webhook management commands", [
+  webhookProvision,
+  webhookList,
+  webhookRevoke
+]);
+var MARKER = "# kb completion";
+var ALIAS_MARKER = "# kb alias";
+var STATIC_FILE = path.join(os.homedir(), ".config", "kb", "completion.zsh");
+function dynamicScript(shell) {
+  switch (shell) {
+    case "bash":
+      return [
+        "_kb_completion() {",
+        "  local words cur",
+        '  cur="${COMP_WORDS[COMP_CWORD]}"',
+        '  words="${COMP_WORDS[*]:1:$((COMP_CWORD - 1))}"',
+        '  COMPREPLY=($(kb __complete $words "$cur" 2>/dev/null))',
+        "  return 0",
+        "}",
+        "complete -o nospace -F _kb_completion kb"
+      ].join("\n");
+    case "zsh":
+      return [
+        "#compdef kb",
+        "_kb_completion() {",
+        "  local completions",
+        "  completions=($(kb __complete ${words[2,-1]} 2>/dev/null))",
+        "  compadd -a completions",
+        "}",
+        "compdef _kb_completion kb"
+      ].join("\n");
+    case "fish":
+      return [
+        "function __kb_complete",
+        "  set -l tokens (commandline -opc)",
+        "  kb __complete $tokens[2..] (commandline -ct) 2>/dev/null",
+        "end",
+        'complete -c kb -f -a "(__kb_complete)"'
+      ].join("\n");
+    default:
+      return null;
   }
-  throw new Error(`Cannot resolve ${spec} from any of: ${pathsToTry.join(", ")}`);
 }
-function checkRequires(manifest, options = {}) {
-  const cwd = options.cwd ?? process.cwd();
-  if (!manifest.requires || manifest.requires.length === 0) {
-    return { available: true };
-  }
-  let isInMonorepo = false;
-  let monorepoRoot = cwd;
-  while (monorepoRoot !== path.dirname(monorepoRoot)) {
-    if (existsSync(path.join(monorepoRoot, "pnpm-workspace.yaml"))) {
-      isInMonorepo = true;
-      break;
-    }
-    monorepoRoot = path.dirname(monorepoRoot);
-  }
-  for (const dep of manifest.requires) {
-    try {
-      const resolved = resolveFromCwd(dep, cwd);
-      if (!resolved.includes("node_modules")) {
-        continue;
-      }
-    } catch (err) {
-      if (isInMonorepo) {
-        continue;
-      }
-      const errorMessage = (err instanceof Error ? err.message : "") || "";
-      const hasExportsError = errorMessage.includes("exports") || errorMessage.includes("main");
-      if (hasExportsError || errorMessage.includes("Cannot resolve")) {
-        const parts = dep.startsWith("@") ? dep.slice(1).split("/") : [dep];
-        if (parts.length === 0) {
-          continue;
-        }
-        const scope = parts.length >= 2 ? parts[0] : "";
-        const packageName = parts.length >= 2 ? parts[1] : parts[0];
-        if (!packageName) {
-          continue;
-        }
-        const cliRoot = path.resolve(__dirname$1, "../../..");
-        const packagePath = scope ? path.join(cliRoot, "node_modules", "@" + scope, packageName, "package.json") : path.join(cliRoot, "node_modules", packageName, "package.json");
-        if (existsSync(packagePath)) {
-          continue;
-        }
+function buildStaticZsh(tree) {
+  const lines = ["#compdef kb", "_kb() {"];
+  const l1 = [...tree.keys()];
+  lines.push(`  if [[ $CURRENT -eq 2 ]]; then`);
+  lines.push(`    compadd -- ${l1.join(" ")}`);
+  lines.push(`    return`);
+  lines.push(`  fi`);
+  lines.push(`  if [[ $CURRENT -eq 3 ]]; then`);
+  lines.push(`    case $words[2] in`);
+  for (const [cmd, subMap] of tree) {
+    const subs = [...subMap.keys()];
+    if (subs.length > 0) {
+      lines.push(`      ${cmd}) compadd -- ${subs.join(" ")} ;;`);
+    }
+  }
+  lines.push(`    esac`);
+  lines.push(`    return`);
+  lines.push(`  fi`);
+  lines.push(`  if [[ $CURRENT -eq 4 ]]; then`);
+  lines.push(`    case "$words[2] $words[3]" in`);
+  for (const [cmd, subMap] of tree) {
+    for (const [sub, leaves] of subMap) {
+      if (leaves.length > 0) {
+        const bare = leaves.map((l) => l.split(" ").pop() ?? l);
+        lines.push(`      "${cmd} ${sub}") compadd -- ${bare.join(" ")} ;;`);
       }
-      const isKbLabsPackage = dep.startsWith("@kb-labs/");
-      const hint = isKbLabsPackage ? `Run: pnpm add ${dep}` : `Run: npm install ${dep}`;
-      return {
-        available: false,
-        reason: `Missing dependency: ${dep}`,
-        hint
-      };
-    }
-  }
-  return { available: true };
-}
-var ajv = new Ajv();
-var flagSchema = {
-  type: "object",
-  required: ["name", "type"],
-  additionalProperties: false,
-  properties: {
-    name: { type: "string" },
-    type: { enum: ["string", "boolean", "number", "array"] },
-    alias: { type: "string", pattern: "^[a-z]$" },
-    // single letter
-    description: { type: "string" },
-    choices: { type: "array", items: { type: "string" } },
-    required: { type: "boolean" },
-    default: {}
-    // must match type
-  }
-};
-var manifestSchema = {
-  type: "object",
-  required: ["manifestVersion", "id", "group", "describe", "loader"],
-  additionalProperties: true,
-  properties: {
-    manifestVersion: { type: "string", enum: ["1.0"] },
-    id: { type: "string", pattern: "^[a-z0-9-]+(?::[a-z0-9-]+)*$" },
-    // Simple or namespaced (colon-separated)
-    aliases: { type: "array", items: { type: "string" } },
-    group: { type: "string" },
-    describe: { type: "string" },
-    longDescription: { type: "string" },
-    requires: { type: "array", items: { type: "string" } },
-    flags: {
-      type: "array",
-      items: flagSchema
-    },
-    examples: { type: "array", items: { type: "string" } }
-  }
-};
-var validateManifest = ajv.compile(manifestSchema);
-var validateFlag = ajv.compile(flagSchema);
-function validateFlagDef(flag, manifestId) {
-  if (!validateFlag(flag)) {
-    throw new Error(
-      `Invalid flag "${flag.name}" in ${manifestId}: ${ajv.errorsText(validateFlag.errors)}`
-    );
-  }
-  if (flag.choices && flag.type !== "string") {
-    throw new Error(`Flag "${flag.name}" in ${manifestId}: choices allowed only for string type`);
-  }
-  if (flag.default !== void 0) {
-    const typeMatches = flag.type === "string" && typeof flag.default === "string" || flag.type === "boolean" && typeof flag.default === "boolean" || flag.type === "number" && typeof flag.default === "number" || flag.type === "array" && Array.isArray(flag.default);
-    if (!typeMatches) {
-      throw new Error(
-        `Flag "${flag.name}" in ${manifestId}: default value type mismatch (expected ${flag.type})`
-      );
     }
   }
+  lines.push(`    esac`);
+  lines.push(`    return`);
+  lines.push(`  fi`);
+  lines.push(`}`, `compdef _kb kb`);
+  lines.push(``, `# pnpm kb \u2014 same completions, shifted by 1 position`);
+  lines.push(`_kb_pnpm_wrap() {`);
+  lines.push(`  if [[ \${words[2]-} == kb ]]; then`);
+  lines.push(`    local CURRENT=$((CURRENT - 1))`);
+  lines.push(`    local -a words=("kb" "\${words[3,-1]}")`);
+  lines.push(`    [[ $CURRENT -lt 1 ]] && CURRENT=1`);
+  lines.push(`    _kb`);
+  lines.push(`    return 0`);
+  lines.push(`  fi`);
+  lines.push(`  (( $+functions[_pnpm_orig] )) && { _pnpm_orig; return; }`);
+  lines.push(`  return 1`);
+  lines.push(`}`);
+  lines.push(`if (( $+functions[_pnpm] )) && ! (( $+functions[_pnpm_orig] )); then`);
+  lines.push(`  functions[_pnpm_orig]=$functions[_pnpm]`);
+  lines.push(`  _pnpm() { _kb_pnpm_wrap; }`);
+  lines.push(`else`);
+  lines.push(`  compdef _kb_pnpm_wrap pnpm`);
+  lines.push(`fi`);
+  return lines.join("\n");
 }
-function validateManifestStructure(manifest) {
-  if (!validateManifest(manifest)) {
-    throw new Error(`Invalid manifest ${manifest.id}: ${ajv.errorsText(validateManifest.errors)}`);
-  }
-  if (manifest.manifestVersion !== "1.0") {
-    throw new Error(
-      `Unsupported manifestVersion "${manifest.manifestVersion}" in ${manifest.id} (expected "1.0")`
-    );
-  }
-  if (manifest.flags && Array.isArray(manifest.flags) && manifest.id) {
-    for (const flag of manifest.flags) {
-      if (flag && typeof flag === "object" && flag.name) {
-        validateFlagDef(flag, manifest.id);
-      }
-    }
-  }
+async function collectTree(registry2) {
+  const tree = /* @__PURE__ */ new Map();
+  const l1 = registry2.complete([""]);
+  for (const cmd of l1) {
+    const subMap = /* @__PURE__ */ new Map();
+    const l2 = registry2.complete([cmd, ""]);
+    for (const full2 of l2) {
+      const sub = full2.split(" ").pop() ?? full2;
+      const l3 = registry2.complete([cmd, sub, ""]);
+      subMap.set(sub, l3);
+    }
+    tree.set(cmd, subMap);
+  }
+  return tree;
 }
-var SOURCE_PRIORITY = {
-  builtin: 4,
-  workspace: 3,
-  linked: 2,
-  node_modules: 1
-};
-function normalizeCommandId(id, _namespace) {
-  return id;
+function detectShell() {
+  const name = path.basename(process.env["SHELL"] ?? "");
+  return ["bash", "zsh", "fish"].includes(name) ? name : "zsh";
 }
-function generateWhitespaceAliases(id) {
-  if (!id.includes(":")) {
-    return [];
+function profilePath(shell) {
+  const home = os.homedir();
+  if (shell === "bash") {
+    return path.join(home, ".bashrc");
+  }
+  if (shell === "fish") {
+    return path.join(home, ".config", "fish", "config.fish");
   }
-  return [id.replace(":", " ")];
+  return path.join(home, ".zshrc");
 }
-function normalizeAliases(manifest, logger) {
-  const log3 = logger ?? platform.logger;
-  const aliases = /* @__PURE__ */ new Set();
-  manifest.namespace || manifest.group;
-  if (manifest.aliases) {
-    for (const alias of manifest.aliases) {
-      if (!/^[a-z0-9-:]+$/i.test(alias)) {
-        log3.warn(`Invalid alias "${alias}" in ${manifest.id}: aliases must be alphanumeric with hyphens or colons`);
-        continue;
-      }
-      aliases.add(alias);
-    }
+function profileLine(shell) {
+  if (shell === "zsh") {
+    return `${MARKER}
+[ -f "${STATIC_FILE}" ] && source "${STATIC_FILE}"`;
   }
-  const whitespaceAliases = generateWhitespaceAliases(manifest.id);
-  for (const alias of whitespaceAliases) {
-    aliases.add(alias);
+  if (shell === "fish") {
+    return `${MARKER}
+test -f "${STATIC_FILE}" && source "${STATIC_FILE}"`;
   }
-  return Array.from(aliases);
+  return `${MARKER}
+command -v kb &>/dev/null && eval "$(kb completion bash 2>/dev/null)" || true`;
 }
-function checkNamespaceCollision(manifest, existing, namespace) {
-  const existingGroup = existing.manifest.group || "";
-  const currentGroup = manifest.group || "";
-  if (existingGroup === currentGroup && existingGroup === namespace && existing.manifest.id === manifest.id) {
-    throw new Error(
-      `Command collision in group "${namespace}": "${manifest.id}" conflicts with existing "${existing.manifest.id}". Rename one of the commands to use a different ID (e.g., "${manifest.id}2" or use --alias to create a different alias).`
-    );
-  }
+function aliasLine(shell) {
+  if (shell === "fish") {
+    return [
+      ALIAS_MARKER,
+      `alias kb='pnpm --silent kb'`,
+      `function pnpm`,
+      `  if test "$argv[1]" = "kb"`,
+      `    command pnpm --silent $argv`,
+      `  else`,
+      `    command pnpm $argv`,
+      `  end`,
+      `end`
+    ].join("\n");
+  }
+  return [
+    ALIAS_MARKER,
+    `alias kb='pnpm --silent kb'`,
+    `pnpm() { if [[ "$1" == "kb" ]]; then command pnpm --silent "$@"; else command pnpm "$@"; fi }`
+  ].join("\n");
 }
-function getSourcePriority(source) {
-  return SOURCE_PRIORITY[source] || 0;
+function commandsHash(registry2) {
+  const keys = registry2.complete([""]).sort().join(",");
+  return createHash("sha256").update(keys).digest("hex").slice(0, 12);
 }
-function checkCollision(manifest, existing, currentSource, namespace) {
-  const existingPriority = getSourcePriority(existing.source);
-  const currentPriority = getSourcePriority(currentSource);
-  checkNamespaceCollision(manifest, existing, namespace);
-  if (currentSource === "workspace" && existing.source === "workspace") {
-    throw new Error(
-      `Command ID collision: "${manifest.id}" is exported by multiple workspace packages. This is not allowed. Please rename one of the commands to use a different ID.`
-    );
-  }
-  if (currentPriority > existingPriority) {
-    return { shouldShadow: true };
-  } else if (currentPriority < existingPriority) {
-    return { shouldShadow: false };
-  }
-  return { shouldShadow: false };
+function hashFromFile(content) {
+  const m = content.match(/^# hash: ([a-f0-9]+)/m);
+  return m?.[1] ?? null;
 }
-function preflightManifests(discoveryResults, logger) {
-  const log3 = logger ?? platform.logger;
-  const logLevel = getLogLevel();
-  const valid = [];
-  const skipped = [];
-  for (const result of discoveryResults) {
-    const allowed = [];
-    for (const manifest of result.manifests) {
-      try {
-        validateManifestStructure(manifest);
-        allowed.push(manifest);
-      } catch (error) {
-        const reason = error instanceof Error ? error.message : "Validation failed";
-        const manifestId = manifest?.id || manifest?.group || result.packageName || "unknown";
-        skipped.push({
-          id: manifestId,
-          source: result.source,
-          reason
-        });
-        log3.warn(`Preflight skipped manifest ${manifestId}: ${reason}`);
-        if (logLevel === "debug") {
-          process.stderr.write(`[debug][preflight] skipped ${manifestId} (${result.source}): ${reason}
-`);
-        }
-      }
-    }
-    if (allowed.length > 0) {
-      valid.push({
-        ...result,
-        manifests: allowed
-      });
-    }
+async function autoUpdateCompletion(registry2) {
+  try {
+    await promises.access(STATIC_FILE);
+  } catch {
+    return;
   }
-  return { valid, skipped };
-}
-async function registerManifests(discoveryResults, registry2, options = {}) {
-  const log3 = options.logger ?? platform.logger;
-  const registered = [];
-  const skipped = [];
-  const globalIds = /* @__PURE__ */ new Map();
-  const globalAliases = /* @__PURE__ */ new Map();
-  const logLevel = getLogLevel();
-  let collisions = 0;
-  let errors = 0;
-  const sorted = [...discoveryResults].sort((a, b) => {
-    const priorityA = getSourcePriority(a.source);
-    const priorityB = getSourcePriority(b.source);
-    return priorityB - priorityA;
-  });
-  for (const result of sorted) {
-    for (const manifest of result.manifests) {
-      const manifestId = manifest.id || manifest.group || "unknown";
-      const namespace = manifest.namespace || manifest.group;
-      try {
-        try {
-          validateManifestStructure(manifest);
-        } catch (err) {
-          throw new Error(`Validation failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        const normalizedId = normalizeCommandId(manifest.id, namespace);
-        if (normalizedId !== manifest.id) {
-          log3.warn(`Command ID "${manifest.id}" normalized to "${normalizedId}"`);
-          manifest.id = normalizedId;
-        }
-        const normalizedAliases = normalizeAliases(manifest, log3);
-        if (normalizedAliases.length > 0) {
-          manifest.aliases = normalizedAliases;
+  const current = commandsHash(registry2);
+  let existing = "";
+  try {
+    existing = await promises.readFile(STATIC_FILE, "utf8");
+  } catch {
+    return;
+  }
+  if (hashFromFile(existing) === current) {
+    return;
+  }
+  const tree = await collectTree(registry2);
+  const script = `# hash: ${current}
+` + buildStaticZsh(tree);
+  await promises.writeFile(STATIC_FILE, script, "utf8");
+}
+function createCompletionCommand(registry2) {
+  return defineSystemCommand({
+    name: "completion",
+    description: "Generate or install shell completion",
+    longDescription: "Print a shell completion script or bake a static one into your shell profile.\n\nUsage:\n  kb completion install   # auto-detect shell, write static file, add to profile\n  kb completion zsh       # print dynamic zsh script\n  kb completion bash      # print dynamic bash script\n  kb completion fish      # print dynamic fish script",
+    flags: {},
+    async handler(_ctx, argv) {
+      const arg = argv[0];
+      if (!arg || arg === "install") {
+        const shell = argv[1] ?? detectShell();
+        if (shell === "zsh") {
+          const tree = await collectTree(registry2);
+          const hash = commandsHash(registry2);
+          const script2 = `# hash: ${hash}
+` + buildStaticZsh(tree);
+          await promises.mkdir(path.dirname(STATIC_FILE), { recursive: true });
+          await promises.writeFile(STATIC_FILE, script2, "utf8");
         }
-        const availability = checkRequires(manifest, {
-          cwd: options.cwd ?? result.pkgRoot
-        });
-        const cmd = {
-          manifest,
-          v3Manifest: manifest.manifestV2,
-          // Extract V3 manifest from legacy field
-          available: availability.available,
-          unavailableReason: availability.available ? void 0 : availability.reason,
-          hint: availability.available ? void 0 : availability.hint,
-          source: result.source,
-          shadowed: false,
-          pkgRoot: result.pkgRoot,
-          packageName: result.packageName
-        };
+        const rcPath = profilePath(shell);
+        let existing = "";
         try {
-          const manifestModule = await import(result.manifestPath);
-          if (manifestModule.init && typeof manifestModule.init === "function") {
-            await manifestModule.init({
-              cwd: result.pkgRoot,
-              package: result.packageName,
-              manifest: cmd.manifest
-            });
-          }
-          if (manifestModule.register && typeof manifestModule.register === "function") {
-            await manifestModule.register({
-              registry: registry2,
-              command: cmd,
-              cwd: result.pkgRoot,
-              package: result.packageName
-            });
-          }
-          if (manifestModule.dispose && typeof manifestModule.dispose === "function") {
-            cmd._disposeHook = manifestModule.dispose;
-          }
-        } catch (hookError) {
-          const hookMsg = hookError instanceof Error ? hookError.message : String(hookError);
-          log3.debug(`Lifecycle hooks unavailable for ${manifest.id}: ${hookMsg}`);
-        }
-        const canonicalKey = manifest.group ? `${manifest.group}:${manifest.id}` : manifest.id;
-        const existing = globalIds.get(canonicalKey);
-        if (existing) {
-          const collision = checkCollision(manifest, existing, result.source, namespace);
-          if (collision.shouldShadow) {
-            existing.shadowed = true;
-            globalIds.set(canonicalKey, cmd);
-            if (logLevel === "info" || logLevel === "debug") {
-              log3.info(`${canonicalKey} from ${result.source} shadows ${existing.source} version`);
-            }
-          } else {
-            cmd.shadowed = true;
-            if (logLevel === "info" || logLevel === "debug") {
-              log3.info(`${canonicalKey} from ${result.source} shadowed by ${existing.source} version`);
-            }
-          }
-        } else {
-          globalIds.set(canonicalKey, cmd);
+          existing = await promises.readFile(rcPath, "utf8");
+        } catch {
         }
-        const aliasesToCheck = manifest.aliases || [];
-        for (const alias of aliasesToCheck) {
-          const existingAlias = globalAliases.get(alias);
-          if (existingAlias) {
-            if (existingAlias.manifest.id === manifest.id) {
-              continue;
-            }
-            const existingPriority = getSourcePriority(existingAlias.source);
-            const currentPriority = getSourcePriority(result.source);
-            if (currentPriority > existingPriority) {
-              existingAlias.shadowed = true;
-              globalAliases.set(alias, cmd);
-              if (logLevel === "info" || logLevel === "debug") {
-                log3.info(`Alias "${alias}" from ${result.source} shadows ${existingAlias.source} version`);
-              }
-            } else if (currentPriority < existingPriority) {
-              if (logLevel === "info" || logLevel === "debug") {
-                log3.info(`Alias "${alias}" from ${result.source} shadowed by ${existingAlias.source} version`);
-              }
-              continue;
-            } else {
-              collisions++;
-              throw new Error(
-                `Alias collision: "${alias}" used by both ${manifest.id} and ${existingAlias.manifest.id}. Rename one alias or use a different namespace.`
-              );
-            }
-          }
-          if (globalIds.has(alias)) {
-            const conflictingCmd = globalIds.get(alias);
-            const existingPriority = getSourcePriority(conflictingCmd.source);
-            const currentPriority = getSourcePriority(result.source);
-            if (currentPriority > existingPriority) {
-              log3.warn(`Alias "${alias}" conflicts with command ID "${alias}". Alias will shadow command.`);
-              globalAliases.set(alias, cmd);
-            } else {
-              throw new Error(
-                `Alias "${alias}" conflicts with existing command ID "${alias}". Rename the alias or use a different name.`
-              );
-            }
-          } else {
-            globalAliases.set(alias, cmd);
-          }
+        const alreadyInstalled = existing.includes(MARKER);
+        if (!alreadyInstalled) {
+          await promises.appendFile(rcPath, `
+${profileLine(shell)}
+`);
         }
-        if (!cmd.shadowed) {
-          registry2.registerManifest(cmd);
+        const aliasAlreadyInstalled = existing.includes(ALIAS_MARKER);
+        if (!aliasAlreadyInstalled) {
+          await promises.appendFile(rcPath, `
+${aliasLine(shell)}
+`);
         }
-        registered.push(cmd);
-      } catch (error) {
-        errors++;
-        const reason = error instanceof Error ? error.message : String(error);
-        skipped.push({
-          id: manifestId,
-          source: result.source,
-          reason
-        });
-        log3.error(`Skipped manifest ${manifestId} (${result.source}): ${reason}`);
-        continue;
+        return { ok: true, status: "success", shell, profilePath: rcPath, alreadyInstalled, aliasInstalled: !aliasAlreadyInstalled };
       }
+      const script = dynamicScript(arg);
+      if (!script) {
+        throw new Error(`Unsupported shell: ${arg}. Supported: bash, zsh, fish`);
+      }
+      return { ok: true, status: "success", script, shell: arg };
+    },
+    formatter(result) {
+      if ("script" in result) {
+        process.stdout.write(result.script + "\n");
+        return;
+      }
+      const r = result;
+      if (r.shell === "zsh") {
+        process.stdout.write(`\u2713 Static completions \u2192 ${STATIC_FILE}
+`);
+      }
+      if (r.alreadyInstalled) {
+        process.stdout.write(`Profile already configured: ${r.profilePath}
+`);
+      } else {
+        process.stdout.write(`\u2713 Added to ${r.profilePath}
+`);
+      }
+      if (r.aliasInstalled) {
+        process.stdout.write(`\u2713 Alias kb='pnpm --silent kb' added
+`);
+      }
+      process.stdout.write(`Run: source ${r.profilePath}
+`);
     }
-  }
-  if (skipped.length > 0) {
-    log3.warn(`Skipped ${skipped.length} manifest(s) during registration`);
-    for (const skip of skipped) {
-      log3.warn(`  \u2022 ${skip.id} [${skip.source}] \u2192 ${skip.reason}`);
-    }
-  }
-  return {
-    registered,
-    skipped,
-    collisions,
-    errors
-  };
-}
-async function disposeAllPlugins(registry2, logger) {
-  const log3 = logger ?? platform.logger;
-  const manifests = registry2.listManifests();
-  const disposePromises = [];
-  for (const cmd of manifests) {
-    const disposeHook = cmd._disposeHook;
-    if (disposeHook && typeof disposeHook === "function") {
-      disposePromises.push(
-        Promise.resolve(disposeHook()).catch((err) => {
-          const errMsg = err instanceof Error ? err.message : String(err);
-          log3.warn(`Dispose hook failed for ${cmd.manifest.id}: ${errMsg}`);
-        })
-      );
-    }
-  }
-  await Promise.allSettled(disposePromises);
+  });
 }
 var log2 = platform.logger.child({ module: "cli:shutdown" });
 var hooks = /* @__PURE__ */ new Set();
@@ -4064,15 +4798,18 @@ async function registerBuiltinCommands(input = {}) {
     return;
   }
   _registered = true;
+  registry.setLogger(log3);
   registry.markPartial(true);
   registeredCommands.length = 0;
   registry.registerGroup(infoGroup);
-  registry.registerGroup(marketplaceGroup);
   registry.registerGroup(registryGroup);
   registry.registerGroup(docsGroup);
   registry.registerGroup(logsGroup);
   registry.registerGroup(authGroup);
   registry.registerGroup(platformGroup);
+  registry.registerGroup(webhookGroup);
+  registry.register(createCompletionCommand(registry));
+  registry.register(diag);
   try {
     const cwd = getContextCwd({ cwd: input.cwd });
     const env = input.env ?? process.env;
@@ -4124,402 +4861,217 @@ async function registerBuiltinCommands(input = {}) {
     _registered = false;
     return;
   }
+  await autoUpdateCompletion(registry).catch(() => {
+  });
   registerShutdownHook(async () => {
     await disposeAllPlugins(registry, log3);
   });
 }
-function renderGroupHelp(group) {
+function renderGroupHelp(opts) {
   const tracker = new TimingTracker();
-  const sortedCommands = [...group.commands].sort(
-    (a, b) => a.name.localeCompare(b.name)
-  );
+  const groupName = opts.segments.join(" ");
   const sections = [];
-  sections.push({
-    items: [
-      `${safeColors.bold("Description")}: ${group.describe}`,
-      `${safeColors.bold("Commands")}: ${sortedCommands.length}`
-    ]
-  });
-  const commandDisplayNames = sortedCommands.map((cmd) => {
-    return cmd.name.replace(/:/g, " ");
-  });
-  const maxNameLength = Math.max(...commandDisplayNames.map((name) => name.length));
-  const commandItems = [];
-  for (let i = 0; i < sortedCommands.length; i++) {
-    const cmd = sortedCommands[i];
-    const displayName = commandDisplayNames[i];
-    if (!cmd || !displayName) {
-      continue;
-    }
-    const paddedName = displayName.padEnd(maxNameLength);
-    const description = cmd.describe || "No description";
-    commandItems.push(`${safeColors.primary(paddedName)}  ${safeColors.muted(description)}`);
-    if (cmd.examples && cmd.examples.length > 0) {
-      for (const example of cmd.examples.slice(0, 2)) {
-        commandItems.push(`  ${safeColors.muted(example)}`);
-      }
+  if (opts.commands && opts.commands.length > 0) {
+    const available = opts.commands.filter((c) => c.available && !c.shadowed);
+    const unavailable = opts.commands.filter((c) => !c.available || c.shadowed);
+    const maxLength = Math.max(
+      ...opts.commands.map((c) => c.manifest.segments.join(" ").length),
+      20
+    );
+    if (available.length > 0) {
+      const items = available.sort((a, b) => a.manifest.segments.join(" ").localeCompare(b.manifest.segments.join(" "))).map((cmd) => {
+        const displayPath = cmd.manifest.segments.join(" ");
+        return `${safeColors.primary(displayPath.padEnd(maxLength))}  ${safeColors.muted(cmd.manifest.describe)}`;
+      });
+      sections.push({ header: "Commands", items });
+    }
+    if (unavailable.length > 0) {
+      const items = unavailable.map((cmd) => {
+        const displayPath = cmd.manifest.segments.join(" ");
+        let line = `${safeColors.muted(displayPath.padEnd(maxLength))}  ${safeColors.muted(cmd.manifest.describe)}`;
+        if (cmd.unavailableReason) {
+          line += `
+   ${safeColors.muted(`Reason: ${cmd.unavailableReason}`)}`;
+        }
+        return line;
+      });
+      sections.push({ header: "Unavailable", items });
     }
+  } else {
+    const sorted = [...opts.childKeys].sort();
+    sections.push({
+      header: "Available",
+      items: sorted.map((k) => safeColors.primary(`  ${k}`))
+    });
   }
   sections.push({
-    header: "Available commands",
-    items: commandItems
-  });
-  sections.push({
-    header: "Next Steps",
-    items: [
-      `kb ${group.name} <command> --help  ${safeColors.muted("Get help for a specific command")}`
-    ]
+    items: [safeColors.muted(`kb ${groupName} <command> --help`)]
   });
   return sideBorderBox({
-    title: `\u{1F4E6} ${group.name}`,
+    title: groupName,
     sections,
     status: "success",
     timing: tracker.total()
   });
 }
-function collectManifestVersions(commands) {
-  const versions = /* @__PURE__ */ new Set();
-  for (const cmd of commands) {
-    const schema = cmd.manifest.manifestV2?.schema;
-    if (typeof schema === "string") {
-      const tail = schema.split("/").pop() ?? schema;
-      const match = tail.match(/\d+/);
-      versions.add(match ? `v${match[0]}` : tail);
-    } else {
-      versions.add("v2");
-    }
+function truncate(s, max) {
+  if (s.length <= max) {
+    return s;
   }
-  return Array.from(versions).sort();
+  return s.slice(0, max - 1) + "\u2026";
 }
-function renderGlobalHelp(groups, standalone) {
-  const lines = [];
-  lines.push(
-    colors.cyan(colors.bold("KB Labs CLI")) + " - Project management and automation tool"
-  );
-  lines.push("");
-  lines.push(colors.bold("Usage:") + " kb [command] [options]");
-  lines.push("");
-  if (groups.length > 0) {
-    lines.push(colors.bold("Product Commands:"));
-    lines.push("");
-    for (const group of groups.sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(
-        `  ${colors.cyan(group.name.padEnd(12))}  ${colors.dim(
-          group.describe ?? ""
-        )}`
-      );
-    }
-    lines.push("");
-  }
-  if (standalone.length > 0) {
-    lines.push(colors.bold("System Commands:"));
-    lines.push("");
-    for (const cmd of standalone.sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(
-        `  ${colors.cyan(cmd.name.padEnd(12))}  ${colors.dim(cmd.describe)}`
-      );
+function renderGlobalHelp(registry2) {
+  const cols = typeof process !== "undefined" && process.stdout?.columns || 80;
+  const sections = [];
+  const systemEntries = registry2.listSystemTopLevel().sort((a, b) => a.name.localeCompare(b.name));
+  if (systemEntries.length > 0) {
+    const nameLen = Math.max(...systemEntries.map((e) => e.name.length), 8);
+    const items = systemEntries.map(
+      ({ name, describe }) => `${colors.cyan(name.padEnd(nameLen))}  ${colors.dim(describe)}`
+    );
+    sections.push({ header: "Commands", items });
+  }
+  const allCommands = registry2.listCommands();
+  const groupNames = [...new Set(allCommands.map((c) => c.manifest.group))].sort();
+  if (groupNames.length > 0) {
+    const nameLen = Math.max(...groupNames.map((g) => g.length), 8);
+    const entries = groupNames.map((name) => ({
+      name,
+      describe: registry2.getPluginGroupDescribe([name]) ?? ""
+    }));
+    const GAP = 4;
+    const minDescLen = 24;
+    const twoColMinWidth = (nameLen + 2 + minDescLen) * 2 + GAP + 4;
+    const useTwoCols = cols >= twoColMinWidth;
+    let items;
+    if (useTwoCols) {
+      const descMax = Math.max(minDescLen, Math.floor((cols - 4 - (nameLen + 2) * 2 - GAP) / 2));
+      const half = Math.ceil(entries.length / 2);
+      const left = entries.slice(0, half);
+      const right = entries.slice(half);
+      items = left.map((l, i) => {
+        const r = right[i];
+        const lName = colors.cyan(l.name.padEnd(nameLen));
+        const lDesc = l.describe ? colors.dim(truncate(l.describe, descMax).padEnd(descMax)) : " ".repeat(descMax);
+        if (!r) {
+          return `${lName}  ${lDesc.trimEnd()}`;
+        }
+        const rName = colors.cyan(r.name.padEnd(nameLen));
+        const rDesc = r.describe ? colors.dim(truncate(r.describe, descMax)) : "";
+        return `${lName}  ${lDesc}  ${" ".repeat(GAP - 2)}${rName}  ${rDesc}`;
+      });
+    } else {
+      const descMax = Math.max(24, cols - 4 - nameLen - 2);
+      items = entries.map(({ name, describe }) => {
+        const n = colors.cyan(name.padEnd(nameLen));
+        return describe ? `${n}  ${colors.dim(truncate(describe, descMax))}` : n;
+      });
     }
-    lines.push("");
+    sections.push({ header: "Plugins", items });
   }
-  lines.push(colors.bold("Global Options:"));
-  lines.push("");
-  lines.push(
-    `  ${colors.cyan("--help".padEnd(12))}  ${colors.dim("Show help information")}`
-  );
-  lines.push(
-    `  ${colors.cyan("--version".padEnd(12))}  ${colors.dim("Show CLI version")}`
-  );
-  lines.push(
-    `  ${colors.cyan("--json".padEnd(12))}  ${colors.dim("Output in JSON format")}`
-  );
-  lines.push(
-    `  ${colors.cyan("--quiet".padEnd(12))}  ${colors.dim("Suppress detailed output")}`
-  );
-  lines.push("");
-  lines.push(
-    colors.dim(
-      "Use 'kb <group> --help' to see commands for a specific product."
-    )
-  );
-  return lines.join("\n");
+  sections.push({ items: [`kb ${colors.dim("<command> [subcommand] [flags]")}    ${colors.dim("\xB7")}    ${colors.dim("kb <command> --help for details")}`] });
+  return sideBorderBox({ title: "KB Labs CLI", sections, status: "info" });
 }
-function renderGlobalHelpNew(registry2) {
-  const products = registry2.listProductGroups();
-  const systemGroups = registry2.listGroups?.() || [];
-  const commandsInGroups = /* @__PURE__ */ new Set();
-  for (const group of systemGroups) {
-    for (const cmd of group.commands) {
-      commandsInGroups.add(cmd.name);
-      for (const alias of cmd.aliases || []) {
-        commandsInGroups.add(alias);
-      }
-    }
-  }
-  const standalone = registry2.list().filter((cmd) => {
-    if (commandsInGroups.has(cmd.name)) {
-      return false;
-    }
-    return !cmd.category || cmd.category === "system";
-  });
+function renderPluginsHelp(registry2) {
+  const commands = registry2.listCommandsUnder(["marketplace"]);
   const sections = [];
-  if (products.length > 0) {
-    const maxProductNameLength = Math.max(
-      ...products.map((p) => p.name.length),
-      12
-    );
-    const productItems = products.sort((a, b) => a.name.localeCompare(b.name)).map((product) => {
-      const availableCount = product.commands.filter(
-        (c) => c.available && !c.shadowed
-      ).length;
-      const badge = colors.green(`(${availableCount})`);
-      return `${colors.cyan(
-        product.name.padEnd(maxProductNameLength)
-      )}  ${badge}`;
-    });
-    sections.push({
-      header: "Products",
-      items: productItems
-    });
-  }
-  if (systemGroups.length > 0) {
-    const maxGroupNameLength = Math.max(
-      ...systemGroups.map((g) => g.name.length),
-      20
-    );
-    const groupItems = systemGroups.sort((a, b) => a.name.localeCompare(b.name)).map((group) => {
-      const commandCount = group.commands.length;
-      const badge = colors.green(`(${commandCount})`);
-      return `${colors.cyan(group.name.padEnd(maxGroupNameLength))}  ${badge}`;
-    });
-    sections.push({
-      header: "System Commands",
-      items: groupItems
-    });
-  }
-  if (standalone.length > 0) {
-    const maxCommandNameLength = Math.max(
-      ...standalone.map((c) => c.name.length),
-      12
-    );
-    const standaloneItems = standalone.sort((a, b) => a.name.localeCompare(b.name)).map(
-      (cmd) => `${colors.cyan(cmd.name.padEnd(maxCommandNameLength))}  ${colors.dim(
-        cmd.describe
-      )}`
-    );
-    sections.push({
-      header: "Other Commands",
-      items: standaloneItems
+  if (commands.length > 0) {
+    const maxLength = Math.max(...commands.map((c) => c.manifest.segments.join(" ").length), 20);
+    const items = commands.filter((c) => c.available && !c.shadowed).sort((a, b) => a.manifest.segments.join(" ").localeCompare(b.manifest.segments.join(" "))).map((cmd) => {
+      const displayPath = cmd.manifest.segments.join(" ");
+      return `${colors.cyan(displayPath.padEnd(maxLength))}  ${colors.dim(cmd.manifest.describe)}`;
     });
+    sections.push({ header: "Plugin Management", items });
   }
-  const globalOptions = [
-    { name: "--help", desc: "Show help information" },
-    { name: "--version", desc: "Show CLI version" },
-    { name: "--json", desc: "Output in JSON format" },
-    { name: "--quiet", desc: "Suppress detailed output" }
-  ];
-  const maxOptionNameLength = Math.max(
-    ...globalOptions.map((o) => o.name.length),
-    12
-  );
-  const optionItems = globalOptions.map(
-    (option) => `${colors.cyan(option.name.padEnd(maxOptionNameLength))}  ${colors.dim(
-      option.desc
-    )}`
-  );
-  sections.push({
-    header: "Global Options",
-    items: optionItems
-  });
-  const nextStepsItems = [];
-  const firstProduct = products[0];
-  if (firstProduct) {
-    nextStepsItems.push(
-      `${colors.cyan(
-        `kb ${firstProduct.name} --help`
-      )}  ${colors.dim("Explore product commands")}`
-    );
-  }
-  const marketplaceGroup2 = systemGroups.find((g) => g.name === "marketplace");
-  if (marketplaceGroup2) {
-    nextStepsItems.push(
-      `${colors.cyan("kb marketplace")}  ${colors.dim("Open marketplace commands")}`
-    );
-  }
-  nextStepsItems.push("");
-  nextStepsItems.push(
-    colors.dim("Use 'kb <product> --help' or 'kb <group> --help' to see commands for a specific product or group.")
-  );
   sections.push({
-    header: "Next Steps",
-    items: nextStepsItems
-  });
-  return sideBorderBox({
-    title: "KB Labs CLI",
-    sections,
-    status: "info"
+    items: [colors.dim("kb marketplace <command> --help")]
   });
+  return sideBorderBox({ title: "\u{1F9E9} Plugin Management", sections, status: "info" });
 }
-function renderPluginsHelp(registry2) {
-  const tracker = new TimingTracker();
-  registry2.list().filter(
-    (cmd) => cmd.name?.startsWith("marketplace:") || cmd.category === "system"
-  );
-  const sections = [];
-  const commandMap = {
-    "marketplace:install": "Install package(s) from marketplace",
-    "marketplace:update": "Update package(s) from marketplace",
-    "marketplace:list": "List all discovered plugins",
-    "marketplace:enable": "Enable a plugin",
-    "marketplace:disable": "Disable a plugin",
-    "marketplace:link": "Link a local plugin for development",
-    "marketplace:unlink": "Unlink a local plugin",
-    "marketplace:doctor": "Diagnose plugin issues",
-    "marketplace:scaffold": "Generate a new plugin template",
-    "marketplace:clear-cache": "Clear plugin discovery cache"
-  };
-  const maxLength = Math.max(
-    ...Object.keys(commandMap).map((c) => c.length),
-    20
-  );
-  const commandItems = Object.entries(commandMap).map(
-    ([cmdName, desc]) => `${colors.cyan(cmdName.padEnd(maxLength))}  ${colors.dim(desc)}`
-  );
-  sections.push({
-    header: "Plugin Management Commands",
-    items: commandItems
-  });
-  const examples = [
-    `kb marketplace list                    ${colors.dim("List all plugins")}`,
-    `kb marketplace enable @kb-labs/devlink-cli  ${colors.dim("Enable a plugin")}`,
-    `kb marketplace doctor                 ${colors.dim("Diagnose plugin issues")}`,
-    `kb marketplace scaffold my-plugin      ${colors.dim("Generate plugin template")}`
-  ];
-  sections.push({
-    header: "Examples",
-    items: examples.map((ex) => colors.dim(ex))
-  });
-  sections.push({
-    header: "Next Steps",
-    items: [colors.dim("Use 'kb marketplace <command> --help' for detailed help")]
-  });
-  return sideBorderBox({
-    title: "\u{1F9E9} Plugin Management",
-    sections,
-    status: "info",
-    timing: tracker.total()
-  });
+var BOX_OVERHEAD = 3;
+var PREFIX_LEN = 2;
+var GAP_LEN = 2;
+function truncateDesc(desc, maxLength) {
+  const cols = typeof process !== "undefined" && process.stdout?.columns || 80;
+  const avail = cols - BOX_OVERHEAD - PREFIX_LEN - maxLength - GAP_LEN;
+  if (avail < 10 || desc.length <= avail) {
+    return desc;
+  }
+  return desc.slice(0, avail - 1) + "\u2026";
 }
 function renderProductHelp(groupName, commands) {
-  const tracker = new TimingTracker();
   const sections = [];
-  const manifestVersions = collectManifestVersions(commands);
-  if (manifestVersions.length > 0) {
-    sections.push({
-      header: "Manifest",
-      items: [colors.cyan(manifestVersions.join(" + "))]
-    });
-  }
   const availableMap = /* @__PURE__ */ new Map();
   const unavailableMap = /* @__PURE__ */ new Map();
   for (const cmd of commands) {
+    const key = cmd.manifest.segments.join(" ");
     if (cmd.available && !cmd.shadowed) {
-      if (!availableMap.has(cmd.manifest.id)) {
-        availableMap.set(cmd.manifest.id, cmd);
+      if (!availableMap.has(key)) {
+        availableMap.set(key, cmd);
       }
-    } else if (!unavailableMap.has(cmd.manifest.id)) {
-      unavailableMap.set(cmd.manifest.id, cmd);
+    } else if (!unavailableMap.has(key)) {
+      unavailableMap.set(key, cmd);
     }
   }
-  const available = Array.from(availableMap.values()).sort(
-    (a, b) => a.manifest.id.localeCompare(b.manifest.id)
-  );
+  const available = Array.from(availableMap.values());
   const unavailable = Array.from(unavailableMap.values()).sort(
-    (a, b) => a.manifest.id.localeCompare(b.manifest.id)
+    (a, b) => a.manifest.segments.join(" ").localeCompare(b.manifest.segments.join(" "))
   );
+  const hasUnavailable = unavailable.length > 0;
+  const displayPath = (cmd) => cmd.manifest.segments.join(" ");
   const maxLength = Math.max(
-    ...[...available, ...unavailable].map((c) => c.manifest.id.replace(/:/g, " ").length),
+    ...[...available, ...unavailable].map((c) => displayPath(c).length),
     20
   );
-  const availableItems = [];
-  for (const cmd of available) {
-    const status = colors.green("\u2713");
-    const displayId = cmd.manifest.id.replace(/:/g, " ");
-    const paddedId = displayId.padEnd(maxLength);
-    availableItems.push(
-      `${status} ${colors.cyan(paddedId)}  ${colors.dim(
-        cmd.manifest.describe
-      )}`
-    );
-    if (cmd.manifest.examples && cmd.manifest.examples.length > 0) {
-      for (const example of cmd.manifest.examples.slice(0, 2)) {
-        availableItems.push(`   ${colors.dim(example)}`);
+  const hasCategories = available.some((c) => c.manifest.category);
+  const prefix = hasUnavailable ? `${colors.green("\u2713")} ` : "  ";
+  if (hasCategories) {
+    const categoryOrder = [];
+    const categoryMap = /* @__PURE__ */ new Map();
+    for (const cmd of available) {
+      const cat = cmd.manifest.category ?? "";
+      if (!categoryMap.has(cat)) {
+        categoryOrder.push(cat);
+        categoryMap.set(cat, []);
       }
+      categoryMap.get(cat).push(cmd);
+    }
+    for (const cat of categoryOrder) {
+      const cmds = categoryMap.get(cat).sort((a, b) => displayPath(a).localeCompare(displayPath(b)));
+      const items = cmds.map((cmd) => {
+        const paddedPath = displayPath(cmd).padEnd(maxLength);
+        return `${prefix}${colors.cyan(paddedPath)}  ${colors.dim(truncateDesc(cmd.manifest.describe, maxLength))}`;
+      });
+      sections.push({ header: cat || "Commands", items });
     }
+  } else {
+    const availableItems = [...available].sort((a, b) => displayPath(a).localeCompare(displayPath(b))).map((cmd) => {
+      const paddedPath = displayPath(cmd).padEnd(maxLength);
+      return `${prefix}${colors.cyan(paddedPath)}  ${colors.dim(cmd.manifest.describe)}`;
+    });
+    sections.push({ header: "Commands", items: availableItems });
   }
-  sections.push({
-    header: "Available Commands",
-    items: availableItems
-  });
-  if (unavailable.length > 0) {
+  if (hasUnavailable) {
     const unavailableItems = [];
     for (const cmd of unavailable) {
-      const status = colors.red("\u2717");
-      const displayId = cmd.manifest.id.replace(/:/g, " ");
-      const paddedId = displayId.padEnd(maxLength);
-      unavailableItems.push(
-        `${status} ${colors.dim(paddedId)}  ${colors.dim(
-          cmd.manifest.describe
-        )}`
-      );
+      const paddedPath = displayPath(cmd).padEnd(maxLength);
+      unavailableItems.push(`${colors.red("\u2717")} ${colors.dim(paddedPath)}  ${colors.dim(cmd.manifest.describe)}`);
       if (cmd.unavailableReason) {
-        unavailableItems.push(
-          `   ${colors.red(`Reason: ${cmd.unavailableReason}`)}`
-        );
+        unavailableItems.push(`   ${colors.red(`Reason: ${cmd.unavailableReason}`)}`);
       }
       if (cmd.hint) {
         unavailableItems.push(`   ${colors.yellow(`Hint: ${cmd.hint}`)}`);
       }
     }
-    sections.push({
-      header: "Unavailable",
-      items: unavailableItems
-    });
-  }
-  const uniqueCommands = /* @__PURE__ */ new Map();
-  for (const cmd of available) {
-    if (!uniqueCommands.has(cmd.manifest.id)) {
-      uniqueCommands.set(cmd.manifest.id, cmd);
-    }
-  }
-  const nextStepsItems = Array.from(uniqueCommands.values()).slice(0, 3).map((cmd) => {
-    const displayId = cmd.manifest.id.replace(/:/g, " ");
-    return `${colors.cyan(`kb ${displayId}`)}  ${colors.dim(
-      cmd.manifest.describe
-    )}`;
-  });
-  if (nextStepsItems.length === 0) {
-    nextStepsItems.push(colors.dim("No available commands in this product"));
-  } else {
-    nextStepsItems.push("");
-    nextStepsItems.push(
-      colors.dim(
-        `Use 'kb ${groupName} <command> --help' for detailed help`
-      )
-    );
+    sections.push({ header: "Unavailable", items: unavailableItems });
   }
-  nextStepsItems.push("");
-  nextStepsItems.push(
-    colors.dim("Use 'kb --help' to see all products and system commands.")
-  );
   sections.push({
-    header: "Next Steps",
-    items: nextStepsItems
+    items: [colors.dim(`kb ${groupName} <command> --help`)]
   });
   return sideBorderBox({
     title: groupName,
     sections,
-    status: "info",
-    timing: tracker.total()
+    status: "info"
   });
 }
 function renderManifestCommandHelp(registered) {
@@ -4609,9 +5161,47 @@ function groupCommands(commands, onlyAvailable) {
   );
 }
 
+// src/presentation/schema-generator.ts
+function flagToProperty(flag) {
+  const prop = {
+    type: flag.type === "array" ? "array" : flag.type,
+    description: flag.description ?? flag.describe
+  };
+  if (flag.default !== void 0) {
+    prop.default = flag.default;
+  }
+  if (flag.choices?.length) {
+    prop.enum = flag.choices;
+  }
+  if (flag.type === "array") {
+    prop.items = { type: "string" };
+  }
+  return prop;
+}
+function generateCommandSchema(manifest) {
+  const properties = {};
+  const required = [];
+  for (const flag of manifest.flags ?? []) {
+    properties[flag.name] = flagToProperty(flag);
+    if (flag.required) {
+      required.push(flag.name);
+    }
+  }
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: manifest.segments.join(" "),
+    description: manifest.describe,
+    ...manifest.operationType ? { operationType: manifest.operationType } : {},
+    type: "object",
+    properties,
+    ...required.length ? { required } : {},
+    examples: manifest.examples ?? []
+  };
+}
+
 // src/index.ts
 init_discover();
 
-export { discoverManifests, discoverManifestsByNamespace, findCommand, findCommandWithType, generateExamples, health, hello, logsContext, logsDiagnose, logsGet, logsQuery, logsSearch, logsStats, logsSummarize, registerBuiltinCommands, registry, renderGlobalHelp, renderGlobalHelpNew, renderGroupHelp, renderHelp, renderManifestCommandHelp, renderPluginsHelp, renderProductHelp, version };
+export { TrieBackedRegistry, createCompletionCommand, createRegistry, discoverManifests, discoverManifestsByNamespace, generateCommandSchema, generateExamples, health, hello, logsContext, logsDiagnose, logsGet, logsQuery, logsSearch, logsStats, logsSummarize, registerBuiltinCommands, registry, renderGlobalHelp, renderGroupHelp, renderHelp, renderManifestCommandHelp, renderPluginsHelp, renderProductHelp, version };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map