@rudderhq/cli 0.3.4-canary.1 → 0.3.4-canary.11

package/dist/index.js

@@ -10,7 +10,7 @@ var __export = (target, all) => {
 };
 
 // ../packages/shared/dist/constants.js
-var ORGANIZATION_STATUSES, ORGANIZATION_INTELLIGENCE_PROFILE_PURPOSES, ORGANIZATION_INTELLIGENCE_PROFILE_STATUSES, DEPLOYMENT_MODES, DEPLOYMENT_EXPOSURES, AUTH_BASE_URL_MODES, AGENT_STATUSES, AGENT_RUNTIME_TYPES, AGENT_ROLES, AGENT_ICON_NAMES, AGENT_DICEBEAR_NOTIONISTS_ICON_PREFIX, AGENT_AVATAR_BACKGROUND_PRESET_IDS, ISSUE_STATUSES, ISSUE_PRIORITIES, CALENDAR_SOURCE_TYPES, CALENDAR_OWNER_TYPES, CALENDAR_VISIBILITIES, CALENDAR_SOURCE_STATUSES, CALENDAR_EVENT_KINDS, CALENDAR_EVENT_STATUSES, CALENDAR_SOURCE_MODES, CHAT_CONVERSATION_STATUSES, CHAT_ISSUE_CREATION_MODES, CHAT_MESSAGE_ROLES, CHAT_MESSAGE_KINDS, CHAT_MESSAGE_STATUSES, CHAT_CONTEXT_ENTITY_TYPES, GOAL_LEVELS, GOAL_STATUSES, PROJECT_STATUSES, ORGANIZATION_RESOURCE_KINDS, ORGANIZATION_RESOURCE_SOURCE_TYPES, PROJECT_RESOURCE_ATTACHMENT_ROLES, AUTOMATION_STATUSES, AUTOMATION_CONCURRENCY_POLICIES, AUTOMATION_CATCH_UP_POLICIES, AUTOMATION_OUTPUT_MODES, AUTOMATION_TRIGGER_SIGNING_MODES, PROJECT_COLORS, APPROVAL_TYPES, SECRET_PROVIDERS, STORAGE_PROVIDERS, BILLING_TYPES, FINANCE_EVENT_KINDS, FINANCE_DIRECTIONS, FINANCE_UNITS, BUDGET_SCOPE_TYPES, BUDGET_METRICS, BUDGET_WINDOW_KINDS, BUDGET_INCIDENT_RESOLUTION_ACTIONS, INVITE_JOIN_TYPES, JOIN_REQUEST_TYPES, JOIN_REQUEST_STATUSES, PERMISSION_KEYS, PLUGIN_STATUSES, PLUGIN_CATEGORIES, PLUGIN_CAPABILITIES, PLUGIN_UI_SLOT_TYPES, PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS, PLUGIN_LAUNCHER_PLACEMENT_ZONES, PLUGIN_LAUNCHER_ACTIONS, PLUGIN_LAUNCHER_BOUNDS, PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS, PLUGIN_UI_SLOT_ENTITY_TYPES, PLUGIN_STATE_SCOPE_KINDS;
+var ORGANIZATION_STATUSES, ORGANIZATION_INTELLIGENCE_PROFILE_PURPOSES, ORGANIZATION_INTELLIGENCE_PROFILE_STATUSES, DEPLOYMENT_MODES, DEPLOYMENT_EXPOSURES, AUTH_BASE_URL_MODES, AGENT_STATUSES, AGENT_RUNTIME_TYPES, AGENT_ROLES, AGENT_ICON_NAMES, AGENT_DICEBEAR_NOTIONISTS_ICON_PREFIX, AGENT_AVATAR_BACKGROUND_PRESET_IDS, ISSUE_STATUSES, ISSUE_PRIORITIES, CALENDAR_SOURCE_TYPES, CALENDAR_OWNER_TYPES, CALENDAR_VISIBILITIES, CALENDAR_SOURCE_STATUSES, CALENDAR_EVENT_KINDS, CALENDAR_EVENT_STATUSES, CALENDAR_SOURCE_MODES, CHAT_CONVERSATION_STATUSES, CHAT_ISSUE_CREATION_MODES, CHAT_MESSAGE_ROLES, CHAT_MESSAGE_KINDS, CHAT_MESSAGE_STATUSES, CHAT_CONTEXT_ENTITY_TYPES, GOAL_LEVELS, GOAL_STATUSES, PROJECT_STATUSES, ORGANIZATION_RESOURCE_KINDS, ORGANIZATION_RESOURCE_SOURCE_TYPES, PROJECT_RESOURCE_ATTACHMENT_ROLES, AUTOMATION_STATUSES, AUTOMATION_CONCURRENCY_POLICIES, AUTOMATION_CATCH_UP_POLICIES, AUTOMATION_OUTPUT_MODES, AUTOMATION_TRIGGER_SIGNING_MODES, PROJECT_COLORS, PROJECT_ICONS, APPROVAL_TYPES, SECRET_PROVIDERS, STORAGE_PROVIDERS, BILLING_TYPES, FINANCE_EVENT_KINDS, FINANCE_DIRECTIONS, FINANCE_UNITS, BUDGET_SCOPE_TYPES, BUDGET_METRICS, BUDGET_WINDOW_KINDS, BUDGET_INCIDENT_RESOLUTION_ACTIONS, INVITE_JOIN_TYPES, JOIN_REQUEST_TYPES, JOIN_REQUEST_STATUSES, PERMISSION_KEYS, PLUGIN_STATUSES, PLUGIN_CATEGORIES, PLUGIN_CAPABILITIES, PLUGIN_UI_SLOT_TYPES, PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS, PLUGIN_LAUNCHER_PLACEMENT_ZONES, PLUGIN_LAUNCHER_ACTIONS, PLUGIN_LAUNCHER_BOUNDS, PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS, PLUGIN_UI_SLOT_ENTITY_TYPES, PLUGIN_STATE_SCOPE_KINDS;
 var init_constants = __esm({
   "../packages/shared/dist/constants.js"() {
     "use strict";
@@ -186,6 +186,24 @@ var init_constants = __esm({
       "linear-gradient(135deg, #475569 0%, #0f766e 100%)",
       "linear-gradient(135deg, #334155 0%, #7c3aed 100%)"
     ];
+    PROJECT_ICONS = [
+      "folder",
+      "book",
+      "plane",
+      "globe",
+      "code",
+      "rocket",
+      "target",
+      "lightbulb",
+      "wrench",
+      "shield",
+      "database",
+      "megaphone",
+      "palette",
+      "users",
+      "calendar",
+      "package"
+    ];
     APPROVAL_TYPES = [
       "hire_agent",
       "approve_ceo_strategy",
@@ -1571,7 +1589,7 @@ function validateProjectWorkspace(value, ctx) {
     });
   }
 }
-var executionWorkspaceStrategySchema, projectExecutionWorkspacePolicySchema, projectWorkspaceSourceTypeSchema, projectWorkspaceVisibilitySchema, projectWorkspaceFields, projectColorValues, legacyProjectColorSchema, projectColorSchema, createProjectWorkspaceSchema, updateProjectWorkspaceSchema, projectFields, createProjectSchema, updateProjectSchema;
+var executionWorkspaceStrategySchema, projectExecutionWorkspacePolicySchema, projectWorkspaceSourceTypeSchema, projectWorkspaceVisibilitySchema, projectWorkspaceFields, projectColorValues, legacyProjectColorSchema, projectColorSchema, projectIconSchema, createProjectWorkspaceSchema, updateProjectWorkspaceSchema, projectFields, createProjectSchema, updateProjectSchema;
 var init_project = __esm({
   "../packages/shared/dist/validators/project.js"() {
     "use strict";
@@ -1617,6 +1635,7 @@ var init_project = __esm({
     projectColorValues = new Set(PROJECT_COLORS);
     legacyProjectColorSchema = z13.string().regex(/^#[0-9a-fA-F]{6}$/);
     projectColorSchema = z13.string().refine((value) => legacyProjectColorSchema.safeParse(value).success || projectColorValues.has(value), "Color must be a 6-digit hex value or a supported project gradient");
+    projectIconSchema = z13.enum(PROJECT_ICONS);
     createProjectWorkspaceSchema = z13.object({
       ...projectWorkspaceFields,
       isPrimary: z13.boolean().optional().default(false)
@@ -1635,6 +1654,7 @@ var init_project = __esm({
       leadAgentId: z13.string().uuid().optional().nullable(),
       targetDate: z13.string().optional().nullable(),
       color: projectColorSchema.optional().nullable(),
+      icon: projectIconSchema.optional().nullable(),
       executionWorkspacePolicy: projectExecutionWorkspacePolicySchema.optional().nullable(),
       resourceAttachments: z13.array(projectResourceAttachmentInputSchema).optional(),
       newResources: z13.array(createProjectInlineResourceSchema).optional(),
@@ -1649,12 +1669,12 @@ var init_project = __esm({
 
 // ../packages/shared/dist/validators/issue.js
 import { z as z14 } from "zod";
-var executionWorkspaceStrategySchema2, issueExecutionWorkspaceSettingsSchema, issueAssigneeAdapterOverridesSchema, createIssueSchema, createIssueLabelSchema, updateIssueLabelSchema, updateIssueSchema, reorderIssueSchema, checkoutIssueSchema, addIssueCommentSchema, updateIssueCommentSchema, reportIssueCommitSchema, linkIssueApprovalSchema, createIssueAttachmentMetadataSchema, createIssueWorkspaceAttachmentSchema, ISSUE_DOCUMENT_FORMATS, issueDocumentFormatSchema, issueDocumentKeySchema, upsertIssueDocumentSchema, createLibraryDocumentSchema, updateLibraryDocumentSchema, restoreLibraryDocumentRevisionSchema;
+var runWorkspaceStrategySchema, issueRunWorkspaceSettingsSchema, issueAssigneeAdapterOverridesSchema, createIssueSchema, createIssueLabelSchema, updateIssueLabelSchema, updateIssueSchema, reorderIssueSchema, checkoutIssueSchema, addIssueCommentSchema, updateIssueCommentSchema, reportIssueCommitSchema, linkIssueApprovalSchema, createIssueAttachmentMetadataSchema, createIssueWorkspaceAttachmentSchema, ISSUE_DOCUMENT_FORMATS, issueDocumentFormatSchema, issueDocumentKeySchema, upsertIssueDocumentSchema, createLibraryDocumentSchema, updateLibraryDocumentSchema, restoreLibraryDocumentRevisionSchema;
 var init_issue = __esm({
   "../packages/shared/dist/validators/issue.js"() {
     "use strict";
     init_constants();
-    executionWorkspaceStrategySchema2 = z14.object({
+    runWorkspaceStrategySchema = z14.object({
       type: z14.enum(["project_primary", "git_worktree", "adapter_managed", "cloud_sandbox"]).optional(),
       baseRef: z14.string().optional().nullable(),
       branchTemplate: z14.string().optional().nullable(),
@@ -1662,9 +1682,9 @@ var init_issue = __esm({
       provisionCommand: z14.string().optional().nullable(),
       teardownCommand: z14.string().optional().nullable()
     }).strict();
-    issueExecutionWorkspaceSettingsSchema = z14.object({
+    issueRunWorkspaceSettingsSchema = z14.object({
       mode: z14.enum(["inherit", "shared_workspace", "isolated_workspace", "operator_branch", "reuse_existing", "agent_default"]).optional(),
-      workspaceStrategy: executionWorkspaceStrategySchema2.optional().nullable(),
+      workspaceStrategy: runWorkspaceStrategySchema.optional().nullable(),
       workspaceRuntime: z14.record(z14.unknown()).optional().nullable()
     }).strict();
     issueAssigneeAdapterOverridesSchema = z14.object({
@@ -1687,7 +1707,19 @@ var init_issue = __esm({
       requestDepth: z14.number().int().nonnegative().optional().default(0),
       billingCode: z14.string().optional().nullable(),
       assigneeAgentRuntimeOverrides: issueAssigneeAdapterOverridesSchema.optional().nullable(),
+      runWorkspaceId: z14.string().uuid().optional().nullable(),
+      runWorkspacePreference: z14.enum([
+        "inherit",
+        "shared_workspace",
+        "isolated_workspace",
+        "operator_branch",
+        "reuse_existing",
+        "agent_default"
+      ]).optional().nullable(),
+      runWorkspaceSettings: issueRunWorkspaceSettingsSchema.optional().nullable(),
+      /** @deprecated Use runWorkspaceId. */
       executionWorkspaceId: z14.string().uuid().optional().nullable(),
+      /** @deprecated Use runWorkspacePreference. */
       executionWorkspacePreference: z14.enum([
         "inherit",
         "shared_workspace",
@@ -1696,7 +1728,8 @@ var init_issue = __esm({
         "reuse_existing",
         "agent_default"
       ]).optional().nullable(),
-      executionWorkspaceSettings: issueExecutionWorkspaceSettingsSchema.optional().nullable(),
+      /** @deprecated Use runWorkspaceSettings. */
+      executionWorkspaceSettings: issueRunWorkspaceSettingsSchema.optional().nullable(),
       labelIds: z14.array(z14.string().uuid()).optional()
     });
     createIssueLabelSchema = z14.object({
@@ -1814,6 +1847,8 @@ var init_work_product = __esm({
     ]);
     createIssueWorkProductSchema = z15.object({
       projectId: z15.string().uuid().optional().nullable(),
+      runWorkspaceId: z15.string().uuid().optional().nullable(),
+      /** @deprecated Use runWorkspaceId. */
       executionWorkspaceId: z15.string().uuid().optional().nullable(),
       runtimeServiceId: z15.string().uuid().optional().nullable(),
       type: issueWorkProductTypeSchema,
@@ -1835,19 +1870,19 @@ var init_work_product = __esm({
 
 // ../packages/shared/dist/validators/execution-workspace.js
 import { z as z16 } from "zod";
-var executionWorkspaceStatusSchema, updateExecutionWorkspaceSchema;
+var runWorkspaceStatusSchema, updateRunWorkspaceSchema;
 var init_execution_workspace = __esm({
   "../packages/shared/dist/validators/execution-workspace.js"() {
     "use strict";
-    executionWorkspaceStatusSchema = z16.enum([
+    runWorkspaceStatusSchema = z16.enum([
       "active",
       "idle",
       "in_review",
       "archived",
       "cleanup_failed"
     ]);
-    updateExecutionWorkspaceSchema = z16.object({
-      status: executionWorkspaceStatusSchema.optional(),
+    updateRunWorkspaceSchema = z16.object({
+      status: runWorkspaceStatusSchema.optional(),
       cleanupEligibleAt: z16.string().datetime().optional().nullable(),
       cleanupReason: z16.string().optional().nullable(),
       metadata: z16.record(z16.unknown()).optional().nullable()
@@ -2713,7 +2748,7 @@ var init_organization_skill_reference = __esm({
 });
 
 // ../packages/shared/dist/project-mentions.js
-var AGENT_AVATAR_UUID_RE, AGENT_ASSET_ICON_RE, AGENT_DICEBEAR_NOTIONISTS_ICON_RE, PROJECT_COLOR_VALUES, AGENT_AVATAR_BACKGROUND_VALUES;
+var AGENT_AVATAR_UUID_RE, AGENT_ASSET_ICON_RE, AGENT_DICEBEAR_NOTIONISTS_ICON_RE, PROJECT_COLOR_VALUES, PROJECT_ICON_VALUES, AGENT_AVATAR_BACKGROUND_VALUES;
 var init_project_mentions = __esm({
   "../packages/shared/dist/project-mentions.js"() {
     "use strict";
@@ -2722,12 +2757,13 @@ var init_project_mentions = __esm({
     AGENT_ASSET_ICON_RE = new RegExp(`^asset:${AGENT_AVATAR_UUID_RE}(?:\\?bg=([a-z0-9-]+))?$`, "i");
     AGENT_DICEBEAR_NOTIONISTS_ICON_RE = new RegExp(`^${AGENT_DICEBEAR_NOTIONISTS_ICON_PREFIX}${AGENT_AVATAR_UUID_RE}(?:\\?bg=([a-z0-9-]+))?$`, "i");
     PROJECT_COLOR_VALUES = new Set(PROJECT_COLORS);
+    PROJECT_ICON_VALUES = new Set(PROJECT_ICONS);
     AGENT_AVATAR_BACKGROUND_VALUES = new Set(AGENT_AVATAR_BACKGROUND_PRESET_IDS);
   }
 });
 
 // ../packages/shared/dist/issue-activity.js
-var ISSUE_UPDATE_ACTIVITY_METADATA_KEYS, LOW_SIGNAL_ISSUE_UPDATE_ACTIVITY_FIELDS, ISSUE_UPDATE_ACTIVITY_METADATA_KEY_SET, LOW_SIGNAL_ISSUE_UPDATE_ACTIVITY_FIELD_SET;
+var ISSUE_UPDATE_ACTIVITY_METADATA_KEYS, LOW_SIGNAL_ISSUE_UPDATE_ACTIVITY_FIELDS, INTERNAL_ISSUE_UPDATE_ACTIVITY_FIELDS, ISSUE_UPDATE_ACTIVITY_METADATA_KEY_SET, LOW_SIGNAL_ISSUE_UPDATE_ACTIVITY_FIELD_SET, INTERNAL_ISSUE_UPDATE_ACTIVITY_FIELD_SET;
 var init_issue_activity = __esm({
   "../packages/shared/dist/issue-activity.js"() {
     "use strict";
@@ -2743,8 +2779,19 @@ var init_issue_activity = __esm({
       "normalizedReason"
     ];
     LOW_SIGNAL_ISSUE_UPDATE_ACTIVITY_FIELDS = ["description", "title"];
+    INTERNAL_ISSUE_UPDATE_ACTIVITY_FIELDS = [
+      "executionWorkspaceId",
+      "executionWorkspacePreference",
+      "executionWorkspaceSettings",
+      "currentExecutionWorkspace",
+      "runWorkspaceId",
+      "runWorkspacePreference",
+      "runWorkspaceSettings",
+      "currentRunWorkspace"
+    ];
     ISSUE_UPDATE_ACTIVITY_METADATA_KEY_SET = new Set(ISSUE_UPDATE_ACTIVITY_METADATA_KEYS);
     LOW_SIGNAL_ISSUE_UPDATE_ACTIVITY_FIELD_SET = new Set(LOW_SIGNAL_ISSUE_UPDATE_ACTIVITY_FIELDS);
+    INTERNAL_ISSUE_UPDATE_ACTIVITY_FIELD_SET = new Set(INTERNAL_ISSUE_UPDATE_ACTIVITY_FIELDS);
   }
 });
 
@@ -10693,7 +10740,7 @@ var AGENT_CLI_CAPABILITIES = [
     id: "issue.documents.put",
     command: "rudder issue documents put <issue> <key> --body-file <path>",
     category: "issue",
-    description: "Legacy create or update of a DB-backed issue document; prefer `rudder library file put` for durable project files.",
+    description: "Legacy create or update of a DB-backed issue document; prefer local project Library files under `$RUDDER_PROJECT_LIBRARY_ROOT` for durable project files.",
     mutating: true,
     contract: "compat",
     requiresOrgId: false,
@@ -10765,7 +10812,7 @@ var AGENT_CLI_CAPABILITIES = [
     id: "library.file.list",
     command: "rudder library file list [directory]",
     category: "library",
-    description: "List path-based Library files and folders.",
+    description: "List Library files and folders; file rows include `libraryEntryId` when a strong reference can be generated.",
     mutating: false,
     contract: "agent-v1",
     requiresOrgId: true,
@@ -10777,7 +10824,31 @@ var AGENT_CLI_CAPABILITIES = [
     id: "library.file.get",
     command: "rudder library file get <path>",
     category: "library",
-    description: "Read one path-based Library file.",
+    description: "Fallback read when local filesystem access is unavailable; JSON includes `mentionHref` and `markdownLink`.",
+    mutating: false,
+    contract: "agent-v1",
+    requiresOrgId: true,
+    requiresAgentId: false,
+    requiresRunId: false,
+    attachesRunIdWhenAvailable: false
+  },
+  {
+    id: "library.file.ref",
+    command: "rudder library file ref <path>",
+    category: "library",
+    description: "Return the stable Markdown reference for one Library file without printing file content.",
+    mutating: false,
+    contract: "agent-v1",
+    requiresOrgId: true,
+    requiresAgentId: false,
+    requiresRunId: false,
+    attachesRunIdWhenAvailable: false
+  },
+  {
+    id: "library.file.link",
+    command: "rudder library file link <path>",
+    category: "library",
+    description: "Compatibility alias for `rudder library file ref <path>`.",
     mutating: false,
     contract: "agent-v1",
     requiresOrgId: true,
@@ -10789,7 +10860,7 @@ var AGENT_CLI_CAPABILITIES = [
     id: "library.file.put",
     command: "rudder library file put <path> --body-file <path>",
     category: "library",
-    description: "Create or update one path-based Library file.",
+    description: "Fallback create/update when local filesystem access is unavailable; JSON includes `mentionHref` and `markdownLink`.",
     mutating: true,
     contract: "agent-v1",
     requiresOrgId: true,
@@ -11545,7 +11616,10 @@ function buildIssueListPath(orgId, opts, searchQuery) {
   if (opts.status) params.set("status", opts.status);
   if (opts.assigneeAgentId) params.set("assigneeAgentId", opts.assigneeAgentId);
   if (opts.projectId) params.set("projectId", opts.projectId);
-  if (searchQuery?.trim()) params.set("q", searchQuery.trim());
+  if (searchQuery?.trim()) {
+    params.set("q", searchQuery.trim());
+    params.set("searchFields", "title,description,comment");
+  }
   const query = params.toString();
   return `/api/orgs/${orgId}/issues${query ? `?${query}` : ""}`;
 }
@@ -11703,10 +11777,14 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
   "- Personal skills live under `$AGENT_HOME/skills`.",
   "- Shared organization workspace root lives under `$RUDDER_ORG_WORKSPACE_ROOT`.",
   "- Shared organization skills live under `$RUDDER_ORG_SKILLS_DIR`.",
-  '- Library-backed project resources use `sourceType: "library"`; their `locator` points into `library:projects/<project-name>/`.',
+  "- Project Library root lives under `$RUDDER_PROJECT_LIBRARY_ROOT` when the run has project context.",
+  "- Project Library locator lives in `$RUDDER_PROJECT_LIBRARY_PATH` when the run has project context, for example `projects/<project-key>`.",
+  '- Library-backed project resources use `sourceType: "library"`; their `locator` points into `library:projects/<project-key>/`.',
   "- Project Context is explicit operator-curated context, not the whole knowledge boundary. When it is insufficient, inspect broader Library and org workspace know-how before concluding context is missing.",
-  "- Durable generated project work files should be written under `library:projects/<project-name>/`.",
-  "- When you create or update a durable Library file, always include a user-visible Markdown link to that file in your final chat reply or issue comment. Use `library-file://file?p=<url-encoded-relative-path>&t=<url-encoded-title>` for Library file links.",
+  "- In local trusted runs, durable generated project work files should be written directly under `$RUDDER_PROJECT_LIBRARY_ROOT` with normal filesystem tools.",
+  "- `library:projects/<project-key>/...` is the Rudder product locator for those files, not the Markdown link syntax and not a reason to route ordinary local edits through the CLI.",
+  '- When you create or update a durable Library file, always include a user-visible Markdown link to that file in your final chat reply or issue comment. Use `rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>" --json` and paste the returned `markdownLink`; do not pass the absolute `$RUDDER_PROJECT_LIBRARY_ROOT/...` path to `ref`, and do not hand-write `library-entry://...` or `library-file://...` links.',
+  '- If `$RUDDER_PROJECT_LIBRARY_ROOT` is unset or inaccessible, use `rudder library file get/put "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>"` as the remote or restricted runtime fallback.',
   "- Use `/tmp` only for transient scratch files and temporary verification files; do not put durable work product there.",
   "- Local trusted runtimes may expose the host operator home as `$RUDDER_OPERATOR_HOME`; use it only when a local skill or script intentionally needs operator-owned desktop app or CLI state. Do not replace `$HOME` with it.",
   "",
@@ -11715,6 +11793,18 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
   "When you write issue comments or chat replies, match the language of the user's or board's most recent substantive message unless they explicitly ask for a different language.",
   "When you mention a web page, issue URL, external dashboard, or other user-openable target in an issue comment or chat reply, write it as a clickable Markdown link with a descriptive label, for example `[NameSilo transfer page](https://www.namesilo.com/account_domain_manage_transfer.php)`. Do not put action URLs in backticks or code blocks unless you are showing literal code or a command.",
   "",
+  "## Rudder Renderable Links",
+  "",
+  "When you mention Rudder entities in any user-visible Markdown output, prefer Rudder's renderable Markdown link syntax over plain IDs, bare URLs, or backticked references so the UI can render chips and navigate correctly.",
+  "",
+  "- Issues: use `[<identifier-or-title>](issue://<issue-id>?r=<identifier>)`; include `&c=<comment-id>` when linking to a specific comment.",
+  "- Agents: use `[<agent-name>](agent://<agent-id>)` for reference-only links. Use `[<agent-name>](agent://<agent-id>?intent=wake)` only when you deliberately want an issue-composer mention to wake that agent.",
+  "- Projects: use `[<project-name>](project://<project-id>)` when citing a Rudder project.",
+  "- Chat threads: use `[<chat-title>](chat://<conversation-id>?t=<url-encoded-title>)` when citing a Rudder chat conversation.",
+  '- Library files: use the `markdownLink` returned by `rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>" --json`; do not hand-write `library-entry://...` links, and treat `library-file://...` as legacy path syntax only.',
+  "",
+  "Write these as normal Markdown links, not inside code spans or code blocks, unless you are literally documenting the syntax.",
+  "",
   "Mention-triggered comment wakes arrive with `RUDDER_WAKE_COMMENT_ID`; read that wake comment before acting. Board/operator issue comments can wake an agent with a plain `@AgentName` token or an issue-composer agent mention serialized as `agent://agent-id?intent=wake`. Plain structured links such as `agent://agent-id` are reference-only links for rendering and navigation. Agent-authored issue comments do not fan out peer wakeups by default; use reviewer, assignment, or explicit handoff workflow instead. Mentioning an agent requests attention or collaboration; it does not transfer issue ownership unless the comment also makes an explicit handoff and normal checkout rules allow it.",
   "",
   "When an issue comment, done comment, or blocker comment cites visual evidence from a local screenshot/image path, attach the image with the Rudder CLI `--image <path>` option instead of leaving only the filesystem path in the text.",
@@ -12700,9 +12790,27 @@ function parseCsv5(value) {
 // src/commands/client/library.ts
 import { readFile as readFile6 } from "node:fs/promises";
 import path20 from "node:path";
+function toLibraryFileLinkResult(detail) {
+  return {
+    filePath: detail.filePath,
+    libraryEntryId: detail.libraryEntryId,
+    mentionHref: detail.mentionHref,
+    markdownLink: detail.markdownLink
+  };
+}
+async function printLibraryFileReference(filePath, opts) {
+  const ctx = resolveCommandContext(opts, { requireCompany: true });
+  const search = new URLSearchParams();
+  search.set("path", filePath.trim());
+  const result = await ctx.api.get(
+    `/api/orgs/${ctx.orgId}/workspace/file?${search.toString()}`
+  );
+  if (!result) throw new Error("Library file not found");
+  printOutput(toLibraryFileLinkResult(result), { json: ctx.json });
+}
 function registerLibraryCommands(program) {
   const library = program.command("library").description("Library file operations");
-  const file = library.command("file").description("Path-based Library file operations");
+  const file = library.command("file").description("Library file operations");
   addCommonClientOptions(
     file.command("list").description(getAgentCliCapabilityById("library.file.list").description).argument("[directoryPath]", "Library directory path", "projects").action(async (directoryPath, opts) => {
       try {
@@ -12737,6 +12845,26 @@ function registerLibraryCommands(program) {
     }),
     { includeCompany: true }
   );
+  addCommonClientOptions(
+    file.command("link").description(getAgentCliCapabilityById("library.file.link").description).argument("<filePath>", "Library file path").action(async (filePath, opts) => {
+      try {
+        await printLibraryFileReference(filePath, opts);
+      } catch (err) {
+        handleCommandError(err);
+      }
+    }),
+    { includeCompany: true }
+  );
+  addCommonClientOptions(
+    file.command("ref").description(getAgentCliCapabilityById("library.file.ref").description).argument("<filePath>", "Library file path").action(async (filePath, opts) => {
+      try {
+        await printLibraryFileReference(filePath, opts);
+      } catch (err) {
+        handleCommandError(err);
+      }
+    }),
+    { 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) => {
       try {