@rudderhq/cli 0.3.6-canary.1 → 0.3.6-canary.3

package/dist/index.js

@@ -784,7 +784,7 @@ var init_adapter_skills = __esm({
 
 // ../packages/shared/dist/validators/chat.js
 import { z as z4 } from "zod";
-var chatConversationStatusSchema, chatIssueCreationModeSchema, chatMessageRoleSchema, chatMessageKindSchema, chatMessageStatusSchema, chatContextEntityTypeSchema, createChatContextLinkSchema, createChatConversationSchema, setChatProjectContextSchema, updateChatConversationSchema, addChatMessageSchema, chatRichReferenceDisplaySchema, chatIssueIdentifierSchema, chatAskUserIdentifierSchema, chatAskUserOptionSchema, chatAskUserQuestionSchema, chatAskUserRequestSchema, chatIssueRichReferenceSchema, chatIssueCommentRichReferenceSchema, chatRichReferenceSchema, chatRichReferencesSchema, chatAutomationCreateSchema, createChatAttachmentMetadataSchema, chatIssueProposalSchema, convertChatToIssueSchema, chatOperationProposalSchema, resolveChatOperationProposalSchema, updateChatConversationUserStateSchema, updateMessengerThreadUserStateSchema, createMessengerCustomGroupSchema, updateMessengerCustomGroupSchema, reorderMessengerCustomGroupsSchema, assignMessengerCustomGroupEntrySchema, reorderMessengerCustomGroupEntriesSchema;
+var chatConversationStatusSchema, chatIssueCreationModeSchema, chatMessageRoleSchema, chatMessageKindSchema, chatMessageStatusSchema, chatContextEntityTypeSchema, createChatContextLinkSchema, createChatConversationSchema, setChatProjectContextSchema, updateChatConversationSchema, addChatMessageSchema, chatRichReferenceDisplaySchema, chatIssueIdentifierSchema, chatAskUserIdentifierSchema, chatAskUserOptionSchema, chatAskUserQuestionSchema, chatAskUserRequestSchema, chatIssueRichReferenceSchema, chatIssueCommentRichReferenceSchema, chatRichReferenceSchema, chatRichReferencesSchema, chatAutomationCreateSchema, createChatAttachmentMetadataSchema, chatIssueProposalSchema, convertChatToIssueSchema, chatOperationProposalSchema, resolveChatOperationProposalSchema, updateChatConversationUserStateSchema, updateMessengerThreadUserStateSchema, createMessengerCustomGroupSchema, createMessengerCustomGroupWithEntriesSchema, updateMessengerCustomGroupSchema, reorderMessengerCustomGroupsSchema, assignMessengerCustomGroupEntrySchema, reorderMessengerCustomGroupEntriesSchema;
 var init_chat = __esm({
   "../packages/shared/dist/validators/chat.js"() {
     "use strict";
@@ -971,6 +971,9 @@ var init_chat = __esm({
       name: z4.string().trim().min(1).max(80),
       icon: z4.string().trim().min(1).max(24).optional().nullable()
     });
+    createMessengerCustomGroupWithEntriesSchema = createMessengerCustomGroupSchema.extend({
+      threadKeys: z4.array(z4.string().trim().min(1).max(240)).min(1).max(50)
+    });
     updateMessengerCustomGroupSchema = z4.object({
       name: z4.string().trim().min(1).max(80).optional(),
       icon: z4.string().trim().min(1).max(24).optional().nullable(),
@@ -7283,6 +7286,7 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
   "",
   "- Issues: use `[](issue://<issue-id>)`; include `?c=<comment-id>` when linking to a specific comment.",
   "- Agents: use `[](agent://<agent-id>)` for reference-only links. In issue comments, use `[](agent://<agent-id>?intent=wake)` only when you intentionally want to wake that agent for attention or collaboration.",
+  "- Automations: use `[](automation://<automation-id>)` when citing a Rudder automation.",
   "- Projects: use `[](project://<project-id>)` when citing a Rudder project.",
   "- Chat threads: use `[](chat://<conversation-id>)` when citing a Rudder chat conversation.",
   "- Skills: use `[](skill://<skill-ref>)` when citing a Rudder skill reference. The skill ref may be an org skill, agent skill, bundled Rudder skill, or local-machine skill ref; the UI resolves the display label when metadata is available.",
@@ -7315,19 +7319,25 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
 var RUDDER_AGENT_HEARTBEAT_INSTRUCTION = [
   "# Rudder Heartbeat Instruction",
   "",
-  "This section is injected by Rudder for heartbeat scene runs. It is the platform-owned timed-wakeup pipeline, not an agent-local `HEARTBEAT.md` file.",
+  "This section is injected by Rudder for heartbeat scene runs. It is the platform-owned timed-wakeup pipeline.",
   "",
   "## Heartbeat Pipeline",
   "",
   "1. Identify yourself and inspect wake context, including `RUDDER_TASK_ID`, `RUDDER_WAKE_REASON`, `RUDDER_WAKE_COMMENT_ID`, and `RUDDER_APPROVAL_ID` when present.",
-  "2. Handle approval follow-up first: read the approval and linked issues, then close resolved work or comment on what remains.",
-  "3. Inspect your Rudder inbox. Prioritize reviewer rows in `in_review` or `blocked`, then assignee `in_progress`, then assignee `todo`. Do not look for unassigned work.",
-  "4. For mention wakes, read the wake comment before acting. Mentions request attention; they do not transfer ownership unless the comment explicitly says so. If the issue is not assigned to you, including user-owned or unassigned issues, and the comment does not explicitly ask you to implement, modify files, close the issue, or take ownership, respond to the comment itself instead of executing the whole issue.",
-  "5. Checkout before doing assignee task work. A `409` means another agent owns the task; do not retry it.",
-  "6. Load compact issue context, do one bounded useful chunk, and preserve evidence.",
-  "7. Before exiting active work, leave exactly one durable signal: progress, done, blocked, explicit handoff, or structured review decision.",
-  "8. Treat passive follow-up as close-out governance, not a fresh assignment.",
-  "9. Treat review close-out follow-up as review governance; free-form accept/reject text is not a durable decision.",
+  "2. Local Planning Check:",
+  "   ",
+  "   1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under \"## Today's Plan\". You need to clearly know your work plan for today, and work according to the plan.",
+  "   2. Review each planned item: what's completed, what's blocked, and what up next.",
+  "   3. Record progress updates in the daily notes.",
+  "   ",
+  "3.Then handle approval follow-up: read the approval and linked issues, then close resolved work or comment on what remains.",
+  "4. Inspect your Rudder inbox. Prioritize reviewer rows in `in_review` or `blocked`, then assignee `in_progress`, then assignee `todo`. Do not look for unassigned work.",
+  "5. For mention wakes, read the wake comment before acting. Mentions request attention; they do not transfer ownership unless the comment explicitly says so. If the issue is not assigned to you, including user-owned or unassigned issues, and the comment does not explicitly ask you to implement, modify files, close the issue, or take ownership, respond to the comment itself instead of executing the whole issue.",
+  "6. Checkout before doing assignee task work. A `409` means another agent owns the task; do not retry it.",
+  "7. Load compact issue context, do one bounded useful chunk, and preserve evidence.",
+  "8. Before exiting active work, leave exactly one durable signal: progress, done, blocked, explicit handoff, or structured review decision.",
+  "9. Treat passive follow-up as close-out governance, not a fresh assignment.",
+  "10. Treat review close-out follow-up as review governance; free-form accept/reject text is not a durable decision.",
   "",
   "Use the Rudder control-plane interface available in this runtime. CLI-capable runtimes should use the bundled `rudder` skill for command details, Library handoff rules, organization-skill workflow, and control-plane best practices. HTTP compatibility runtimes should follow the explicit HTTP workflow in their wake text; that workflow overrides CLI command guidance."
 ].join("\n");
@@ -8423,7 +8433,7 @@ function formatAgentCliCapabilitiesHumanReadable(capabilities = getAgentCliCapab
 function formatExamplesAndCautions(notes) {
   const sections = [];
   if (notes.examples?.length) {
-    sections.push(["Examples:", ...notes.examples.map((example) => `  ${example}`)].join("\n"));
+    sections.push(["Examples:", ...notes.examples.map(formatHelpExample)].join("\n"));
   }
   if (notes.cautions?.length) {
     sections.push(["Cautions:", ...notes.cautions.map((caution) => `  - ${caution}`)].join("\n"));
@@ -8431,6 +8441,13 @@ function formatExamplesAndCautions(notes) {
   return sections.length > 0 ? `
 ${sections.join("\n\n")}` : "";
 }
+function formatHelpExample(example) {
+  if (typeof example === "string") {
+    return `  ${example}`;
+  }
+  return `  ${example.description}
+    ${example.command}`;
+}
 
 // src/commands/client/agent.ts
 var __moduleDir = path10.dirname(fileURLToPath3(import.meta.url));
@@ -8750,8 +8767,14 @@ function registerAgentCommands(program) {
   addCommonClientOptions(
     skills.command("enable").description(getAgentCliCapabilityById("agent.skills.enable").description).argument("<agentId>", "Agent ID").argument("<selectionRefs...>", "Skill selection refs to enable").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder agent skills enable <agent-id> rudder/rudder local/abc123/custom-skill",
-        "rudder agent skills enable <agent-id> <selection-ref> --json"
+        {
+          description: "Add skills while preserving the agent's existing enabled set:",
+          command: "rudder agent skills enable <agent-id> rudder/rudder local/abc123/custom-skill"
+        },
+        {
+          description: "Enable one newly created private skill and inspect the resulting snapshot:",
+          command: "rudder agent skills enable <agent-id> <selection-ref> --json"
+        }
       ],
       cautions: [
         "This is additive and preserves existing enabled optional skills.",
@@ -8775,8 +8798,14 @@ function registerAgentCommands(program) {
       "Comma-separated desired skill refs (for example rudder/rudder)"
     ).addHelpText("after", formatExamplesAndCautions({
       examples: [
-        'rudder agent skills sync <agent-id> --desired-skills "rudder/rudder,local/abc123/custom-skill"',
-        'rudder agent skills sync <agent-id> --desired-skills "" --json'
+        {
+          description: "Replace the optional enabled set with an explicitly preserved CSV:",
+          command: 'rudder agent skills sync <agent-id> --desired-skills "rudder/rudder,local/abc123/custom-skill"'
+        },
+        {
+          description: "Clear optional skills only when that is the intended final state:",
+          command: 'rudder agent skills sync <agent-id> --desired-skills "" --json'
+        }
       ],
       cautions: [
         "Sync replaces the full optional enabled-skill set; use enable for additive changes.",
@@ -9073,8 +9102,14 @@ function registerApprovalCommands(program) {
   addCommonClientOptions(
     approval.command("approve").description("Approve an approval request").argument("<approvalId>", "Approval ID").option("--decision-note <text>", "Decision note").option("--decided-by-user-id <id>", "Decision actor user ID").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder approval get <approval-id> --json",
-        'rudder approval approve <approval-id> --decision-note "Approved after reviewing linked issues" --json'
+        {
+          description: "Read the approval payload before deciding:",
+          command: "rudder approval get <approval-id> --json"
+        },
+        {
+          description: "Record the durable approval decision with concise context:",
+          command: 'rudder approval approve <approval-id> --decision-note "Approved after reviewing linked issues" --json'
+        }
       ],
       cautions: [
         "Read the approval and linked issues before approving; this is a governed mutation.",
@@ -9141,8 +9176,14 @@ function registerApprovalCommands(program) {
   addCommonClientOptions(
     approval.command("comment").description(getAgentCliCapabilityById("approval.comment").description).argument("<approvalId>", "Approval ID").option("--body-file <path>", "Read comment body from a file, or '-' for stdin").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder approval comment <approval-id> --body-file ./approval-note.md --json",
-        "printf '%s\\n' 'Need one more linked issue checked.' | rudder approval comment <approval-id> --body-file -"
+        {
+          description: "Add a longer Markdown discussion note without deciding:",
+          command: "rudder approval comment <approval-id> --body-file ./approval-note.md --json"
+        },
+        {
+          description: "Ask a short follow-up from stdin:",
+          command: "printf '%s\\n' 'Need one more linked issue checked.' | rudder approval comment <approval-id> --body-file -"
+        }
       ],
       cautions: [
         "Comments do not approve or reject; use approve/reject/request-revision for the durable decision.",
@@ -9442,8 +9483,14 @@ function registerAutomationCommands(program) {
   addCommonClientOptions(
     automation.command("run").description(getAgentCliCapabilityById("automation.run").description).argument("<automationId>", "Automation ID").option("--trigger-id <id>", "Trigger ID").option("--payload <json>", "Manual run payload JSON").option("--idempotency-key <key>", "Idempotency key").option("--source <source>", "Run source", "manual").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        `rudder automation run <automation-id> --payload '{"manual":true}' --json`,
-        "rudder automation run <automation-id> --trigger-id <trigger-id> --idempotency-key zst-123-smoke"
+        {
+          description: "Run a verified automation manually with an explicit payload:",
+          command: `rudder automation run <automation-id> --payload '{"manual":true}' --json`
+        },
+        {
+          description: "Retry a trigger-specific smoke run with duplicate protection:",
+          command: "rudder automation run <automation-id> --trigger-id <trigger-id> --idempotency-key zst-123-smoke"
+        }
       ],
       cautions: [
         "Confirm the automation and trigger target before running; manual runs can create tracked issues or chats.",
@@ -9641,8 +9688,14 @@ function registerChatCommands(program) {
   addCommonClientOptions(
     chat.command("read").description(getAgentCliCapabilityById("chat.read").description).argument("<chatId>", "Chat conversation ID").option("--include-transcript", "Include assistant transcript entries").option("--include-output", "Alias for --include-transcript").option("--include-outputs", "Alias for --include-transcript").option("--limit <n>", "Maximum recent messages", "20").option("--turn-limit <n>", "Alias for --limit for chat turn snapshots").option("--cursor <cursor>", "Stable message cursor returned in page.nextCursor").option("--max-output-chars <n>", "Maximum transcript output chars for human output", "1200").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder chat read <chat-id> --turn-limit 20 --include-output",
-        "rudder chat read <chat-id> --cursor <nextCursor> --json"
+        {
+          description: "Read a bounded conversation page with transcript output when needed:",
+          command: "rudder chat read <chat-id> --turn-limit 20 --include-output"
+        },
+        {
+          description: "Continue from a stable cursor in scripts:",
+          command: "rudder chat read <chat-id> --cursor <nextCursor> --json"
+        }
       ],
       cautions: [
         "Read bounded pages first; long chats can include large transcript payloads.",
@@ -9698,8 +9751,14 @@ function registerChatCommands(program) {
   addCommonClientOptions(
     chat.command("send").description(getAgentCliCapabilityById("chat.send").description).argument("<chatId>", "Chat conversation ID").option("--body <text>", "Message body").option("--edit-user-message-id <id>", "Regenerate/edit from a prior user message").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        'rudder chat send <chat-id> --body "Status: validation is running"',
-        "printf '%s\\n' 'Multiline note' | rudder chat send <chat-id>"
+        {
+          description: "Append a short agent-authored status note:",
+          command: 'rudder chat send <chat-id> --body "Status: validation is running"'
+        },
+        {
+          description: "Send a longer or multiline note through stdin:",
+          command: "printf '%s\\n' 'Multiline note' | rudder chat send <chat-id>"
+        }
       ],
       cautions: [
         "chat send accepts --body or stdin; it does not support --body-file.",
@@ -11301,8 +11360,14 @@ function registerIssueCommands(program) {
   addCommonClientOptions(
     issue.command("comment").description(getAgentCliCapabilityById("issue.comment").description).argument("<issueId>", "Issue ID").option("--body-file <path>", "Read comment body from a file, or '-' for stdin").option("--image <path>", "Image file to upload and append to the comment; may be repeated", collectImagePath, []).option("--reopen", "Reopen if issue is done/cancelled").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder issue comment ZST-123 --body-file ./progress.md --image ./screenshot.png --json",
-        "printf '%s\\n' 'Short status' | rudder issue comment ZST-123 --body-file -"
+        {
+          description: "Progress update with attached screenshot evidence:",
+          command: "rudder issue comment ZST-123 --body-file ./progress.md --image ./screenshot.png --json"
+        },
+        {
+          description: "Short stdin status when a separate file is unnecessary:",
+          command: "printf '%s\\n' 'Short status' | rudder issue comment ZST-123 --body-file -"
+        }
       ],
       cautions: [
         "Use --body-file for multiline Markdown; the old --body option is intentionally rejected.",
@@ -11338,8 +11403,14 @@ function registerIssueCommands(program) {
       "Review decision: approve, request_changes, needs_followup, or blocked"
     ).option("--comment-file <path>", "Read required review comment from a file, or '-' for stdin").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder issue review ZST-123 --decision request_changes --comment-file ./review.md --json",
-        "rudder issue review ZST-123 --decision approve --comment-file ./review.md"
+        {
+          description: "Return implementation work with durable review feedback:",
+          command: "rudder issue review ZST-123 --decision request_changes --comment-file ./review.md --json"
+        },
+        {
+          description: "Approve after reading the issue evidence and validation:",
+          command: "rudder issue review ZST-123 --decision approve --comment-file ./review.md"
+        }
       ],
       cautions: [
         "Free-form comments are not durable review decisions; use this command for approve/request_changes/etc.",
@@ -11387,8 +11458,14 @@ function registerIssueCommands(program) {
   addCommonClientOptions(
     issue.command("done").description(getAgentCliCapabilityById("issue.done").description).argument("<issueId>", "Issue ID").option("--comment-file <path>", "Read required completion comment from a file, or '-' for stdin").option("--image <path>", "Image file to upload and append to the completion comment; may be repeated", collectImagePath, []).addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder issue done ZST-123 --comment-file ./done.md --image ./screenshot.png --json",
-        "rudder issue done ZST-123 --comment-file - < ./done.md"
+        {
+          description: "Close out with validation summary and visual evidence:",
+          command: "rudder issue done ZST-123 --comment-file ./done.md --image ./screenshot.png --json"
+        },
+        {
+          description: "Read the completion note from stdin in scripts:",
+          command: "rudder issue done ZST-123 --comment-file - < ./done.md"
+        }
       ],
       cautions: [
         "Include validation evidence and commit/push status in the completion comment.",
@@ -11775,8 +11852,14 @@ function registerLibraryCommands(program) {
   addCommonClientOptions(
     file.command("ref").description(getAgentCliCapabilityById("library.file.ref").description).argument("<filePath>", "Library file path").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder library file ref projects/rudder/proposals/plan.md --json",
-        'rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/proposals/plan.md" --json'
+        {
+          description: "Return the renderable Markdown link for a known Library file:",
+          command: "rudder library file ref projects/rudder/proposals/plan.md --json"
+        },
+        {
+          description: "Reference a file under the current project Library path:",
+          command: 'rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/proposals/plan.md" --json'
+        }
       ],
       cautions: [
         "Pass the Library-relative path, not an absolute filesystem path.",
@@ -11794,8 +11877,14 @@ function registerLibraryCommands(program) {
   addCommonClientOptions(
     file.command("put").description(getAgentCliCapabilityById("library.file.put").description).argument("<filePath>", "Library file path").option("--body-file <path>", "Read file content from a file, or '-' for stdin").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder library file put projects/rudder/proposals/plan.md --body-file ./plan.md --json",
-        "printf '%s\\n' '# Plan' | rudder library file put projects/rudder/proposals/plan.md --body-file -"
+        {
+          description: "Upload a durable Markdown artifact from a local file:",
+          command: "rudder library file put projects/rudder/proposals/plan.md --body-file ./plan.md --json"
+        },
+        {
+          description: "Write a small generated artifact from stdin:",
+          command: "printf '%s\\n' '# Plan' | rudder library file put projects/rudder/proposals/plan.md --body-file -"
+        }
       ],
       cautions: [
         "Use --body-file for content; the old --body option is intentionally rejected.",
@@ -12090,8 +12179,14 @@ function registerProjectCommands(program) {
   addCommonClientOptions(
     project.command("create").description(getAgentCliCapabilityById("project.create").description).option("-O, --org-id <id>", "Organization ID").requiredOption("--name <name>", "Project name").option("--description <text>", "Project description").option("--status <status>", "Project status").option("--goal-id <id>", "Primary goal ID").option("--goal-ids <csv>", "Comma-separated goal IDs").option("--lead-agent-id <id>", "Lead agent ID").option("--target-date <date>", "Target date").option("--color <value>", "Project color or supported gradient token").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        'rudder project create --org-id <org-id> --name "Rudder dev" --status in_progress --json',
-        'rudder project create --org-id <org-id> --name "Release" --goal-id <goal-id> --lead-agent-id <agent-id>'
+        {
+          description: "Create a new active workstream after confirming it does not already exist:",
+          command: 'rudder project create --org-id <org-id> --name "Rudder dev" --status in_progress --json'
+        },
+        {
+          description: "Create a project tied to a goal and responsible agent:",
+          command: 'rudder project create --org-id <org-id> --name "Release" --goal-id <goal-id> --lead-agent-id <agent-id>'
+        }
       ],
       cautions: [
         "Project mutations are organization-scoped; pass --org-id when context might be ambiguous.",
@@ -12121,8 +12216,14 @@ function registerProjectCommands(program) {
   addCommonClientOptions(
     project.command("update").description(getAgentCliCapabilityById("project.update").description).argument("<projectIdOrShortname>", "Project ID or shortname").option("-O, --org-id <id>", "Organization ID for shortname resolution").option("--name <name>", "Project name").option("--description <text>", "Project description").option("--status <status>", "Project status").option("--goal-id <id>", "Primary goal ID").option("--goal-ids <csv>", "Comma-separated goal IDs").option("--lead-agent-id <id>", "Lead agent ID").option("--target-date <date>", "Target date").option("--color <value>", "Project color or supported gradient token").option("--archived-at <iso8601|null>", "Set archivedAt timestamp or literal 'null'").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder project update rudder-dev --org-id <org-id> --status in_progress --json",
-        "rudder project update <project-id> --archived-at null"
+        {
+          description: "Move a known project shortname under the intended org:",
+          command: "rudder project update rudder-dev --org-id <org-id> --status in_progress --json"
+        },
+        {
+          description: "Unarchive a verified project id:",
+          command: "rudder project update <project-id> --archived-at null"
+        }
       ],
       cautions: [
         "Shortname resolution needs the intended organization; include --org-id for cross-org local contexts.",
@@ -12173,8 +12274,14 @@ function registerRunsCommands(program) {
   addCommonClientOptions(
     runs.command("list").description(getAgentCliCapabilityById("runs.list").description).option("-O, --org-id <id>", "Organization ID").option("--updated-after <iso>", "Only runs updated after this timestamp").option("--run-id-prefix <prefix>", "Filter by run ID prefix").option("--agent-id <id>", "Filter by agent ID").option("--status <status>", "Filter by run status").option("--runtime <type>", "Filter by runtime type").option("--issue-id <id>", "Filter by linked issue ID").option("--used-skill <key-or-name>", "Filter by skill actually used during the run").option("--loaded-skill <key-or-name>", "Filter by skill loaded for the run").option("--created-before <iso>", "Only runs created before this timestamp").option("--limit <n>", "Maximum rows", "200").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder runs list --org-id <org-id> --agent-id <agent-id> --status failed --limit 20",
-        "rudder runs list --org-id <org-id> --issue-id ZST-123 --used-skill release-maintainer --json"
+        {
+          description: "Find recent failures for one agent before opening transcripts:",
+          command: "rudder runs list --org-id <org-id> --agent-id <agent-id> --status failed --limit 20"
+        },
+        {
+          description: "Collect skill-specific evidence for a linked issue:",
+          command: "rudder runs list --org-id <org-id> --issue-id ZST-123 --used-skill release-maintainer --json"
+        }
       ],
       cautions: [
         "Filter first by org, agent, issue, status, skill, or time; do not start by dumping broad run history.",
@@ -12247,8 +12354,14 @@ function registerRunsCommands(program) {
   addCommonClientOptions(
     runs.command("transcript").description(getAgentCliCapabilityById("runs.transcript").description).argument("<runId>", "Run ID or short run ID").option("--errors-only", "Show only error transcript rows").option("--around-error <id>", "Show context around a run error id such as step-12").option("--context-turns <n>", "Turns around --around-error", "1").option("--cursor <cursor>", "Stable transcript cursor returned in page.nextCursor").option("--turn-limit <n>", "Maximum turns to return", "20").option("--chronological", "Show oldest-first instead of default newest-first").option("--narrative", "Use a narrative human layout").option("--max-chars <n>", "Maximum output characters per row", "1200").option("--max-output-chars <n>", "Alias for --max-chars").option("--include-output", "Include row output in compact human transcript rows").option("--include-outputs", "Alias for --include-output").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder runs transcript <run-id> --around-error step-12 --context-turns 2",
-        "rudder runs transcript <run-id> --chronological --turn-limit 30 --include-output"
+        {
+          description: "Inspect the neighborhood around a failing step:",
+          command: "rudder runs transcript <run-id> --around-error step-12 --context-turns 2"
+        },
+        {
+          description: "Reconstruct a bounded chronological decision trail:",
+          command: "rudder runs transcript <run-id> --chronological --turn-limit 30 --include-output"
+        }
       ],
       cautions: [
         "Human output is compact and clipped by default; use --json only when a script needs the full payload.",
@@ -12275,8 +12388,14 @@ function registerRunsCommands(program) {
   addCommonClientOptions(
     runs.command("errors").description(getAgentCliCapabilityById("runs.errors").description).argument("<runId>", "Run ID or short run ID").option("--max-chars <n>", "Maximum output characters per error", "1200").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder runs errors <run-id>",
-        "rudder runs errors <run-id> --max-chars 4000 --json"
+        {
+          description: "Start failed-run investigation with error summaries:",
+          command: "rudder runs errors <run-id>"
+        },
+        {
+          description: "Increase clipped error output for scripts or reports:",
+          command: "rudder runs errors <run-id> --max-chars 4000 --json"
+        }
       ],
       cautions: [
         "Start here for failed runs, then follow the transcript context command returned for the relevant step.",
@@ -12579,8 +12698,14 @@ function registerSkillCommands(program) {
   addCommonClientOptions(
     skill.command("file").description(getAgentCliCapabilityById("skill.file").description).argument("<skillId>", "Skill ID").option("-O, --org-id <id>", "Organization ID").option("--path <path>", "Skill package file path", "SKILL.md").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder skill file <skill-uuid> --path SKILL.md --org-id <org-id>",
-        "rudder skill file <skill-uuid> --path references/usage.md --json"
+        {
+          description: "Read the main skill trigger and workflow instructions:",
+          command: "rudder skill file <skill-uuid> --path SKILL.md --org-id <org-id>"
+        },
+        {
+          description: "Inspect a specific reference file in the skill package:",
+          command: "rudder skill file <skill-uuid> --path references/usage.md --json"
+        }
       ],
       cautions: [
         "Prefer the skill UUID for slashful keys such as local/<hash>/<slug>.",
@@ -12603,8 +12728,14 @@ function registerSkillCommands(program) {
   addCommonClientOptions(
     skill.command("import").description(getAgentCliCapabilityById("skill.import").description).option("-O, --org-id <id>", "Organization ID").requiredOption("--source <source>", "Skill source (local path, URL, or repo ref)").addHelpText("after", formatExamplesAndCautions({
       examples: [
-        "rudder skill import --org-id <org-id> --source /abs/path/to/skill --json",
-        "rudder skill list --org-id <org-id> --json"
+        {
+          description: "Import a durable organization-shared skill package:",
+          command: "rudder skill import --org-id <org-id> --source /abs/path/to/skill --json"
+        },
+        {
+          description: "List imported skills afterward to get stable ids:",
+          command: "rudder skill list --org-id <org-id> --json"
+        }
       ],
       cautions: [
         "Import organization-shared skills from durable shared paths, not disposable agent-private work directories.",