@tablation/crew 0.43.0 → 0.43.2

package/dist/cli.js

@@ -3184,6 +3184,7 @@ var DEFAULT_CONTRACT = {
     blockedBy: "blocked_by",
     updatedAt: "updated_at",
     needsDesign: "needs_design",
+    attachments: "attachments",
     workMode: "work_mode",
     reportType: "report_type",
     epic: "epic_id",
@@ -4786,6 +4787,7 @@ var Tracker = class {
    * so concurrent first writes share one round of field-metadata reads.
    */
   authorship;
+  attachments;
   stateDir;
   constructor(route, ship) {
     this.route = route;
@@ -5238,6 +5240,28 @@ var Tracker = class {
       shipId: shipRow?.id ?? null
     };
   }
+  /**
+   * The attachments probe (CREW-1558): which table the Issues `attachments`
+   * column references, read once per process like the authorship probe. On
+   * TABL-1557 two runs reported a ticket's screenshot as a 404 because, with
+   * no table id in hand, they guessed `files/<attachment id>` paths; naming
+   * the table in the Environment section is what makes the lookup mechanical.
+   */
+  attachmentsProbe() {
+    this.attachments ??= this.probeAttachments();
+    return this.attachments;
+  }
+  async probeAttachments() {
+    try {
+      const model = await this.client.dataModels.get(this.models.issues);
+      const field = model.fields.find((f) => f.columnName === this.contract.columns.attachments);
+      const fieldType = field?.fieldType;
+      const target = fieldType?.targetModelId;
+      return { mediaLibraryModelId: typeof target === "string" && target ? target : null };
+    } catch {
+      return { mediaLibraryModelId: null };
+    }
+  }
   async columnNames(modelId) {
     try {
       const model = await this.client.dataModels.get(modelId);
@@ -6874,6 +6898,7 @@ function renderEnvironment(i) {
   const only = repos.length === 1 ? repos[0] : void 0;
   const models = route.resolved?.models;
   const epicsModelId = route.resolved?.epicsModelId;
+  const mediaLibraryModelId = i.attachments?.mediaLibraryModelId ?? null;
   const key = "ISSUE-000";
   const lines = [
     "# Your environment",
@@ -6898,7 +6923,8 @@ function renderEnvironment(i) {
       `- Issues: \`${models.issues}\``,
       `- Comments: \`${models.comments}\``,
       `- Crew: \`${models.crew}\``,
-      ...epicsModelId ? [`- Epics: \`${epicsModelId}\``] : []
+      ...epicsModelId ? [`- Epics: \`${epicsModelId}\``] : [],
+      ...mediaLibraryModelId ? [`- Media Library: \`${mediaLibraryModelId}\` (what a ticket's \`${contract.columns.attachments}\` ids point into)`] : []
     );
   }
   const workspaceId = route.resolved?.workspaceId;
@@ -6925,6 +6951,30 @@ function renderEnvironment(i) {
       "status and response body in your comment \u2014 do not write that uploads are",
       "impossible."
     );
+    if (mediaLibraryModelId) {
+      lines.push(
+        "",
+        "## Opening a ticket's attachments",
+        "",
+        `A ticket's or a comment's \`${contract.columns.attachments}\` value is a list of Media Library`,
+        "**record ids** \u2014 not file ids and not URLs. `files/<id>`, `files/<id>/download` and",
+        "`media-library/<id>/...` do not exist for such an id and return 404. For each id,",
+        "read the record, then fetch the file by its storage key:",
+        "",
+        "```sh",
+        `curl -s -H "Authorization: Bearer $${API_KEY_VAR}" -H "User-Agent: ${i.userAgent}" \\`,
+        `  "${base}/api/workspaces/${workspaceId}/data-models/${mediaLibraryModelId}/records/<attachment id>"`,
+        '# \u2192 JSON with `storage_key` ("<uuid>/<filename>") and `mime_type`',
+        `curl -s -o <scratch dir>/<filename> -H "Authorization: Bearer $${API_KEY_VAR}" -H "User-Agent: ${i.userAgent}" \\`,
+        `  "${base}/api/workspaces/${workspaceId}/files/<storage_key>"`,
+        "```",
+        "",
+        "The MCP forms are `records_controller_find_one` (`dataModelId` = the Media Library",
+        "id above) and `files_controller_download` (`uuid` and `filename` = the two halves",
+        "of the storage key). Save the file outside the repository and open it; where it",
+        "disagrees with the description, the picture is the reproduction."
+      );
+    }
   }
   if (i.shipName) {
     lines.push(
@@ -7275,6 +7325,12 @@ async function fetchLatestHistoryId(route, agentsModelId, recordId, userAgent) {
 function promptSourceFields(model, prompt) {
   return model.fields?.some((f) => f.columnName === "prompt_baseline") ? { prompt_source: "crew", prompt_baseline: prompt } : {};
 }
+function hasPromptBaselineColumn(model) {
+  return model.fields?.some((f) => f.columnName === "prompt_baseline") === true;
+}
+function needsBaselineBackfill(model, row) {
+  return hasPromptBaselineColumn(model) && row.prompt_customized !== true && (typeof row.prompt_baseline !== "string" || !row.prompt_source);
+}
 function isPromptGateRejection(e) {
   return e instanceof TablationApiError && e.status === 422;
 }
@@ -7319,8 +7375,16 @@ async function syncPersonas(route, opts) {
       continue;
     }
     if (row.prompt === defaultPrompt) {
+      let anchoredAt = row.updated_at;
+      if (!opts.dryRun && needsBaselineBackfill(agentsModel, row)) {
+        try {
+          anchoredAt = (await client2.records.update(agentsModel.id, row.id, promptSourceFields(agentsModel, defaultPrompt), row.updated_at)).updated_at;
+        } catch (e) {
+          if (!(e instanceof StaleWriteError6) && !isPromptGateRejection(e)) throw e;
+        }
+      }
       const historyId = await fetchLatestHistoryId(route, agentsModel.id, row.id, opts.userAgent);
-      agentPersonas[role] = { agentId: row.id, lastSyncedUpdatedAt: row.updated_at, ...historyId ? { historyId } : {} };
+      agentPersonas[role] = { agentId: row.id, lastSyncedUpdatedAt: anchoredAt, ...historyId ? { historyId } : {} };
       outcomes.push({ role, action: "unchanged", agentId: row.id });
       continue;
     }
@@ -7350,20 +7414,28 @@ async function syncPersonas(route, opts) {
       continue;
     }
     const cached = cache[role]?.agentId === row.id ? cache[role] : void 0;
-    if (!cached?.historyId) {
-      outcomes.push({ role, action: "diverged", agentId: row.id });
-      continue;
-    }
-    let lastSyncedPrompt;
-    try {
-      const entries = await fetchHistoryEntries(route, agentsModel.id, row.id, opts.userAgent);
-      lastSyncedPrompt = entries.find((e) => e.history_id === cached.historyId)?.prompt;
-    } catch {
-      lastSyncedPrompt = void 0;
-    }
-    if (lastSyncedPrompt === void 0 || lastSyncedPrompt !== row.prompt) {
-      outcomes.push({ role, action: "diverged", agentId: row.id });
-      continue;
+    const baselineKnown = hasPromptBaselineColumn(agentsModel) && typeof row.prompt_baseline === "string";
+    if (baselineKnown) {
+      if (row.prompt !== row.prompt_baseline) {
+        outcomes.push({ role, action: "diverged", agentId: row.id });
+        continue;
+      }
+    } else {
+      if (!cached?.historyId) {
+        outcomes.push({ role, action: "diverged", agentId: row.id });
+        continue;
+      }
+      let lastSyncedPrompt;
+      try {
+        const entries = await fetchHistoryEntries(route, agentsModel.id, row.id, opts.userAgent);
+        lastSyncedPrompt = entries.find((e) => e.history_id === cached.historyId)?.prompt;
+      } catch {
+        lastSyncedPrompt = void 0;
+      }
+      if (lastSyncedPrompt === void 0 || lastSyncedPrompt !== row.prompt) {
+        outcomes.push({ role, action: "diverged", agentId: row.id });
+        continue;
+      }
     }
     if (opts.dryRun) {
       outcomes.push({ role, action: "updated", agentId: row.id });
@@ -7385,7 +7457,7 @@ async function syncPersonas(route, opts) {
         continue;
       }
       if (isPromptGateRejection(e)) {
-        agentPersonas[role] = { agentId: row.id, lastSyncedUpdatedAt: row.updated_at, historyId: cached.historyId };
+        agentPersonas[role] = { agentId: row.id, lastSyncedUpdatedAt: row.updated_at, ...cached?.historyId ? { historyId: cached.historyId } : {} };
         outcomes.push({ role, action: "overridden", agentId: row.id });
         continue;
       }
@@ -7554,7 +7626,20 @@ async function syncSkills(route, opts) {
       continue;
     }
     if (row.description === skill.description && row.prompt === skill.prompt) {
-      agentSkills[skill.name] = { skillId: row.id, lastSyncedUpdatedAt: row.updated_at };
+      let anchoredAt = row.updated_at;
+      if (!opts.dryRun && needsBaselineBackfill(skillsModel, row)) {
+        try {
+          anchoredAt = (await client2.records.update(
+            skillsModel.id,
+            row.id,
+            promptSourceFields(skillsModel, skill.prompt),
+            row.updated_at
+          )).updated_at;
+        } catch (e) {
+          if (!(e instanceof StaleWriteError7) && !isPromptGateRejection(e)) throw e;
+        }
+      }
+      agentSkills[skill.name] = { skillId: row.id, lastSyncedUpdatedAt: anchoredAt };
       outcomes.push({ name: skill.name, action: "unchanged", skillId: row.id });
       continue;
     }
@@ -7563,7 +7648,32 @@ async function syncSkills(route, opts) {
       outcomes.push({ name: skill.name, action: "overridden", skillId: row.id });
       continue;
     }
-    const knownBaseline = cache[skill.name]?.skillId === row.id ? cache[skill.name]?.lastSyncedUpdatedAt : void 0;
+    const body = { description: skill.description, prompt: skill.prompt, ...promptSourceFields(skillsModel, skill.prompt) };
+    if (opts.force) {
+      if (opts.dryRun) {
+        outcomes.push({ name: skill.name, action: "forced", skillId: row.id });
+        continue;
+      }
+      try {
+        const updated = await client2.records.update(skillsModel.id, row.id, body);
+        agentSkills[skill.name] = { skillId: row.id, lastSyncedUpdatedAt: updated.updated_at };
+        outcomes.push({ name: skill.name, action: "forced", skillId: row.id });
+      } catch (e) {
+        if (!isPromptGateRejection(e)) throw e;
+        outcomes.push({ name: skill.name, action: "overridden", skillId: row.id });
+      }
+      continue;
+    }
+    let knownBaseline;
+    if (hasPromptBaselineColumn(skillsModel) && typeof row.prompt_baseline === "string") {
+      if (row.prompt !== row.prompt_baseline) {
+        outcomes.push({ name: skill.name, action: "diverged", skillId: row.id });
+        continue;
+      }
+      knownBaseline = row.updated_at;
+    } else {
+      knownBaseline = cache[skill.name]?.skillId === row.id ? cache[skill.name]?.lastSyncedUpdatedAt : void 0;
+    }
     if (!knownBaseline) {
       outcomes.push({ name: skill.name, action: "diverged", skillId: row.id });
       continue;
@@ -7576,7 +7686,7 @@ async function syncSkills(route, opts) {
       const updated = await client2.records.update(
         skillsModel.id,
         row.id,
-        { description: skill.description, prompt: skill.prompt, ...promptSourceFields(skillsModel, skill.prompt) },
+        body,
         knownBaseline
       );
       agentSkills[skill.name] = { skillId: row.id, lastSyncedUpdatedAt: updated.updated_at };
@@ -7605,6 +7715,8 @@ function describeSkillSyncOutcome(o) {
       return `${o.name}: already in sync`;
     case "overridden":
       return `${o.name}: override in place \u2014 prompt not synced (clear "Customize prompt" on the Agent Skills row to resume)`;
+    case "forced":
+      return `${o.name}: overwritten from crew's local file (--force)`;
     case "diverged":
       return `${o.name}: HAS LOCAL EDITS \u2014 crew's default is newer but was NOT applied; review ${o.skillId} in the app before syncing again`;
   }
@@ -7629,6 +7741,7 @@ async function fetchSkillOverrides(route, opts) {
   for (const row of rows) {
     const name = row.name;
     if (row.prompt === local.get(name)?.prompt) continue;
+    if (row.prompt_customized !== true && row.prompt === row.prompt_baseline) continue;
     const cached = cache[name];
     if (cached?.skillId === row.id && cached.lastSyncedUpdatedAt === row.updated_at) continue;
     out[name] = row.prompt;
@@ -11987,7 +12100,8 @@ async function buildEnvironment(route, ship, ticket) {
     };
   });
   const authorship = await tracker.authorshipProbe().catch(() => null);
-  return renderEnvironment({ route, userAgent: ship.userAgent, repos, contract, sourceTicket: ticket, authorship, shipName: ship.name });
+  const attachments = await tracker.attachmentsProbe().catch(() => null);
+  return renderEnvironment({ route, userAgent: ship.userAgent, repos, contract, sourceTicket: ticket, authorship, attachments, shipName: ship.name });
 }
 
 // src/cli.ts
@@ -12127,7 +12241,7 @@ function usage() {
   crew inbox [--member NAME]    your tickets across every workspace (or a colleague's)
   crew connect                  resolve a workspace's ids into a crew.yaml block (--no-mcp skips registering the Tablation MCP server with Claude Code; --mcp replace overwrites a different one)
   crew disconnect               remove what connect installed for Pair (Claude MCP; Codex/Gemini instructions block and MCP entry per ship.pair)
-  crew agents sync [route] [--force]   push crew's personas AND skill files into the workspace Agents/Agent Skills tables (--force overwrites even a diverged persona)
+  crew agents sync [route] [--force]   push crew's personas AND skill files into the workspace Agents/Agent Skills tables (--force overwrites even a diverged persona or skill; never one marked Customize prompt)
   crew agents prompt R [route] print one persona's current prompt (e.g. R=pair, for a SessionStart hook; --harness H adds which CLI it serves)
   crew skills sync [route]      push only crew's skill files (e.g. grill-me) into the workspace Agent Skills table
   crew repos add [ROUTE] [NAME] [PATH]  attach a local checkout to a route in crew.yaml (--dry-run previews)
@@ -12620,6 +12734,7 @@ ${changed2.map((c) => `  - ${c}
       contract,
       sourceTicket: ticket,
       authorship: await tracker.authorshipProbe().catch(() => null),
+      attachments: await tracker.attachmentsProbe().catch(() => null),
       shipName: cfg.ship.name
     });
   }
@@ -13567,7 +13682,7 @@ ${changed2.map((c) => `  - ${c}
         break;
       }
       if (sub !== "sync") {
-        process.stderr.write("crew agents sync [route] [--force]    push crew's personas (Developer/Design/QA/Triage/Pair) AND skill files (e.g. grill-me) into the workspace Agents/Agent Skills tables (--force overwrites even a diverged persona)\n");
+        process.stderr.write("crew agents sync [route] [--force]    push crew's personas (Developer/Design/QA/Triage/Pair) AND skill files (e.g. grill-me) into the workspace Agents/Agent Skills tables (--force overwrites even a diverged persona or skill; never one marked Customize prompt)\n");
         process.stderr.write(`crew agents prompt <role> [route]     print a persona's current prompt (roles: ${ROLE_NAMES.join(", ")})
 `);
         process.exit(2);
@@ -13610,7 +13725,7 @@ ${changed2.map((c) => `  - ${c}
 `);
       let skillResult;
       try {
-        skillResult = await syncSkills(target, { userAgent: cfg.ship.userAgent, dryRun });
+        skillResult = await syncSkills(target, { userAgent: cfg.ship.userAgent, dryRun, force });
       } catch (e) {
         if (e instanceof SkillSyncError) {
           process.stderr.write(`crew agents sync: ${e.message}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.43.0",
+  "version": "0.43.2",
   "description": "A standing team of headless agents that picks work off a Tablation board, does it on a machine you control, and reports back.",
   "type": "module",
   "license": "MIT",

package/prompts/default/personas/lane-qa.md

@@ -47,9 +47,12 @@ pass.
    builder's closing comment — what it changed, how it says it verified,
    what it admits it could not test — is the thing you are checking.
    Anything it skipped is your first test. **Open the ticket's own
-   attachments first** (Step 3.4 in the shared policy says how): the
-   reporter's screenshot is the repro you are judging the fix against. If
-   you cannot open one, say so and set `needs_info` rather than passing it.
+   attachments first**, exactly as Step 3.4 in the shared policy says: read
+   the Media Library record for its `storage_key`, then fetch
+   `files/<storage_key>` — never a guessed `files/<id>` path. The reporter's
+   screenshot is the repro you are judging the fix against. If you cannot
+   open one, say so with the exact request and response and set `needs_info`
+   rather than passing it.
 4. **Get the branch and read the diff.** The branch on the remote is what
    you test, and you never need the builder's worktree: cut your own with
    `crew worktree <number>` (it prints the path), unless the builder's

package/prompts/default/skills/crew-lane-agent.md

@@ -284,12 +284,21 @@ before going further, and never change a ticket's `report_type` yourself.
 4. **Post a short comment** on what you are about to do (Comments table:
    `ticket_id`, `team_member_id` = your id, markdown `body`), and further
    comments at meaningful milestones — the operator wants visible progress,
-   not just status flips. **Open the ticket's attachments before you start:**
-   an `attachments` value is a list of Media Library record ids, usually the
-   repro screenshot, and where it disagrees with the description the picture
-   is the reproduction. If you cannot open one, that is a blocker (comment,
-   `needs_info` plus `needs_planning`, stop). The `Ticket Attachments` skill
-   has the resolution steps.
+   not just status flips. **Open the ticket's attachments before you start.**
+   An `attachments` value on the ticket or a comment is a list of Media
+   Library record ids — not file ids and not URLs, so no `files/<id>` path
+   will ever work. For each id: (1) read the Media Library record,
+   `GET /api/workspaces/<workspaceId>/data-models/<Media Library id>/records/<id>`
+   (the Environment section's "Opening a ticket's attachments" gives the
+   table id), and take its `storage_key`; (2) fetch the bytes with
+   `GET /api/workspaces/<workspaceId>/files/<storage_key>` (the MCP form is
+   `files_controller_download` with `uuid` and `filename` being the two
+   halves of the storage key) into a scratch directory and open it; (3)
+   compare it with the description — where they disagree, the picture is the
+   reproduction. If you cannot open one, that is a blocker (comment naming
+   it and the exact failure, `needs_info` plus `needs_planning`, stop); never
+   proceed on the prose alone. The `Ticket Attachments` skill has the edge
+   cases.
 5. **Implement the fix.** Read the relevant code first; do not guess at the
    architecture. **Never bump the version or edit the changelog on this
    branch** — the release phase assigns the version once per release, over

package/prompts/default/skills/ticket-attachments.md

@@ -12,14 +12,20 @@ you picked up, and on any comment that has them, before you start.
 
 1. **Read the Media Library record for that id.** The `attachments` column is
    a reference into the workspace's Media Library table; its `storage_key`
-   and `mime_type` are what you need. Take that table's id from the
-   Environment section if it lists one, otherwise from a workspace-level
-   model listing — never by reading the whole Issues model definition, which
-   is over a megabyte.
-2. **Fetch the bytes:** `GET /api/workspaces/<workspaceId>/files/<storage_key>`
-   with the usual headers (the tracker MCP form is `files_controller_download`,
-   which hands an image back as a viewable block). Save the file in a scratch
-   directory outside the repository, then open it.
+   and `mime_type` are what you need:
+   `GET /api/workspaces/<workspaceId>/data-models/<Media Library id>/records/<id>`
+   (MCP: `records_controller_find_one`). The Environment section's "Opening
+   a ticket's attachments" names the table id; if it is absent, find the
+   table by name in a workspace-level model listing — never by reading the
+   whole Issues model definition, which is over a megabyte. The id is a
+   record id, not a file id: `files/<id>`, `files/<id>/download` and
+   `media-library/<id>/...` all 404 by design.
+2. **Fetch the bytes:** the `storage_key` has the form `<uuid>/<filename>`;
+   `GET /api/workspaces/<workspaceId>/files/<uuid>/<filename>` with the usual
+   headers streams it (the MCP form is `files_controller_download` with
+   `workspaceId`, `uuid` and `filename`, which hands an image back as a
+   viewable block). Save the file in a scratch directory outside the
+   repository, then open it.
 3. **Compare what the picture shows with what the description says.** Where
    they disagree, the picture is the reproduction.
 

package/prompts/dev-qa/personas/lane-qa.md

@@ -46,9 +46,12 @@ pass.
    builder's closing comment — what it changed, how it says it verified,
    what it admits it could not test — is the thing you are checking.
    Anything it skipped is your first test. **Open the ticket's own
-   attachments first** (Step 3.4 in the shared policy says how): the
-   reporter's screenshot is the repro you are judging the fix against. If
-   you cannot open one, say so and set `needs_info` rather than passing it.
+   attachments first**, exactly as Step 3.4 in the shared policy says: read
+   the Media Library record for its `storage_key`, then fetch
+   `files/<storage_key>` — never a guessed `files/<id>` path. The reporter's
+   screenshot is the repro you are judging the fix against. If you cannot
+   open one, say so with the exact request and response and set `needs_info`
+   rather than passing it.
 4. **Get the branch and read the diff.** The branch on the remote is what
    you test, and you never need the builder's worktree: cut your own with
    `crew worktree <number>` (it prints the path), unless the builder's

package/prompts/dev-qa/skills/crew-lane-agent.md

@@ -284,12 +284,21 @@ before going further, and never change a ticket's `report_type` yourself.
 4. **Post a short comment** on what you are about to do (Comments table:
    `ticket_id`, `team_member_id` = your id, markdown `body`), and further
    comments at meaningful milestones — the operator wants visible progress,
-   not just status flips. **Open the ticket's attachments before you start:**
-   an `attachments` value is a list of Media Library record ids, usually the
-   repro screenshot, and where it disagrees with the description the picture
-   is the reproduction. If you cannot open one, that is a blocker (comment,
-   `needs_info` plus `needs_planning`, stop). The `Ticket Attachments` skill
-   has the resolution steps.
+   not just status flips. **Open the ticket's attachments before you start.**
+   An `attachments` value on the ticket or a comment is a list of Media
+   Library record ids — not file ids and not URLs, so no `files/<id>` path
+   will ever work. For each id: (1) read the Media Library record,
+   `GET /api/workspaces/<workspaceId>/data-models/<Media Library id>/records/<id>`
+   (the Environment section's "Opening a ticket's attachments" gives the
+   table id), and take its `storage_key`; (2) fetch the bytes with
+   `GET /api/workspaces/<workspaceId>/files/<storage_key>` (the MCP form is
+   `files_controller_download` with `uuid` and `filename` being the two
+   halves of the storage key) into a scratch directory and open it; (3)
+   compare it with the description — where they disagree, the picture is the
+   reproduction. If you cannot open one, that is a blocker (comment naming
+   it and the exact failure, `needs_info` plus `needs_planning`, stop); never
+   proceed on the prose alone. The `Ticket Attachments` skill has the edge
+   cases.
 5. **Implement the fix.** Read the relevant code first; do not guess at the
    architecture. **Never bump the version or edit the changelog on this
    branch** — the release phase assigns the version once per release, over

package/prompts/dev-qa/skills/ticket-attachments.md

@@ -12,14 +12,20 @@ you picked up, and on any comment that has them, before you start.
 
 1. **Read the Media Library record for that id.** The `attachments` column is
    a reference into the workspace's Media Library table; its `storage_key`
-   and `mime_type` are what you need. Take that table's id from the
-   Environment section if it lists one, otherwise from a workspace-level
-   model listing — never by reading the whole Issues model definition, which
-   is over a megabyte.
-2. **Fetch the bytes:** `GET /api/workspaces/<workspaceId>/files/<storage_key>`
-   with the usual headers (the tracker MCP form is `files_controller_download`,
-   which hands an image back as a viewable block). Save the file in a scratch
-   directory outside the repository, then open it.
+   and `mime_type` are what you need:
+   `GET /api/workspaces/<workspaceId>/data-models/<Media Library id>/records/<id>`
+   (MCP: `records_controller_find_one`). The Environment section's "Opening
+   a ticket's attachments" names the table id; if it is absent, find the
+   table by name in a workspace-level model listing — never by reading the
+   whole Issues model definition, which is over a megabyte. The id is a
+   record id, not a file id: `files/<id>`, `files/<id>/download` and
+   `media-library/<id>/...` all 404 by design.
+2. **Fetch the bytes:** the `storage_key` has the form `<uuid>/<filename>`;
+   `GET /api/workspaces/<workspaceId>/files/<uuid>/<filename>` with the usual
+   headers streams it (the MCP form is `files_controller_download` with
+   `workspaceId`, `uuid` and `filename`, which hands an image back as a
+   viewable block). Save the file in a scratch directory outside the
+   repository, then open it.
 3. **Compare what the picture shows with what the description says.** Where
    they disagree, the picture is the reproduction.