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

package/dist/index.js

@@ -572,6 +572,13 @@ var init_constants = __esm({
   }
 });
 
+// ../packages/shared/dist/agent-run.js
+var init_agent_run = __esm({
+  "../packages/shared/dist/agent-run.js"() {
+    "use strict";
+  }
+});
+
 // ../packages/shared/dist/types/observability.js
 var init_observability = __esm({
   "../packages/shared/dist/types/observability.js"() {
@@ -784,7 +791,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 +978,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(),
@@ -1768,7 +1778,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, connectAgentIntegrationSchema, feishuEventHeaderSchema, feishuSenderIdSchema, feishuMessageMentionSchema, feishuMessageSchema, feishuEventSchema, mockFeishuInboundEventSchema;
 var init_agent_integration = __esm({
   "../packages/shared/dist/validators/agent-integration.js"() {
     "use strict";
@@ -1792,6 +1802,59 @@ var init_agent_integration = __esm({
       installerUserId: z13.string().min(1).optional().nullable(),
       manageUrl: z13.string().url().optional().nullable()
     });
+    connectAgentIntegrationSchema = createAgentIntegrationSchema.omit({ agentId: true });
+    feishuEventHeaderSchema = z13.object({
+      event_id: z13.string().min(1).optional(),
+      app_id: z13.string().min(1).optional(),
+      token: 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({
+      type: z13.string().min(1).optional(),
+      token: z13.string().min(1).optional(),
+      challenge: z13.string().min(1).optional(),
+      mockVerificationToken: z13.string().min(1).optional(),
+      mockEncryptKey: z13.string().min(1).optional(),
+      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();
   }
 });
 
@@ -2929,6 +2992,7 @@ var init_api = __esm({
       secrets: `${API_PREFIX}/secrets`,
       costs: `${API_PREFIX}/costs`,
       activity: `${API_PREFIX}/activity`,
+      agentRuns: `${API_PREFIX}/agent-runs`,
       dashboard: `${API_PREFIX}/dashboard`,
       sidebarBadges: `${API_PREFIX}/sidebar-badges`,
       invites: `${API_PREFIX}/invites`,
@@ -2987,6 +3051,19 @@ var init_project_url_key = __esm({
   }
 });
 
+// ../packages/shared/dist/short-refs.js
+var SHORT_REF_PREFIX_BY_KIND, SHORT_REF_KIND_BY_PREFIX;
+var init_short_refs = __esm({
+  "../packages/shared/dist/short-refs.js"() {
+    "use strict";
+    SHORT_REF_PREFIX_BY_KIND = {
+      agent: "agt",
+      issue_comment: "cmt"
+    };
+    SHORT_REF_KIND_BY_PREFIX = Object.fromEntries(Object.entries(SHORT_REF_PREFIX_BY_KIND).map(([kind, prefix]) => [prefix, kind]));
+  }
+});
+
 // ../packages/shared/dist/token-usage.js
 var init_token_usage = __esm({
   "../packages/shared/dist/token-usage.js"() {
@@ -3191,6 +3268,7 @@ var init_dist = __esm({
   "../packages/shared/dist/index.js"() {
     "use strict";
     init_constants();
+    init_agent_run();
     init_observability();
     init_workspace_backup();
     init_validators();
@@ -3202,6 +3280,7 @@ var init_dist = __esm({
     init_organization_url_key();
     init_project_mentions();
     init_project_url_key();
+    init_short_refs();
     init_token_usage();
     init_issue_activity();
     init_config_schema();
@@ -6966,7 +7045,7 @@ function printOutput(data, opts = {}) {
 }
 function formatInlineRecord(record, opts = {}) {
   const displayRecord = shouldShowFullIds(opts.fullIds) ? record : toCliShortIdOutput(record);
-  const keyOrder = ["identifier", "id", "name", "status", "priority", "title", "action"];
+  const keyOrder = ["identifier", "shortRef", "id", "name", "status", "priority", "title", "action"];
   const seen = /* @__PURE__ */ new Set();
   const parts = [];
   for (const key of keyOrder) {
@@ -7237,6 +7316,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.",
@@ -7252,7 +7332,7 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
   "",
   "You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing shared work notes. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, and recall conventions.",
   "",
-  "Keep stable preferences and operating lessons in `$AGENT_HOME/instructions/MEMORY.md`. Use `$AGENT_HOME/memory/YYYY-MM-DD.md` for daily notes and `$AGENT_HOME/life/` for structured long-term memory; those files are not auto-loaded.",
+  "Keep stable preferences and operating lessons in `$AGENT_HOME/instructions/MEMORY.md`. Use `$AGENT_HOME/memory/YYYY-MM-DD.md` for daily notes and `$AGENT_HOME/life/` for structured long-term memory. Rudder injects bounded today/yesterday daily-memory excerpts in the startup context bundle; open the files directly when you need full detail.",
   "",
   "Invoke it whenever you need to remember, retrieve, or organize anything.",
   "",
@@ -7269,19 +7349,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");
@@ -7390,9 +7476,9 @@ var AGENT_CLI_CAPABILITIES = [
   },
   {
     id: "agent.get",
-    command: "rudder agent get <agent-id-or-shortname>",
+    command: "rudder agent get <agent-id-or-shortname-or-agt-ref>",
     category: "agent",
-    description: "Read one agent by id or shortname.",
+    description: "Read one agent by id, shortname, or agt_<uuid-prefix> short ref.",
     mutating: false,
     contract: "compat",
     requiresOrgId: false,
@@ -7546,9 +7632,9 @@ var AGENT_CLI_CAPABILITIES = [
   },
   {
     id: "issue.context",
-    command: "rudder issue context <issue>",
+    command: "rudder issue context <issue> [--wake-comment-id <comment-id-or-cmt-ref>]",
     category: "issue",
-    description: "Read the compact heartbeat context for an issue.",
+    description: "Read the compact heartbeat context for an issue; wake comments may be addressed by full id or cmt_<uuid-prefix>.",
     mutating: false,
     contract: "agent-v1",
     requiresOrgId: false,
@@ -7582,9 +7668,9 @@ var AGENT_CLI_CAPABILITIES = [
   },
   {
     id: "issue.comments.list",
-    command: "rudder issue comments list <issue>",
+    command: "rudder issue comments list <issue> [--after <comment-id-or-cmt-ref>]",
     category: "issue",
-    description: "List issue comments, optionally only newer comments after a cursor.",
+    description: "List issue comments, optionally only newer comments after a full comment id or cmt_<uuid-prefix> with --after.",
     mutating: false,
     contract: "agent-v1",
     requiresOrgId: false,
@@ -7594,9 +7680,9 @@ var AGENT_CLI_CAPABILITIES = [
   },
   {
     id: "issue.comments.get",
-    command: "rudder issue comments get <issue> <comment-id>",
+    command: "rudder issue comments get <issue> <comment-id-or-cmt-ref>",
     category: "issue",
-    description: "Read one issue comment by id.",
+    description: "Read one issue comment by full id or cmt_<uuid-prefix> scoped to the issue.",
     mutating: false,
     contract: "agent-v1",
     requiresOrgId: false,
@@ -8373,6 +8459,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() {
@@ -8537,6 +8643,7 @@ function registerAgentCommands(program) {
         for (const row of rows) {
           console.log(
             formatInlineRecord({
+              shortRef: row.shortRef,
               id: row.id,
               name: row.name,
               role: row.role,
@@ -8689,7 +8796,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 +8827,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 +9131,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 +9205,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 +9512,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 +9717,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 +9780,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 +11389,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 +11432,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 +11487,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({
@@ -11288,7 +11545,7 @@ function registerIssueCommands(program) {
   );
   const comments = issue.command("comments").description("Issue comment operations");
   addCommonClientOptions(
-    comments.command("list").description(getAgentCliCapabilityById("issue.comments.list").description).argument("<issueId>", "Issue ID").option("--after <commentId>", "Only return comments after this comment ID").option("--order <order>", "Comment ordering (asc or desc)", "desc").action(async (issueId, opts) => {
+    comments.command("list").description(getAgentCliCapabilityById("issue.comments.list").description).argument("<issueId>", "Issue ID").option("--after <commentId>", "Only return comments after this full comment ID or cmt_<uuid-prefix>").option("--order <order>", "Comment ordering (asc or desc)", "desc").action(async (issueId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const params = new URLSearchParams();
@@ -11305,7 +11562,7 @@ function registerIssueCommands(program) {
     })
   );
   addCommonClientOptions(
-    comments.command("get").description(getAgentCliCapabilityById("issue.comments.get").description).argument("<issueId>", "Issue ID").argument("<commentId>", "Comment ID").action(async (issueId, commentId, opts) => {
+    comments.command("get").description(getAgentCliCapabilityById("issue.comments.get").description).argument("<issueId>", "Issue ID").argument("<commentId>", "Full comment ID or cmt_<uuid-prefix>").action(async (issueId, commentId, opts) => {
       try {
         const ctx = resolveCommandContext(opts);
         const row = await ctx.api.get(`/api/issues/${issueId}/comments/${commentId}`);
@@ -11624,7 +11881,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 +11906,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 +12208,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 +12245,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 +12303,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 +12383,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 +12417,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 +12727,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 +12757,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 });
@@ -13405,6 +13797,7 @@ function createByteProgress(label, options = {}) {
 init_version();
 var DEFAULT_DESKTOP_RELEASE_REPO = "Undertone0809/rudder";
 var DESKTOP_UPDATE_QUIT_ARG = "--rudder-update-quit";
+var DESKTOP_UPDATE_FORCE_ARG = "--rudder-update-force";
 var STABLE_SEMVER_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
 var CANARY_SEMVER_RE = /^[0-9]+\.[0-9]+\.[0-9]+-canary\.[0-9]+$/;
 var CLI_REGISTRY_LATEST_URL = "https://registry.npmjs.org/@rudderhq%2fcli/latest";
@@ -13488,7 +13881,7 @@ function createDesktopProgressFactory() {
 async function waitForDesktopApplySignal() {
   process.stdin.setEncoding("utf8");
   process.stdin.resume();
-  await new Promise((resolve, reject) => {
+  return await new Promise((resolve, reject) => {
     let buffer = "";
     const cleanup = () => {
       process.stdin.off("data", onData);
@@ -13499,9 +13892,15 @@ async function waitForDesktopApplySignal() {
       buffer += chunk;
       const lines = buffer.split(/\r?\n/);
       buffer = lines.pop() ?? "";
-      if (lines.some((line) => line.trim() === "apply")) {
+      const commands = lines.map((line) => line.trim());
+      if (commands.includes("force-apply")) {
         cleanup();
-        resolve();
+        resolve({ force: true });
+        return;
+      }
+      if (commands.includes("apply")) {
+        cleanup();
+        resolve({ force: false });
       }
     };
     const onEnd = () => {
@@ -14214,14 +14613,6 @@ function isInstalledDesktopCurrent(metadata, releaseTag, assetName, assetChecksu
     metadata && metadata.releaseTag === releaseTag && metadata.assetName === assetName && metadata.assetChecksum === assetChecksum
   );
 }
-function buildForceQuitCommand(target) {
-  if (target.platform === "windows") return { command: "taskkill.exe", args: ["/IM", `${DESKTOP_APP_NAME}.exe`, "/T", "/F"] };
-  return { command: "pkill", args: ["-x", DESKTOP_APP_NAME] };
-}
-function forceQuitDesktopProcesses(target) {
-  const command = buildForceQuitCommand(target);
-  spawnSync3(command.command, command.args, { stdio: "ignore" });
-}
 function forceQuitDesktopProcess(pid, target) {
   if (target.platform === "windows") {
     spawnSync3("taskkill.exe", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
@@ -14232,8 +14623,35 @@ function forceQuitDesktopProcess(pid, target) {
   } catch {
   }
 }
-function isRunningInsideDesktopExecutable() {
-  return path21.basename(process.execPath).toLowerCase().startsWith(DESKTOP_APP_NAME.toLowerCase());
+function quotePowerShellString(value) {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+function findDesktopExecutablePids(executablePath, target) {
+  if (target.platform === "windows") {
+    const result2 = spawnSync3("powershell.exe", [
+      "-NoProfile",
+      "-Command",
+      `Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -eq ${quotePowerShellString(executablePath)} } | Select-Object -ExpandProperty ProcessId`
+    ], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (result2.status !== 0) return [];
+    return result2.stdout.split(/\r?\n/).map((line) => Number.parseInt(line.trim(), 10)).filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== process.pid);
+  }
+  const result = spawnSync3("ps", ["-eo", "pid=,args="], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (result.status !== 0) return [];
+  return result.stdout.split(/\r?\n/).flatMap((line) => {
+    const match = line.match(/^\s*(\d+)\s+(.+)$/);
+    if (!match) return [];
+    const pid = Number.parseInt(match[1], 10);
+    const commandLine = match[2];
+    const matchesExecutable = commandLine === executablePath || commandLine.startsWith(`${executablePath} `);
+    return matchesExecutable && pid !== process.pid ? [pid] : [];
+  });
 }
 async function waitForUpdateQuitResponse(responsePath, timeoutMs = 8e3) {
   const startedAt = Date.now();
@@ -14245,10 +14663,13 @@ async function waitForUpdateQuitResponse(responsePath, timeoutMs = 8e3) {
   }
   return null;
 }
-async function requestDesktopQuit(executablePath, target) {
+async function requestDesktopQuit(executablePath, target, options = {}) {
   if (!await pathExists2(executablePath)) return { ok: true, status: "not_running" };
   const responsePath = path21.join(tmpdir(), `rudder-update-quit-${process.pid}-${Date.now()}.json`);
-  const result = spawnSync3(executablePath, [`${DESKTOP_UPDATE_QUIT_ARG}=${responsePath}`], {
+  const result = spawnSync3(executablePath, [
+    `${DESKTOP_UPDATE_QUIT_ARG}=${responsePath}`,
+    ...options.forceUpdate ? [DESKTOP_UPDATE_FORCE_ARG] : []
+  ], {
     stdio: "ignore",
     timeout: 5e3
   });
@@ -14256,7 +14677,7 @@ async function requestDesktopQuit(executablePath, target) {
     return null;
   }
   try {
-    return await waitForUpdateQuitResponse(responsePath);
+    return await waitForUpdateQuitResponse(responsePath, options.responseTimeoutMs);
   } finally {
     await rm2(responsePath, { force: true });
   }
@@ -14285,6 +14706,12 @@ async function waitForProcessExit(pid, timeoutMs = 2e4, intervalMs = 250) {
   }
   return !processExists(pid);
 }
+async function waitForProcessesExit(pids, waitForExit) {
+  const uniquePids = [...new Set(pids)];
+  if (uniquePids.length === 0) return true;
+  const results = await Promise.all(uniquePids.map((pid) => waitForExit(pid)));
+  return results.every(Boolean);
+}
 async function removePathWithRetry(targetPath, attempts = 5) {
   for (let attempt = 0; attempt < attempts; attempt += 1) {
     try {
@@ -14297,50 +14724,98 @@ async function removePathWithRetry(targetPath, attempts = 5) {
   return false;
 }
 async function prepareForDesktopReplace(paths, target, options = {}) {
-  const forceQuit = options.forceQuitDesktopProcesses ?? forceQuitDesktopProcesses;
   const forceQuitPid = options.forceQuitDesktopProcess ?? forceQuitDesktopProcess;
   const waitForExit = options.waitForDesktopProcessExit ?? waitForProcessExit;
+  const findPids = options.findDesktopExecutablePids ?? findDesktopExecutablePids;
+  async function forceQuitPidAndConfirm(pid) {
+    forceQuitPid(pid, target);
+    await delay2(options.updateQuitForceDelayMs ?? UPDATE_QUIT_FORCE_DELAY_MS);
+    if (!await waitForExit(pid)) {
+      throw new Error(`Rudder Desktop process ${pid} did not exit after force-quit fallback. Close Rudder and rerun start.`);
+    }
+  }
+  async function forceQuitPidsAndConfirm(pids) {
+    const uniquePids = [...new Set(pids)];
+    for (const pid of uniquePids) {
+      forceQuitPid(pid, target);
+    }
+    await delay2(options.updateQuitForceDelayMs ?? UPDATE_QUIT_FORCE_DELAY_MS);
+    if (!await waitForProcessesExit(uniquePids, waitForExit)) {
+      throw new Error(`Rudder Desktop process${uniquePids.length === 1 ? "" : "es"} ${uniquePids.join(", ")} did not exit after force-quit fallback. Close Rudder and rerun start.`);
+    }
+  }
+  let quitPid = null;
+  let managedExecutablePids = [];
   const hasManagedExecutable = await pathExists2(paths.executablePath);
   if (hasManagedExecutable) {
-    let quitResponse = await requestDesktopQuit(paths.executablePath, target);
-    while (quitResponse && !quitResponse.ok && quitResponse.status === "active_runs" && options.waitForActiveRuns) {
+    managedExecutablePids = findPids(paths.executablePath, target);
+    const requestQuit = () => requestDesktopQuit(paths.executablePath, target, {
+      forceUpdate: options.forceUpdate,
+      responseTimeoutMs: options.updateQuitResponseTimeoutMs
+    });
+    let quitResponse = await requestQuit();
+    while (quitResponse && !quitResponse.ok && quitResponse.status === "active_runs" && options.waitForActiveRuns && !options.forceUpdate) {
       p15.log.warn(
         `Rudder Desktop has ${quitResponse.totalRuns} active run${quitResponse.totalRuns === 1 ? "" : "s"}; waiting before replacing Desktop.`
       );
       await delay2(options.activeRunPollIntervalMs ?? 15e3);
-      quitResponse = await requestDesktopQuit(paths.executablePath, target);
+      quitResponse = await requestQuit();
     }
     if (quitResponse && !quitResponse.ok && quitResponse.status === "active_runs") {
+      if (!options.forceUpdate) {
+        throw new Error(
+          `Rudder Desktop has ${quitResponse.totalRuns} active run${quitResponse.totalRuns === 1 ? "" : "s"}. Stop active work, then rerun start.`
+        );
+      }
       throw new Error(
-        `Rudder Desktop has ${quitResponse.totalRuns} active run${quitResponse.totalRuns === 1 ? "" : "s"}. Stop active work, then rerun start.`
+        `Rudder Desktop still has ${quitResponse.totalRuns} active run${quitResponse.totalRuns === 1 ? "" : "s"} after the force-update request. Stop active work, then rerun start.`
       );
     }
-    const quitPid = readUpdateQuitPid(quitResponse);
+    if (quitResponse && !quitResponse.ok && quitResponse.status === "failed") {
+      throw new Error(quitResponse.message);
+    }
+    quitPid = readUpdateQuitPid(quitResponse);
     if (quitPid) {
       p15.log.info(`Waiting for existing Rudder Desktop process ${quitPid} to exit before replacing it.`);
       if (!await waitForExit(quitPid)) {
         p15.log.warn(`Rudder Desktop process ${quitPid} did not exit in time; attempting force-quit fallback.`);
-        forceQuitPid(quitPid, target);
-        await delay2(options.updateQuitForceDelayMs ?? UPDATE_QUIT_FORCE_DELAY_MS);
+        await forceQuitPidAndConfirm(quitPid);
       }
     } else if (isLegacyUnconfirmedUpdateQuit(quitResponse)) {
       const graceMs = options.legacyUpdateQuitGraceMs ?? LEGACY_UPDATE_QUIT_GRACE_MS;
       p15.log.warn(
-        `Existing Rudder Desktop acknowledged update quit without a process id; waiting ${Math.ceil(graceMs / 1e3)}s before force-quit fallback.`
+        `Existing Rudder Desktop acknowledged update quit without a process id; waiting ${Math.ceil(graceMs / 1e3)}s before replacement.`
       );
       await delay2(graceMs);
-      forceQuit(target);
-      await delay2(options.updateQuitForceDelayMs ?? UPDATE_QUIT_FORCE_DELAY_MS);
+      if (managedExecutablePids.length > 0 && !await waitForProcessesExit(managedExecutablePids, waitForExit)) {
+        p15.log.warn(
+          `Existing Rudder Desktop did not exit after acknowledging update quit; attempting path-scoped force-quit for process${managedExecutablePids.length === 1 ? "" : "es"} ${managedExecutablePids.join(", ")}.`
+        );
+        await forceQuitPidsAndConfirm(managedExecutablePids);
+      }
+    } else if (!quitResponse) {
+      if (options.forceUpdate && managedExecutablePids.length > 0) {
+        p15.log.warn(
+          `Existing Rudder Desktop did not respond to the update quit request; attempting path-scoped force-quit for process${managedExecutablePids.length === 1 ? "" : "es"} ${managedExecutablePids.join(", ")}.`
+        );
+        await forceQuitPidsAndConfirm(managedExecutablePids);
+      } else {
+        throw new Error("Existing Rudder Desktop did not respond to the update quit request. Close Rudder and rerun start.");
+      }
     } else {
       await delay2(options.updateQuitForceDelayMs ?? UPDATE_QUIT_FORCE_DELAY_MS);
     }
-  } else if (!isRunningInsideDesktopExecutable()) {
-    forceQuit(target);
   }
   const replacePath = target.platform === "windows" ? paths.installRoot : paths.appPath;
   if (await removePathWithRetry(replacePath)) return;
-  forceQuit(target);
-  await delay2(options.updateQuitForceDelayMs ?? UPDATE_QUIT_FORCE_DELAY_MS);
+  if (!quitPid) {
+    if (managedExecutablePids.length > 0) {
+      await forceQuitPidsAndConfirm(managedExecutablePids);
+      if (await removePathWithRetry(replacePath, 6)) return;
+    }
+    throw new Error(`Failed to replace existing Rudder Desktop at ${replacePath}. Close Rudder and rerun start.`);
+  }
+  await forceQuitPidAndConfirm(quitPid);
   if (await removePathWithRetry(replacePath, 6)) return;
   throw new Error(`Failed to replace existing Rudder Desktop at ${replacePath}. Close Rudder and rerun start.`);
 }
@@ -14673,22 +15148,26 @@ async function startCommand(opts) {
           () => assertChecksumMatch(cachedAsset.path, expectedChecksum),
           desktopProgressJson ? "verifying_checksum" : null
         );
+        let applySignal = null;
         if (desktopProgressJson && opts.desktopWaitForApply === true) {
           writeDesktopProgress({
             phase: "ready_to_install",
             message: "Desktop update is downloaded and verified.",
             percent: 100
           });
-          await waitForDesktopApplySignal();
+          applySignal = await waitForDesktopApplySignal();
           writeDesktopProgress({
             phase: "preparing_restart",
-            message: "Applying Desktop update..."
+            message: applySignal.force ? "Applying Desktop update and quitting active runs..." : "Applying Desktop update..."
           });
         }
         await runStartPhase(
           "Replacing existing Rudder Desktop if needed...",
           "Existing Desktop install is ready for replacement.",
-          () => prepareForDesktopReplace(installPaths, target, { waitForActiveRuns: opts.waitForActiveRuns === true }),
+          () => prepareForDesktopReplace(installPaths, target, {
+            waitForActiveRuns: opts.waitForActiveRuns === true,
+            forceUpdate: applySignal?.force === true
+          }),
           desktopProgressJson ? opts.waitForActiveRuns === true ? "waiting_for_active_runs" : "preparing_restart" : null
         );
         await runStartPhase(