@rudderhq/cli 0.3.6-canary.0 → 0.3.6-canary.2

package/dist/index.js

@@ -1768,7 +1768,7 @@ var init_agent = __esm({
 
 // ../packages/shared/dist/validators/agent-integration.js
 import { z as z13 } from "zod";
-var agentIntegrationProviderSchema, agentIntegrationStatusSchema, agentIntegrationTransportSchema, agentIntegrationProviderRegionSchema, agentIntegrationChatTypeSchema, agentIntegrationDropReasonSchema, agentIntegrationOutboundStatusSchema, createAgentIntegrationSchema;
+var agentIntegrationProviderSchema, agentIntegrationStatusSchema, agentIntegrationTransportSchema, agentIntegrationProviderRegionSchema, agentIntegrationChatTypeSchema, agentIntegrationDropReasonSchema, agentIntegrationOutboundStatusSchema, createAgentIntegrationSchema, feishuEventHeaderSchema, feishuSenderIdSchema, feishuMessageMentionSchema, feishuMessageSchema, feishuEventSchema, mockFeishuInboundEventSchema;
 var init_agent_integration = __esm({
   "../packages/shared/dist/validators/agent-integration.js"() {
     "use strict";
@@ -1792,6 +1792,52 @@ var init_agent_integration = __esm({
       installerUserId: z13.string().min(1).optional().nullable(),
       manageUrl: z13.string().url().optional().nullable()
     });
+    feishuEventHeaderSchema = z13.object({
+      event_id: z13.string().min(1).optional(),
+      app_id: z13.string().min(1).optional(),
+      create_time: z13.string().min(1).optional()
+    }).passthrough();
+    feishuSenderIdSchema = z13.object({
+      open_id: z13.string().min(1).optional(),
+      union_id: z13.string().min(1).optional()
+    }).passthrough();
+    feishuMessageMentionSchema = z13.object({
+      key: z13.string().optional(),
+      id: feishuSenderIdSchema.optional()
+    }).passthrough();
+    feishuMessageSchema = z13.object({
+      message_id: z13.string().min(1).optional(),
+      chat_id: z13.string().min(1).optional(),
+      chat_type: agentIntegrationChatTypeSchema.optional(),
+      message_type: z13.string().min(1).optional(),
+      content: z13.string().optional(),
+      mentions: z13.array(feishuMessageMentionSchema).optional(),
+      parent_id: z13.string().min(1).optional().nullable()
+    }).passthrough();
+    feishuEventSchema = z13.object({
+      sender: z13.object({
+        sender_id: feishuSenderIdSchema.optional()
+      }).passthrough().optional(),
+      message: feishuMessageSchema.optional()
+    }).passthrough();
+    mockFeishuInboundEventSchema = z13.object({
+      eventId: z13.string().min(1).optional(),
+      appId: z13.string().min(1).optional(),
+      botOpenId: z13.string().min(1).optional().nullable(),
+      chatId: z13.string().min(1).optional(),
+      chatType: agentIntegrationChatTypeSchema.optional(),
+      messageId: z13.string().min(1).optional(),
+      senderOpenId: z13.string().min(1).optional(),
+      senderUnionId: z13.string().min(1).optional().nullable(),
+      body: z13.string().optional(),
+      commandBody: z13.string().optional(),
+      addressedToBot: z13.boolean().optional(),
+      messageType: z13.string().min(1).optional(),
+      parentMessageId: z13.string().min(1).optional().nullable(),
+      receivedAt: z13.string().datetime().optional(),
+      header: feishuEventHeaderSchema.optional(),
+      event: feishuEventSchema.optional()
+    }).passthrough();
   }
 });
 
@@ -8373,6 +8419,26 @@ function formatAgentCliCapabilitiesHumanReadable(capabilities = getAgentCliCapab
   return lines.join("\n").trimEnd();
 }
 
+// src/commands/client/help.ts
+function formatExamplesAndCautions(notes) {
+  const sections = [];
+  if (notes.examples?.length) {
+    sections.push(["Examples:", ...notes.examples.map(formatHelpExample)].join("\n"));
+  }
+  if (notes.cautions?.length) {
+    sections.push(["Cautions:", ...notes.cautions.map((caution) => `  - ${caution}`)].join("\n"));
+  }
+  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));
 function codexSkillsHome() {
@@ -8689,7 +8755,22 @@ function registerAgentCommands(program) {
     })
   );
   addCommonClientOptions(
-    skills.command("enable").description(getAgentCliCapabilityById("agent.skills.enable").description).argument("<agentId>", "Agent ID").argument("<selectionRefs...>", "Skill selection refs to enable").action(async (agentId, selectionRefs, opts) => {
+    skills.command("enable").description(getAgentCliCapabilityById("agent.skills.enable").description).argument("<agentId>", "Agent ID").argument("<selectionRefs...>", "Skill selection refs to enable").addHelpText("after", formatExamplesAndCautions({
+      examples: [
+        {
+          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.",
+        "After creating or copying a private skill, enable it before claiming future runs will load it."
+      ]
+    })).action(async (agentId, selectionRefs, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const snapshot = await ctx.api.post(`/api/agents/${agentId}/skills/enable`, {
@@ -8705,7 +8786,22 @@ function registerAgentCommands(program) {
     skills.command("sync").description(getAgentCliCapabilityById("agent.skills.sync").description).argument("<agentId>", "Agent ID").requiredOption(
       "--desired-skills <csv>",
       "Comma-separated desired skill refs (for example rudder/rudder)"
-    ).action(async (agentId, opts) => {
+    ).addHelpText("after", formatExamplesAndCautions({
+      examples: [
+        {
+          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.",
+        "Preserve every existing desired skill in the CSV unless you intentionally want to disable it."
+      ]
+    })).action(async (agentId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const snapshot = await ctx.api.post(`/api/agents/${agentId}/skills/sync`, {
@@ -8994,7 +9090,22 @@ function registerApprovalCommands(program) {
     { includeCompany: false }
   );
   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").action(async (approvalId, opts) => {
+    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: [
+        {
+          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.",
+        "approval approve/reject use --decision-note, while approval comment uses --body-file."
+      ]
+    })).action(async (approvalId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const payload = resolveApprovalSchema.parse({
@@ -9053,7 +9164,22 @@ 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").action(async (approvalId, opts) => {
+    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: [
+        {
+          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.",
+        "Use --body-file for multiline Markdown. Do not pass decision notes here."
+      ]
+    })).action(async (approvalId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const body = await resolveBodyFile(opts.bodyFile);
@@ -9345,7 +9471,22 @@ 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").action(async (automationId, opts) => {
+    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: [
+        {
+          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.",
+        "Use an idempotency key for retried manual invocations so duplicate work is easier to detect."
+      ]
+    })).action(async (automationId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const payload = runAutomationSchema.parse({
@@ -9535,7 +9676,22 @@ 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").action(async (chatId, opts) => {
+    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: [
+        {
+          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.",
+        "Use --include-output only when transcript output is needed for diagnosis."
+      ]
+    })).action(async (chatId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const [conversation, page] = await Promise.all([
@@ -9583,7 +9739,22 @@ function registerChatCommands(program) {
     { includeCompany: false }
   );
   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").action(async (chatId, opts) => {
+    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: [
+        {
+          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.",
+        "Agent-authenticated sends append an agent-authored message and do not start a new assistant reply."
+      ]
+    })).action(async (chatId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const body = opts.body ?? await readStdin();
@@ -11177,7 +11348,22 @@ 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").action(async (issueId, opts) => {
+    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: [
+        {
+          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.",
+        "Attach local visual evidence with --image instead of leaving only a filesystem path in the comment."
+      ]
+    })).action(async (issueId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const bodyText = await resolveFileTextInput({
@@ -11205,7 +11391,22 @@ function registerIssueCommands(program) {
     issue.command("review").description(getAgentCliCapabilityById("issue.review").description).argument("<issueId>", "Issue ID").requiredOption(
       "--decision <decision>",
       "Review decision: approve, request_changes, needs_followup, or blocked"
-    ).option("--comment-file <path>", "Read required review comment from a file, or '-' for stdin").action(async (issueId, opts) => {
+    ).option("--comment-file <path>", "Read required review comment from a file, or '-' for stdin").addHelpText("after", formatExamplesAndCautions({
+      examples: [
+        {
+          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.",
+        "Approving an implementation issue can move it to done, so use request_changes when returning it for fixes."
+      ]
+    })).action(async (issueId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const decision = parseReviewDecision(opts.decision);
@@ -11245,7 +11446,22 @@ 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, []).action(async (issueId, opts) => {
+    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: [
+        {
+          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.",
+        "If the server reports a run ownership conflict, stop and inspect the issue/run instead of retrying blindly."
+      ]
+    })).action(async (issueId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const commentText = await resolveFileTextInput({
@@ -11624,7 +11840,22 @@ function registerLibraryCommands(program) {
     { includeCompany: true }
   );
   addCommonClientOptions(
-    file.command("ref").description(getAgentCliCapabilityById("library.file.ref").description).argument("<filePath>", "Library file path").action(async (filePath, opts) => {
+    file.command("ref").description(getAgentCliCapabilityById("library.file.ref").description).argument("<filePath>", "Library file path").addHelpText("after", formatExamplesAndCautions({
+      examples: [
+        {
+          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.",
+        "Use the returned markdownLink in issue comments instead of hand-writing library-entry URLs."
+      ]
+    })).action(async (filePath, opts) => {
       try {
         await printLibraryFileReference(filePath, opts);
       } catch (err) {
@@ -11634,7 +11865,22 @@ function registerLibraryCommands(program) {
     { includeCompany: true }
   );
   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").action(async (filePath, opts) => {
+    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: [
+        {
+          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.",
+        "For local trusted runs, prefer writing durable files under the project Library root, then use file ref for the renderable link."
+      ]
+    })).action(async (filePath, opts) => {
       try {
         const ctx = resolveCommandContext(opts, { requireCompany: true });
         const body = await resolveBodyFileInput(opts.bodyFile);
@@ -11921,7 +12167,22 @@ function registerProjectCommands(program) {
     { includeCompany: false }
   );
   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").action(async (opts) => {
+    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: [
+        {
+          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.",
+        "Use existing project IDs/shortnames for updates instead of creating duplicate project containers."
+      ]
+    })).action(async (opts) => {
       try {
         const ctx = resolveCommandContext(opts, { requireCompany: true });
         const payload = createProjectSchema.parse({
@@ -11943,7 +12204,22 @@ function registerProjectCommands(program) {
     { includeCompany: false }
   );
   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'").action(async (projectRef, opts) => {
+    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: [
+        {
+          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.",
+        "Archiving and unarchiving changes project visibility, so verify the target with project get first."
+      ]
+    })).action(async (projectRef, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const payload = updateProjectSchema.parse({
@@ -11986,7 +12262,22 @@ function projectPath(projectRef, orgId) {
 function registerRunsCommands(program) {
   const runs = program.command("runs").description("Run debugging operations");
   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").action(async (opts) => {
+    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: [
+        {
+          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.",
+        "Use runs errors or runs transcript for detail instead of expecting list to return full debug payloads."
+      ]
+    })).action(async (opts) => {
       try {
         assertSingleSkillFilter(opts);
         const ctx = resolveCommandContext(opts, { requireCompany: true });
@@ -12051,7 +12342,22 @@ 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").action(async (runId, opts) => {
+    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: [
+        {
+          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.",
+        "Use --around-error from runs errors when investigating a failure instead of reading the entire run first."
+      ]
+    })).action(async (runId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const payload = await ctx.api.get(
@@ -12070,7 +12376,22 @@ 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").action(async (runId, opts) => {
+    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: [
+        {
+          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.",
+        "Increase --max-chars deliberately; large tool outputs can be noisy and expensive to inspect."
+      ]
+    })).action(async (runId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const params = new URLSearchParams();
@@ -12365,7 +12686,22 @@ function registerSkillCommands(program) {
     { includeCompany: false }
   );
   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").action(async (skillId, opts) => {
+    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: [
+        {
+          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>.",
+        "Read SKILL.md before assuming a skill's trigger or workflow behavior."
+      ]
+    })).action(async (skillId, opts) => {
       try {
         const ctx = resolveCommandContext(opts, { requireCompany: true });
         const query = new URLSearchParams({ path: opts.path ?? "SKILL.md" });
@@ -12380,7 +12716,22 @@ function registerSkillCommands(program) {
     { includeCompany: false }
   );
   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)").action(async (opts) => {
+    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: [
+        {
+          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.",
+        "Importing a skill does not automatically enable it for every agent; update agent skill selections separately."
+      ]
+    })).action(async (opts) => {
       try {
         const ctx = resolveCommandContext(opts, { requireCompany: true });
         const payload = organizationSkillImportSchema.parse({ source: opts.source });