@cleocode/cleo 2026.4.27 → 2026.4.28

package/dist/cli/index.js

@@ -110221,7 +110221,9 @@ var init_check = __esm({
               return wrapResult(result, "query", "check", operation, startTime);
             }
             case "archive.stats": {
-              const result = await systemArchiveStats(projectRoot);
+              const result = await systemArchiveStats(projectRoot, {
+                period: params?.period
+              });
               return wrapResult(result, "query", "check", operation, startTime);
             }
             // T5405: WarpChain validation
@@ -117397,7 +117399,9 @@ var ADD_PARAMS = [
   }
 ];
 function registerAddCommand(program) {
-  const cmd = program.command("add").description(buildOperationHelp("tasks.add", "Create a new task", ADD_PARAMS));
+  const cmd = program.command("add").description(
+    buildOperationHelp("tasks.add", "Create a new task (requires active session)", ADD_PARAMS)
+  );
   applyParamDefsToCommand(cmd, ADD_PARAMS, "tasks.add");
   cmd.option("--add-phase", "Create new phase if it does not exist").option("--desc <desc>", "Task description (alias for --description)").option("--dry-run", "Show what would be created without making changes").action(async (title, opts) => {
     const params = { title };
@@ -119760,10 +119764,6 @@ function capitalizeFirst(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
-// packages/cleo/src/cli/commands/agents.ts
-function registerAgentsCommand(_program) {
-}
-
 // packages/cleo/src/cli/commands/analyze.ts
 init_cli();
 function registerAnalyzeCommand(program) {
@@ -120219,7 +120219,9 @@ async function promptPassphrase() {
 }
 function registerBackupCommand(program) {
   const backup = program.command("backup").description("Add backup of todo files or list available backups");
-  backup.command("add").alias("create").description("Add a new backup of all CLEO data files").option("--destination <dir>", "Backup destination directory").option("--global", "Also snapshot global-tier databases (nexus.db)").action(async (opts) => {
+  backup.command("add").alias("create").description(
+    "Add a new backup of all CLEO data files (backup create is an alias for backup add)"
+  ).option("--destination <dir>", "Backup destination directory").option("--global", "Also snapshot global-tier databases (nexus.db)").action(async (opts) => {
     await dispatchFromCli(
       "mutate",
       "admin",
@@ -120622,7 +120624,7 @@ function registerBrainCommand(program) {
 init_cli();
 function registerBriefingCommand(program) {
   program.command("briefing").description(
-    "Show composite session-start context (handoff, focus, next tasks, bugs, blockers, epics)"
+    "Session resume context: last handoff, current task, next tasks, bugs, blockers, epics, and memory. Use at session start to restore context."
   ).option("-s, --scope <scope>", "Scope filter (global or epic:T###)").option("--max-next <n>", "Maximum next tasks to show", "5").option("--max-bugs <n>", "Maximum bugs to show", "10").option("--max-blocked <n>", "Maximum blocked tasks to show", "10").option("--max-epics <n>", "Maximum active epics to show", "5").action(async (opts) => {
     const scope = opts["scope"];
     const maxNextTasks = parseInt(opts["maxNext"], 10);
@@ -120656,7 +120658,7 @@ var SEVERITY_MAP = {
 };
 var VALID_SEVERITIES = Object.keys(SEVERITY_MAP);
 function registerBugCommand(program) {
-  program.command("bug <title>").description("Create a bug report task with severity mapping").option("-s, --severity <level>", "Severity level (P0, P1, P2, P3) - required", "P2").option("-e, --epic <id>", "Epic ID to link as parent (optional)").option("-d, --description <desc>", "Bug description").option("--dry-run", "Show what would be created without making changes").action(async (title, opts) => {
+  program.command("bug <title>").description("Create a bug report task with severity mapping (requires active session)").option("-s, --severity <level>", "Severity level (P0, P1, P2, P3) - required", "P2").option("-e, --epic <id>", "Epic ID to link as parent (optional)").option("-d, --description <desc>", "Bug description").option("--dry-run", "Show what would be created without making changes").action(async (title, opts) => {
     const severity = opts["severity"] || "P2";
     if (!VALID_SEVERITIES.includes(severity)) {
       console.error(
@@ -121170,7 +121172,9 @@ function registerUnclaimCommand(program) {
 // packages/cleo/src/cli/commands/commands.ts
 init_cli();
 function registerCommandsCommand(program) {
-  program.command("commands [command]").description("List and query available CLEO commands (delegates to admin help)").option("-c, --category <category>", "Filter by category").option("-r, --relevance <level>", "Filter by agent relevance").option("--tier <n>", "Help tier level (0=basic, 1=extended, 2=full)", parseInt).action(async (commandName, opts) => {
+  program.command("commands [command]").description(
+    "DEPRECATED: Use `cleo ops` instead. List and query available CLEO commands (delegates to admin help)"
+  ).option("-c, --category <category>", "Filter by category").option("-r, --relevance <level>", "Filter by agent relevance").option("--tier <n>", "Help tier level (0=basic, 1=extended, 2=full)", parseInt).action(async (commandName, opts) => {
     console.error(
       "[DEPRECATED] cleo commands now delegates to admin.help.\nUse: cleo help (CLI)\n"
     );
@@ -121230,7 +121234,13 @@ var COMPLETE_PARAMS = [
   }
 ];
 function registerCompleteCommand(program) {
-  const cmd = program.command("complete").alias("done").description(buildOperationHelp("tasks.complete", "Mark a task as completed", COMPLETE_PARAMS));
+  const cmd = program.command("complete").alias("done").description(
+    buildOperationHelp(
+      "tasks.complete",
+      "Mark a task as completed (requires active session)",
+      COMPLETE_PARAMS
+    )
+  );
   applyParamDefsToCommand(cmd, COMPLETE_PARAMS, "tasks.complete");
   cmd.action(async (taskId, opts) => {
     const response = await dispatchRaw("mutate", "tasks", "complete", {
@@ -121441,7 +121451,9 @@ function registerConfigCommand(program) {
 // packages/cleo/src/cli/commands/consensus.ts
 init_cli();
 function registerConsensusCommand(program) {
-  const consensus = program.command("consensus").description("Validate consensus protocol compliance for multi-agent decision tasks");
+  const consensus = program.command("consensus").description(
+    "Validate consensus protocol compliance (alias for `cleo check protocol consensus`)"
+  );
   consensus.command("validate <taskId>").description("Validate consensus protocol compliance for task").option("--strict", "Exit with error code on violations").option("--voting-matrix <file>", "Path to voting matrix JSON file").action(async (taskId, opts) => {
     await dispatchFromCli(
       "query",
@@ -121490,7 +121502,7 @@ function registerContextCommand(program) {
       { command: "context" }
     );
   });
-  context.command("check").description("Check threshold, return exit code for scripting").option("--session <id>", "Check specific CLEO session").action(async (opts) => {
+  context.command("check").description("Show context window state (same as status)").option("--session <id>", "Check specific CLEO session").action(async (opts) => {
     await dispatchFromCli(
       "query",
       "admin",
@@ -121502,7 +121514,7 @@ function registerContextCommand(program) {
       { command: "context" }
     );
   });
-  context.command("list").description("List all context state files (multi-session)").action(async () => {
+  context.command("list").description("Show context window state including all sessions").action(async () => {
     await dispatchFromCli(
       "query",
       "admin",
@@ -121518,7 +121530,9 @@ function registerContextCommand(program) {
 // packages/cleo/src/cli/commands/contribution.ts
 init_cli();
 function registerContributionCommand(program) {
-  const contribution = program.command("contribution").description("Validate contribution protocol compliance for shared codebase work");
+  const contribution = program.command("contribution").description(
+    "Validate contribution protocol compliance (alias for `cleo check protocol contribution`)"
+  );
   contribution.command("validate <taskId>").description("Validate contribution protocol compliance for task").option("--strict", "Exit with error code on violations").action(async (taskId, opts) => {
     await dispatchFromCli(
       "query",
@@ -121552,7 +121566,9 @@ function registerContributionCommand(program) {
 // packages/cleo/src/cli/commands/current.ts
 init_cli();
 function registerCurrentCommand(program) {
-  program.command("current").description("Show the current task being worked on").action(async () => {
+  program.command("current").description(
+    "Show the current task being worked on. Returns: {currentTask: string|null, currentPhase: string|null}"
+  ).action(async () => {
     await dispatchFromCli("query", "tasks", "current", {}, { command: "current" });
   });
 }
@@ -121560,15 +121576,25 @@ function registerCurrentCommand(program) {
 // packages/cleo/src/cli/commands/dash.ts
 init_cli();
 function registerDashCommand(program) {
-  program.command("dash").description("Project dashboard with status summary, phase progress, recent activity").option("-c, --compact", "Condensed single-line view").option("--period <days>", "Stats period in days", "7").option("--no-chart", "Disable ASCII charts/progress bars").option("--sections <list>", "Comma-separated list of sections to show").option("-v, --verbose", "Show full task details").action(async () => {
-    await dispatchFromCli("query", "admin", "dash", {}, { command: "dash" });
+  program.command("dash").description(
+    "Project health dashboard: status summary, phase progress, recent activity, high priority tasks. Use for overall project status."
+  ).option("--blocked-limit <n>", "Max blocked tasks to show", parseInt).action(async (opts) => {
+    await dispatchFromCli(
+      "query",
+      "admin",
+      "dash",
+      { blockedTasksLimit: opts["blockedLimit"] },
+      { command: "dash" }
+    );
   });
 }
 
 // packages/cleo/src/cli/commands/decomposition.ts
 init_cli();
 function registerDecompositionCommand(program) {
-  const decomposition = program.command("decomposition").description("Validate decomposition protocol compliance for epic breakdown tasks");
+  const decomposition = program.command("decomposition").description(
+    "Validate decomposition protocol compliance (alias for `cleo check protocol decomposition`)"
+  );
   decomposition.command("validate <taskId>").description("Validate decomposition protocol compliance for task").option("--strict", "Exit with error code on violations").option("--epic <id>", "Specify parent epic ID").action(async (taskId, opts) => {
     await dispatchFromCli(
       "query",
@@ -121749,7 +121775,8 @@ function findProjectRoot() {
 function registerDetectDriftCommand(program) {
   program.command("detect-drift").description("Detect documentation drift against TypeScript source of truth").action(async () => {
     const projectRoot = findProjectRoot();
-    const isCleoRepo = existsSync129(join125(projectRoot, "src", "cli", "commands")) || existsSync129(join125(projectRoot, "packages", "cleo", "src"));
+    const isCleoRepo = existsSync129(join125(projectRoot, "packages", "cleo", "src"));
+    const cleoSrcRoot = isCleoRepo ? join125(projectRoot, "packages", "cleo", "src") : join125(projectRoot, "src");
     const safeRead = (filePath) => {
       try {
         return readFileSync98(filePath, "utf-8");
@@ -121815,17 +121842,17 @@ function registerDetectDriftCommand(program) {
       }
     };
     try {
-      const specPath = join125(projectRoot, "docs", "specs", "CLEO-OPERATIONS-REFERENCE.md");
-      const registryPath = join125(projectRoot, "src", "dispatch", "registry.ts");
-      const dispatchDomainsDir = join125(projectRoot, "src", "dispatch", "domains");
+      const specPath = join125(projectRoot, "docs", "specs", "CLEO-OPERATION-CONSTITUTION.md");
+      const registryPath = join125(cleoSrcRoot, "dispatch", "registry.ts");
+      const dispatchDomainsDir = join125(cleoSrcRoot, "dispatch", "domains");
       if (!existsSync129(specPath)) {
-        addCheck("Gateway-to-spec sync", "fail", "CLEO-OPERATIONS-REFERENCE.md missing", [
+        addCheck("Gateway-to-spec sync", "fail", "CLEO-OPERATION-CONSTITUTION.md missing", [
           {
             severity: "error",
             category: "spec",
             message: "Operations reference specification not found",
             file: specPath,
-            recommendation: "Create docs/specs/CLEO-OPERATIONS-REFERENCE.md with canonical operation definitions"
+            recommendation: "Create docs/specs/CLEO-OPERATION-CONSTITUTION.md with canonical operation definitions"
           }
         ]);
       } else if (!existsSync129(registryPath) || !existsSync129(dispatchDomainsDir)) {
@@ -121835,7 +121862,7 @@ function registerDetectDriftCommand(program) {
             category: "implementation",
             message: "Dispatch registry or domains directory not found",
             file: registryPath,
-            recommendation: "Verify src/dispatch/registry.ts and src/dispatch/domains/ exist"
+            recommendation: "Verify packages/cleo/src/dispatch/registry.ts and packages/cleo/src/dispatch/domains/ exist"
           }
         ]);
       } else {
@@ -121892,14 +121919,14 @@ function registerDetectDriftCommand(program) {
       ]);
     }
     try {
-      const cliDir = join125(projectRoot, "src", "cli", "commands");
-      const coreDir = join125(projectRoot, "src", "core");
+      const cliDir = join125(cleoSrcRoot, "cli", "commands");
+      const coreDir = isCleoRepo ? join125(projectRoot, "packages", "core", "src") : join125(projectRoot, "src", "core");
       if (!existsSync129(cliDir)) {
         addCheck("CLI-to-core sync", "fail", "CLI commands directory missing", [
           {
             severity: "error",
             category: "structure",
-            message: "src/cli/commands/ directory not found",
+            message: `${cliDir} directory not found`,
             recommendation: "Verify TypeScript source structure is intact"
           }
         ]);
@@ -121908,7 +121935,7 @@ function registerDetectDriftCommand(program) {
           {
             severity: "error",
             category: "structure",
-            message: "src/core/ directory not found",
+            message: `${coreDir} directory not found`,
             recommendation: "Verify TypeScript source structure is intact"
           }
         ]);
@@ -121922,13 +121949,13 @@ function registerDetectDriftCommand(program) {
       addCheck("CLI-to-core sync", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const domainsDir = join125(projectRoot, "src", "dispatch", "domains");
+      const domainsDir = join125(cleoSrcRoot, "dispatch", "domains");
       if (!existsSync129(domainsDir)) {
         addCheck("Domain handler coverage", "fail", "Dispatch domains directory missing", [
           {
             severity: "error",
             category: "structure",
-            message: "src/dispatch/domains/ not found",
+            message: `${domainsDir} not found`,
             recommendation: "Verify dispatch domain handlers are in place"
           }
         ]);
@@ -121940,13 +121967,13 @@ function registerDetectDriftCommand(program) {
       addCheck("Domain handler coverage", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const matrixPath = join125(projectRoot, "src", "dispatch", "lib", "capability-matrix.ts");
+      const matrixPath = join125(cleoSrcRoot, "dispatch", "lib", "capability-matrix.ts");
       if (!existsSync129(matrixPath)) {
         addCheck("Capability matrix", "fail", "Capability matrix missing", [
           {
             severity: "error",
             category: "configuration",
-            message: "src/dispatch/lib/capability-matrix.ts not found",
+            message: `${matrixPath} not found`,
             recommendation: "Create capability matrix to document supported operations"
           }
         ]);
@@ -122078,14 +122105,14 @@ function registerDetectDriftCommand(program) {
       addCheck("Agent injection", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const exitCodesPath = join125(projectRoot, "src", "types", "exit-codes.ts");
+      const exitCodesPath = join125(cleoSrcRoot, "dispatch", "lib", "exit-codes.ts");
       if (!existsSync129(exitCodesPath)) {
         addCheck("Exit codes", "fail", "Exit codes definition missing", [
           {
             severity: "error",
             category: "protocol",
-            message: "src/types/exit-codes.ts not found",
-            recommendation: "Create exit codes enum for CLI protocol compliance"
+            message: `${exitCodesPath} not found`,
+            recommendation: "Create exit codes definition for CLI protocol compliance"
           }
         ]);
       } else {
@@ -122098,7 +122125,6 @@ function registerDetectDriftCommand(program) {
     }
     if (result.summary.errors > 0) {
       result.recommendations.push("Address all ERROR-level issues before proceeding");
-      result.recommendations.push("Run cleo detect-drift --json for structured output");
     }
     if (result.summary.warnings > 0) {
       result.recommendations.push("Review WARNING-level issues for documentation improvements");
@@ -122597,7 +122623,7 @@ var FIND_PARAMS = [
     name: "query",
     type: "string",
     required: false,
-    description: "Fuzzy search query (title/description)",
+    description: "Search text (required unless --id is provided)",
     cli: { positional: true }
   },
   {
@@ -122626,7 +122652,7 @@ var FIND_PARAMS = [
     name: "field",
     type: "string",
     required: false,
-    description: "Field to search in (title, description, etc.)",
+    description: "Field to search in (title|description|notes|id)",
     cli: { flag: "in" }
   },
   {
@@ -122950,7 +122976,9 @@ function registerHistoryCommand(program) {
 // packages/cleo/src/cli/commands/implementation.ts
 init_cli();
 function registerImplementationCommand(program) {
-  const implementation = program.command("implementation").description("Validate implementation protocol compliance for code tasks");
+  const implementation = program.command("implementation").description(
+    "Validate implementation protocol compliance (alias for `cleo check protocol implementation`)"
+  );
   implementation.command("validate <taskId>").description("Validate implementation protocol compliance for task").option("--strict", "Exit with error code on violations").action(async (taskId, opts) => {
     await dispatchFromCli(
       "query",
@@ -123153,7 +123181,7 @@ function registerLabelsCommand(program) {
     await dispatchFromCli("query", "tasks", "label.list", {}, { command: "labels" });
   });
   labels.command("show <label>").description("Show tasks with specific label").action(async (label) => {
-    await dispatchFromCli("query", "tasks", "label.list", { label }, { command: "labels" });
+    await dispatchFromCli("query", "tasks", "list", { label }, { command: "labels" });
   });
   labels.command("stats").description("Show detailed label statistics").action(async () => {
     await dispatchFromCli("query", "tasks", "label.list", {}, { command: "labels" });
@@ -123176,7 +123204,9 @@ function registerLifecycleCommand(program) {
       { command: "lifecycle" }
     );
   });
-  lifecycle.command("start <epicId> <stage>").description("Start a lifecycle stage").action(async (epicId, stage) => {
+  lifecycle.command("start <epicId> <stage>").description(
+    "Start a lifecycle stage. Valid stages: research|consensus|architecture_decision|specification|decomposition|implementation|validation|testing|release|contribution"
+  ).action(async (epicId, stage) => {
     await dispatchFromCli(
       "mutate",
       "pipeline",
@@ -123189,7 +123219,9 @@ function registerLifecycleCommand(program) {
       { command: "lifecycle" }
     );
   });
-  lifecycle.command("complete <epicId> <stage>").description("Complete a lifecycle stage").option("--artifacts <artifacts>", "Comma-separated artifact paths").option("--notes <notes>", "Completion notes").action(async (epicId, stage, opts) => {
+  lifecycle.command("complete <epicId> <stage>").description(
+    "Complete a lifecycle stage. Valid stages: research|consensus|architecture_decision|specification|decomposition|implementation|validation|testing|release|contribution"
+  ).option("--artifacts <artifacts>", "Comma-separated artifact paths").option("--notes <notes>", "Completion notes").action(async (epicId, stage, opts) => {
     await dispatchFromCli(
       "mutate",
       "pipeline",
@@ -123203,7 +123235,9 @@ function registerLifecycleCommand(program) {
       { command: "lifecycle" }
     );
   });
-  lifecycle.command("skip <epicId> <stage>").description("Skip a lifecycle stage").requiredOption("--reason <reason>", "Reason for skipping").action(async (epicId, stage, opts) => {
+  lifecycle.command("skip <epicId> <stage>").description(
+    "Skip a lifecycle stage. Valid stages: research|consensus|architecture_decision|specification|decomposition|implementation|validation|testing|release|contribution"
+  ).requiredOption("--reason <reason>", "Reason for skipping").action(async (epicId, stage, opts) => {
     await dispatchFromCli(
       "mutate",
       "pipeline",
@@ -123256,7 +123290,9 @@ function registerLifecycleCommand(program) {
       { command: "lifecycle" }
     );
   });
-  lifecycle.command("reset <epicId> <stage>").description("Reset a lifecycle stage back to pending").requiredOption("--reason <reason>", "Reason for resetting the stage").action(async (epicId, stage, opts) => {
+  lifecycle.command("reset <epicId> <stage>").description(
+    "Reset a lifecycle stage back to pending. Valid stages: research|consensus|architecture_decision|specification|decomposition|implementation|validation|testing|release|contribution"
+  ).requiredOption("--reason <reason>", "Reason for resetting the stage").action(async (epicId, stage, opts) => {
     await dispatchFromCli(
       "mutate",
       "pipeline",
@@ -124286,7 +124322,9 @@ function registerOrchestrateCommand(program) {
 init_internal();
 init_renderers();
 function registerOtelCommand(program) {
-  const otel = program.command("otel").description("Token metrics tracking - view status, summary, and manage tracking data");
+  const otel = program.command("otel").description(
+    "Lightweight token metrics from .cleo/metrics/TOKEN_USAGE.jsonl (session-level, spawn-level events)"
+  );
   otel.command("status").description("Show token tracking status and recent activity").action(async () => {
     try {
       const result = await getOtelStatus();
@@ -124451,11 +124489,15 @@ function registerPhaseCommand(program) {
 // packages/cleo/src/cli/commands/phases.ts
 init_cli();
 function registerPhasesCommand(program) {
-  const phases = program.command("phases").description("List phases with progress bars and statistics");
+  const phases = program.command("phases").description(
+    "DEPRECATED: Use `cleo phase` instead. List phases with progress bars and statistics"
+  );
   phases.command("list", { isDefault: true }).description("List all phases with progress (default)").action(async () => {
+    console.error("[DEPRECATED] cleo phases is deprecated. Use: cleo phase list");
     await dispatchFromCli("query", "pipeline", "phase.list", {}, { command: "phases" });
   });
   phases.command("show <phase>").description("Show phase details and task counts").action(async (phase) => {
+    console.error("[DEPRECATED] cleo phases is deprecated. Use: cleo phase show");
     await dispatchFromCli(
       "query",
       "pipeline",
@@ -124465,6 +124507,7 @@ function registerPhasesCommand(program) {
     );
   });
   phases.command("stats").description("Show detailed phase statistics").action(async () => {
+    console.error("[DEPRECATED] cleo phases is deprecated. Use: cleo phase list");
     await dispatchFromCli("query", "pipeline", "phase.list", {}, { command: "phases" });
   });
 }
@@ -124473,7 +124516,7 @@ function registerPhasesCommand(program) {
 init_cli();
 function registerPlanCommand(program) {
   program.command("plan").description(
-    "Composite planning view: in-progress epics, ready tasks, blocked tasks, open bugs"
+    "Task prioritization view: in-progress epics, ready tasks, blocked tasks, open bugs with scoring. Use when deciding what to work on next."
   ).action(async () => {
     await dispatchFromCli(
       "query",
@@ -124682,7 +124725,9 @@ function registerRelatesCommand(program) {
     handleRawError(response, { command: "relates", operation: "relates" });
     cliOutput(response.data ?? {}, { command: "relates" });
   });
-  relates.command("add <from> <to> <type> <reason>").description("Add a relates entry to a task").action(async (from, to2, type, reason) => {
+  relates.command("add <from> <to> <type> <reason>").description(
+    "Add a relates entry to a task. Valid types: blocks|related|duplicates|absorbs|fixes|extends|supersedes"
+  ).action(async (from, to2, type, reason) => {
     await dispatchFromCli(
       "mutate",
       "tasks",
@@ -124736,15 +124781,6 @@ function registerReleaseCommand(program) {
       { command: "release" }
     );
   });
-  release2.command("changelog <version>").description("Generate changelog for a release").action(async (version2) => {
-    await dispatchFromCli(
-      "mutate",
-      "pipeline",
-      "release.ship",
-      { version: version2, step: "changelog" },
-      { command: "release" }
-    );
-  });
   release2.command("cancel <version>").description("Cancel and remove a release in draft or prepared state").action(async (version2) => {
     await dispatchFromCli(
       "mutate",
@@ -124890,15 +124926,15 @@ function registerRemoteCommand(program) {
       const remoteName = opts["remote"];
       const result = await pull(remoteName);
       if (!result.success) {
-        const output = {
+        const details = {
           pulled: false,
           branch: result.branch,
           remote: result.remote
         };
         if (result.hasConflicts) {
-          output["conflicts"] = result.conflictFiles;
+          details["conflicts"] = result.conflictFiles;
         }
-        cliOutput(output, { command: "pull", message: result.message });
+        cliError(result.message, 1 /* GENERAL_ERROR */, { details });
         process.exit(1 /* GENERAL_ERROR */);
       }
       cliOutput(
@@ -124957,7 +124993,7 @@ function registerRemoteCommand(program) {
 // packages/cleo/src/cli/commands/reorder.ts
 init_cli();
 function registerReorderCommand(program) {
-  program.command("reorder <task-id>").description("Change task position within sibling group").option("--position <n>", "Move to specific position", parseInt).option("--before <id>", "Move before specified task").option("--after <id>", "Move after specified task").option("--top", "Move to first position").option("--bottom", "Move to last position").action(async (taskId, opts) => {
+  program.command("reorder <task-id>").description("Change task position within sibling group").option("--position <n>", "Move to specific zero-based position among siblings", parseInt).action(async (taskId, opts) => {
     const position = opts["position"];
     await dispatchFromCli(
       "mutate",
@@ -126249,7 +126285,13 @@ var SHOW_PARAMS = [
   }
 ];
 function registerShowCommand(program) {
-  const cmd = program.command("show").description(buildOperationHelp("tasks.show", "Show full task details by ID", SHOW_PARAMS));
+  const cmd = program.command("show").description(
+    buildOperationHelp(
+      "tasks.show",
+      "Show full task details by ID (returns complete task record with metadata, verification, lifecycle)",
+      SHOW_PARAMS
+    )
+  );
   applyParamDefsToCommand(cmd, SHOW_PARAMS, "tasks.show");
   cmd.action(async (taskId) => {
     await dispatchFromCli("query", "tasks", "show", { taskId }, { command: "show" });
@@ -126481,7 +126523,9 @@ function registerSnapshotCommand(program) {
 // packages/cleo/src/cli/commands/specification.ts
 init_cli();
 function registerSpecificationCommand(program) {
-  const specification = program.command("specification").description("Validate specification protocol compliance");
+  const specification = program.command("specification").description(
+    "Validate specification protocol compliance (alias for `cleo check protocol specification`)"
+  );
   specification.command("validate <taskId>").description("Validate specification protocol compliance for task").option("--strict", "Exit with error code on violations").option("--spec-file <file>", "Path to specification file").action(async (taskId, opts) => {
     await dispatchFromCli(
       "query",
@@ -126517,7 +126561,7 @@ function registerSpecificationCommand(program) {
 // packages/cleo/src/cli/commands/start.ts
 init_cli();
 function registerStartCommand(program) {
-  program.command("start <taskId>").description("Start working on a task").action(async (taskId) => {
+  program.command("start <taskId>").description("Start working on a task (sets it as the current task in the active session)").action(async (taskId) => {
     await dispatchFromCli("mutate", "tasks", "start", { taskId }, { command: "start" });
   });
 }
@@ -126531,7 +126575,7 @@ function registerStatsCommand(program) {
       "admin",
       "stats",
       {
-        period: opts["period"] ? Number(opts["period"]) : 30
+        period: opts["period"] ?? 30
       },
       { command: "stats", operation: "admin.stats" }
     );
@@ -126728,7 +126772,9 @@ function collect(value, previous) {
 // packages/cleo/src/cli/commands/stop.ts
 init_cli();
 function registerStopCommand(program) {
-  program.command("stop").description("Stop working on the current task").action(async () => {
+  program.command("stop").description(
+    "Stop working on the current task (clears the active task, returns {cleared: boolean, previousTask: string|null})"
+  ).action(async () => {
     await dispatchFromCli("mutate", "tasks", "stop", {}, { command: "stop" });
   });
 }
@@ -126880,7 +126926,9 @@ function readPayload(opts, textKey, fileKey) {
   return text3;
 }
 function registerTokenCommand(program) {
-  const token = program.command("token").description("Provider-aware token telemetry and estimation");
+  const token = program.command("token").description(
+    "Provider-aware token telemetry from tasks.db (historical, per-operation tracking)"
+  );
   token.command("summary").description("Summarize recorded token telemetry").option("--provider <provider>", "Filter by provider").option("--transport <transport>", "Filter by transport").option("--domain <domain>", "Filter by domain").option("--operation <name>", "Filter by operation name").option("--session <id>", "Filter by session ID").option("--task <id>", "Filter by task ID").action(async (opts) => {
     await dispatchFromCli(
       "query",
@@ -126976,7 +127024,7 @@ function registerTokenCommand(program) {
 // packages/cleo/src/cli/commands/update.ts
 init_cli();
 function registerUpdateCommand(program) {
-  program.command("update <taskId>").description("Update a task").option("--title <title>", "New title").option("-s, --status <status>", "New status").option("-p, --priority <priority>", "New priority").option("-t, --type <type>", "New type").option("--size <size>", "New size").option("-P, --phase <phase>", "New phase").option("-d, --description <desc>", "New description").option("-l, --labels <labels>", "Set labels (comma-separated)").option("--add-labels <labels>", "Add labels (comma-separated)").option("--remove-labels <labels>", "Remove labels (comma-separated)").option("-D, --depends <ids>", "Set dependencies (comma-separated)").option("--add-depends <ids>", "Add dependencies (comma-separated)").option("--remove-depends <ids>", "Remove dependencies (comma-separated)").option("--notes <note>", "Add a note").option(
+  program.command("update <taskId>").description("Update a task").option("--title <title>", "New title").option("-s, --status <status>", "New status (pending|active|blocked|done|cancelled)").option("-p, --priority <priority>", "New priority (critical|high|medium|low)").option("-t, --type <type>", "New type (task|epic|subtask|bug)").option("--size <size>", "New size").option("-P, --phase <phase>", "New phase").option("-d, --description <desc>", "New description").option("-l, --labels <labels>", "Set labels (comma-separated)").option("--add-labels <labels>", "Add labels (comma-separated)").option("--remove-labels <labels>", "Remove labels (comma-separated)").option("-D, --depends <ids>", "Set dependencies (comma-separated)").option("--add-depends <ids>", "Add dependencies (comma-separated)").option("--remove-depends <ids>", "Remove dependencies (comma-separated)").option("--notes <note>", "Add a note").option(
     "--acceptance <criteria>",
     'Set acceptance criteria (pipe-separated, e.g. "AC1|AC2|AC3")'
   ).option("--files <files>", "Set files (comma-separated)").option("--blocked-by <reason>", "Set blocked-by reason").option("--parent <id>", "Set parent ID").option("--no-auto-complete", "Disable auto-complete for epic").option(
@@ -127099,7 +127147,10 @@ function registerUpgradeCommand(program) {
 // packages/cleo/src/cli/commands/validate.ts
 init_cli();
 function registerValidateCommand(program) {
-  program.command("validate").description("Validate task data against schema and business rules").option("--strict", "Treat warnings as errors").action(async (opts) => {
+  program.command("validate").description(
+    "DEPRECATED: Use `cleo check schema todo` instead. Validate task data against schema and business rules"
+  ).option("--strict", "Treat warnings as errors").action(async (opts) => {
+    console.error("[DEPRECATED] cleo validate is deprecated. Use: cleo check schema todo");
     await dispatchFromCli(
       "query",
       "check",
@@ -127468,7 +127519,6 @@ function getPackageVersion() {
 var CLI_VERSION = getPackageVersion();
 var rootShim = new ShimCommand();
 registerAgentCommand(rootShim);
-registerAgentsCommand(rootShim);
 registerAddCommand(rootShim);
 registerAddBatchCommand(rootShim);
 registerListCommand(rootShim);