ticketlens 0.30.0 → 0.32.0

package/README.md

@@ -413,7 +413,9 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
-`note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead.
+`note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead. Each result shows a relative time (`2h ago`, `3d ago`) rather than a bare date — the full-precision timestamp is always in the note file's own frontmatter.
+
+**Tags matter for search relevance.** `--tags=a,b` accepts anything, but a generic tag (the project name, "gotcha", "bug") gives future search almost nothing to match on. Tag with what the note is actually *about* — the specific technology, error type, or root cause (`retry-backoff`, `null-pointer`, `auth-middleware`) — so it surfaces when someone else hits the same problem.
 
 **Gaps** — every `ticketlens PROJ-123` brief also diffs the ticket's own description against its linked tickets (from the depth traversal you already requested) and its own downloaded attachments, looking for requirements mentioned there but missing here. Anything uncovered shows up under a `## Gaps` section, citing exactly where it came from — a linked ticket key or an attachment filename — as evidence, never an instruction to act on. Nothing is saved anywhere; it's recomputed fresh on every fetch. Requires a Pro license, same as Recall. No network call beyond what the brief already made.
 

package/bin/ticketlens.mjs

@@ -542,7 +542,7 @@ switch (command) {
   case 'cloud-keys': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printCloudKeysHelp(); break; }
 
-    const { listCloudKeys, addCloudKey, removeCloudKey, setPriority, setTimeout_, testCloudKey } =
+    const { listCloudKeys, addCloudKey, runCloudKeysRemove, setPriority, setTimeout_, testCloudKey } =
       await import('../skills/jtb/scripts/lib/cloud-keys.mjs');
 
     const cliToken = readCliToken();
