@rallycry/conveyor-agent 11.0.40 → 11.0.41

package/dist/{chunk-RZNNJUGW.js → chunk-G2CE3NFY.js}

@@ -8,7 +8,7 @@ import {
   readWorkspaceBytes,
   statWorkspacePath,
   workspacePathExists
-} from "./chunk-UB7QZE25.js";
+} from "./chunk-CG7AHC25.js";
 import {
   reportBootMilestone
 } from "./chunk-Q4FQOJ7D.js";

package/dist/{chunk-GI2FF7FX.js → chunk-SELXSOT7.js}

@@ -97,7 +97,7 @@ import {
   statWorkspacePath,
   updateRemoteToken,
   verifyGitCredential
-} from "./chunk-UB7QZE25.js";
+} from "./chunk-CG7AHC25.js";
 import {
   registerBootMilestoneSocketFallback,
   reportBootMilestone
@@ -7350,6 +7350,7 @@ function defineToolContract(contract) {
 var mcpProjectId = f.optional(f.string({ desc: "Target Conveyor project ID" }));
 var cardDescriptionDesc = (lead) => `${lead} \u2014 ${CARD_DESCRIPTION_FIELD_HINT}`;
 var storyPointValueDesc = "Story point value (1=Common, 2=Magic, 3=Rare, 5=Unique)";
+var priorityValueDesc = "Priority value from manage_priorities list (1 = the project's highest level; seeded defaults are 1=High, 2=Medium, 3=Low)";
 var getTaskContract = defineToolContract({
   name: "get_task",
   agent: {
@@ -7583,7 +7584,7 @@ var updateTaskContract = defineToolContract({
     }
   },
   mcp: {
-    description: "Update task fields: title, description, plan, status, risk, story points, assignment, githubBranch, onHold, or tags. Set status to claim a card (InProgress), triage it (Open), or cancel it (Cancelled); for review approvals prefer approve_task / request_changes, which guard against stale-state races. Set onHold to park a card (true) or bring it back to the active board (false) without cancelling it. Tags are additive/subtractive \u2014 pass addTags/removeTags with tag names (not a replace-set). Pass projectId to target a specific project; otherwise the configured default project is used. Moving a task beyond Planning auto-fills any missing icon, story points, and agent assignment \u2014 don't spend turns on them; pass storyPointValue only to correct the sizing yourself. For subtasks use update_subtask.",
+    description: "Update task fields: title, description, plan, status, risk, story points, priority, assignment, githubBranch, onHold, or tags. Set status to claim a card (InProgress), triage it (Open), or cancel it (Cancelled); for review approvals prefer approve_task / request_changes, which guard against stale-state races. Set onHold to park a card (true) or bring it back to the active board (false) without cancelling it. Tags are additive/subtractive \u2014 pass addTags/removeTags with tag names (not a replace-set). Pass projectId to target a specific project; otherwise the configured default project is used. Moving a task beyond Planning auto-fills any missing icon, story points, and agent assignment \u2014 don't spend turns on them; pass storyPointValue only to correct the sizing yourself. For subtasks use update_subtask.",
     fields: {
       projectId: mcpProjectId,
       taskId: f.string({ desc: "The task ID" }),
@@ -7605,6 +7606,13 @@ var updateTaskContract = defineToolContract({
           })
         )
       ),
+      priorityValue: f.optional(
+        f.nullable(
+          f.number({
+            desc: `${priorityValueDesc}. The levels are per-project \u2014 a value the project has not configured is rejected. Pass null to clear it.`
+          })
+        )
+      ),
       assignedUserId: f.optional(f.nullable(f.string({ desc: "User ID to assign, or null" }))),
       subProjectId: f.optional(
         f.nullable(
@@ -8066,13 +8074,13 @@ var agentTaskIdOrSlug = f.optional(
 var listTaskFilesContract = defineToolContract({
   name: "list_task_files",
   agent: {
-    description: "List all files attached to this task with metadata. Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment. Pass task_id to list another card's files in this project, for example the pack parent's source documents.",
+    description: "List all files attached to this task with metadata. Showcase files (the card's deliverables, `showcase: true` on each row) list first; a row with `supersedesFileId` is a newer version of that file. Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment. Pass task_id to list another card's files in this project, for example the pack parent's source documents.",
     fields: {
       task_id: agentTaskIdOrSlug
     }
   },
   mcp: {
-    description: "List all files attached to a task with metadata (no contents \u2014 fast and small). Pass projectId to target a specific project; otherwise the configured default project is used. Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment.",
+    description: "List all files attached to a task with metadata (no contents \u2014 fast and small). Showcase files (the card's deliverables, `showcase: true` on each row) list first; a row with `supersedesFileId` is a newer version of that file. Pass projectId to target a specific project; otherwise the configured default project is used. Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment.",
     fields: {
       projectId: mcpProjectId,
       taskId: mcpTaskIdOrSlug
@@ -8116,10 +8124,20 @@ var attachmentTags = f.optional(
     desc: `Glossary tag names this file is a relevant example of. MUST be a JSON array of quoted strings, e.g. ["ops-hub", "platform-support"] \u2014 bare unquoted words are invalid JSON and fail the whole call before it is parsed (21 fleet calls in one week died this way). Use it when the file shows a tagged entity in a particular state: the tag's page lists its recent tagged attachments, so a reader can see what the entity looks like across the app and spot visual changes over time. Names are matched case-insensitively within the project; a name that matches no tag is reported back and never fails the upload. Max 5.`
   })
 );
+var attachmentShowcase = f.optional(
+  f.boolean({
+    desc: "Mark this file as a showcase: the finished result of the card. Showcase files render first with a thumbnail on the card, are what a tag gallery shows, always post to chat, get a long-lived link, are kept past the 90-day purge, and are appended to the PR body under '## Showcase'. Use it for the final capture, not for scoping or before shots."
+  })
+);
+var attachmentSupersedes = f.optional(
+  f.string({
+    desc: "File id (from list_task_files) of an older file on this card that this upload replaces, e.g. the previous cut of a video. The old file loses showcase and collapses under the new one as history; the new one inherits its showcase flag and tag labels. Naming a file that already has a newer version replaces the newest one. A bad id never fails the upload \u2014 the reason comes back instead."
+  })
+);
 var uploadAttachmentContract = defineToolContract({
   name: "upload_attachment",
   agent: {
-    description: "Upload a file (doc, notes, data, diagram, screenshot \u2014 any file type, up to 25MB) as a task attachment AND post it to the task chat in one step \u2014 no follow-up post_to_chat call needed. This is how you deliver a file the user should keep: it attaches to the card. Never publish deliverables as an external Claude artifact. Pass `tags` when the file is a good example of a glossary tag in some state.",
+    description: "Upload a file (doc, notes, data, diagram, screenshot \u2014 any file type, up to 25MB) as a task attachment AND post it to the task chat in one step \u2014 no follow-up post_to_chat call needed. This is how you deliver a file the user should keep: it attaches to the card. Never publish deliverables as an external Claude artifact. Pass `showcase: true` for the capture that shows the finished result, `supersedes` with the old file's id when this is a newer version of a file already on the card, and `tags` when the file is a good example of a glossary tag in some state.",
     fields: {
       path: f.string({
         desc: "Path to the file \u2014 absolute, or relative to the workspace root"
@@ -8132,11 +8150,13 @@ var uploadAttachmentContract = defineToolContract({
           desc: "Alias of `title` (the external conveyor-mcp surface names this field `comment`). Provide at most one of the two."
         })
       ),
-      tags: attachmentTags
+      tags: attachmentTags,
+      showcase: attachmentShowcase,
+      supersedes: attachmentSupersedes
     }
   },
   mcp: {
-    description: "Upload a local file as a task attachment (any file type, up to 25MB). Pass projectId to target a specific project; otherwise the configured default project is used. The file appears under the task's Files. Pass `comment` to also post it to the task chat in the same step, and `tags` when the file is a good example of a glossary tag in some state.",
+    description: "Upload a local file as a task attachment (any file type, up to 25MB). Pass projectId to target a specific project; otherwise the configured default project is used. The file appears under the task's Files. Pass `comment` to also post it to the task chat in the same step, `showcase: true` for the capture that shows the finished result (a showcase file always posts to chat), `supersedes` with the old file's id when this is a newer version of a file already on the card, and `tags` when the file is a good example of a glossary tag in some state.",
     fields: {
       projectId: mcpProjectId,
       taskId: mcpTaskIdOrSlug,
@@ -8150,6 +8170,8 @@ var uploadAttachmentContract = defineToolContract({
         })
       ),
       tags: attachmentTags,
+      showcase: attachmentShowcase,
+      supersedes: attachmentSupersedes,
       mimeType: f.optional(
         f.string({ desc: "Override the mime type inferred from the file extension" })
       )
@@ -8174,11 +8196,35 @@ var deleteAttachmentContract = defineToolContract({
     }
   }
 });
+var SET_SHOWCASE_BEHAVIOR = "Mark an already-uploaded attachment as the card's showcase (`showcase: true`) or clear the flag (`showcase: false`) \u2014 the same flag upload_attachment sets at upload time, so promote an earlier capture here instead of uploading it again. A flip to showcase posts the file to the task chat once; a file that a chat message already carries is not posted again. `fileId` comes from list_task_files.";
+var showcaseFlag = f.boolean({
+  desc: "true marks the file as the card's showcase; false clears the flag."
+});
+var setShowcaseContract = defineToolContract({
+  name: "set_showcase",
+  agent: {
+    description: `${SET_SHOWCASE_BEHAVIOR} A pod can only change files on its own card.`,
+    fields: {
+      fileId: f.string({ desc: "The file ID to change" }),
+      showcase: showcaseFlag
+    }
+  },
+  mcp: {
+    description: `${SET_SHOWCASE_BEHAVIOR} Requires Moderate on the project, the same bar as the star on the card's Files list. Pass projectId to target a specific project; otherwise the configured default project is used.`,
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The task ID or slug the file is attached to" }),
+      fileId: f.string({ desc: "The file ID to change" }),
+      showcase: showcaseFlag
+    }
+  }
+});
 var attachmentsContracts = [
   listTaskFilesContract,
   getAttachmentContract,
   uploadAttachmentContract,
-  deleteAttachmentContract
+  deleteAttachmentContract,
+  setShowcaseContract
 ];
 var createSuggestionContract = defineToolContract({
   name: "create_suggestion",
@@ -8501,7 +8547,7 @@ var createPullRequestContract = defineToolContract({
     fields: {
       title: f.string({ desc: "The PR title" }),
       body: f.string({
-        desc: "The PR description/body in markdown. If the diff changes anything a user sees rendered, the body MUST show the visual proof inline, not just point at the card: upload the capture with upload_attachment, then embed the downloadUrl it returns under a '## Screenshots' heading (![caption](url) for images, [caption](url) for video). Only image and video URLs belong in a PR body: a document downloadUrl (csv, pdf, md, \u2026) needs a signed-in project member and shows 404 to a reviewer on GitHub, so point at the card instead. Attach to the card as well \u2014 the card is the durable home, the PR body is what the reviewer reads."
+        desc: "The PR description/body in markdown. If the diff changes anything a user sees rendered, the body MUST show the visual proof inline, not just point at the card: upload the capture with upload_attachment, then embed the downloadUrl it returns under a '## Screenshots' heading (![caption](url) for images, [caption](url) for video). Only image and video URLs belong in a PR body: a document downloadUrl (csv, pdf, md, \u2026) needs a signed-in project member and shows 404 to a reviewer on GitHub, so point at the card instead. Attach to the card as well \u2014 the card is the durable home, the PR body is what the reviewer reads. Showcase attachments (uploaded with `showcase: true`) are appended under '## Showcase' automatically when Conveyor creates the PR; mention them inline yourself only if you want them next to specific text."
       }),
       branch: f.optional(
         f.string({
@@ -8532,7 +8578,7 @@ var createPullRequestContract = defineToolContract({
       taskId: f.string({ desc: "The task ID whose branch should be opened as a PR" }),
       title: f.string({ desc: "Pull request title" }),
       body: f.string({
-        desc: "Pull request body (markdown). For a diff that changes rendered UI, embed the visual proof inline: upload the capture with upload_attachment and paste the downloadUrl it returns as ![caption](url), in addition to leaving it on the card."
+        desc: "Pull request body (markdown). For a diff that changes rendered UI, embed the visual proof inline: upload the capture with upload_attachment and paste the downloadUrl it returns as ![caption](url), in addition to leaving it on the card. Showcase attachments (uploaded with `showcase: true`) are appended under '## Showcase' automatically when Conveyor creates the PR; mention them inline yourself only if you want them next to specific text."
       }),
       head: f.optional(
         f.string({ desc: "Source branch for the PR (defaults to the task's branch)" })
@@ -10137,6 +10183,8 @@ var MIME_BY_EXT = {
   ".gz": "application/gzip",
   ".mp4": "video/mp4",
   ".webm": "video/webm",
+  ".mov": "video/quicktime",
+  ".m4v": "video/x-m4v",
   ".mp3": "audio/mpeg",
   ".wav": "audio/wav"
 };
@@ -10151,20 +10199,28 @@ function describeTags(applied, unknown) {
   }
   return parts.join("");
 }
+function describeSupersede(superseded, error) {
+  if (superseded) {
+    return ` Replaces ${superseded.fileName} (${superseded.fileId}), which now collapses under it as history.`;
+  }
+  if (error) return ` Did not replace the older file: ${error}.`;
+  return "";
+}
 var EMBEDDABLE_IN_MARKDOWN = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
-function describeEmbed(fileName, downloadUrl) {
+function describeEmbed(fileName, downloadUrl, showcase) {
   if (!downloadUrl) return "";
   const isImage = EMBEDDABLE_IN_MARKDOWN.has(extname(fileName).toLowerCase());
+  const lead = showcase ? "Put this line under '## Showcase' in the PR body (the server adds it if you forget)" : "Paste this into the PR description";
   if (isImage) {
     return `
 
-Paste this into the PR description to show it inline:
+${lead} to show it inline:
 ![${fileName}](${downloadUrl})`;
   }
   if (isCapabilityServableMime(inferMimeType(fileName))) {
     return `
 
-Paste this into the PR description to link it:
+${lead} to link it:
 [${fileName}](${downloadUrl})`;
   }
   return `
@@ -10172,69 +10228,98 @@ Paste this into the PR description to link it:
 downloadUrl (signed-in project members only; agents read it with get_attachment): ${downloadUrl}`;
 }
 function buildUploadAttachmentTool(connection, config) {
-  return defineContractTool(uploadAttachmentContract, async ({ path, title, comment, tags }) => {
-    const caption = title ?? comment;
-    try {
-      const filePath = isAbsolute(path) ? path : join17(config.workspaceDir, path);
-      const mimeType = inferMimeType(filePath);
-      const info = await statWorkspacePath(filePath);
-      if (!info.isFile) {
-        return textResult(`File not found: ${filePath}`);
-      }
-      if (info.size > MAX_FILE_SIZE_BYTES) {
+  return defineContractTool(
+    uploadAttachmentContract,
+    async ({ path, title, comment, tags, showcase, supersedes }) => {
+      const caption = title ?? comment;
+      try {
+        const filePath = isAbsolute(path) ? path : join17(config.workspaceDir, path);
+        const mimeType = inferMimeType(filePath);
+        const info = await statWorkspacePath(filePath);
+        if (!info.isFile) {
+          return textResult(`File not found: ${filePath}`);
+        }
+        if (info.size > MAX_FILE_SIZE_BYTES) {
+          return textResult(
+            `File is ${info.size} bytes \u2014 exceeds the ${MAX_FILE_SIZE_BYTES} byte (25MB) upload limit.`
+          );
+        }
+        const fileName = basename2(filePath);
+        const { fileId, uploadUrl } = await connection.call("requestFileUpload", {
+          sessionId: connection.sessionId,
+          fileName,
+          mimeType,
+          fileSize: info.size
+        });
+        const bytes = await readWorkspaceBytes(filePath);
+        const res = await fetch(uploadUrl, {
+          method: "PUT",
+          headers: { "Content-Type": mimeType },
+          // Normalize to a plain Uint8Array: the workbench proxy hands back a
+          // Buffer<ArrayBufferLike> that newer @types/node rejects as a BodyInit.
+          body: new Uint8Array(bytes)
+        });
+        if (!res.ok) {
+          return textResult(
+            `Upload to storage failed: HTTP ${res.status} ${await res.text().catch(() => "")}`
+          );
+        }
+        const result = await connection.call("confirmFileUpload", {
+          sessionId: connection.sessionId,
+          fileId,
+          title: caption,
+          tags,
+          // Omitted when unset so the payload stays byte-identical for callers
+          // that never heard of the flag.
+          ...showcase === void 0 ? {} : { showcase },
+          ...supersedes ? { supersedes } : {}
+        });
+        const isShowcase = result.showcase === true;
         return textResult(
-          `File is ${info.size} bytes \u2014 exceeds the ${MAX_FILE_SIZE_BYTES} byte (25MB) upload limit.`
+          `${isShowcase ? "Showcase attachment. " : ""}Uploaded ${fileName} (${info.size} bytes) and posted it to the task chat${caption ? ` with caption "${caption}"` : ""}. File ID: ${result.fileId}${describeTags(result.appliedTags, result.unknownTags)}${describeSupersede(result.superseded, result.supersedeError)}${describeEmbed(fileName, result.downloadUrl, isShowcase)}`
         );
-      }
-      const fileName = basename2(filePath);
-      const { fileId, uploadUrl } = await connection.call("requestFileUpload", {
-        sessionId: connection.sessionId,
-        fileName,
-        mimeType,
-        fileSize: info.size
-      });
-      const bytes = await readWorkspaceBytes(filePath);
-      const res = await fetch(uploadUrl, {
-        method: "PUT",
-        headers: { "Content-Type": mimeType },
-        // Normalize to a plain Uint8Array: the workbench proxy hands back a
-        // Buffer<ArrayBufferLike> that newer @types/node rejects as a BodyInit.
-        body: new Uint8Array(bytes)
-      });
-      if (!res.ok) {
+      } catch (error) {
         return textResult(
-          `Upload to storage failed: HTTP ${res.status} ${await res.text().catch(() => "")}`
+          `Failed to upload attachment: ${error instanceof Error ? error.message : "Unknown error"}`
         );
       }
-      const result = await connection.call("confirmFileUpload", {
+    }
+  );
+}
+function buildDeleteAttachmentTool(connection) {
+  return defineContractTool(deleteAttachmentContract, async ({ fileId }) => {
+    try {
+      const result = await connection.call("deleteTaskFile", {
         sessionId: connection.sessionId,
-        fileId,
-        title: caption,
-        tags
+        fileId
       });
       return textResult(
-        `Uploaded ${fileName} (${info.size} bytes) and posted it to the task chat${caption ? ` with caption "${caption}"` : ""}. File ID: ${result.fileId}${describeTags(result.appliedTags, result.unknownTags)}${describeEmbed(fileName, result.downloadUrl)}`
+        `Deleted ${result.fileName} (${result.id}) permanently. Any chat message that announced it keeps its text without the attachment.`
       );
     } catch (error) {
       return textResult(
-        `Failed to upload attachment: ${error instanceof Error ? error.message : "Unknown error"}`
+        `Failed to delete attachment: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   });
 }
-function buildDeleteAttachmentTool(connection) {
-  return defineContractTool(deleteAttachmentContract, async ({ fileId }) => {
+function buildSetShowcaseTool(connection) {
+  return defineContractTool(setShowcaseContract, async ({ fileId, showcase }) => {
     try {
-      const result = await connection.call("deleteTaskFile", {
+      const result = await connection.call("setTaskFileShowcase", {
         sessionId: connection.sessionId,
-        fileId
+        fileId,
+        showcase
       });
+      if (!result.showcase) {
+        return textResult(`${result.fileName} (${result.id}) is no longer a showcase file.`);
+      }
       return textResult(
-        `Deleted ${result.fileName} (${result.id}) permanently. Any chat message that announced it keeps its text without the attachment.`
+        `${result.fileName} (${result.id}) is now a showcase file. It is in the task chat and the server adds it to the PR body under '## Showcase'.${describeEmbed(result.fileName, result.downloadUrl, true)}`
       );
     } catch (error) {
       return textResult(
-        `Failed to delete attachment: ${error instanceof Error ? error.message : "Unknown error"}`
+        `Failed to set showcase: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   });
@@ -10470,7 +10555,8 @@ function buildCommonTools(connection, config) {
     ...buildMutationTools(connection, config),
     buildUpdateIncidentTool(connection),
     buildUploadAttachmentTool(connection, config),
-    buildDeleteAttachmentTool(connection)
+    buildDeleteAttachmentTool(connection),
+    buildSetShowcaseTool(connection)
   ];
 }
 

package/dist/cli.js

@@ -7,7 +7,7 @@ import {
   WorkspaceCommandSupervisor,
   startWorkspaceCommandsAfterConnect,
   stopWorkspaceCommands
-} from "./chunk-RZNNJUGW.js";
+} from "./chunk-G2CE3NFY.js";
 import {
   PtyHarness,
   SessionRunner,
@@ -27,7 +27,7 @@ import {
   runUsageProbe,
   sampleKeyUsage,
   usesNativeUsageReporting
-} from "./chunk-GI2FF7FX.js";
+} from "./chunk-SELXSOT7.js";
 import "./chunk-37J5MMQT.js";
 import {
   inheritedEnv,
@@ -46,7 +46,7 @@ import {
   createServiceLogger,
   fetchBootstrap,
   loadConveyorConfig
-} from "./chunk-UB7QZE25.js";
+} from "./chunk-CG7AHC25.js";
 import "./chunk-Q4FQOJ7D.js";
 import "./chunk-W4LZ7R6Z.js";
 import "./chunk-372R6E4C.js";
@@ -1468,7 +1468,7 @@ if (!RUNNER_MODES.includes(CONVEYOR_MODE)) {
   process.exit(1);
 }
 if (CONVEYOR_MODE === "serving") {
-  const { runServingSession } = await import("./serve-boot-ZJ4BI7P2.js");
+  const { runServingSession } = await import("./serve-boot-YARBQBSA.js");
   exitContext.runnerMode = "serving";
   exitContext.sessionId = process.env.CONVEYOR_SESSION_ID ?? exitContext.sessionId;
   const outcome = await runServingSession({

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   SessionRunner,
   unshallowRepo
-} from "./chunk-GI2FF7FX.js";
+} from "./chunk-SELXSOT7.js";
 import "./chunk-37J5MMQT.js";
 import "./chunk-EKTPDG3G.js";
 import {
@@ -17,7 +17,7 @@ import {
   stageAndCommit,
   updateRemoteToken,
   workspacePathExists
-} from "./chunk-UB7QZE25.js";
+} from "./chunk-CG7AHC25.js";
 import "./chunk-Q4FQOJ7D.js";
 import {
   runAuthTokenCommand,

package/dist/{serve-boot-ZJ4BI7P2.js → serve-boot-YARBQBSA.js}

@@ -1,6 +1,6 @@
 import {
   WorkspaceCommandSupervisor
-} from "./chunk-RZNNJUGW.js";
+} from "./chunk-G2CE3NFY.js";
 import {
   AgentConnection,
   CodespacePortVisibility,
@@ -11,7 +11,7 @@ import {
   createServiceLogger,
   ensureOnTaskBranch,
   loadConveyorConfig
-} from "./chunk-UB7QZE25.js";
+} from "./chunk-CG7AHC25.js";
 import "./chunk-Q4FQOJ7D.js";
 import "./chunk-W4LZ7R6Z.js";
 import "./chunk-IA45XHOA.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-agent",
-  "version": "11.0.40",
+  "version": "11.0.41",
   "description": "Conveyor Agent Runner v10 - PTY harness for the task chat (SDK harness for audit/project-chat). Agent-as-User architecture with BaseService patterns. Works locally too.",
   "keywords": [
     "agent",

package/skills/conveyor-build/SKILL.md

@@ -204,7 +204,14 @@ runner: the pod can sleep mid-run and nothing will wake you.
 **A UI-visible change needs visual proof before the PR**, in both environments:
 capture a screenshot (static) or a short recording (interaction) with the host
 repo's own tooling and attach it with `mcp__conveyor__upload_attachment`, then
-embed the returned URL in the PR body. A UI PR without it is incomplete.
+embed the returned URL in the PR body. A UI PR without it is incomplete. Pass
+`showcase: true` for the capture that shows the finished result (the after
+shot, the final recording); leave it off for before shots and scoping captures.
+Showcase files post to chat, render first on the card, and land in the PR body
+under `## Showcase`. A re-capture of something already on the card (a new cut
+of the same recording) passes `supersedes: "<old fileId>"` from
+`list_task_files`: the new file takes the old one's star and tags, and the old
+one collapses under it as history instead of showing twice.
 
 **Manual tests are for human eyes, and few.** Before the PR, record with
 `mcp__conveyor__set_manual_tests` only what a person must see in the running
@@ -262,10 +269,12 @@ Instead: post the answer, config, or findings with
 `mcp__conveyor__upload_attachment` (any file type, up to 25MB), and complete
 the card directly with `force_update_task_status("Complete")` — there is no PR
 or review step for a no-code task. Never publish a deliverable as an off-card
-link; the card is where it belongs. When a revision supersedes an earlier
-upload, remove the old copy with `mcp__conveyor__delete_attachment` (permanent,
-`fileId` from `list_task_files`) so the Files list shows one current version
-of each deliverable.
+link; the card is where it belongs. When a revision replaces an earlier
+upload, upload it with `supersedes: "<old fileId>"` (the id from
+`list_task_files`) so the card shows one current version of each deliverable
+with the history collapsed under it. Reach for
+`mcp__conveyor__delete_attachment` (permanent) only for a copy that should not
+survive at all.
 
 When unsure, check the diff: a real diff means open a PR, no diff means finish
 in chat and mark it Complete.