@cleocode/cleo 2026.5.83 → 2026.5.84

package/dist/cli/index.js

@@ -268,16 +268,6 @@ async function runCommand(cmd, opts) {
   }
   return { result };
 }
-async function resolveSubCommand(cmd, rawArgs, parent) {
-  const subCommands2 = await resolveValue(cmd.subCommands);
-  if (subCommands2 && Object.keys(subCommands2).length > 0) {
-    const subCommandArgIndex = rawArgs.findIndex((arg) => !arg.startsWith("-"));
-    const subCommandName = rawArgs[subCommandArgIndex];
-    const subCommand = await resolveValue(subCommands2[subCommandName]);
-    if (subCommand) return resolveSubCommand(subCommand, rawArgs.slice(subCommandArgIndex + 1), cmd);
-  }
-  return [cmd, parent];
-}
 async function showUsage(cmd, parent) {
   try {
     console.log(await renderUsage(cmd, parent) + "\n");
@@ -347,26 +337,6 @@ async function renderUsage(cmd, parent) {
   }
   return usageLines.filter((l) => typeof l === "string").join("\n");
 }
-async function runMain(cmd, opts = {}) {
-  const rawArgs = opts.rawArgs || process.argv.slice(2);
-  const showUsage$1 = opts.showUsage || showUsage;
-  try {
-    if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
-      await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
-      process.exit(0);
-    } else if (rawArgs.length === 1 && rawArgs[0] === "--version") {
-      const meta = typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
-      if (!meta?.version) throw new CLIError("No version specified", "E_NO_VERSION");
-      console.log(meta.version);
-    } else await runCommand(cmd, { rawArgs });
-  } catch (error) {
-    if (error instanceof CLIError) {
-      await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
-      console.error(error.message);
-    } else console.error(error, "\n");
-    process.exit(1);
-  }
-}
 var CLIError, noColor, _c, bold, cyan, gray, underline, negativePrefixRe;
 var init_dist = __esm({
   "node_modules/.pnpm/citty@0.2.1/node_modules/citty/dist/index.mjs"() {
@@ -9063,6 +9033,25 @@ var init_registry = __esm({
           }
         ]
       },
+      {
+        gateway: "query",
+        domain: "pipeline",
+        operation: "release.pr-status",
+        description: "Poll GitHub CI check statuses for the open release PR matching release/v<version> (T9095)",
+        tier: 1,
+        idempotent: true,
+        sessionRequired: false,
+        requiredParams: ["version"],
+        params: [
+          {
+            name: "version",
+            type: "string",
+            required: true,
+            description: "Release version (e.g. 2026.5.43 or v2026.5.43)",
+            cli: { positional: true }
+          }
+        ]
+      },
       // release.prepare/changelog/commit/tag/push/gates.run removed — merged into release.ship via step param (T5615)
       {
         gateway: "mutate",
@@ -27375,6 +27364,7 @@ var init_pipeline3 = __esm({
           "release.show",
           "release.channel.show",
           "release.changelog.since",
+          "release.pr-status",
           "phase.show",
           "phase.list",
           "chain.show",
@@ -41102,7 +41092,10 @@ import {
   publishDocs,
   rankDocs,
   readJson,
-  searchDocs as searchDocs2
+  recordPublication,
+  searchDocs as searchDocs2,
+  statusDocs,
+  syncFromGit
 } from "@cleocode/core/internal";
 async function getScriptNames(projectRoot) {
   const scriptsDir = join14(projectRoot, "scripts");
@@ -41166,7 +41159,7 @@ async function runGapCheck(_projectRoot, filterId) {
   }
   return results;
 }
-var addCommand4, listCommand7, fetchCommand, removeCommand2, generateCommand, exportCommand4, searchCommand, mergeCommand, graphCommand, rankCommand, versionsCommand, publishCommand2, syncCommand3, gapCheckCommand, docsCommand;
+var addCommand4, listCommand7, fetchCommand, removeCommand2, generateCommand, exportCommand4, searchCommand, mergeCommand, graphCommand, rankCommand, versionsCommand, publishCommand2, syncCommand3, statusCommand6, gapCheckCommand, docsCommand;
 var init_docs3 = __esm({
   "packages/cleo/src/cli/commands/docs.ts"() {
     "use strict";
@@ -41718,30 +41711,87 @@ var init_docs3 = __esm({
             attachmentId: args.attachment ?? void 0,
             projectRoot
           });
+          try {
+            await recordPublication({
+              ownerId: result.ownerId,
+              blobName: result.blobName,
+              publishedPath: result.relativePath,
+              lastBlobSha: result.blobSha256,
+              projectRoot
+            });
+          } catch {
+          }
           cliOutput(result, { command: "docs publish", operation: "docs.publish" });
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          cliOutput(
-            formatError5(new CleoError3(1 /* GENERAL_ERROR */, `docs publish failed: ${message}`)),
-            { command: "docs publish", operation: "docs.publish" }
-          );
+          cliError(`docs publish failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_PUBLISH_FAILED"
+          });
           process.exit(1 /* GENERAL_ERROR */);
         }
       }
     });
     syncCommand3 = defineCommand({
-      meta: { name: "sync", description: "Run drift detection between scripts and docs index" },
+      meta: {
+        name: "sync",
+        description: "Bidirectional docs sync. Use --from <path> --for <ownerId> to ingest a git file as a new blob version. Without --from, runs the legacy drift check between scripts/ and COMMANDS-INDEX.json."
+      },
       args: {
+        from: {
+          type: "string",
+          description: "Git-tracked file path to ingest as a new blob version (triggers reverse-ingest mode)"
+        },
+        for: {
+          type: "string",
+          description: "Owner entity ID for reverse-ingest mode (T###, ses_*, O-*). Required when --from is set."
+        },
+        name: {
+          type: "string",
+          description: "Override the blob name used in the manifest. Default: basename of --from."
+        },
+        "content-type": {
+          type: "string",
+          description: "IANA MIME type recorded with the new blob version (default: application/octet-stream)"
+        },
         quick: {
           type: "boolean",
-          description: "Quick check (commands only)"
+          description: "Legacy mode only: quick check (commands only)"
         },
         strict: {
           type: "boolean",
-          description: "Exit with error on any drift"
+          description: "Legacy mode only: exit with error on any drift"
         }
       },
       async run({ args }) {
+        if (args.from) {
+          const projectRoot = getProjectRoot27();
+          const ownerId = args.for ?? void 0;
+          if (!ownerId) {
+            cliError(
+              "--for <ownerId> is required when --from <path> is set",
+              6 /* VALIDATION_ERROR */,
+              { name: "E_VALIDATION" }
+            );
+            process.exit(6 /* VALIDATION_ERROR */);
+          }
+          try {
+            const result = await syncFromGit({
+              ownerId: String(ownerId),
+              fromPath: String(args.from),
+              blobName: args.name ?? void 0,
+              contentType: args["content-type"] ?? void 0,
+              projectRoot
+            });
+            cliOutput(result, { command: "docs sync", operation: "docs.sync" });
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            cliError(`docs sync failed: ${message}`, 1 /* GENERAL_ERROR */, {
+              name: "E_DOCS_SYNC_FAILED"
+            });
+            process.exit(1 /* GENERAL_ERROR */);
+          }
+          return;
+        }
         try {
           const projectRoot = process.cwd();
           const result = await detectDrift(projectRoot);
@@ -41769,6 +41819,34 @@ var init_docs3 = __esm({
         }
       }
     });
+    statusCommand6 = defineCommand({
+      meta: {
+        name: "status",
+        description: "Compare published files on disk against the docs SSoT and report drift. Exits 0 when all entries are in-sync, 2 when any drift is present."
+      },
+      args: {
+        json: {
+          type: "boolean",
+          description: "Emit LAFS JSON envelope"
+        }
+      },
+      async run() {
+        const projectRoot = getProjectRoot27();
+        try {
+          const result = await statusDocs({ projectRoot });
+          cliOutput(result, { command: "docs status", operation: "docs.status" });
+          if (!result.allInSync) {
+            process.exit(2);
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          cliError(`docs status failed: ${message}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_STATUS_FAILED"
+          });
+          process.exit(1 /* GENERAL_ERROR */);
+        }
+      }
+    });
     gapCheckCommand = defineCommand({
       meta: {
         name: "gap-check",
@@ -41812,7 +41890,7 @@ var init_docs3 = __esm({
     docsCommand = defineCommand({
       meta: {
         name: "docs",
-        description: "Documentation attachment management (add/list/fetch/remove), llmtxt primitives (search/merge/graph/rank/versions/publish), and drift detection (sync/gap-check)"
+        description: "Documentation attachment management (add/list/fetch/remove), llmtxt primitives (search/merge/graph/rank/versions/publish), and drift detection (sync/status/gap-check)"
       },
       subCommands: {
         add: addCommand4,
@@ -41828,6 +41906,7 @@ var init_docs3 = __esm({
         versions: versionsCommand,
         publish: publishCommand2,
         sync: syncCommand3,
+        status: statusCommand6,
         "gap-check": gapCheckCommand
       },
       async run({ cmd, rawArgs }) {
@@ -43490,7 +43569,7 @@ function formatBytes(bytes) {
   const value = bytes / 1024 ** exp;
   return `${value.toFixed(exp === 0 ? 0 : 1)} ${units[exp] ?? "B"}`;
 }
-var runCommand2, statusCommand6, worktreesCommand, tempCommand, gcCommand;
+var runCommand2, statusCommand7, worktreesCommand, tempCommand, gcCommand;
 var init_gc = __esm({
   "packages/cleo/src/cli/commands/gc.ts"() {
     "use strict";
@@ -43543,7 +43622,7 @@ var init_gc = __esm({
         }
       }
     });
-    statusCommand6 = defineCommand({
+    statusCommand7 = defineCommand({
       meta: {
         name: "status",
         description: "Show last GC run stats, disk usage, and escalation state"
@@ -43706,7 +43785,7 @@ var init_gc = __esm({
       },
       subCommands: {
         run: runCommand2,
-        status: statusCommand6,
+        status: statusCommand7,
         worktrees: worktreesCommand,
         temp: tempCommand
       },
@@ -44005,7 +44084,7 @@ function applyJsonFlag(jsonFlag) {
     setFormatContext({ format: "json", source: "flag", quiet: false });
   }
 }
-var statusCommand7, resolveCommand, depsCommand2, rawCommand, discoverCommand, searchCommand2, augmentCommand, contextCommand2, impactCommand2, impactFullCommand, clustersCommand, flowsCommand, diffCommand, routeMapCommand, shapeCheckCommand, searchCodeCommand, wikiCommand, hotPathsCommand, hotNodesCommand, coldSymbolsCommand, orphansCommand, queryCommand, initCommand, syncCommand4, reconcileCommand, livingFullContextCommand, livingTaskFootprintCommand, livingBrainAnchorsCommand, livingWhyCommand, livingConduitScanCommand, livingCommand, graphCommand2;
+var statusCommand8, resolveCommand, depsCommand2, rawCommand, discoverCommand, searchCommand2, augmentCommand, contextCommand2, impactCommand2, impactFullCommand, clustersCommand, flowsCommand, diffCommand, routeMapCommand, shapeCheckCommand, searchCodeCommand, wikiCommand, hotPathsCommand, hotNodesCommand, coldSymbolsCommand, orphansCommand, queryCommand, initCommand, syncCommand4, reconcileCommand, livingFullContextCommand, livingTaskFootprintCommand, livingBrainAnchorsCommand, livingWhyCommand, livingConduitScanCommand, livingCommand, graphCommand2;
 var init_graph2 = __esm({
   "packages/cleo/src/cli/commands/graph.ts"() {
     "use strict";
@@ -44013,7 +44092,7 @@ var init_graph2 = __esm({
     init_cli();
     init_format_context();
     init_renderers();
-    statusCommand7 = defineCommand({
+    statusCommand8 = defineCommand({
       meta: {
         name: "status",
         description: "Show code intelligence index freshness: file count, node/relation counts, last indexed time."
@@ -44800,7 +44879,7 @@ var init_graph2 = __esm({
         description: "Project-scoped code intelligence: symbol graph, impact analysis, clusters, flows"
       },
       subCommands: {
-        status: statusCommand7,
+        status: statusCommand8,
         resolve: resolveCommand,
         deps: depsCommand2,
         raw: rawCommand,
@@ -49723,7 +49802,7 @@ function applyJsonFlag2(jsonFlag) {
     setFormatContext({ format: "json", source: "flag", quiet: false });
   }
 }
-var initCommand3, registerCommand2, unregisterCommand, listCommand12, statusCommand8, showCommand8, resolveCommand2, discoverCommand2, augmentCommand2, setupCommand, searchCommand3, depsCommand3, criticalPathCommand2, blockingCommand, orphansCommand2, syncCommand5, reconcileCommand2, graphCommand3, shareStatusCommand, transferPreviewCommand, transferCommand, permissionSetCommand, permissionCommand, shareExportCommand, shareImportCommand, shareCommand, clustersCommand2, flowsCommand2, contextCommand4, impactCommand3, analyzeCommand3, projectsListCommand, projectsRegisterCommand, projectsRemoveCommand, projectsScanCommand, projectsCleanCommand, projectsCommand, refreshBridgeCommand, exportCommand6, diffCommand2, queryCommand2, routeMapCommand2, shapeCheckCommand2, fullContextCommand, taskFootprintCommand, brainAnchorsCommand, whyCommand, impactFullCommand2, conduitScanCommand, taskSymbolsCommand, searchCodeCommand2, contractsSyncCommand, contractsShowCommand, contractsLinkTasksCommand, contractsCommand, groupCommand, wikiCommand2, hotPathsCommand2, hotNodesCommand2, coldSymbolsCommand2, sigilSyncCommand, sigilListCommand, sigilCommand, topEntriesCommand, nexusCommand;
+var initCommand3, registerCommand2, unregisterCommand, listCommand12, statusCommand9, showCommand8, resolveCommand2, discoverCommand2, augmentCommand2, setupCommand, searchCommand3, depsCommand3, criticalPathCommand2, blockingCommand, orphansCommand2, syncCommand5, reconcileCommand2, graphCommand3, shareStatusCommand, transferPreviewCommand, transferCommand, permissionSetCommand, permissionCommand, shareExportCommand, shareImportCommand, shareCommand, clustersCommand2, flowsCommand2, contextCommand4, impactCommand3, analyzeCommand3, projectsListCommand, projectsRegisterCommand, projectsRemoveCommand, projectsScanCommand, projectsCleanCommand, projectsCommand, refreshBridgeCommand, exportCommand6, diffCommand2, queryCommand2, routeMapCommand2, shapeCheckCommand2, fullContextCommand, taskFootprintCommand, brainAnchorsCommand, whyCommand, impactFullCommand2, conduitScanCommand, taskSymbolsCommand, searchCodeCommand2, contractsSyncCommand, contractsShowCommand, contractsLinkTasksCommand, contractsCommand, groupCommand, wikiCommand2, hotPathsCommand2, hotNodesCommand2, coldSymbolsCommand2, sigilSyncCommand, sigilListCommand, sigilCommand, topEntriesCommand, nexusCommand;
 var init_nexus4 = __esm({
   "packages/cleo/src/cli/commands/nexus.ts"() {
     "use strict";
@@ -49795,7 +49874,7 @@ var init_nexus4 = __esm({
         await dispatchFromCli("query", "nexus", "list", {}, { command: "nexus" });
       }
     });
-    statusCommand8 = defineCommand({
+    statusCommand9 = defineCommand({
       meta: {
         name: "status",
         description: "Show code intelligence index freshness: file count, node/relation counts, last indexed time, stale files. Falls back to NEXUS registry status if code-intelligence index is unavailable."
@@ -52224,7 +52303,7 @@ var init_nexus4 = __esm({
         register: registerCommand2,
         unregister: unregisterCommand,
         list: listCommand12,
-        status: statusCommand8,
+        status: statusCommand9,
         show: showCommand8,
         resolve: resolveCommand2,
         discover: discoverCommand2,
@@ -52363,7 +52442,7 @@ function formatRollupTable(rollup) {
   }
   return lines.join("\n");
 }
-var rollupCommand, startCommand5, statusCommand9, analyzeCommand4, readyCommand, nextCommand2, wavesCommand2, planCommand, spawnCommand2, validateCommand6, contextCommand5, ivtrCommand, parallelCommand, tesseraListCommand, tesseraInstantiateCommand, tesseraCommand, unblockCommand, bootstrapCommand, classifyCommand, fanoutStatusCommand, handoffCommand, spawnExecuteCommand, fanoutCommand, pruneCommand, worktreeCompleteCommand, conduitStatusCommand, conduitPeekCommand, conduitStartCommand, conduitStopCommand, approveCommand, rejectCommand, pendingCommand, conduitSendCommand, orchestrateCommand;
+var rollupCommand, startCommand5, statusCommand10, analyzeCommand4, readyCommand, nextCommand2, wavesCommand2, planCommand, spawnCommand2, validateCommand6, contextCommand5, ivtrCommand, parallelCommand, tesseraListCommand, tesseraInstantiateCommand, tesseraCommand, unblockCommand, bootstrapCommand, classifyCommand, fanoutStatusCommand, handoffCommand, spawnExecuteCommand, fanoutCommand, pruneCommand, worktreeCompleteCommand, conduitStatusCommand, conduitPeekCommand, conduitStartCommand, conduitStopCommand, approveCommand, rejectCommand, pendingCommand, conduitSendCommand, orchestrateCommand;
 var init_orchestrate3 = __esm({
   "packages/cleo/src/cli/commands/orchestrate.ts"() {
     "use strict";
@@ -52415,7 +52494,7 @@ var init_orchestrate3 = __esm({
         );
       }
     });
-    statusCommand9 = defineCommand({
+    statusCommand10 = defineCommand({
       meta: { name: "status", description: "Get orchestration status for an epic or overall project" },
       args: {
         epic: {
@@ -53159,7 +53238,7 @@ var init_orchestrate3 = __esm({
       meta: { name: "orchestrate", description: "Multi-agent orchestration commands" },
       subCommands: {
         start: startCommand5,
-        status: statusCommand9,
+        status: statusCommand10,
         "roll-up": rollupCommand,
         analyze: analyzeCommand4,
         ready: readyCommand,
@@ -53215,13 +53294,13 @@ import {
   getOtelSummary,
   getRealTokenUsage
 } from "@cleocode/core/internal";
-var statusCommand10, summaryCommand2, sessionsCommand, spawnsCommand, realCommand, clearCommand, otelCommand;
+var statusCommand11, summaryCommand2, sessionsCommand, spawnsCommand, realCommand, clearCommand, otelCommand;
 var init_otel = __esm({
   "packages/cleo/src/cli/commands/otel.ts"() {
     "use strict";
     init_dist();
     init_renderers();
-    statusCommand10 = defineCommand({
+    statusCommand11 = defineCommand({
       meta: { name: "status", description: "Show token tracking status and recent activity" },
       async run() {
         try {
@@ -53356,7 +53435,7 @@ var init_otel = __esm({
         description: "Lightweight token metrics from .cleo/metrics/TOKEN_USAGE.jsonl (session-level, spawn-level events)"
       },
       subCommands: {
-        status: statusCommand10,
+        status: statusCommand11,
         summary: summaryCommand2,
         sessions: sessionsCommand,
         spawns: spawnsCommand,
@@ -53661,7 +53740,7 @@ var playbook_exports = {};
 __export(playbook_exports, {
   playbookCommand: () => playbookCommand
 });
-var runCommand3, statusCommand11, resumeCommand, createCommand2, listCommand14, validateCommand7, playbookCommand;
+var runCommand3, statusCommand12, resumeCommand, createCommand2, listCommand14, validateCommand7, playbookCommand;
 var init_playbook3 = __esm({
   "packages/cleo/src/cli/commands/playbook.ts"() {
     "use strict";
@@ -53693,7 +53772,7 @@ var init_playbook3 = __esm({
         );
       }
     });
-    statusCommand11 = defineCommand({
+    statusCommand12 = defineCommand({
       meta: {
         name: "status",
         description: "Return the current state of a playbook run from playbook_runs"
@@ -53850,7 +53929,7 @@ var init_playbook3 = __esm({
       },
       subCommands: {
         run: runCommand3,
-        status: statusCommand11,
+        status: statusCommand12,
         resume: resumeCommand,
         list: listCommand14,
         create: createCommand2,
@@ -54690,18 +54769,34 @@ var init_release3 = __esm({
         description: "Generate CHANGELOG from git log since a given tag, with task/epic grouping"
       },
       args: {
+        sinceTag: {
+          type: "positional",
+          description: "Git tag or ref to generate changelog from (e.g. v2026.4.75)",
+          required: false
+        },
         since: {
           type: "string",
-          description: "Git tag or ref to generate changelog from (e.g. v2026.4.75)",
-          required: true
+          description: "Git tag or ref to generate changelog from (e.g. v2026.4.75). Alias for the positional argument.",
+          required: false
         }
       },
       async run({ args }) {
+        const sinceTag = typeof args["sinceTag"] === "string" && args["sinceTag"].length > 0 ? args["sinceTag"] : typeof args["since"] === "string" && args["since"].length > 0 ? args["since"] : void 0;
+        if (sinceTag === void 0) {
+          cliError(
+            "Missing required argument: <sinceTag> (or --since)",
+            2,
+            { name: "E_MISSING_ARGUMENT", fix: "Run: cleo release changelog <tag>" },
+            { operation: "release.changelog.since" }
+          );
+          process.exit(2);
+          return;
+        }
         await dispatchFromCli(
           "query",
           "pipeline",
           "release.changelog.since",
-          { sinceTag: args.since },
+          { sinceTag },
           { command: "release" }
         );
       }
@@ -54915,8 +55010,21 @@ var init_release3 = __esm({
           fromWorkflow: args["from-workflow"] === true,
           rollback: args.rollback === true
         });
-        cliOutput(result, { command: "release", operation: "release.reconcile" });
-        if (!result.success) process.exit(1);
+        if (result.success) {
+          cliOutput(result.data, { command: "release", operation: "release.reconcile" });
+          return;
+        }
+        cliError(
+          result.error.message,
+          result.error.code,
+          {
+            name: result.error.code,
+            ...result.error.details ? { details: result.error.details } : {},
+            ...result.error.fix ? { fix: result.error.fix } : {}
+          },
+          { operation: "release.reconcile" }
+        );
+        process.exit(1);
       }
     });
     releaseCommand = defineCommand({
@@ -58144,7 +58252,7 @@ async function promptOwnerAuthPassword(sessionName) {
   const token = deriveOwnerAuthToken(sessionName, password);
   return token;
 }
-var startCommand7, endCommand, handoffCommand2, statusCommand12, resumeCommand2, findCommand6, listCommand21, gcCommand2, showCommand13, driftCommand, contextDriftCommand, suspendCommand, recordAssumptionCommand, recordDecisionCommand, decisionLogCommand, sessionCommand;
+var startCommand7, endCommand, handoffCommand2, statusCommand13, resumeCommand2, findCommand6, listCommand21, gcCommand2, showCommand13, driftCommand, contextDriftCommand, suspendCommand, recordAssumptionCommand, recordDecisionCommand, decisionLogCommand, sessionCommand;
 var init_session4 = __esm({
   "packages/cleo/src/cli/commands/session.ts"() {
     "use strict";
@@ -58332,7 +58440,7 @@ var init_session4 = __esm({
         );
       }
     });
-    statusCommand12 = defineCommand({
+    statusCommand13 = defineCommand({
       meta: { name: "status", description: "Show current session status" },
       async run() {
         const response = await dispatchRaw("query", "session", "status");
@@ -58672,7 +58780,7 @@ var init_session4 = __esm({
         end: endCommand,
         stop: endCommand,
         handoff: handoffCommand2,
-        status: statusCommand12,
+        status: statusCommand13,
         resume: resumeCommand2,
         find: findCommand6,
         list: listCommand21,
@@ -59299,7 +59407,8 @@ var skills_exports = {};
 __export(skills_exports, {
   skillsCommand: () => skillsCommand2
 });
-var listCommand22, searchCommand4, validateCommand8, infoCommand, installCommand3, uninstallCommand2, enableCommand2, disableCommand2, refreshCommand, dispatchCommand, catalogCommand, precedenceCommand, depsCommand4, spawnProvidersCommand, skillsCommand2;
+import { AgentsSkillsRealDirError, runDoctorBridge } from "@cleocode/caamp";
+var listCommand22, searchCommand4, validateCommand8, infoCommand, installCommand3, uninstallCommand2, enableCommand2, disableCommand2, refreshCommand, dispatchCommand, catalogCommand, precedenceCommand, depsCommand4, doctorBridgeCommand, doctorCommand4, spawnProvidersCommand, skillsCommand2;
 var init_skills2 = __esm({
   "packages/cleo/src/cli/commands/skills.ts"() {
     "use strict";
@@ -59600,6 +59709,72 @@ var init_skills2 = __esm({
         );
       }
     });
+    doctorBridgeCommand = defineCommand({
+      meta: {
+        name: "bridge",
+        description: "Create the single ~/.agents/skills bridge symlink + remove orphan per-skill symlinks"
+      },
+      args: {
+        force: {
+          type: "boolean",
+          description: "Back up and replace a real ~/.agents/skills directory if present"
+        },
+        "dry-run": {
+          type: "boolean",
+          description: "Print planned actions without mutating disk state"
+        },
+        json: {
+          type: "boolean",
+          description: "Output as JSON (default)"
+        },
+        human: {
+          type: "boolean",
+          description: "Output in human-readable format"
+        }
+      },
+      async run({ args }) {
+        const { cliError: cliError2, cliOutput: cliOutput2 } = await Promise.resolve().then(() => (init_renderers(), renderers_exports));
+        try {
+          const result = await runDoctorBridge({
+            force: args.force === true,
+            dryRun: args["dry-run"] === true
+          });
+          cliOutput2(
+            { success: true, data: result },
+            { command: "skills doctor bridge", operation: "skills.doctor.bridge" }
+          );
+        } catch (error) {
+          if (error instanceof AgentsSkillsRealDirError) {
+            cliError2(
+              error.message,
+              error.code,
+              {
+                details: {
+                  agentsSkillsPath: error.agentsSkillsPath,
+                  entryCount: error.entryCount
+                }
+              },
+              { operation: "skills.doctor.bridge" }
+            );
+            process.exit(1);
+          }
+          const message = error instanceof Error ? error.message : String(error);
+          cliError2(message, "E_INTERNAL_ERROR", void 0, {
+            operation: "skills.doctor.bridge"
+          });
+          process.exit(1);
+        }
+      }
+    });
+    doctorCommand4 = defineCommand({
+      meta: {
+        name: "doctor",
+        description: "Diagnose and repair the skill storage topology"
+      },
+      subCommands: {
+        bridge: doctorBridgeCommand
+      }
+    });
     spawnProvidersCommand = defineCommand({
       meta: { name: "spawn-providers", description: "List providers capable of spawning subagents" },
       args: {
@@ -59634,7 +59809,8 @@ var init_skills2 = __esm({
         catalog: catalogCommand,
         precedence: precedenceCommand,
         deps: depsCommand4,
-        "spawn-providers": spawnProvidersCommand
+        "spawn-providers": spawnProvidersCommand,
+        doctor: doctorCommand4
       },
       async run({ cmd, rawArgs }) {
         if (isSubCommandDispatch(rawArgs, cmd.subCommands)) return;
@@ -59862,7 +60038,7 @@ var init_stats = __esm({
 // packages/cleo/src/cli/commands/status.ts
 var status_exports = {};
 __export(status_exports, {
-  statusCommand: () => statusCommand13
+  statusCommand: () => statusCommand14
 });
 import { getCleoStatus } from "@cleocode/core/status";
 function formatEpoch(epoch) {
@@ -59948,7 +60124,7 @@ function computeExitCode(status) {
   const hasInvalid = status.credentials.some((c) => c.lastStatus === "invalid");
   return hasInvalid ? 1 : 0;
 }
-var statusCommand13;
+var statusCommand14;
 var init_status = __esm({
   "packages/cleo/src/cli/commands/status.ts"() {
     "use strict";
@@ -59956,7 +60132,7 @@ var init_status = __esm({
     init_format_context();
     init_colors();
     init_renderers();
-    statusCommand13 = defineCommand({
+    statusCommand14 = defineCommand({
       meta: {
         name: "status",
         description: "Unified config + credential + session + harness + daemon snapshot. Use --json for the full LAFS envelope (CleoStatus interface). Exits non-zero when any credential is in invalid state."
@@ -60573,7 +60749,7 @@ var testing_exports = {};
 __export(testing_exports, {
   testingCommand: () => testingCommand
 });
-var validateCommand9, checkCommand7, statusCommand14, coverageCommand, runCommand4, testingCommand;
+var validateCommand9, checkCommand7, statusCommand15, coverageCommand, runCommand4, testingCommand;
 var init_testing = __esm({
   "packages/cleo/src/cli/commands/testing.ts"() {
     "use strict";
@@ -60634,7 +60810,7 @@ var init_testing = __esm({
         );
       }
     });
-    statusCommand14 = defineCommand({
+    statusCommand15 = defineCommand({
       meta: { name: "status", description: "Show test suite status" },
       async run() {
         await dispatchFromCli(
@@ -60681,7 +60857,7 @@ var init_testing = __esm({
       subCommands: {
         validate: validateCommand9,
         check: checkCommand7,
-        status: statusCommand14,
+        status: statusCommand15,
         coverage: coverageCommand,
         run: runCommand4
       },
@@ -62050,7 +62226,7 @@ Logs: ${logFile}`
     { command: "web", message: `CLEO Web UI running on port ${port}` }
   );
 }
-var DEFAULT_PORT, DEFAULT_HOST, startCommand9, stopCommand5, restartCommand, statusCommand15, openCommand2, webCommand;
+var DEFAULT_PORT, DEFAULT_HOST, startCommand9, stopCommand5, restartCommand, statusCommand16, openCommand2, webCommand;
 var init_web = __esm({
   "packages/cleo/src/cli/commands/web.ts"() {
     "use strict";
@@ -62182,7 +62358,7 @@ var init_web = __esm({
         }
       }
     });
-    statusCommand15 = defineCommand({
+    statusCommand16 = defineCommand({
       meta: { name: "status", description: "Check server status" },
       async run() {
         try {
@@ -62236,7 +62412,7 @@ var init_web = __esm({
         start: startCommand9,
         stop: stopCommand5,
         restart: restartCommand,
-        status: statusCommand15,
+        status: statusCommand16,
         open: openCommand2
       },
       async run({ cmd, rawArgs }) {
@@ -62470,8 +62646,14 @@ var init_worktree3 = __esm({
         prune: pruneCommand3,
         "force-unlock": forceUnlockCommand
       },
-      async run() {
-        await showUsage(worktreeCommand);
+      // Early-return when a subcommand was matched; citty still invokes the
+      // parent run() after the subcommand finishes which would otherwise
+      // append the help text to the subcommand's JSON envelope output
+      // (T9686-A bug A4).
+      async run({ cmd, rawArgs }) {
+        const firstArg = rawArgs?.find((a) => !a.startsWith("-"));
+        if (firstArg && cmd.subCommands && firstArg in cmd.subCommands) return;
+        await showUsage(cmd);
       }
     });
   }
@@ -63774,7 +63956,51 @@ async function startCli() {
       }
     }
   }
-  runMain(main, { showUsage: customShowUsage });
+  await runMainWithLafsEnvelope(main, argv, customShowUsage);
+}
+function asCittyCliError(value) {
+  if (!(value instanceof Error)) return null;
+  if (value.name !== "CLIError") return null;
+  if (!("code" in value)) return null;
+  const code = value.code;
+  if (typeof code !== "string") return null;
+  return value;
+}
+async function runMainWithLafsEnvelope(cmd, rawArgs, showUsage2) {
+  const helpFlags = ["--help", "-h"];
+  const versionFlags = ["--version", "-V"];
+  if (rawArgs.some((a) => helpFlags.includes(a))) {
+    await showUsage2(cmd);
+    process.exit(0);
+  }
+  if (rawArgs.length === 1 && versionFlags.includes(rawArgs[0])) {
+    const meta = typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
+    const version = meta?.version;
+    if (!version) {
+      const { cliError: cliError2 } = await Promise.resolve().then(() => (init_renderers(), renderers_exports));
+      cliError2("No version specified", 1, { name: "E_NO_VERSION" });
+      process.exit(1);
+    }
+    process.stdout.write(`${version}
+`);
+    process.exit(0);
+  }
+  try {
+    await runCommand(cmd, { rawArgs });
+  } catch (err) {
+    const { cliError: cliError2 } = await Promise.resolve().then(() => (init_renderers(), renderers_exports));
+    const cittyCliError = asCittyCliError(err);
+    if (cittyCliError) {
+      cliError2(cittyCliError.message, 1, {
+        name: cittyCliError.code === "EARG" ? "E_VALIDATION" : `E_${cittyCliError.code}`,
+        fix: `Run 'cleo <command> --help' to see required arguments.`
+      });
+      process.exit(1);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    cliError2(message, 1, { name: "E_CLI_UNCAUGHT" });
+    process.exit(1);
+  }
 }
 async function runStartupMaintenance() {
   const {