@gethmy/mcp 2.18.0 → 2.20.0

package/dist/cli.js

@@ -3644,6 +3644,43 @@ async function putToSignedUrl(uploadUrl, bytes, contentType) {
     throw new Error(`Direct storage upload failed: ${res.status}${detail ? ` — ${detail}` : ""}`);
   }
 }
+async function attachFileToCard(client3, cardId, file) {
+  const { filePath, base64Data, fileName, contentType } = file;
+  if (filePath && base64Data) {
+    throw new Error("Provide either filePath or base64Data, not both.");
+  }
+  if (filePath) {
+    const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
+    const resolvedName = fileName || basename(filePath);
+    const signed = await client3.requestCardAttachmentUploadUrl(cardId, {
+      fileName: resolvedName,
+      fileType: contentType,
+      size: bytes.byteLength
+    });
+    await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
+    return await client3.finalizeCardAttachment(cardId, {
+      storagePath: signed.storagePath,
+      fileName: resolvedName,
+      fileType: contentType || signed.fileType,
+      sha256: sha256Hex(bytes),
+      size: bytes.byteLength
+    });
+  }
+  if (base64Data) {
+    if (!fileName) {
+      throw new Error("fileName is required when using base64Data.");
+    }
+    if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+      throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
+    }
+    return await client3.uploadCardAttachment(cardId, {
+      fileName,
+      data: base64Data,
+      fileType: contentType
+    });
+  }
+  throw new Error("Provide either filePath or base64Data.");
+}
 var memorySessions = new Map;
 function parseLabelList(raw) {
   if (raw === undefined || raw === null)
@@ -3800,7 +3837,7 @@ function cleanupMemorySession(cardId) {
 }
 var TOOLS = {
   harmony_create_card: {
-    description: "Create a new card in a Kanban column",
+    description: "Create a new card in a Kanban column. Optionally attach reference files " + "(e.g. a screenshot from the prompt) at creation time via `attachments` — " + "the card is created first, then each file is uploaded to it.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3823,6 +3860,31 @@ var TOOLS = {
         planId: {
           type: "string",
           description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
+        },
+        attachments: {
+          type: "array",
+          description: "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " + "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " + "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " + "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " + "harness has written it to a local file you can pass as filePath — a model cannot re-emit " + "pasted image bytes into base64Data. Per-file failures never block card creation; they are " + "reported back in the result's `attachments` array so you can retry via harmony_upload.",
+          items: {
+            type: "object",
+            properties: {
+              filePath: {
+                type: "string",
+                description: "Absolute path to a local file the server can read. Mutually exclusive with base64Data."
+              },
+              base64Data: {
+                type: "string",
+                description: "Base64-encoded bytes (a `data:` URL prefix is accepted and stripped). Requires fileName. Mutually exclusive with filePath."
+              },
+              fileName: {
+                type: "string",
+                description: "File name including extension (required with base64Data; else defaults to the filePath basename)."
+              },
+              contentType: {
+                type: "string",
+                description: "Optional MIME type (inferred from the extension when omitted)."
+              }
+            }
+          }
         }
       },
       required: ["title"]
@@ -5637,6 +5699,12 @@ async function handleToolCall(name, args, deps) {
     case "harmony_create_card": {
       const title = z.string().min(1).max(500).parse(args.title);
       const projectId = args.projectId || getProjectId();
+      const attachments = args.attachments != null ? z.array(z.object({
+        filePath: z.string().optional(),
+        base64Data: z.string().optional(),
+        fileName: z.string().optional(),
+        contentType: z.string().optional()
+      })).parse(args.attachments) : [];
       const result = await client3.createCard(projectId, {
         title,
         columnId: args.columnId,
@@ -5645,7 +5713,30 @@ async function handleToolCall(name, args, deps) {
         assigneeId: args.assigneeId,
         planId: args.planId
       });
-      return { success: true, ...result };
+      if (attachments.length === 0) {
+        return { success: true, ...result };
+      }
+      const cardId = result.card?.id;
+      if (!cardId) {
+        return {
+          success: true,
+          ...result,
+          attachmentWarning: "Card created, but attachments were skipped: no card id was returned to upload against."
+        };
+      }
+      const attachmentResults = await Promise.all(attachments.map(async (file) => {
+        try {
+          const uploaded = await attachFileToCard(client3, cardId, file);
+          return { ok: true, attachment: uploaded.attachment };
+        } catch (err) {
+          return {
+            ok: false,
+            fileName: file.fileName ?? file.filePath ?? "(unnamed)",
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+      }));
+      return { success: true, ...result, attachments: attachmentResults };
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -5931,37 +6022,12 @@ ${list}
         const cardId2 = z.string().uuid().parse(args.cardId);
         const fileName = args.fileName != null ? z.string().parse(args.fileName) : undefined;
         const contentType = args.contentType != null ? z.string().parse(args.contentType) : undefined;
-        if (filePath) {
-          const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
-          const resolvedName = fileName || basename(filePath);
-          const signed = await client3.requestCardAttachmentUploadUrl(cardId2, {
-            fileName: resolvedName,
-            fileType: contentType,
-            size: bytes.byteLength
-          });
-          await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
-          return await client3.finalizeCardAttachment(cardId2, {
-            storagePath: signed.storagePath,
-            fileName: resolvedName,
-            fileType: contentType || signed.fileType,
-            sha256: sha256Hex(bytes),
-            size: bytes.byteLength
-          });
-        }
-        if (base64Data) {
-          if (!fileName) {
-            throw new Error("fileName is required when using base64Data.");
-          }
-          if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
-            throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
-          }
-          return await client3.uploadCardAttachment(cardId2, {
-            fileName,
-            data: base64Data,
-            fileType: contentType
-          });
-        }
-        throw new Error("Provide either filePath or base64Data.");
+        return await attachFileToCard(client3, cardId2, {
+          filePath,
+          base64Data,
+          fileName,
+          contentType
+        });
       }
       const title = args.title != null ? z.string().parse(args.title) : undefined;
       const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
@@ -7261,7 +7327,7 @@ import {
 } from "node:fs";
 import { homedir as homedir6 } from "node:os";
 import { dirname as dirname3, join as join8 } from "node:path";
-import * as p3 from "@clack/prompts";
+import * as p4 from "@clack/prompts";
 init_config();
 init_oauth_login();
 
@@ -7319,10 +7385,21 @@ function detectAgents(cwd = process.cwd()) {
   });
 }
 
+// src/tui/confirm.ts
+import * as p from "@clack/prompts";
+function shouldAssumeYes(yesFlag, isTTY) {
+  return yesFlag === true || isTTY !== true;
+}
+async function confirmOrDefault(assumeYes, opts) {
+  if (assumeYes)
+    return opts.initialValue ?? true;
+  return p.confirm(opts);
+}
+
 // src/tui/docs.ts
 import { existsSync as existsSync6, readdirSync as readdirSync2, readFileSync as readFileSync5, statSync as statSync2 } from "node:fs";
 import { isAbsolute, join as join7, resolve, sep as sep2 } from "node:path";
-import * as p from "@clack/prompts";
+import * as p2 from "@clack/prompts";
 
 // src/tui/theme.ts
 import pc from "picocolors";
@@ -7970,11 +8047,11 @@ async function runDocsStep(cwd) {
   const info = scanProject(cwd);
   const hasDocs = info.existingDocs.agentsMd || info.existingDocs.claudeMd;
   if (!hasDocs) {
-    const shouldGenerate = await p.confirm({
+    const shouldGenerate = await p2.confirm({
       message: "No project docs found. Generate AGENTS.md and CLAUDE.md?",
       initialValue: true
     });
-    if (p.isCancel(shouldGenerate) || !shouldGenerate) {
+    if (p2.isCancel(shouldGenerate) || !shouldGenerate) {
       return { files: [], issues: [], skipped: true };
     }
     const files = [];
@@ -7995,32 +8072,32 @@ async function runDocsStep(cwd) {
         type: "text"
       });
     }
-    p.log.success(`Generated ${files.length} doc file(s): ${files.map((f) => f.path.replace(cwd + "/", "")).join(", ")}`);
+    p2.log.success(`Generated ${files.length} doc file(s): ${files.map((f) => f.path.replace(cwd + "/", "")).join(", ")}`);
     return { files, issues: [], skipped: false };
   }
-  const shouldVerify = await p.confirm({
+  const shouldVerify = await p2.confirm({
     message: "Project docs found. Verify for issues?",
     initialValue: false
   });
-  if (p.isCancel(shouldVerify) || !shouldVerify) {
+  if (p2.isCancel(shouldVerify) || !shouldVerify) {
     return { files: [], issues: [], skipped: true };
   }
   const issues = verifyDocs(cwd);
   if (issues.length === 0) {
-    p.log.success("No issues found in project docs.");
+    p2.log.success("No issues found in project docs.");
   } else {
     for (const issue of issues) {
       const prefix = `${colors.bold(issue.file)}:`;
       if (issue.severity === "error") {
-        p.log.error(`${prefix} ${issue.message}`);
+        p2.log.error(`${prefix} ${issue.message}`);
       } else {
-        p.log.warning(`${prefix} ${issue.message}`);
+        p2.log.warning(`${prefix} ${issue.message}`);
       }
       if (issue.fix) {
-        p.log.message(`  ${symbols.arrow} ${colors.dim(issue.fix)}`);
+        p2.log.message(`  ${symbols.arrow} ${colors.dim(issue.fix)}`);
       }
     }
-    p.log.info(`Found ${issues.length} issue(s) (${issues.filter((i) => i.severity === "error").length} errors, ${issues.filter((i) => i.severity === "warning").length} warnings)`);
+    p2.log.info(`Found ${issues.length} issue(s) (${issues.filter((i) => i.severity === "error").length} errors, ${issues.filter((i) => i.severity === "warning").length} warnings)`);
   }
   return { files: [], issues, skipped: false };
 }
@@ -8035,7 +8112,7 @@ import {
 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
 import { dirname as dirname2 } from "node:path";
-import * as p2 from "@clack/prompts";
+import * as p3 from "@clack/prompts";
 function ensureDir(dirPath) {
   if (!existsSync7(dirPath)) {
     mkdirSync4(dirPath, { recursive: true, mode: 493 });
@@ -8155,7 +8232,7 @@ function appendToToml(filePath, section, content, options = {}) {
 async function writeFilesWithProgress(files, options = {}) {
   const results = [];
   const home = homedir5();
-  const spinner2 = p2.spinner();
+  const spinner2 = p3.spinner();
   spinner2.start("Writing configuration files...");
   for (const file of files) {
     let result;
@@ -8647,6 +8724,10 @@ async function runSetup(options = {}) {
   const home = homedir6();
   console.clear();
   console.log(messages.header());
+  const assumeYes = shouldAssumeYes(options.yes, process.stdin.isTTY);
+  if (assumeYes) {
+    p4.log.info(options.yes ? "Non-interactive mode (--yes): using the default answer for each confirmation." : "No interactive terminal detected: using the default answer for each confirmation.");
+  }
   const existingConfig = loadConfig();
   const alreadyConfigured = isConfigured();
   const skillsStatus = areSkillsInstalled(cwd);
@@ -8666,7 +8747,7 @@ async function runSetup(options = {}) {
   let createdNewAccount = false;
   let oauthTokens;
   if (options.apiKey) {
-    p3.log.warn(colors.warning(`--api-key is deprecated and insecure: the key is exposed in your shell
+    p4.log.warn(colors.warning(`--api-key is deprecated and insecure: the key is exposed in your shell
 history, terminal scrollback, and the process list. Prefer the browser
 sign-in (run \`npx @gethmy/mcp setup\` with no --api-key). Use --api-key
 only for unattended CI where you accept that risk.`));
@@ -8677,7 +8758,7 @@ only for unattended CI where you accept that risk.`));
     if (!useNewAccount && options.apiKey) {
       useNewAccount = false;
     } else if (!useNewAccount && !options.apiKey) {
-      const getStarted = await p3.select({
+      const getStarted = await p4.select({
         message: "How would you like to connect?",
         options: [
           {
@@ -8698,15 +8779,15 @@ only for unattended CI where you accept that risk.`));
         ],
         initialValue: "browser"
       });
-      if (p3.isCancel(getStarted)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(getStarted)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
       useNewAccount = getStarted === "create";
       useBrowserAuth = getStarted === "browser";
     }
     if (useBrowserAuth) {
-      const spinner4 = p3.spinner();
+      const spinner4 = p4.spinner();
       spinner4.start("Opening your browser to authorize…");
       try {
         oauthTokens = await loginWithBrowser({
@@ -8731,12 +8812,12 @@ ${colors.dim(url)}`);
       } catch (error) {
         spinner4.stop(colors.error("Browser authorization failed"));
         const msg = error instanceof Error ? error.message : "Unknown error";
-        p3.log.error(msg);
-        p3.log.info("You can retry, or run with --api-key for unattended setup.");
+        p4.log.error(msg);
+        p4.log.info("You can retry, or run with --api-key for unattended setup.");
         process.exit(1);
       }
     } else if (useNewAccount) {
-      const fullName = options.name || await p3.text({
+      const fullName = options.name || await p4.text({
         message: "Full name",
         placeholder: "Jane Smith",
         validate: (v) => {
@@ -8747,11 +8828,11 @@ ${colors.dim(url)}`);
           return;
         }
       });
-      if (p3.isCancel(fullName)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(fullName)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
-      const email = options.userEmail || await p3.text({
+      const email = options.userEmail || await p4.text({
         message: "Email",
         placeholder: "you@example.com",
         validate: (v) => {
@@ -8764,11 +8845,11 @@ ${colors.dim(url)}`);
           return;
         }
       });
-      if (p3.isCancel(email)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(email)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
-      const password2 = await p3.password({
+      const password2 = await p4.password({
         message: "Password",
         validate: (v) => {
           if (!v)
@@ -8780,11 +8861,11 @@ ${colors.dim(url)}`);
           return;
         }
       });
-      if (p3.isCancel(password2)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(password2)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
-      const spinner4 = p3.spinner();
+      const spinner4 = p4.spinner();
       spinner4.start("Creating your account...");
       try {
         const result = await onboardNewUser({
@@ -8804,15 +8885,15 @@ ${colors.dim(url)}`);
         saveConfig({ apiKey, userEmail, apiUrl: API_URL });
         setActiveWorkspace(selectedWorkspaceIdFromSignup);
         setActiveProject(selectedProjectIdFromSignup);
-        p3.log.success("Workspace and board created");
+        p4.log.success("Workspace and board created");
       } catch (error) {
         spinner4.stop(colors.error("Account creation failed"));
         const msg = error instanceof Error ? error.message : "Unknown error";
         if (msg.includes("already") || msg.includes("409")) {
-          p3.log.error("Account already exists. Sign in at app.gethmy.com to get your API key, or re-run setup and choose 'I already have an API key'.");
+          p4.log.error("Account already exists. Sign in at app.gethmy.com to get your API key, or re-run setup and choose 'I already have an API key'.");
         } else {
-          p3.log.error(msg);
-          p3.log.info("Please try again or visit https://app.gethmy.com");
+          p4.log.error(msg);
+          p4.log.info("Please try again or visit https://app.gethmy.com");
         }
         process.exit(1);
       }
@@ -8820,7 +8901,7 @@ ${colors.dim(url)}`);
       apiKey = options.apiKey;
       needsApiKey = true;
     } else {
-      const keyInput = await p3.text({
+      const keyInput = await p4.text({
         message: "Enter your Harmony API key",
         placeholder: "hmy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
         validate: (value) => {
@@ -8833,24 +8914,24 @@ ${colors.dim(url)}`);
           return;
         }
       });
-      if (p3.isCancel(keyInput)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(keyInput)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
       apiKey = keyInput;
       needsApiKey = true;
     }
   } else {
-    p3.log.success(`Using existing API key: ${apiKey.slice(0, 8)}...`);
+    p4.log.success(`Using existing API key: ${apiKey.slice(0, 8)}...`);
   }
-  const spinner3 = p3.spinner();
+  const spinner3 = p4.spinner();
   if (!createdNewAccount) {
     spinner3.start("Validating API key...");
     const validation = await validateApiKey(apiKey);
     if (!validation.valid) {
       spinner3.stop(colors.error("API key validation failed"));
-      p3.log.error(validation.error || "Could not connect to Harmony API");
-      p3.log.info("Get an API key at: https://app.gethmy.com/user/keys");
+      p4.log.error(validation.error || "Could not connect to Harmony API");
+      p4.log.info("Get an API key at: https://app.gethmy.com/user/keys");
       process.exit(1);
     }
     if (!userEmail) {
@@ -8861,13 +8942,13 @@ ${colors.dim(url)}`);
   let selectedAgents = [];
   let installMode = options.installMode || "global";
   if (skillsStatus.installed && !options.force) {
-    p3.log.success(`Skills already installed (${skillsStatus.location})`);
-    const reinstall = await p3.confirm({
+    p4.log.success(`Skills already installed (${skillsStatus.location})`);
+    const reinstall = await confirmOrDefault(assumeYes, {
       message: "Reinstall skills?",
       initialValue: false
     });
-    if (p3.isCancel(reinstall)) {
-      p3.cancel("Setup cancelled");
+    if (p4.isCancel(reinstall)) {
+      p4.cancel("Setup cancelled");
       process.exit(0);
     }
     needsSkills = reinstall;
@@ -8882,23 +8963,23 @@ ${colors.dim(url)}`);
         label: agent.name,
         hint: agent.detected ? colors.success(`${agent.description} (detected)`) : colors.dim(`${agent.description}`)
       }));
-      const agentSelection = await p3.multiselect({
+      const agentSelection = await p4.multiselect({
         message: "Select agents to configure",
         options: agentOptions,
         initialValues: detectedAgents2.filter((a) => a.detected).map((a) => a.id),
         required: true
       });
-      if (p3.isCancel(agentSelection)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(agentSelection)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
       selectedAgents = agentSelection;
     }
     if (selectedAgents.length === 0) {
-      p3.log.warning("No agents selected. Skipping skills installation.");
+      p4.log.warning("No agents selected. Skipping skills installation.");
       needsSkills = false;
     } else if (!options.installMode) {
-      const modeSelection = await p3.select({
+      const modeSelection = await p4.select({
         message: "Where should Harmony skills be installed?",
         options: [
           {
@@ -8914,8 +8995,8 @@ ${colors.dim(url)}`);
         ],
         initialValue: "global"
       });
-      if (p3.isCancel(modeSelection)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(modeSelection)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
       installMode = modeSelection;
@@ -8939,7 +9020,7 @@ ${colors.dim(url)}`);
         spinner3.stop(colors.warning(`Slug "${options.projectSlug}" is ambiguous — it exists in multiple workspaces`));
         const list = resolved.candidates.map((c) => `  • ${c.workspaceName ?? c.workspaceId}`).join(`
 `);
-        p3.log.warning(`"${options.projectSlug}" matches projects in multiple workspaces:
+        p4.log.warning(`"${options.projectSlug}" matches projects in multiple workspaces:
 ${list}
 Specify the workspace with --workspace <id>, or select one below.`);
       } else {
@@ -8960,7 +9041,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
       spinner3.stop(colors.success(`Found ${workspaces.length} workspace(s)`));
     } catch (_error) {
       spinner3.stop(colors.warning("Could not fetch workspaces"));
-      p3.log.warning("Skipping workspace/project selection. You can set this later.");
+      p4.log.warning("Skipping workspace/project selection. You can set this later.");
       needsContext = false;
     }
     if (needsContext && workspaces.length > 0) {
@@ -8972,12 +9053,12 @@ Specify the workspace with --workspace <id>, or select one below.`);
           value: ws.id,
           label: ws.name
         }));
-        const workspaceSelection = await p3.select({
+        const workspaceSelection = await p4.select({
           message: candidateIds.size > 0 ? `Select workspace for "${options.projectSlug}"` : "Select workspace",
           options: workspaceOptions
         });
-        if (p3.isCancel(workspaceSelection)) {
-          p3.cancel("Setup cancelled");
+        if (p4.isCancel(workspaceSelection)) {
+          p4.cancel("Setup cancelled");
           process.exit(0);
         }
         selectedWorkspaceId = workspaceSelection;
@@ -8996,7 +9077,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
         spinner3.stop(colors.success(`Found ${projects.length} project(s)`));
       } catch (_error) {
         spinner3.stop(colors.warning("Could not fetch projects"));
-        p3.log.warning("Skipping project selection. You can set this later.");
+        p4.log.warning("Skipping project selection. You can set this later.");
       }
       if (projects.length > 0 && !selectedProjectId) {
         const projectOptions = projects.map((proj) => ({
@@ -9004,18 +9085,18 @@ Specify the workspace with --workspace <id>, or select one below.`);
           label: proj.name,
           hint: proj.description ? colors.dim(proj.description.slice(0, 50)) : undefined
         }));
-        const projectSelection = await p3.select({
+        const projectSelection = await p4.select({
           message: "Select project",
           options: projectOptions
         });
-        if (p3.isCancel(projectSelection)) {
-          p3.cancel("Setup cancelled");
+        if (p4.isCancel(projectSelection)) {
+          p4.cancel("Setup cancelled");
           process.exit(0);
         }
         selectedProjectId = projectSelection;
-        selectedProjectName = projects.find((p4) => p4.id === selectedProjectId)?.name;
+        selectedProjectName = projects.find((p5) => p5.id === selectedProjectId)?.name;
       } else if (selectedProjectId && !selectedProjectName) {
-        selectedProjectName = projects.find((p4) => p4.id === selectedProjectId)?.name;
+        selectedProjectName = projects.find((p5) => p5.id === selectedProjectId)?.name;
       }
     }
   }
@@ -9062,7 +9143,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
   }
   const detectedAgents = detectAgents(cwd);
   console.log("");
-  p3.log.step("Summary");
+  p4.log.step("Summary");
   console.log("");
   if (oauthTokens) {
     console.log(`  ${colors.bold("Credential:")} Browser sign-in (OAuth, workspace-scoped)`);
@@ -9118,12 +9199,12 @@ Specify the workspace with --workspace <id>, or select one below.`);
     }
   }
   console.log("");
-  const shouldProceed = await p3.confirm({
+  const shouldProceed = await confirmOrDefault(assumeYes, {
     message: "Proceed with setup?",
     initialValue: true
   });
-  if (p3.isCancel(shouldProceed) || !shouldProceed) {
-    p3.cancel("Setup cancelled");
+  if (p4.isCancel(shouldProceed) || !shouldProceed) {
+    p4.cancel("Setup cancelled");
     process.exit(0);
   }
   console.log("");
@@ -9153,7 +9234,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
         }
         symlinkSync(symlink.target, symlink.link);
       } catch {
-        p3.log.warning(`Failed to create symlink: ${symlink.link}`);
+        p4.log.warning(`Failed to create symlink: ${symlink.link}`);
       }
     }
   }
@@ -9167,16 +9248,19 @@ Specify the workspace with --workspace <id>, or select one below.`);
         await writeMcpConfigFallback(home);
         console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join8(home, ".claude", "settings.json"), home))} ${colors.dim("(updated)")}`);
       } catch {
-        p3.log.warning("Could not register MCP server. Run manually: claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve");
+        p4.log.warning("Could not register MCP server. Run manually: claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve");
       }
     }
   }
   if (claudeDetected || selectedAgents.includes("claude")) {
     const allowAll = options.allowAllTools === true;
     const message = allowAll ? "Allowlist EVERY Harmony tool without confirmation, including destructive ones (delete/archive/api-key/invite)?" : "Allowlist common Harmony tools (reads + create/update/move/comment) so /hmy doesn't prompt each time? Destructive tools (delete/archive/api-key/invite) will still ask.";
-    const allowTools = await p3.confirm({ message, initialValue: true });
-    if (p3.isCancel(allowTools)) {
-      p3.cancel("Setup cancelled.");
+    const allowTools = await confirmOrDefault(assumeYes, {
+      message,
+      initialValue: true
+    });
+    if (p4.isCancel(allowTools)) {
+      p4.cancel("Setup cancelled.");
       process.exit(0);
     }
     if (allowTools) {
@@ -9185,7 +9269,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
         const scope = allowAll ? "all tools" : "safe tools";
         console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join8(home, ".claude", "settings.json"), home))} ${colors.dim(result === "added" ? `(${scope} allowlisted)` : `(${scope} already allowlisted)`)}`);
       } catch {
-        p3.log.warning("Could not allowlist Harmony tools. Run /permissions in Claude Code and choose “always allow” for Harmony, or add mcp__harmony to permissions.allow in ~/.claude/settings.json.");
+        p4.log.warning("Could not allowlist Harmony tools. Run /permissions in Claude Code and choose “always allow” for Harmony, or add mcp__harmony to permissions.allow in ~/.claude/settings.json.");
       }
     } else {
       console.log(`  ${colors.dim("Skipped tool allowlist — you'll be prompted per tool, or run /permissions in Claude Code later.")}`);
@@ -9205,7 +9289,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
       setActiveProject(selectedProjectId);
   }
   console.log("");
-  p3.outro(colors.success("Setup complete!"));
+  p4.outro(colors.success("Setup complete!"));
   if (createdNewAccount && selectedWorkspaceNameFromSignup) {
     const wsSlug = selectedWorkspaceNameFromSignup.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
     const projSlug = (selectedProjectNameFromSignup || "my-first-board").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
@@ -9338,7 +9422,7 @@ program.command("reset").description("Remove stored configuration").action(() =>
   console.log(`
 To reconfigure, run: npx @gethmy/mcp setup`);
 });
-program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "DEPRECATED (insecure: key leaks via argv/shell history). For unattended CI only — interactive setup uses browser sign-in.").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").option("--allow-all-tools", "Allowlist every Harmony tool (incl. destructive: delete/archive/api-key/invite) without confirmation. Default allowlists only read + routine-write tools; destructive tools keep prompting.").action(async (slug, options) => {
+program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "DEPRECATED (insecure: key leaks via argv/shell history). For unattended CI only — interactive setup uses browser sign-in.").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("-y, --yes", "Non-interactive: answer every yes/no confirmation with its default. Implied when there is no TTY (pipe / coding agent / CI). Provide the other inputs via flags (--api-key, --agents, --workspace/--project or --skip-context, --skip-docs).").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").option("--allow-all-tools", "Allowlist every Harmony tool (incl. destructive: delete/archive/api-key/invite) without confirmation. Default allowlists only read + routine-write tools; destructive tools keep prompting.").action(async (slug, options) => {
   await runSetup({
     force: options.force,
     apiKey: options.apiKey,
@@ -9352,7 +9436,8 @@ program.command("setup").description("Smart setup wizard for Harmony MCP (recomm
     skipDocs: options.skipDocs,
     newAccount: options.new,
     name: options.name,
-    allowAllTools: options.allowAllTools
+    allowAllTools: options.allowAllTools,
+    yes: options.yes
   });
 });
 program.parse();

package/dist/index.js

@@ -3639,6 +3639,43 @@ async function putToSignedUrl(uploadUrl, bytes, contentType) {
     throw new Error(`Direct storage upload failed: ${res.status}${detail ? ` — ${detail}` : ""}`);
   }
 }
+async function attachFileToCard(client3, cardId, file) {
+  const { filePath, base64Data, fileName, contentType } = file;
+  if (filePath && base64Data) {
+    throw new Error("Provide either filePath or base64Data, not both.");
+  }
+  if (filePath) {
+    const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
+    const resolvedName = fileName || basename(filePath);
+    const signed = await client3.requestCardAttachmentUploadUrl(cardId, {
+      fileName: resolvedName,
+      fileType: contentType,
+      size: bytes.byteLength
+    });
+    await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
+    return await client3.finalizeCardAttachment(cardId, {
+      storagePath: signed.storagePath,
+      fileName: resolvedName,
+      fileType: contentType || signed.fileType,
+      sha256: sha256Hex(bytes),
+      size: bytes.byteLength
+    });
+  }
+  if (base64Data) {
+    if (!fileName) {
+      throw new Error("fileName is required when using base64Data.");
+    }
+    if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+      throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
+    }
+    return await client3.uploadCardAttachment(cardId, {
+      fileName,
+      data: base64Data,
+      fileType: contentType
+    });
+  }
+  throw new Error("Provide either filePath or base64Data.");
+}
 var memorySessions = new Map;
 function parseLabelList(raw) {
   if (raw === undefined || raw === null)
@@ -3795,7 +3832,7 @@ function cleanupMemorySession(cardId) {
 }
 var TOOLS = {
   harmony_create_card: {
-    description: "Create a new card in a Kanban column",
+    description: "Create a new card in a Kanban column. Optionally attach reference files " + "(e.g. a screenshot from the prompt) at creation time via `attachments` — " + "the card is created first, then each file is uploaded to it.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3818,6 +3855,31 @@ var TOOLS = {
         planId: {
           type: "string",
           description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
+        },
+        attachments: {
+          type: "array",
+          description: "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " + "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " + "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " + "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " + "harness has written it to a local file you can pass as filePath — a model cannot re-emit " + "pasted image bytes into base64Data. Per-file failures never block card creation; they are " + "reported back in the result's `attachments` array so you can retry via harmony_upload.",
+          items: {
+            type: "object",
+            properties: {
+              filePath: {
+                type: "string",
+                description: "Absolute path to a local file the server can read. Mutually exclusive with base64Data."
+              },
+              base64Data: {
+                type: "string",
+                description: "Base64-encoded bytes (a `data:` URL prefix is accepted and stripped). Requires fileName. Mutually exclusive with filePath."
+              },
+              fileName: {
+                type: "string",
+                description: "File name including extension (required with base64Data; else defaults to the filePath basename)."
+              },
+              contentType: {
+                type: "string",
+                description: "Optional MIME type (inferred from the extension when omitted)."
+              }
+            }
+          }
         }
       },
       required: ["title"]
@@ -5632,6 +5694,12 @@ async function handleToolCall(name, args, deps) {
     case "harmony_create_card": {
       const title = z.string().min(1).max(500).parse(args.title);
       const projectId = args.projectId || getProjectId();
+      const attachments = args.attachments != null ? z.array(z.object({
+        filePath: z.string().optional(),
+        base64Data: z.string().optional(),
+        fileName: z.string().optional(),
+        contentType: z.string().optional()
+      })).parse(args.attachments) : [];
       const result = await client3.createCard(projectId, {
         title,
         columnId: args.columnId,
@@ -5640,7 +5708,30 @@ async function handleToolCall(name, args, deps) {
         assigneeId: args.assigneeId,
         planId: args.planId
       });
-      return { success: true, ...result };
+      if (attachments.length === 0) {
+        return { success: true, ...result };
+      }
+      const cardId = result.card?.id;
+      if (!cardId) {
+        return {
+          success: true,
+          ...result,
+          attachmentWarning: "Card created, but attachments were skipped: no card id was returned to upload against."
+        };
+      }
+      const attachmentResults = await Promise.all(attachments.map(async (file) => {
+        try {
+          const uploaded = await attachFileToCard(client3, cardId, file);
+          return { ok: true, attachment: uploaded.attachment };
+        } catch (err) {
+          return {
+            ok: false,
+            fileName: file.fileName ?? file.filePath ?? "(unnamed)",
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+      }));
+      return { success: true, ...result, attachments: attachmentResults };
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -5926,37 +6017,12 @@ ${list}
         const cardId2 = z.string().uuid().parse(args.cardId);
         const fileName = args.fileName != null ? z.string().parse(args.fileName) : undefined;
         const contentType = args.contentType != null ? z.string().parse(args.contentType) : undefined;
-        if (filePath) {
-          const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
-          const resolvedName = fileName || basename(filePath);
-          const signed = await client3.requestCardAttachmentUploadUrl(cardId2, {
-            fileName: resolvedName,
-            fileType: contentType,
-            size: bytes.byteLength
-          });
-          await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
-          return await client3.finalizeCardAttachment(cardId2, {
-            storagePath: signed.storagePath,
-            fileName: resolvedName,
-            fileType: contentType || signed.fileType,
-            sha256: sha256Hex(bytes),
-            size: bytes.byteLength
-          });
-        }
-        if (base64Data) {
-          if (!fileName) {
-            throw new Error("fileName is required when using base64Data.");
-          }
-          if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
-            throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
-          }
-          return await client3.uploadCardAttachment(cardId2, {
-            fileName,
-            data: base64Data,
-            fileType: contentType
-          });
-        }
-        throw new Error("Provide either filePath or base64Data.");
+        return await attachFileToCard(client3, cardId2, {
+          filePath,
+          base64Data,
+          fileName,
+          contentType
+        });
       }
       const title = args.title != null ? z.string().parse(args.title) : undefined;
       const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.18.0",
+  "version": "2.20.0",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -64,7 +64,7 @@
     "serve:remote": "bun src/remote.ts",
     "dev": "bun --watch src/index.ts",
     "test": "bun run test:unit && bun run test:integration",
-    "test:unit": "bun test src/__tests__/active-learning.test.ts src/__tests__/context-assembly.test.ts src/__tests__/prompt-builder.test.ts src/__tests__/memory-audit.test.ts src/__tests__/skills.test.ts src/__tests__/hmy-config.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts src/__tests__/auto-session.test.ts",
+    "test:unit": "bun test src/__tests__/active-learning.test.ts src/__tests__/context-assembly.test.ts src/__tests__/prompt-builder.test.ts src/__tests__/memory-audit.test.ts src/__tests__/skills.test.ts src/__tests__/hmy-config.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts src/__tests__/auto-session.test.ts src/__tests__/setup-confirm.test.ts",
     "test:integration": "bun test src/__tests__/integration-memory-system.test.ts src/__tests__/integration-memory-crud.test.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run typecheck && bun run build"

package/src/cli.ts

@@ -167,6 +167,10 @@ program
   .option("-p, --project <id>", "Set project context (UUID)")
   .option("--skip-context", "Skip workspace/project selection")
   .option("--skip-docs", "Skip project docs scaffold/verification")
+  .option(
+    "-y, --yes",
+    "Non-interactive: answer every yes/no confirmation with its default. Implied when there is no TTY (pipe / coding agent / CI). Provide the other inputs via flags (--api-key, --agents, --workspace/--project or --skip-context, --skip-docs).",
+  )
   .option("--new", "Create a new account (skip the choice prompt)")
   .option("-n, --name <name>", "Full name (for account creation)")
   .option(
@@ -192,6 +196,7 @@ program
       newAccount: options.new,
       name: options.name,
       allowAllTools: options.allowAllTools,
+      yes: options.yes,
     });
   });
 

package/src/server.ts

@@ -221,6 +221,80 @@ async function putToSignedUrl(
   }
 }
 
+/** One card-attachment input: bytes as a local `filePath` (preferred — read
+ * direct-to-storage) or a small `base64Data` blob (requires `fileName`). */
+export interface CardAttachmentInput {
+  filePath?: string;
+  base64Data?: string;
+  fileName?: string;
+  contentType?: string;
+}
+
+/**
+ * Attach one file to an existing card, running the same direct-to-storage
+ * handshake as `harmony_upload` `{target:"card_attachment"}`. Extracted so
+ * `harmony_create_card` can attach reference files (e.g. a prompt screenshot)
+ * at creation time without duplicating the orchestration. Requires an existing
+ * `cardId` — attachment upload is inherently a second step after the card row
+ * exists, so the create path calls this only after `createCard` returns.
+ */
+async function attachFileToCard(
+  client: HarmonyApiClient,
+  cardId: string,
+  file: CardAttachmentInput,
+) {
+  const { filePath, base64Data, fileName, contentType } = file;
+  if (filePath && base64Data) {
+    throw new Error("Provide either filePath or base64Data, not both.");
+  }
+
+  if (filePath) {
+    // Server can read the file → upload direct-to-storage via the handshake
+    // (no base64 through the model context or edge-fn body).
+    const bytes = await readFileForUpload(
+      filePath,
+      MAX_ATTACHMENT_SIZE,
+      "attachment",
+    );
+    const resolvedName = fileName || basename(filePath);
+    const signed = await client.requestCardAttachmentUploadUrl(cardId, {
+      fileName: resolvedName,
+      fileType: contentType,
+      size: bytes.byteLength,
+    });
+    await putToSignedUrl(
+      signed.uploadUrl,
+      bytes,
+      contentType || signed.fileType || "application/octet-stream",
+    );
+    return await client.finalizeCardAttachment(cardId, {
+      storagePath: signed.storagePath,
+      fileName: resolvedName,
+      fileType: contentType || signed.fileType,
+      sha256: sha256Hex(bytes),
+      size: bytes.byteLength,
+    });
+  }
+
+  if (base64Data) {
+    if (!fileName) {
+      throw new Error("fileName is required when using base64Data.");
+    }
+    if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+      throw new Error(
+        `File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`,
+      );
+    }
+    return await client.uploadCardAttachment(cardId, {
+      fileName,
+      data: base64Data,
+      fileType: contentType,
+    });
+  }
+
+  throw new Error("Provide either filePath or base64Data.");
+}
+
 /**
  * Dependencies injected into tool handlers.
  * Allows the same handlers to be used by both stdio and remote (HTTP) transports.
@@ -524,7 +598,10 @@ function cleanupMemorySession(cardId: string): void {
 export const TOOLS = {
   // Card operations
   harmony_create_card: {
-    description: "Create a new card in a Kanban column",
+    description:
+      "Create a new card in a Kanban column. Optionally attach reference files " +
+      "(e.g. a screenshot from the prompt) at creation time via `attachments` — " +
+      "the card is created first, then each file is uploaded to it.",
     inputSchema: {
       type: "object",
       properties: {
@@ -550,6 +627,42 @@ export const TOOLS = {
           description:
             "Plan ID to link this card to (optional). Links the card to that plan via its plan_id.",
         },
+        attachments: {
+          type: "array",
+          description:
+            "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " +
+            "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " +
+            "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " +
+            "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " +
+            "harness has written it to a local file you can pass as filePath — a model cannot re-emit " +
+            "pasted image bytes into base64Data. Per-file failures never block card creation; they are " +
+            "reported back in the result's `attachments` array so you can retry via harmony_upload.",
+          items: {
+            type: "object",
+            properties: {
+              filePath: {
+                type: "string",
+                description:
+                  "Absolute path to a local file the server can read. Mutually exclusive with base64Data.",
+              },
+              base64Data: {
+                type: "string",
+                description:
+                  "Base64-encoded bytes (a `data:` URL prefix is accepted and stripped). Requires fileName. Mutually exclusive with filePath.",
+              },
+              fileName: {
+                type: "string",
+                description:
+                  "File name including extension (required with base64Data; else defaults to the filePath basename).",
+              },
+              contentType: {
+                type: "string",
+                description:
+                  "Optional MIME type (inferred from the extension when omitted).",
+              },
+            },
+          },
+        },
       },
       required: ["title"],
     },
@@ -2681,6 +2794,19 @@ async function handleToolCall(
     case "harmony_create_card": {
       const title = z.string().min(1).max(500).parse(args.title);
       const projectId = (args.projectId as string) || getProjectId();
+      const attachments =
+        args.attachments != null
+          ? z
+              .array(
+                z.object({
+                  filePath: z.string().optional(),
+                  base64Data: z.string().optional(),
+                  fileName: z.string().optional(),
+                  contentType: z.string().optional(),
+                }),
+              )
+              .parse(args.attachments)
+          : [];
       const result = await client.createCard(projectId, {
         title,
         columnId: args.columnId as string | undefined,
@@ -2689,7 +2815,40 @@ async function handleToolCall(
         assigneeId: args.assigneeId as string | undefined,
         planId: args.planId as string | undefined,
       });
-      return { success: true, ...result };
+
+      if (attachments.length === 0) {
+        return { success: true, ...result };
+      }
+
+      // Attach reference files (e.g. a prompt screenshot) to the freshly
+      // created card. Attachment upload requires an existing cardId, so this
+      // runs only after createCard returns. A bad attachment must never lose
+      // the card — per-file failures are captured and reported alongside the
+      // successes rather than throwing out the whole create.
+      const cardId = (result.card as { id?: string } | null)?.id;
+      if (!cardId) {
+        return {
+          success: true,
+          ...result,
+          attachmentWarning:
+            "Card created, but attachments were skipped: no card id was returned to upload against.",
+        };
+      }
+      const attachmentResults = await Promise.all(
+        attachments.map(async (file) => {
+          try {
+            const uploaded = await attachFileToCard(client, cardId, file);
+            return { ok: true as const, attachment: uploaded.attachment };
+          } catch (err) {
+            return {
+              ok: false as const,
+              fileName: file.fileName ?? file.filePath ?? "(unnamed)",
+              error: err instanceof Error ? err.message : String(err),
+            };
+          }
+        }),
+      );
+      return { success: true, ...result, attachments: attachmentResults };
     }
 
     case "harmony_update_card": {
@@ -3162,52 +3321,13 @@ async function handleToolCall(
           args.contentType != null
             ? z.string().parse(args.contentType)
             : undefined;
-
-        if (filePath) {
-          // Server can read the file → upload direct-to-storage via the
-          // handshake (no base64 through the model context or edge-fn body).
-          const bytes = await readFileForUpload(
-            filePath,
-            MAX_ATTACHMENT_SIZE,
-            "attachment",
-          );
-          const resolvedName = fileName || basename(filePath);
-          const signed = await client.requestCardAttachmentUploadUrl(cardId, {
-            fileName: resolvedName,
-            fileType: contentType,
-            size: bytes.byteLength,
-          });
-          await putToSignedUrl(
-            signed.uploadUrl,
-            bytes,
-            contentType || signed.fileType || "application/octet-stream",
-          );
-          return await client.finalizeCardAttachment(cardId, {
-            storagePath: signed.storagePath,
-            fileName: resolvedName,
-            fileType: contentType || signed.fileType,
-            sha256: sha256Hex(bytes),
-            size: bytes.byteLength,
-          });
-        }
-
-        if (base64Data) {
-          if (!fileName) {
-            throw new Error("fileName is required when using base64Data.");
-          }
-          if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
-            throw new Error(
-              `File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`,
-            );
-          }
-          return await client.uploadCardAttachment(cardId, {
-            fileName,
-            data: base64Data,
-            fileType: contentType,
-          });
-        }
-
-        throw new Error("Provide either filePath or base64Data.");
+        // Same handshake as the create-card `attachments` path (shared helper).
+        return await attachFileToCard(client, cardId, {
+          filePath,
+          base64Data,
+          fileName,
+          contentType,
+        });
       }
 
       // target === "artifact"

package/src/tui/confirm.ts

@@ -0,0 +1,33 @@
+import * as p from "@clack/prompts";
+
+/**
+ * Whether yes/no confirmations should resolve to their default without
+ * prompting. True when the user passed `--yes`, OR when there is no interactive
+ * terminal on stdin (a pipe, a file, or nothing — how a coding agent or CI runs
+ * commands). In that second case `@clack/prompts` can't read a keypress and the
+ * confirm would otherwise stall or cancel the whole run, so we take the default.
+ *
+ * `isTTY` is `process.stdin.isTTY`, which Node sets to `true` only for a real
+ * TTY and leaves `undefined` otherwise — hence the `!== true` test.
+ */
+export function shouldAssumeYes(
+  yesFlag: boolean | undefined,
+  isTTY: boolean | undefined,
+): boolean {
+  return yesFlag === true || isTTY !== true;
+}
+
+/**
+ * Resolve a confirmation. In non-interactive mode (see {@link shouldAssumeYes})
+ * it returns the prompt's documented default (`initialValue`, or `true` when
+ * unset) instead of blocking on a keypress that will never arrive. Interactive
+ * runs (a human at a TTY, no `--yes`) delegate to `p.confirm` and behave exactly
+ * as before, including returning the cancel symbol on Ctrl-C.
+ */
+export async function confirmOrDefault(
+  assumeYes: boolean,
+  opts: { message: string; initialValue?: boolean },
+): Promise<boolean | symbol> {
+  if (assumeYes) return opts.initialValue ?? true;
+  return p.confirm(opts);
+}

package/src/tui/setup.ts

@@ -26,6 +26,7 @@ import { loginWithBrowser, type OAuthTokens } from "../oauth-login.js";
 import { onboardNewUser } from "../onboard.js";
 import { buildSkillFile, HARMONY_WORKFLOW_PROMPT } from "../skills.js";
 import { type AgentId, detectAgents } from "./agents.js";
+import { confirmOrDefault, shouldAssumeYes } from "./confirm.js";
 import { runDocsStep } from "./docs.js";
 import { colors, formatPath, messages } from "./theme.js";
 import { getWriteSummary, writeFilesWithProgress } from "./writer.js";
@@ -46,6 +47,11 @@ export interface SetupOptions {
   newAccount?: boolean;
   name?: string;
   allowAllTools?: boolean;
+  /**
+   * Answer every yes/no confirmation with its default and skip the prompt.
+   * Also implied when stdin is not a TTY (pipe/agent/CI). See `./confirm.ts`.
+   */
+  yes?: boolean;
 }
 
 /**
@@ -723,6 +729,19 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   console.clear();
   console.log(messages.header());
 
+  // Non-interactive mode: `--yes`, or no TTY (pipe / coding agent / CI). Every
+  // yes/no confirmation below resolves to its default instead of blocking on a
+  // keypress that will never arrive. Selection/text prompts are unaffected —
+  // suppress those with their own flags (--api-key, --agents, --skip-context…).
+  const assumeYes = shouldAssumeYes(options.yes, process.stdin.isTTY);
+  if (assumeYes) {
+    p.log.info(
+      options.yes
+        ? "Non-interactive mode (--yes): using the default answer for each confirmation."
+        : "No interactive terminal detected: using the default answer for each confirmation.",
+    );
+  }
+
   // Check existing configuration
   const existingConfig = loadConfig();
   const alreadyConfigured = isConfigured();
@@ -1005,7 +1024,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   if (skillsStatus.installed && !options.force) {
     p.log.success(`Skills already installed (${skillsStatus.location})`);
 
-    const reinstall = await p.confirm({
+    const reinstall = await confirmOrDefault(assumeYes, {
       message: "Reinstall skills?",
       initialValue: false,
     });
@@ -1397,7 +1416,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   console.log("");
 
   // Step 6: Confirm and execute
-  const shouldProceed = await p.confirm({
+  const shouldProceed = await confirmOrDefault(assumeYes, {
     message: "Proceed with setup?",
     initialValue: true,
   });
@@ -1486,7 +1505,10 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     const message = allowAll
       ? "Allowlist EVERY Harmony tool without confirmation, including destructive ones (delete/archive/api-key/invite)?"
       : "Allowlist common Harmony tools (reads + create/update/move/comment) so /hmy doesn't prompt each time? Destructive tools (delete/archive/api-key/invite) will still ask.";
-    const allowTools = await p.confirm({ message, initialValue: true });
+    const allowTools = await confirmOrDefault(assumeYes, {
+      message,
+      initialValue: true,
+    });
     if (p.isCancel(allowTools)) {
       p.cancel("Setup cancelled.");
       process.exit(0);