@@ -592,12 +592,14 @@ switch (command) {
       if (subCmd === 'remove') {
         const provider = cmdArgs[1];
         if (!provider) {
-          process.stderr.write('Usage: ticketlens cloud-keys remove <provider>\n');
+          process.stderr.write('Usage: ticketlens cloud-keys remove <provider> [--yes|-y]\n');
           process.exitCode = 1;
           return;
         }
-        await removeCloudKey(cfg, provider);
-        process.stdout.write(`${s.brand('✓')} ${provider} key removed.\n`);
+        const forceYes = cmdArgs.includes('--yes') || cmdArgs.includes('-y');
+        const { removed } = await runCloudKeysRemove(cfg, provider, { forceYes });
+        if (removed) process.stdout.write(`${s.brand('✓')} ${provider} key removed.\n`);
+        else process.exitCode = 1;
         return;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.26.0 -->
+<!-- jtb-skill-version: 0.27.0 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -66,6 +66,8 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb assign PROD-1234 --to=me          # assign the ticket to yourself (Pro)
 ```
 
+**Destructive commands** (`note delete`, `cloud-keys remove`, `delete <profile>`) prompt for interactive y/N confirmation and refuse outright in a non-interactive shell unless `--yes` is passed — there is no way to silently skip this. Only pass `--yes` when the user has explicitly asked for that specific deletion in this conversation (their message *is* the confirmation); never add it to route around the prompt for a deletion you decided to make on your own.
+
 ## Prerequisites
 
 TicketLens supports two connection methods — check in this order:
@@ -91,7 +93,7 @@ If the first argument is `triage`:
 
 Run:
 ```bash
-node ~/.agents/skills/jtb/scripts/fetch-my-tickets.mjs $EXTRA_ARGS
+ticketlens triage $EXTRA_ARGS
 ```
 
 Where `$EXTRA_ARGS` are any flags passed (e.g. `--stale=3 --status=QA --profile=acme`).
@@ -112,7 +114,7 @@ If the first argument is `collisions`:
 
 Run:
 ```bash
-node ~/.agents/skills/jtb/scripts/lib/run-collisions.mjs $EXTRA_ARGS
+ticketlens collisions $EXTRA_ARGS
 ```
 
 Where `$EXTRA_ARGS` are any flags passed (e.g. `--json`, `--plain`).
@@ -136,7 +138,7 @@ Follow the Prerequisites section above:
 
 Run:
 ```bash
-node ~/.agents/skills/jtb/scripts/fetch-ticket.mjs "$TICKET_KEY" $EXTRA_ARGS
+ticketlens "$TICKET_KEY" $EXTRA_ARGS
 ```
 
 Where `$TICKET_KEY` is the first argument (e.g. `PROD-1234`) and `$EXTRA_ARGS` are any flags passed (e.g. `--depth=0`).
@@ -234,9 +236,11 @@ echo "The body text of the note, one or more paragraphs." | \
   ticketlens note add --title="Short title" --ticket=TICKET-KEY --tags=a,b
 ```
 
+**Choosing tags:** derive them from this note's actual content — the specific technology, error type, root cause, or affected component (e.g. `retry-backoff`, `null-pointer`, `auth-middleware`) — never the project name or a generic category word like `gotcha` or `bug`. A tag like `jtb` or `ticketlens` tells a future search nothing that the ticket/project context doesn't already say; a tag like `retry-backoff` is what actually surfaces this note when someone else hits the same problem. Same rule whether you're constructing the bash command above or calling `recall_add` directly — see its tool description for the same guidance.
+
 To search saved notes directly (outside of automatic brief injection): `ticketlens recall "<query>"`.
 
-**Pick exactly one path per capture — never both.** If this harness has TicketLens's MCP server configured (`ticketlens mcp` — `recall_add`/`recall_search` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same secret scan, same vault, same team sync, just no shell command to construct. Fall back to the bash form only when the MCP tools aren't available. Calling both for the same insight creates two near-duplicate notes (no dedup exists between the two paths) and, with team sync on, two separate pushes for a manager to review.
+**Pick exactly one path per capture — never both.** If this harness has TicketLens's MCP server configured (tools named `recall_add`/`recall_search` — often shown as `mcp__ticketlens__recall_add` — visible in your tool list), **use those tools, not the bash commands above** — same license gate, same secret scan, same vault, same team sync, just no shell command to construct. Only fall back to the bash form when the MCP tools are genuinely absent from your tool list. If they're absent because this project has never registered the server, tell the user once: `ticketlens mcp install` writes (or merges into) this project's `.mcp.json` — don't run it yourself unprompted, since it changes what your harness auto-connects to on next launch, and the user should be the one deciding that. Calling both for the same insight creates two near-duplicate notes (no dedup exists between the two paths) and, with team sync on, two separate pushes for a manager to review.
 
 ### Quality loop (Pro, in-session only)
 
@@ -284,7 +288,7 @@ ticketlens duplicates PROD-1234                               # find likely dupl
 
 The three write actions (comment/transition/assign) have a short local debounce (10s) against an accidental double-fire, and every write is appended to a local audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — surface the failure to the user rather than silently re-attempting, since a ticket write isn't naturally idempotent the way a Recall note save is. `duplicates` has neither, since nothing is written.
 
-**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (`ticketlens mcp` — `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same cooldown, same audit log. Fall back to the bash form only when the MCP tools aren't available.
+**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (tools named `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates`/`ticket_link`/`ticket_update`/`ticket_create` — often shown as `mcp__ticketlens__ticket_comment` etc. — visible in your tool list), **use those tools, not the bash commands above** — same license gate, same cooldown, same audit log. Only fall back to the bash form when the MCP tools are genuinely absent from your tool list; if that's because this project has never registered the server, see the `ticketlens mcp install` note above (Recall section) — same guidance applies here.
 
 Requires a Pro license — on Free, all four no-op with an upgrade hint on stderr.
 

package/skills/jtb/scripts/lib/adapters/jira-adapter.mjs

@@ -1,4 +1,7 @@
 import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, fetchProjects, fetchIssueTypes, postComment, getTransitions, postTransition, assignIssue, escapeJql, getIssueLinkTypes, postIssueLink, updateIssue, createIssue } from '../jira-client.mjs';
+import { uploadAttachment, resolveMediaId } from '../jira-attachment-client.mjs';
+import { readAttachments } from '../attachment-uploader.mjs';
+import { buildMediaNode } from '../adf-converter.mjs';
 import { buildJiraEnv } from '../config.mjs';
 
 /**
@@ -149,5 +152,54 @@ export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
 
     /** Real, currently-configured issue types for one project. */
     listIssueTypes: (projectKey, opts = {}) => fetchIssueTypes(projectKey, { ...base, ...opts }),
+
+    /**
+     * Best-effort, per-file: one bad path or one failed upload never blocks
+     * the rest (same `{applied/uploaded, errors}` shape convention as
+     * updateFields' GitHub label loop). Two different inline-thumbnail
+     * mechanisms per apiVersion, both real:
+     *  - Server/DC (v2, plain-string bodies): legacy wiki markup
+     *    `!filename|thumbnail!`, resolved by filename — returned as
+     *    `inlineMarkup`, a plain string the caller appends to body text.
+     *  - Cloud (v3, ADF): a real `mediaSingle`/`media` ADF node — returned
+     *    as `adfMediaNode`, an object the caller threads through
+     *    `postComment`'s `extraAdfNodes`. Requires one extra call
+     *    (`resolveMediaId`) to resolve the Media Services UUID; if that
+     *    fails, `adfMediaNode` stays null — the classic attachment above
+     *    already succeeded and is genuinely visible on the issue either
+     *    way, so this failure is swallowed, not surfaced as an error.
+     * Both are image-only; non-image files get neither.
+     */
+    async attachFiles(key, filePaths, opts = {}) {
+      const { files, droppedCount } = readAttachments(filePaths);
+      const uploaded = [];
+      const errors = [];
+      for (const f of files) {
+        if (!f.ok) {
+          errors.push({ path: f.path, message: f.error });
+          continue;
+        }
+        try {
+          const result = await uploadAttachment(key, f, { ...base, ...opts });
+          const isImage = f.mimeType.startsWith('image/');
+          let inlineMarkup = null;
+          let adfMediaNode = null;
+          if (isImage && apiVersion === 2) {
+            inlineMarkup = `!${result.filename}|thumbnail!`;
+          } else if (isImage && apiVersion === 3 && result.url) {
+            try {
+              const mediaId = await resolveMediaId(result.url, { ...base, ...opts });
+              adfMediaNode = buildMediaNode(mediaId, key);
+            } catch {
+              // Enhancement only — see doc comment above.
+            }
+          }
+          uploaded.push({ filename: result.filename, size: result.size, url: result.url, inlineMarkup, adfMediaNode });
+        } catch (err) {
+          errors.push({ path: f.path, message: err.message });
+        }
+      }
+      return { uploaded, errors, droppedCount };
+    },
   };
 }

package/skills/jtb/scripts/lib/adapters/linear-adapter.mjs

@@ -1,4 +1,6 @@
 import { tokenize } from '../duplicate-scorer.mjs';
+import { readAttachments } from '../attachment-uploader.mjs';
+import { isSafeRedirectUrl, validateResolvedHost, defaultLookupFor } from '../jira-client.mjs';
 
 const LINEAR_API = 'https://api.linear.app/graphql';
 
@@ -487,5 +489,77 @@ export function createLinearAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       );
       return (data.teams?.nodes ?? []).map(t => ({ key: t.key, name: t.name }));
     },
+
+    /**
+     * Linear's fileUpload mutation is workspace-scoped, not issue-scoped —
+     * unlike Jira, there is no issue key involved in the upload itself, so
+     * this works identically whether the target issue already exists
+     * (comment) or was just created (create). Two-step, both officially
+     * documented: request a signed PUT URL, then PUT the bytes directly to
+     * it. Linear renders any Markdown image URL inline automatically — no
+     * separate node-graph system the way Jira's ADF has, so this is the one
+     * tracker in this family with a fully working, gap-free thumbnail path.
+     * Best-effort per file, same `{uploaded, errors}` shape as Jira's
+     * attachFiles.
+     */
+    async attachFiles(key, filePaths, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 30_000);
+      const { lookup = defaultLookupFor(fetcher), allowPrivateIp = false } = opts;
+      const { files, droppedCount } = readAttachments(filePaths);
+      const uploaded = [];
+      const errors = [];
+      for (const f of files) {
+        if (!f.ok) {
+          errors.push({ path: f.path, message: f.error });
+          continue;
+        }
+        try {
+          const data = await gql(
+            `mutation ($contentType: String!, $filename: String!, $size: Int!) {
+              fileUpload(contentType: $contentType, filename: $filename, size: $size) {
+                success
+                uploadFile { uploadUrl assetUrl headers { key value } }
+              }
+            }`,
+            { contentType: f.mimeType, filename: f.filename, size: f.size },
+            { token, fetcher, signal },
+          );
+          const target = data.fileUpload?.uploadFile;
+          if (!data.fileUpload?.success || !target) {
+            errors.push({ path: f.path, message: 'Linear fileUpload did not return an upload target' });
+            continue;
+          }
+          if (!isSafeRedirectUrl(target.uploadUrl)) {
+            errors.push({ path: f.path, message: 'refusing an unsafe upload URL returned by Linear (non-HTTPS or a private/internal host)' });
+            continue;
+          }
+          // DNS-rebinding guard, same as every other server-supplied URL
+          // this codebase connects to (see jira-client.mjs's guardedFetch) —
+          // isSafeRedirectUrl above only checks the hostname string; this
+          // resolves it. redirect:'manual' + the explicit 3xx refusal below
+          // mirrors guardedFetch's "never follow a redirect on a write" rule.
+          await validateResolvedHost(new URL(target.uploadUrl).hostname, lookup, allowPrivateIp);
+          const putHeaders = Object.fromEntries((target.headers ?? []).map(h => [h.key, h.value]));
+          const putRes = await fetcher(target.uploadUrl, { method: 'PUT', headers: putHeaders, body: f.buffer, signal, redirect: 'manual' });
+          if (putRes.status >= 300 && putRes.status < 400) {
+            errors.push({ path: f.path, message: `upload PUT redirected unexpectedly (status ${putRes.status}) — refusing to follow` });
+            continue;
+          }
+          if (!putRes.ok) {
+            errors.push({ path: f.path, message: `upload PUT failed with ${putRes.status}` });
+            continue;
+          }
+          uploaded.push({
+            filename: f.filename,
+            size: f.size,
+            url: target.assetUrl,
+            inlineMarkup: f.mimeType.startsWith('image/') ? `![${f.filename}](${target.assetUrl})` : `[${f.filename}](${target.assetUrl})`,
+          });
+        } catch (err) {
+          errors.push({ path: f.path, message: err.message });
+        }
+      }
+      return { uploaded, errors, droppedCount };
+    },
   };
 }

package/skills/jtb/scripts/lib/adf-converter.mjs

@@ -23,6 +23,32 @@ export function textToAdf(text) {
   };
 }
 
+/**
+ * Builds an ADF mediaSingle+media node embedding an already-uploaded Jira
+ * attachment as a real inline image. `collection` does NOT need to be
+ * Jira's actual internal Media Services collection — real-instance
+ * verification against a live Jira Cloud site confirmed the image renders
+ * correctly regardless of the collection value given (including the
+ * ticket key, used here as a stable value requiring no extra lookup);
+ * the content-scoped access token embedded when resolving `id` is what
+ * actually grants read access, not this field.
+ */
+export function buildMediaNode(mediaId, collection) {
+  return {
+    type: 'mediaSingle',
+    attrs: { layout: 'center' },
+    content: [{ type: 'media', attrs: { type: 'file', id: mediaId, collection } }],
+  };
+}
+
+/**
+ * Appends block-level nodes (e.g. a media node) after an ADF doc's existing
+ * content, without mutating the original doc.
+ */
+export function appendNodesToAdf(adfDoc, extraNodes) {
+  return { ...adfDoc, content: [...adfDoc.content, ...extraNodes] };
+}
+
 export function adfToText(value) {
   if (value == null) return '';
   if (typeof value === 'string') return value;

package/skills/jtb/scripts/lib/attachment-downloader.mjs

@@ -159,7 +159,7 @@ function makeResult(attachment, localPath, skipReason, error) {
   };
 }
 
-function sanitizeFilename(filename) {
+export function sanitizeFilename(filename) {
   // Strip directory components, replace unsafe chars, preserve extension
   return path.basename(filename).replace(/[^a-zA-Z0-9._\-]/g, '_');
 }

package/skills/jtb/scripts/lib/attachment-uploader.mjs

@@ -0,0 +1,96 @@
+/**
+ * Validates and reads local files for upload to a tracker (Jira attachment
+ * API, Linear fileUpload). Shared across trackers — the read/validate step
+ * is identical regardless of where the bytes end up.
+ *
+ * No path allowlist: the caller (a human, or an AI harness the human is
+ * directing) is trusted to supply a legitimate path — the same trust
+ * boundary already extended to every other free-text write field in this
+ * ticket-write family (comment bodies, summaries). This was a deliberate,
+ * reviewed choice, not an oversight — see the security-reviewer pass for
+ * this feature.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { sanitizeFilename } from './attachment-downloader.mjs';
+
+export const MAX_ATTACHMENTS = 20; // mirrors attachment-downloader.mjs's download-side cap
+export const MAX_FILE_BYTES = 10 * 1024 * 1024; // 10 MB — same
+export const MAX_TOTAL_BYTES = 50 * 1024 * 1024; // 50 MB aggregate per call — bounds worst-case memory use across a whole batch
+
+const MIME_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain',
+  '.log': 'text/plain',
+  '.md': 'text/markdown',
+  '.csv': 'text/csv',
+  '.json': 'application/json',
+  '.zip': 'application/zip',
+};
+
+function mimeTypeFor(filePath) {
+  return MIME_TYPES[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+
+/**
+ * Size is checked via a stat call BEFORE reading the file into memory — a
+ * path to a huge file is rejected without ever buffering it.
+ *
+ * @returns {{ path: string, filename: string, buffer: Buffer, mimeType: string, size: number }
+ *          | { path: string, error: 'not-found'|'not-a-file'|'empty'|'too-large' }}
+ */
+export function readAttachmentFile(filePath) {
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return { path: filePath, error: 'not-found' };
+  }
+  if (!stat.isFile()) return { path: filePath, error: 'not-a-file' };
+  if (stat.size === 0) return { path: filePath, error: 'empty' };
+  if (stat.size > MAX_FILE_BYTES) return { path: filePath, error: 'too-large' };
+
+  return {
+    path: filePath,
+    filename: sanitizeFilename(path.basename(filePath)),
+    buffer: fs.readFileSync(filePath),
+    mimeType: mimeTypeFor(filePath),
+    size: stat.size,
+  };
+}
+
+/**
+ * Reads a batch of paths, best-effort — one bad path never blocks the rest.
+ * Paths beyond MAX_ATTACHMENTS are dropped and counted, not silently read.
+ * A cheap pre-stat tracks the running total so a file that would push the
+ * batch over MAX_TOTAL_BYTES is rejected without ever being buffered — same
+ * "reject before read" principle as the per-file size cap. The pre-stat's
+ * own errors are ignored here; readAttachmentFile below produces the real,
+ * specific error (not-found/not-a-file/etc.) for those paths.
+ *
+ * @param {string[]} paths
+ * @returns {{ files: Array<{ok: boolean} & (ReturnType<typeof readAttachmentFile>)>, droppedCount: number }}
+ */
+export function readAttachments(paths) {
+  const capped = paths.slice(0, MAX_ATTACHMENTS);
+  const files = [];
+  let totalBytes = 0;
+  for (const p of capped) {
+    let precheckSize = 0;
+    try { precheckSize = fs.statSync(p).size; } catch { /* handled below */ }
+    if (precheckSize > 0 && totalBytes + precheckSize > MAX_TOTAL_BYTES) {
+      files.push({ ok: false, path: p, error: 'total-size-exceeded' });
+      continue;
+    }
+    const result = readAttachmentFile(p);
+    if (!result.error) totalBytes += result.size;
+    files.push({ ok: !result.error, ...result });
+  }
+  return { files, droppedCount: paths.length - capped.length };
+}

package/skills/jtb/scripts/lib/cli.mjs

@@ -130,6 +130,10 @@ export function parseCommand(args) {
     return { command: 'mcp', args: args.slice(1) };
   }
 
+  if (first === 'cloud-keys') {
+    return { command: 'cloud-keys', args: args.slice(1) };
+  }
+
   if (first === 'comment') {
     return { command: 'comment', args: args.slice(1) };
   }

package/skills/jtb/scripts/lib/cloud-keys.mjs

@@ -4,6 +4,8 @@
  * All operations require a CLI token (set via `ticketlens login`).
  */
 
+import { confirmDestructive } from './confirm.mjs';
+
 const SUPPORTED_PROVIDERS = ['groq', 'anthropic', 'openai'];
 
 function apiBase(config) {
@@ -84,6 +86,29 @@ export async function removeCloudKey(config, provider) {
   await fetchApi(config, `/v1/ai-providers/${target.id}`, 'DELETE');
 }
 
+/**
+ * CLI-facing wrapper around removeCloudKey — gates the irreversible remote
+ * deletion behind a y/N confirmation (or --yes) before calling it.
+ */
+export async function runCloudKeysRemove(config, provider, opts = {}) {
+  const {
+    stream = process.stderr,
+    stdin = process.stdin,
+    forceYes = false,
+    confirmFn = confirmDestructive,
+    removeCloudKeyFn = removeCloudKey,
+  } = opts;
+
+  const confirmed = await confirmFn(`Remove the ${provider} key`, { stdin, stream, forceYes });
+  if (!confirmed) {
+    stream.write('  Aborted — key was not removed.\n');
+    return { removed: false };
+  }
+
+  await removeCloudKeyFn(config, provider);
+  return { removed: true };
+}
+
 export async function setPriority(config, provider, priority) {
   const target = await findProvider(config, provider);
   await fetchApi(config, `/v1/ai-providers/${target.id}`, 'PUT', { priority: Number(priority) });

package/skills/jtb/scripts/lib/config.mjs

@@ -42,10 +42,13 @@ export function getPackageMeta() {
   };
 }
 
-/** Human-readable relative time from an ISO date string. */
-export function timeAgo(dateStr) {
+/**
+ * Human-readable relative time from an ISO date string.
+ * @param {{ now?: () => Date }} [opts] - injectable clock, for deterministic tests only
+ */
+export function timeAgo(dateStr, { now = () => new Date() } = {}) {
   if (!dateStr) return '';
-  const diff = Date.now() - new Date(dateStr).getTime();
+  const diff = now().getTime() - new Date(dateStr).getTime();
   const mins = Math.floor(diff / 60000);
   if (mins < 60) return `${mins}m ago`;
   const hours = Math.floor(mins / 60);

package/skills/jtb/scripts/lib/confirm.mjs

@@ -0,0 +1,29 @@
+/**
+ * Interactive y/N confirmation gate for destructive, unrecoverable actions
+ * (deleting a Recall note, removing a stored cloud-provider key, etc).
+ * Enter with no input aborts — an accidental keystroke never destroys data.
+ * Non-interactive callers must pass forceYes explicitly (--yes/-y at the CLI).
+ */
+export async function confirmDestructive(action, opts = {}) {
+  const { stdin = process.stdin, stream = process.stderr, forceYes = false } = opts;
+
+  if (forceYes) return true;
+
+  if (!stdin.isTTY || !stdin.setRawMode) {
+    stream.write('  ✖ Non-interactive mode: pass --yes to confirm without a prompt.\n');
+    return false;
+  }
+
+  stream.write(`  ${action} — this cannot be restored. Continue?  y/N  `);
+  return new Promise(resolve => {
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.once('data', buf => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      const confirmed = buf.toString().toLowerCase() === 'y';
+      stream.write(confirmed ? 'y\n' : 'N\n');
+      resolve(confirmed);
+    });
+  });
+}

package/skills/jtb/scripts/lib/help.mjs

@@ -574,11 +574,12 @@ export function printNoteHelp({ stream = process.stdout } = {}) {
     `  Code session — not typically invoked by hand. Every note it writes gets the`,
     `  same structural and secret-scan checks ${s.brand('note add')} applies to user input.`,
     '',
-    `  ${s.bold('ticketlens note delete')} ${s.dim('--id="..." [--ticket=KEY]')}  ${s.dim('[Pro]')}`,
+    `  ${s.bold('ticketlens note delete')} ${s.dim('--id="..." [--ticket=KEY] [--yes]')}  ${s.dim('[Pro]')}`,
     '',
     `  Removes a note from your local vault. Local only — if this note was already`,
     `  pushed to a team, teammates who pulled it keep their copy; deleting it there`,
-    `  too is a manager action from the Console (Admin > Recall).`,
+    `  too is a manager action from the Console (Admin > Recall). In TTY mode,`,
+    `  prompts for confirmation before deleting. Pass ${s.cyan('--yes')} (or ${s.cyan('-y')}) to skip the prompt.`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');
@@ -669,20 +670,24 @@ export function printCommentHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [
     '',
-    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('comment')} ${s.dim('TICKET-KEY --body="..."')}  ${s.dim('[Pro]')}`,
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('comment')} ${s.dim('TICKET-KEY --body="..." [--attach=path1,path2]')}  ${s.dim('[Pro]')}`,
     '',
     `  Post a comment directly to the ticket in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
     `  Writes to the real tracker — this is not a local Recall note.`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',
-    `    ${s.brand('--body')}=${s.dim('TEXT')}    Comment body ${s.dim('(required)')}`,
-    `    ${s.brand('--profile')}=${s.dim('NAME')} Connection profile to use ${s.dim('(optional)')}`,
-    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    `    ${s.brand('--body')}=${s.dim('TEXT')}      Comment body ${s.dim('(required)')}`,
+    `    ${s.brand('--attach')}=${s.dim('PATHS')}   Comma-separated local file paths to attach ${s.dim('(optional)')}`,
+    `                    Images render as an inline thumbnail on Jira and Linear.`,
+    `                    Not supported on GitHub — no attachment upload API exists there.`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')}   Connection profile to use ${s.dim('(optional)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}     Show this help`,
     '',
     `  ${s.bold('EXAMPLES')}`,
     '',
     `    ${s.dim('$')} ticketlens comment PROD-123 --body="Looks good, merging."`,
+    `    ${s.dim('$')} ticketlens comment PROD-123 --body="See screenshot" --attach=./bug.png`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');
@@ -860,6 +865,8 @@ export function printCreateHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--type')}=${s.dim('NAME')}       Issue type ${s.dim('(Jira only, required there)')}`,
     `    ${s.brand('--summary')}=${s.dim('TEXT')}    Ticket title/summary ${s.dim('(required)')}`,
     `    ${s.brand('--description')}=${s.dim('TEXT')}  Ticket description`,
+    `    ${s.brand('--attach')}=${s.dim('PATHS')}    Comma-separated local file paths to attach, uploaded after creation`,
+    `                    ${s.dim('(optional)')}. Not supported on GitHub — no attachment upload API exists there.`,
     `    ${s.brand('--profile')}=${s.dim('NAME')}     Connection profile to use ${s.dim('(optional)')}`,
     `    ${s.brand('-h')}, ${s.brand('--help')}       Show this help`,
     '',
@@ -867,6 +874,7 @@ export function printCreateHelp({ stream = process.stdout } = {}) {
     '',
     `    ${s.dim('$')} ticketlens create --project=PROD --type="Task" --summary="Fix login on mobile"`,
     `    ${s.dim('$')} ticketlens create --project=ENG --summary="New Linear issue" --profile=linear-team`,
+    `    ${s.dim('$')} ticketlens create --project=PROD --type="Bug" --summary="Broken layout" --attach=./screenshot.png`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');
@@ -1263,7 +1271,7 @@ export function printCloudKeysHelp({ stream = process.stdout } = {}) {
     '',
     `    ${s.brand('list')}                          List configured providers`,
     `    ${s.brand('add')} ${s.dim('<provider> <key>')}         Add or replace an API key`,
-    `    ${s.brand('remove')} ${s.dim('<provider>')}            Remove a provider's key`,
+    `    ${s.brand('remove')} ${s.dim('<provider>')} ${s.dim('[--yes]')}   Remove a provider's key — prompts for confirmation`,
     `    ${s.brand('test')} ${s.dim('<provider>')}              Send a test request through the provider`,
     `    ${s.brand('priority')} ${s.dim('<provider> <N>')}      Set priority (lower = tried first)`,
     `    ${s.brand('timeout')} ${s.dim('<provider> <seconds>')} Set per-request timeout`,
@@ -1271,6 +1279,7 @@ export function printCloudKeysHelp({ stream = process.stdout } = {}) {
     `  ${s.bold('OPTIONS')}`,
     '',
     `    ${s.brand('--timeout')}=${s.dim('N')}   Timeout in seconds when adding a key  ${s.dim('(default: 5)')}`,
+    `    ${s.brand('--yes')}, ${s.brand('-y')}   Skip the confirmation prompt when removing a key`,
     `    ${s.brand('-h')}, ${s.brand('--help')}  Show this help`,
     '',
     `  ${s.bold('PROVIDERS')}`,

package/skills/jtb/scripts/lib/jira-attachment-client.mjs

@@ -0,0 +1,80 @@
+/**
+ * Uploads a file to a Jira issue's attachments. Multipart/form-data, not
+ * JSON — the one write in this codebase with a genuinely different request
+ * shape from every other Jira write (comment/transition/assign/link/update/
+ * create all send `Content-Type: application/json`). Reuses the same
+ * guardedFetch/validateBaseUrl/buildAuthHeader SSRF/auth guards as every
+ * other call in jira-client.mjs, imported rather than duplicated.
+ */
+
+import { guardedFetch, validateBaseUrl, buildAuthHeader, defaultLookupFor, validateResolvedHost } from './jira-client.mjs';
+
+/**
+ * @param {string} ticketKey
+ * @param {{ filename: string, buffer: Buffer, mimeType: string }} file - from attachment-uploader.mjs's readAttachmentFile
+ * @param {object} opts
+ * @returns {Promise<{ id: string, filename: string, size: number, url: string|null }>}
+ */
+export async function uploadAttachment(ticketKey, file, opts = {}) {
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 30_000, allowPrivateIp = false } = opts;
+  validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);
+  const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
+  const url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/attachments`;
+
+  const form = new FormData();
+  form.append('file', new Blob([file.buffer], { type: file.mimeType }), file.filename);
+
+  // No Content-Type header here — FormData sets its own multipart boundary.
+  // Every other write in jira-client.mjs sets 'Content-Type': 'application/json';
+  // copying that here would silently break the upload.
+  const fetchOpts = {
+    method: 'POST',
+    headers: { ...buildAuthHeader(env), 'X-Atlassian-Token': 'no-check' },
+    body: form,
+  };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+  if (!response.ok) {
+    const err = new Error(`Jira API error ${response.status} attaching ${file.filename} to ${ticketKey}`);
+    err.status = response.status;
+    throw err;
+  }
+  const raw = await response.json();
+  const uploaded = (Array.isArray(raw) ? raw[0] : raw) ?? {};
+  return {
+    id: uploaded.id,
+    filename: uploaded.filename ?? file.filename,
+    size: uploaded.size ?? file.buffer.length,
+    url: uploaded.content ?? null,
+  };
+}
+
+/**
+ * Resolves the Media Services UUID for an already-uploaded attachment —
+ * a completely different ID space from the classic attachment id above,
+ * and required to embed the attachment as real inline media in an ADF
+ * comment (see adf-converter.mjs's buildMediaNode). The only documented
+ * way to get it: a manual-redirect GET on the attachment's content URL,
+ * whose Location header points to
+ * `https://api.media.atlassian.com/file/{UUID}/binary?token=...` — the
+ * UUID is parsed out of that path without ever following the redirect
+ * (no need to actually download the file just to discard it).
+ *
+ * Real-instance-verified against a live Jira Cloud site: the resulting
+ * media node renders as a genuine inline thumbnail — see buildMediaNode's
+ * doc comment for what was confirmed about the `collection` attribute.
+ */
+export async function resolveMediaId(contentUrl, opts = {}) {
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), allowPrivateIp = false } = opts;
+  await validateResolvedHost(new URL(contentUrl).hostname, lookup, allowPrivateIp);
+  const response = await fetcher(contentUrl, { headers: buildAuthHeader(env), redirect: 'manual' });
+  if (response.status < 300 || response.status >= 400) {
+    throw new Error(`Expected a redirect resolving the media id for ${contentUrl}, got ${response.status}`);
+  }
+  const location = response.headers.get('location');
+  if (!location) throw new Error(`Media content redirect for ${contentUrl} had no Location header`);
+  const match = new URL(location).pathname.match(/\/file\/([^/]+)\/binary/);
+  if (!match) throw new Error(`Could not parse a media uuid from redirect target for ${contentUrl}`);
+  return match[1];
+}

package/skills/jtb/scripts/lib/jira-client.mjs

@@ -4,7 +4,7 @@
  * Supports v2 (Server/DC) and v3 (Cloud) API versions.
  */
 
-import { adfToText, textToAdf } from './adf-converter.mjs';
+import { adfToText, textToAdf, appendNodesToAdf } from './adf-converter.mjs';
 import { lookup as dnsLookup } from 'node:dns/promises';
 
 function toText(value) {
@@ -420,14 +420,21 @@ export async function fetchRemoteLinks(ticketKey, opts = {}) {
  * Adds a comment to an issue. Cloud (v3) rejects a plain string body
  * outright and requires ADF; Server/DC (v2) accepts plain text directly —
  * same apiVersion branch point every other write/read here already uses.
+ *
+ * `extraAdfNodes` (Cloud only — a v2 string body has no ADF structure to
+ * append to) lets a caller embed real inline media (e.g. an uploaded
+ * attachment's mediaSingle node from adf-converter.mjs's buildMediaNode)
+ * after the text content, in the same atomic comment write.
  */
 export async function postComment(ticketKey, body, opts = {}) {
-  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 10_000, allowPrivateIp = false } = opts;
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 10_000, allowPrivateIp = false, extraAdfNodes = [] } = opts;
   validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);
   const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
   const url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/comment`;
 
-  const payload = { body: apiVersion === 3 ? textToAdf(body) : body };
+  let payloadBody = apiVersion === 3 ? textToAdf(body) : body;
+  if (apiVersion === 3 && extraAdfNodes.length) payloadBody = appendNodesToAdf(payloadBody, extraAdfNodes);
+  const payload = { body: payloadBody };
   const fetchOpts = {
     method: 'POST',
     headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' },

package/skills/jtb/scripts/lib/mcp-server.mjs

@@ -36,7 +36,7 @@ const TOOLS = [
       properties: {
         title: { type: 'string', description: 'Short one-line title.' },
         ticket: { type: 'string', description: 'Optional ticket key, e.g. PROJ-123.' },
-        tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags.' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags derived from this note\'s actual content — the specific technology, error type, root cause, or affected component (e.g. "retry-backoff", "null-pointer", "auth-middleware"). Never the project name or a generic category word like "gotcha" or "bug" — those provide no search signal to someone else looking for this note later.' },
         body: { type: 'string', description: 'The note body — one or more paragraphs.' },
       },
       required: ['title', 'body'],
@@ -61,6 +61,7 @@ const TOOLS = [
       properties: {
         ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
         body: { type: 'string', description: 'Comment body.' },
+        attachments: { type: 'array', items: { type: 'string' }, description: 'Local file paths to attach — images render as a real inline thumbnail in the posted comment on both Jira (Cloud and Server/Data Center) and Linear. Not supported on GitHub — no PAT-compatible upload API exists there.' },
       },
       required: ['ticket', 'body'],
     },
@@ -142,6 +143,7 @@ const TOOLS = [
         type: { type: 'string', description: 'Jira issue type, e.g. "Task" or "Bug". Required for Jira only; ignored on GitHub/Linear.' },
         summary: { type: 'string', description: 'Ticket title/summary.' },
         description: { type: 'string', description: 'Ticket description. Omit for none.' },
+        attachments: { type: 'array', items: { type: 'string' }, description: 'Local file paths to attach, uploaded after the ticket is created. On Linear the image is automatically linked into the description. On Jira it becomes a real, visible attachment on the issue, but is not embedded inline in the initial description (use ticket_comment afterward for an inline thumbnail). Not supported on GitHub.' },
       },
       required: ['summary'],
     },
@@ -222,8 +224,10 @@ async function callTicketComment(args, { configDir, runTicketCommentFn }) {
   if (!args.body) {
     return { isError: true, content: [{ type: 'text', text: 'Missing required argument: body' }] };
   }
+  const cmdArgs = [args.ticket, `--body=${args.body}`];
+  if (args.attachments?.length) cmdArgs.push(`--attach=${args.attachments.join(',')}`);
   const capture = capturingStream();
-  const { ok } = await runTicketCommentFn([args.ticket, `--body=${args.body}`], { configDir, stream: capture });
+  const { ok } = await runTicketCommentFn(cmdArgs, { configDir, stream: capture });
   const content = [{ type: 'text', text: capture.text }];
   return ok ? { content } : { isError: true, content };
 }
@@ -350,6 +354,7 @@ function buildTicketCreateArgs(args) {
   if (args.type !== undefined) cmdArgs.push(`--type=${args.type}`);
   cmdArgs.push(`--summary=${args.summary}`);
   if (args.description !== undefined) cmdArgs.push(`--description=${args.description}`);
+  if (args.attachments?.length) cmdArgs.push(`--attach=${args.attachments.join(',')}`);
   return cmdArgs;
 }
 

package/skills/jtb/scripts/lib/note-command.mjs

@@ -19,6 +19,7 @@ import { incrementDraftKept, incrementDraftDeleted } from './activity-counter.mj
 import { extractText } from './attachment-text.mjs';
 import { TICKET_KEY_PATTERN } from './cli.mjs';
 import { createStyler } from './ansi.mjs';
+import { confirmDestructive } from './confirm.mjs';
 
 function defaultListAttachments(configDir, ticketKey) {
   const cacheDir = path.join(configDir, 'cache', ticketKey);
@@ -226,8 +227,10 @@ export async function runNotePatch(cmdArgs, {
 export async function runNoteDelete(cmdArgs, {
   configDir = DEFAULT_CONFIG_DIR,
   stream = process.stderr,
+  stdin = process.stdin,
   isLicensedFn = isLicensed,
   deleteNoteFn = deleteNote,
+  confirmFn = confirmDestructive,
 } = {}) {
   if (!isLicensedFn('pro', configDir)) {
     showUpgradePrompt('pro', 'ticketlens note', { stream });
@@ -236,7 +239,7 @@ export async function runNoteDelete(cmdArgs, {
 
   const id = parseFlag(cmdArgs, 'id');
   if (!id) {
-    stream.write('Usage: ticketlens note delete --id="..." [--ticket=KEY]\n');
+    stream.write('Usage: ticketlens note delete --id="..." [--ticket=KEY] [--yes|-y]\n');
     return { deleted: false };
   }
 
@@ -246,6 +249,13 @@ export async function runNoteDelete(cmdArgs, {
     return { deleted: false };
   }
 
+  const forceYes = cmdArgs.includes('--yes') || cmdArgs.includes('-y');
+  const confirmed = await confirmFn(`Delete note (${id})`, { stdin, stream, forceYes });
+  if (!confirmed) {
+    stream.write('  Aborted — note was not deleted.\n');
+    return { deleted: false };
+  }
+
   const { deleted } = deleteNoteFn({ external_id: id, tickets: ticketKey ? [ticketKey] : [] }, { configDir });
   stream.write(deleted
     ? `  Deleted note (${id}) — local vault only; see help for team-synced notes.\n`

package/skills/jtb/scripts/lib/recall-vault.mjs

@@ -14,7 +14,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { DEFAULT_CONFIG_DIR, escapeLeadingHeading } from './config.mjs';
+import { DEFAULT_CONFIG_DIR, escapeLeadingHeading, timeAgo } from './config.mjs';
 import { TICKET_KEY_PATTERN } from './cli.mjs';
 import { parseFrontmatter, serializeFrontmatter } from './frontmatter.mjs';
 
@@ -348,7 +348,7 @@ export function rebuildIndex(prefix, { configDir = DEFAULT_CONFIG_DIR } = {}) {
     // content is lower trust than a user's own local notes, so it needs the same
     // heading-injection guard already applied in brief-assembler.mjs/styled-assembler.mjs.
     const ticketList = n.tickets.length > 0 ? ` — ${escapeLeadingHeading(n.tickets.join(', '))}` : '';
-    lines.push(`- [[${escapeLeadingHeading(n.title)}]]${ticketList} — ${n.created.split('T')[0]}`);
+    lines.push(`- [[${escapeLeadingHeading(n.title)}]]${ticketList} — ${timeAgo(n.created)}`);
   }
 
   writeFileAtomically(indexPath, lines.join('\n') + '\n');

package/skills/jtb/scripts/lib/run-collisions.mjs

@@ -71,3 +71,12 @@ export async function runCollisions(args = [], opts = {}) {
     return { ok: false };
   }
 }
+
+// Run if invoked directly
+const isMain = process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/.*\//, ''));
+if (isMain) {
+  runCollisions(process.argv.slice(2)).catch(err => {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/skills/jtb/scripts/lib/styled-assembler.mjs

@@ -115,7 +115,7 @@ export function styleRecallResults(digests, opts = {}) {
   if (!styled) {
     const entries = digests.map(d => {
       const ticketList = d.tickets?.length > 0 ? ` (${escapeLeadingHeading(d.tickets.join(', '))})` : '';
-      const summary = `${escapeLeadingHeading(d.title)}${ticketList} — ${d.created.split('T')[0]}  [${d.id}]`;
+      const summary = `${escapeLeadingHeading(d.title)}${ticketList} — ${timeAgo(d.created)}  [${d.id}]`;
       return full ? `${summary}\n${escapeLeadingHeading(d.body)}` : summary;
     });
     return entries.join(full ? '\n\n' : '\n');
@@ -124,9 +124,9 @@ export function styleRecallResults(digests, opts = {}) {
   const s = createStyler({ forceColor: true });
   const entries = digests.map(d => {
     const ticketList = d.tickets?.length > 0 ? ` ${s.dim(`(${escapeLeadingHeading(d.tickets.join(', '))})`)}` : '';
-    const date = s.dim(d.created.split('T')[0]);
+    const ago = s.dim(timeAgo(d.created));
     const id = s.dim(`[${d.id}]`);
-    const summary = `${s.brand('●')} ${s.bold(escapeLeadingHeading(d.title))}${ticketList} ${s.dim('—')} ${date}  ${id}`;
+    const summary = `${s.brand('●')} ${s.bold(escapeLeadingHeading(d.title))}${ticketList} ${s.dim('—')} ${ago}  ${id}`;
     return full ? `${summary}\n${escapeLeadingHeading(d.body)}` : summary;
   });
   return entries.join(full ? '\n\n' : '\n');

package/skills/jtb/scripts/lib/ticket-command.mjs

@@ -20,11 +20,39 @@ import { readMetadataCache, writeMetadataCache } from './ticket-metadata-cache.m
 import { detectProjectOrTypeError, enrichCreateFailure } from './ticket-create-enrichment.mjs';
 import { TICKET_KEY_PATTERN } from './cli.mjs';
 import { scoreCandidates } from './duplicate-scorer.mjs';
+import { MAX_ATTACHMENTS } from './attachment-uploader.mjs';
 
 function parseFlag(cmdArgs, name) {
   return cmdArgs.find(a => a.startsWith(`--${name}=`))?.slice(name.length + 3);
 }
 
+function parseAttachPaths(cmdArgs) {
+  const raw = parseFlag(cmdArgs, 'attach');
+  return raw ? raw.split(',').map(p => p.trim()).filter(Boolean) : [];
+}
+
+/**
+ * GitHub has no PAT-compatible public API for uploading issue/comment
+ * assets (confirmed via research — the only upload endpoint requires a
+ * browser session, not a token). Refused before the adapter is ever
+ * called, same pattern already used for GitHub's --priority refusal in
+ * ticket_update, rather than silently no-op-ing.
+ */
+function refuseGithubAttachments(adapter, attachPaths, stream) {
+  if (!attachPaths.length || adapter.type !== 'github') return false;
+  stream.write('  Note: GitHub does not support file attachments via the API — no supported way to upload issue/comment assets exists. Continuing without --attach.\n');
+  return true;
+}
+
+function formatAttachSummary(attachResult) {
+  if (!attachResult) return '';
+  const lines = [];
+  for (const u of attachResult.uploaded) lines.push(`  Attached ${u.filename}${u.url ? ` (${u.url})` : ''}\n`);
+  for (const e of attachResult.errors) lines.push(`  Failed to attach ${e.path}: ${e.message}\n`);
+  if (attachResult.droppedCount > 0) lines.push(`  ${attachResult.droppedCount} attachment(s) dropped — exceeds the ${MAX_ATTACHMENTS}-file limit per call.\n`);
+  return lines.join('');
+}
+
 /**
  * Distinguishes retryable/terminal/rate-limited write failures so CLI and
  * MCP callers get the same actionable signal instead of a generic catch —
@@ -205,7 +233,7 @@ export async function runTicketComment(cmdArgs, {
   logActionFn = logAction,
   actor = os.userInfo().username,
 } = {}) {
-  const usage = 'Usage: ticketlens comment TICKET-KEY --body="..."\n';
+  const usage = 'Usage: ticketlens comment TICKET-KEY --body="..." [--attach=path1,path2]\n';
   if (!requireLicense(isLicensedFn, configDir, 'ticketlens comment', stream)) return { ok: false };
 
   const ticketKey = requireTicketKey(cmdArgs, usage, stream);
@@ -216,6 +244,7 @@ export async function runTicketComment(cmdArgs, {
     stream.write(usage);
     return { ok: false };
   }
+  const attachPaths = parseAttachPaths(cmdArgs);
 
   const cooldown = checkCooldownFn(ticketKey, 'comment', { configDir });
   if (cooldown.active) {
@@ -226,14 +255,32 @@ export async function runTicketComment(cmdArgs, {
   const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
   if (!adapter) return { ok: false };
 
+  // Uploaded BEFORE the comment write so a tracker capable of inline
+  // rendering (Jira Server/DC via wiki markup, Jira Cloud via a real ADF
+  // media node, Linear via Markdown) can fold it into the same atomic
+  // comment post rather than needing a second edit call.
+  let attachResult = null;
+  if (attachPaths.length && !refuseGithubAttachments(adapter, attachPaths, stream)) {
+    attachResult = await adapter.attachFiles(ticketKey, attachPaths);
+  }
+  const inlineSnippets = (attachResult?.uploaded ?? []).filter(a => a.inlineMarkup).map(a => a.inlineMarkup).join('\n\n');
+  const finalBody = inlineSnippets ? `${body}\n\n${inlineSnippets}` : body;
+  const extraAdfNodes = (attachResult?.uploaded ?? []).filter(a => a.adfMediaNode).map(a => a.adfMediaNode);
+
   try {
-    const result = await adapter.addComment(ticketKey, body);
+    const result = await adapter.addComment(ticketKey, finalBody, extraAdfNodes.length ? { extraAdfNodes } : {});
     recordActionFn(ticketKey, 'comment', { configDir });
-    logActionFn({ ticketKey, action: 'comment', actor, tracker: adapter.type, detail: { id: result.id } }, { configDir });
-    stream.write(`  Comment posted to ${ticketKey}${result.url ? ` (${result.url})` : ''}\n`);
+    // attachPaths (every path attempted, raw) plus attachedFilenames (what
+    // actually landed) — a partial attach failure is reconstructable from
+    // the difference between the two, not just silently absent from audit.
+    logActionFn({ ticketKey, action: 'comment', actor, tracker: adapter.type, detail: { id: result.id, attachPaths, attachedFilenames: (attachResult?.uploaded ?? []).map(a => a.filename) } }, { configDir });
+    stream.write(`  Comment posted to ${ticketKey}${result.url ? ` (${result.url})` : ''}\n` + formatAttachSummary(attachResult));
     return { ok: true };
   } catch (err) {
-    stream.write(formatWriteFailure(ticketKey, err));
+    // Attachments (if any) genuinely landed on the tracker before this
+    // write was attempted — formatAttachSummary is still shown here so a
+    // caller retrying the whole command doesn't blindly re-upload them.
+    stream.write(formatWriteFailure(ticketKey, err) + formatAttachSummary(attachResult));
     return { ok: false };
   }
 }
@@ -705,9 +752,11 @@ export async function runTicketCreate(cmdArgs, {
   const project = parseFlag(cmdArgs, 'project');
   const type = parseFlag(cmdArgs, 'type');
   const description = parseFlag(cmdArgs, 'description');
+  const attachPaths = parseAttachPaths(cmdArgs);
 
   const adapter = resolveTicketAdapter(undefined, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
   if (!adapter) return { ok: false };
+  const attachRefused = refuseGithubAttachments(adapter, attachPaths, stream);
 
   if (adapter.type !== 'github' && !project) {
     stream.write(`  --project is required for ${adapter.type === 'jira' ? 'Jira (project key)' : 'Linear (team key)'}.\n`);
@@ -758,6 +807,44 @@ export async function runTicketCreate(cmdArgs, {
   } catch (bookkeepingErr) {
     stream.write(`  Warning: ${result.key} was created but could not be logged: ${bookkeepingErr.message}\n`);
   }
-  stream.write(`  Created ${result.key}${result.url ? ` (${result.url})` : ''}\n`);
+
+  // Attachments upload AFTER creation — Jira/Linear both need a real issue
+  // key to attach to (Jira strictly; Linear's fileUpload doesn't, but the
+  // same ordering is kept uniform across trackers for simplicity). The
+  // ticket has already landed, so nothing in this block may ever cause
+  // runTicketCreate to report the create itself as failed — wrapped in its
+  // own try/catch, mirroring the bookkeeping block above.
+  let attachResult = null;
+  if (attachPaths.length && !attachRefused) {
+    try {
+      attachResult = await adapter.attachFiles(result.key, attachPaths);
+
+      // Linear has no separate attachment list on an issue — unlike Jira's
+      // classic attachment (real regardless of description text), an
+      // uploaded Linear asset is only ever associated with the issue by
+      // referencing its URL in a text field. Without this follow-up edit,
+      // the file would be uploaded to Linear's storage but completely
+      // orphaned from the ticket. Best-effort: if this edit fails, the
+      // asset is still genuinely uploaded, just not linked — reported as
+      // an error entry, not a lost/misreported create.
+      const inlineSnippets = attachResult.uploaded.filter(a => a.inlineMarkup).map(a => a.inlineMarkup).join('\n\n');
+      if (inlineSnippets && adapter.type === 'linear') {
+        try {
+          await adapter.updateFields(result.key, { description: description ? `${description}\n\n${inlineSnippets}` : inlineSnippets });
+        } catch (linkErr) {
+          attachResult = { ...attachResult, errors: [...attachResult.errors, { path: '(description update)', message: `uploaded but failed to link into the ticket description: ${linkErr.message}` }] };
+        }
+      }
+
+      try {
+        logActionFn({ ticketKey: result.key, action: 'create', actor, tracker: adapter.type, detail: { attachPaths, attachedFilenames: attachResult.uploaded.map(a => a.filename) } }, { configDir });
+      } catch { /* best-effort, same as the primary bookkeeping above */ }
+    } catch (attachErr) {
+      stream.write(`  Warning: ${result.key} was created but attaching files failed: ${attachErr.message}\n`);
+      attachResult = null;
+    }
+  }
+
+  stream.write(`  Created ${result.key}${result.url ? ` (${result.url})` : ''}\n` + formatAttachSummary(attachResult));
   return { ok: true, key: result.key };
 }