trelly 0.2.1 → 0.3.1

package/README.md

@@ -211,29 +211,20 @@ CI runs the same via `bun install --frozen-lockfile`. See `AGENTS.md` for conven
 
 ## Agent skills & plugins
 
-Shipped in the npm package for **end users** — skills plus IDE plugin manifests. Full
-plugin docs: [PLUGIN.md](PLUGIN.md) · Privacy: [PRIVACY.md](PRIVACY.md) ·
-[skills/README.md](skills/README.md).
+The npm package ships agent skills plus plugin manifests, so Claude Code, Cursor,
+and pi agents learn the trelly CLI + MCP conventions automatically.
 
-```bash
-npm install -g trelly
-trelly auth setup && trelly auth login
+Install trelly and log in first (`npm install -g trelly && trelly auth setup && trelly auth login`), then:
 
-pi install npm:trelly
-claude plugin install "$(npm root -g)/trelly"
-./bin/install-cursor-plugin-local.sh   # Cursor local test (copy, not symlink)
+```bash
+claude plugin install "$(npm root -g)/trelly"                    # Claude Code
+"$(npm root -g)/trelly/bin/install-cursor-plugin-local.sh"       # Cursor (copies plugin, then reload window)
+pi install npm:trelly                                            # pi
 ```
 
-MCP-only (no plugin): add `trelly-mcp` to `~/.cursor/mcp.json` — [mcp.example.json](mcp.example.json).
-
-### Marketplace submission
-
-| Platform | Submit |
-|----------|--------|
-| **Cursor** | [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish) → `https://github.com/brandonkramer/trelly` |
-| **Claude Code** | [clau.de/plugin-directory-submission](https://clau.de/plugin-directory-submission) |
+MCP-only (no plugin): add `trelly-mcp` to `~/.cursor/mcp.json` — see [mcp.example.json](mcp.example.json).
 
-Open source (MIT). After Claude listing: `/plugin install trelly@claude-plugins-official`.
+Details: [PLUGIN.md](PLUGIN.md) · [PRIVACY.md](PRIVACY.md) · [skills/README.md](skills/README.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trelly",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "trelly — fast Trello CLI with multi-profile auth, MCP server, and kanban TUI",
   "type": "module",
   "license": "MIT",

package/skills/README.md

@@ -6,8 +6,9 @@ developing this repo.
 
 | Skill | Use when |
 |-------|----------|
-| [trelly](trelly/SKILL.md) | Terminal / bash: `trelly boards list`, auth, attachments, GitHub PR/commit links, `--json` |
-| [trelly-mcp](trelly-mcp/SKILL.md) | IDE agent with MCP wired: tool names, GitHub links via `trello_api`, envelopes, safety |
+| [trelly](trelly/SKILL.md) | Terminal / bash: human card lists, auth, attachments, GitHub links, `--json` |
+| [trelly-mcp](trelly-mcp/SKILL.md) | IDE + MCP: paste `display` from list tools, GitHub links, safety |
+| [trelly-card-display](trelly-card-display.md) | **Required** when user asks to see/list cards (all platforms) |
 
 **One copy of the content:** `skills/trelly/` and `skills/trelly-mcp/` in the installed
 package. Plugins and Pi load from there — you don't maintain separate copies.

package/skills/trelly/SKILL.md

@@ -4,7 +4,8 @@ description: >-
   Operate the trelly Trello CLI (npm trelly; bins trelly/trello): auth setup/login,
   human vs --json output, boards/lists/cards, search, attachments, GitHub PR/commit
   links on cards, trello ui, trello api. Use when the user asks to run trelly/trello
-  commands, link a GitHub PR or commit to a Trello card, or automate Trello with trelly.
+  commands, list or show Trello cards/todos, link a GitHub PR or commit to a card, or
+  automate Trello with trelly.
 ---
 
 # trelly
@@ -12,6 +13,10 @@ description: >-
 Fast Trello CLI (`npm install -g trelly`). **Human Trello-styled output by default**;
 **`--json` for scripts**. Commands: **`trelly`** or **`trello`** (same binary).
 
+> **Showing cards to a user?** Read [trelly-card-display.md](trelly-card-display.md).
+> Pi has no MCP — use **human CLI** (`trelly lists cards LIST_ID` without `--json`)
+> or format per that contract. Never reply with titles-only.
+
 ## Prerequisites
 
 ```bash
@@ -40,6 +45,10 @@ Credentials: `~/.config/trelly/config.json` (migrates from `~/.config/trello-cli
 | Pretty JSON | `--json --pretty` |
 
 - **Scripts:** always `--json` if parsing stdout.
+- **Token cost:** raw `--json` returns full Trello objects (a board list ≈ 10k tokens) — trim with `jq` (e.g. `| jq '.data[] | {id,name}'`) or request fewer fields (`--fields`, `--query "fields=id,name"`).
+- **Showing cards to a human?** See [trelly-card-display.md](trelly-card-display.md).
+  Human CLI (`trelly lists cards LIST_ID`) already matches the contract. With `--json`,
+  slim first: `jq '.data[] | {name, shortUrl, labels: [.labels[] | {name, color}], badges: {comments: .badges.comments, attachments: .badges.attachments, checkItems: .badges.checkItems, checkItemsChecked: .badges.checkItemsChecked}, due, dueComplete}'`.
 - **`--pretty` alone** does not emit JSON; it only indents `--json` output.
 - Errors: red `✗` in human mode; exit code `1`.
 

package/skills/trelly-card-display.md

@@ -0,0 +1,39 @@
+# Card list display contract (all agents)
+
+When the user asks to **see**, **list**, or **show** Trello cards (todo, backlog,
+board, column, "what's on…"), you MUST NOT reply with a plain numbered title list.
+
+## MCP (Cursor, Claude Code, Codex with trelly-mcp)
+
+`trello_list_cards` and `trello_board_cards` return:
+
+- `display` — markdown-v1, ready to paste (linked titles + badges)
+- `data` — slim JSON for automation
+
+**Rule: paste `display` verbatim** (optionally add a heading via `displayHeading`).
+Do not re-summarize `data` into your own format.
+
+Example line:
+
+```text
+1. [Publish module behavior](https://trello.com/c/1jH2UTAu) · 💬 2 · 📎 2
+```
+
+Badge keys (omit when zero): 💬 comments · 📎 attachments · ✓ checked/total · ⏰ due.
+Labels: colored dot + `` `name` `` (🔴 🟠 🟡 🟢 🔵 🟣 ⚫ ⚪).
+
+## CLI / Pi (no MCP)
+
+**Preferred:** human output (no `--json`):
+
+```bash
+trelly lists cards LIST_ID
+```
+
+**If using `--json`:** format with the jq recipe in `skills/trelly/SKILL.md` Output
+contract, or call MCP when available.
+
+## Automation only
+
+Plain `data` / names-only output is OK when the user wants scripts, counts, or IDs —
+not when they asked to **see** the board.

package/skills/trelly-mcp/SKILL.md

@@ -3,7 +3,8 @@ name: trelly-mcp
 description: >-
   Configure and use the trelly MCP stdio server (trello_boards_list,
   trello_card_create, trello_search, trello_api, etc.). Use when wiring Cursor/Claude
-  MCP, linking GitHub PRs/commits to Trello cards from an agent, or choosing MCP vs CLI.
+  MCP, listing or showing Trello cards/todos, linking GitHub PRs/commits, or choosing
+  MCP vs CLI.
 ---
 
 # trelly-mcp
@@ -12,6 +13,34 @@ MCP server for Trello (npm package **trelly**, bin **`trelly-mcp`**). Returns JS
 envelope on every tool: `{ ok, profile, data }` /
 `{ ok: false, error, status?, details? }`. Never uses CLI human/Ink output.
 
+> **Listing cards for a user?** Read [trelly-card-display.md](trelly-card-display.md).
+> **`trello_list_cards` / `trello_board_cards` include `display` — paste it verbatim.**
+
+List/get tools default to lean `fields` (id, name, url, due, …) to keep responses
+token-cheap; pass `fields: "all"` when you need more.
+`trello_list_cards` and `trello_board_cards` include slim `badges`, `labels`, and
+pre-rendered **`display`** (markdown-v1).
+
+## Rendering card lists for humans
+
+**Do not reformat.** When `display` is present, show it to the user unchanged
+(you may prepend context from `displayHeading` or your own board/list title).
+
+MCP tool text also leads with `display`, then JSON — prefer the markdown block.
+
+Manual format (only if `display` missing — e.g. raw `trello_api`):
+
+```
+1. [Publish module behavior](https://trello.com/c/1jH2UTAu) 🔴 `Priority: Highest` · 💬 4 · 📎 2 · ✓ 2/5 · ⏰ Jul 5
+```
+
+- Title → `[name](shortUrl)`. Counts from `badges`: 💬 comments · 📎 attachments · ✓ checkItemsChecked/checkItems.
+- Due: `⏰ Jul 5`, add `(overdue)` if past and not `dueComplete`; `✓` if complete.
+- Labels: colored dot + name in backticks. Trello color → emoji: red 🔴 · orange 🟠 · yellow 🟡 · green/lime 🟢 · blue/sky 🔵 · purple/pink 🟣 · black ⚫ · none ⚪.
+- Custom-field chips (e.g. `Priority: Highest`): fetch defs once via `trello_api` GET
+  `/boards/{boardId}/customFields`, request `customFieldItems` on cards, match
+  `idValue` → option text/color. Skip unless the user wants them — it's an extra call.
+
 ## Setup
 
 ### 1. Auth (CLI, once)
@@ -78,9 +107,9 @@ Starts stdio MCP manually (IDE normally launches `trelly-mcp` itself).
 | `trello_board_create` | Create board |
 | `trello_board_archive` | Close board (reversible) |
 | `trello_board_lists` | Lists on board |
-| `trello_board_cards` | All cards on board |
+| `trello_board_cards` | All cards on board (**returns `display` — paste for users**) |
 | `trello_list_create` | Create list |
-| `trello_list_cards` | Cards in list |
+| `trello_list_cards` | Cards in list (**returns `display` markdown — paste for users**) |
 | `trello_card_get` | Card (`fields` optional) |
 | `trello_card_create` | Create card on list |
 | `trello_card_update` | Update card fields map |

package/src/index.test.ts

@@ -7,6 +7,7 @@ import { customFieldChips } from "./cli/ui/custom-fields.ts";
 import { dueStatus, labelHex, listAccentHex } from "./cli/ui/palette.ts";
 import { isBoard, isCard, isLabel, isList } from "./cli/ui/shapes.ts";
 import { attachmentMime } from "./util/attachment.ts";
+import { formatCardLine, formatCardListMarkdown } from "./util/card-display.ts";
 
 describe("parseKvPairs", () => {
   it("parses key=value pairs", () => {
@@ -124,3 +125,30 @@ describe("ui shapes", () => {
     assert.ok(isBoard(board) && !isBoard(card) && !isBoard(list));
   });
 });
+
+describe("card display markdown", () => {
+  it("formats linked title with labels and non-zero badges only", () => {
+    const line = formatCardLine({
+      name: "Publish module behavior",
+      shortUrl: "https://trello.com/c/1jH2UTAu",
+      labels: [{ name: "Backend", color: "blue" }],
+      badges: { comments: 2, attachments: 2, checkItems: 0, checkItemsChecked: 0 },
+    });
+    assert.match(
+      line,
+      /^\[Publish module behavior\]\(https:\/\/trello\.com\/c\/1jH2UTAu\)/,
+    );
+    assert.match(line, /🔵 `Backend`/);
+    assert.match(line, /💬 2/);
+    assert.match(line, /📎 2/);
+    assert.doesNotMatch(line, /✓/);
+  });
+
+  it("builds numbered list with optional heading", () => {
+    const md = formatCardListMarkdown(
+      [{ name: "A", shortUrl: "https://trello.com/c/a" }],
+      "**To do**",
+    );
+    assert.equal(md, "**To do**\n\n1. [A](https://trello.com/c/a)");
+  });
+});

package/src/mcp/handlers.ts

@@ -2,11 +2,19 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { type JsonValue, type TrelloClient, TrelloError } from "../api/client.ts";
 import { getClient } from "../cli/context.ts";
+import {
+  CARD_LIST_DISPLAY_FORMAT,
+  type CardDisplayInput,
+  formatCardListMarkdown,
+} from "../util/card-display.ts";
 
 export const toolEnvelopeSchema = z.object({
   ok: z.boolean(),
   profile: z.string().optional(),
   data: z.unknown().optional(),
+  /** Pre-rendered markdown card list — agents MUST show this to users when present. */
+  display: z.string().optional(),
+  displayFormat: z.string().optional(),
   error: z.string().optional(),
   status: z.number().optional(),
   details: z.unknown().optional(),
@@ -17,13 +25,104 @@ export type ToolEnvelope = z.infer<typeof toolEnvelopeSchema>;
 export const profileField = z.string().optional().describe("Auth profile name");
 
 export function toolResult(envelope: ToolEnvelope): CallToolResult {
+  const text =
+    envelope.display && envelope.ok
+      ? `${envelope.display}\n\n---\n${JSON.stringify(envelope)}`
+      : JSON.stringify(envelope);
   return {
     structuredContent: envelope,
-    content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+    content: [{ type: "text", text }],
     isError: envelope.ok === false,
   };
 }
 
+/** Attach markdown-v1 card list for agent display (see skills/trelly-mcp). */
+export function cardListDisplay(
+  cards: CardDisplayInput[],
+  heading?: string,
+): Pick<ToolEnvelope, "display" | "displayFormat"> {
+  if (cards.length === 0) {
+    return {
+      display: heading ? `${heading}\n\n(no cards)` : "(no cards)",
+      displayFormat: CARD_LIST_DISPLAY_FORMAT,
+    };
+  }
+  return {
+    display: formatCardListMarkdown(cards, heading),
+    displayFormat: CARD_LIST_DISPLAY_FORMAT,
+  };
+}
+
+// Trello's badges object is ~400 chars of mostly unused keys; keep the 4 that matter.
+const BADGE_KEYS = ["comments", "attachments", "checkItems", "checkItemsChecked"];
+
+function slimCard(card: Record<string, unknown>): Record<string, unknown> {
+  const out = { ...card };
+  if (out.badges && typeof out.badges === "object" && !Array.isArray(out.badges)) {
+    const badges = out.badges as Record<string, unknown>;
+    out.badges = Object.fromEntries(
+      BADGE_KEYS.filter((key) => badges[key] !== undefined).map((key) => [
+        key,
+        badges[key],
+      ]),
+    );
+  }
+  if (Array.isArray(out.labels)) {
+    out.labels = out.labels.map((label) => {
+      const { id, name, color } = label as Record<string, unknown>;
+      return { id, name, color };
+    });
+  }
+  return out;
+}
+
+/** Slim badges/labels on a card or card array returned by Trello. */
+export function slimCards(data: unknown): unknown {
+  if (Array.isArray(data)) {
+    return data.map((item) =>
+      item && typeof item === "object"
+        ? slimCard(item as Record<string, unknown>)
+        : item,
+    );
+  }
+  if (data && typeof data === "object") {
+    return slimCard(data as Record<string, unknown>);
+  }
+  return data;
+}
+
+export async function withCardListResult(
+  profile: string | undefined,
+  fn: (client: TrelloClient) => Promise<unknown>,
+  heading?: string,
+): Promise<CallToolResult> {
+  try {
+    const { profileName, client } = getClient(profile);
+    const raw = await fn(client);
+    const cards = slimCards(raw);
+    const arr = Array.isArray(cards) ? (cards as CardDisplayInput[]) : [];
+    return toolResult({
+      ok: true,
+      profile: profileName,
+      data: arr,
+      ...cardListDisplay(arr, heading),
+    });
+  } catch (err) {
+    if (err instanceof TrelloError) {
+      return toolResult({
+        ok: false,
+        error: err.message,
+        status: err.status,
+        details: err.body,
+      });
+    }
+    return toolResult({
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
 export async function withClient<T>(
   profile: string | undefined,
   fn: (client: TrelloClient, profileName: string) => Promise<T>,

package/src/mcp/tools/boards.ts

@@ -1,6 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+import {
+  profileField,
+  toolEnvelopeSchema,
+  withCardListResult,
+  withClient,
+} from "../handlers.ts";
 
 export function registerBoardTools(server: McpServer): void {
   const outputSchema = toolEnvelopeSchema;
@@ -25,7 +30,10 @@ export function registerBoardTools(server: McpServer): void {
           ])
           .optional()
           .default("open"),
-        fields: z.string().optional(),
+        fields: z
+          .string()
+          .default("id,name,shortUrl,closed")
+          .describe('comma-separated fields, "all" for everything'),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
@@ -41,7 +49,10 @@ export function registerBoardTools(server: McpServer): void {
       inputSchema: {
         profile: profileField,
         boardId: z.string().min(1),
-        fields: z.string().optional(),
+        fields: z
+          .string()
+          .default("id,name,desc,shortUrl,closed")
+          .describe('comma-separated fields, "all" for everything'),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
@@ -94,23 +105,42 @@ export function registerBoardTools(server: McpServer): void {
         profile: profileField,
         boardId: z.string().min(1),
         filter: z.string().optional().default("open"),
+        fields: z
+          .string()
+          .default("id,name,closed,pos")
+          .describe('comma-separated fields, "all" for everything'),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
-    async ({ profile, boardId, filter }) =>
-      withClient(profile, (client) => client.boardLists(boardId, { filter })),
+    async ({ profile, boardId, filter, fields }) =>
+      withClient(profile, (client) => client.boardLists(boardId, { filter, fields })),
   );
 
   server.registerTool(
     "trello_board_cards",
     {
-      description: "List all cards on a board.",
-      inputSchema: { profile: profileField, boardId: z.string().min(1) },
+      description:
+        "List all cards on a board. Default fields omit badges/labels — pass fields including badges,labels for rich `display`. When showing cards to the user, paste response `display` verbatim.",
+      inputSchema: {
+        profile: profileField,
+        boardId: z.string().min(1),
+        fields: z
+          .string()
+          .default("id,name,idList,due,dueComplete,shortUrl,closed,badges,labels")
+          .describe(
+            'comma-separated fields, "all" for everything; badges,labels included by default for display',
+          ),
+        displayHeading: z.string().optional(),
+      },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
-    async ({ profile, boardId }) =>
-      withClient(profile, (client) => client.boardCards(boardId)),
+    async ({ profile, boardId, fields, displayHeading }) =>
+      withCardListResult(
+        profile,
+        (client) => client.boardCards(boardId, { fields }),
+        displayHeading,
+      ),
   );
 }

package/src/mcp/tools/cards.ts

@@ -1,6 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+import {
+  profileField,
+  slimCards,
+  toolEnvelopeSchema,
+  withClient,
+} from "../handlers.ts";
 
 export function registerCardTools(server: McpServer): void {
   const outputSchema = toolEnvelopeSchema;
@@ -12,13 +17,18 @@ export function registerCardTools(server: McpServer): void {
       inputSchema: {
         profile: profileField,
         cardId: z.string().min(1),
-        fields: z.string().optional(),
+        fields: z
+          .string()
+          .default("id,name,desc,due,dueComplete,idList,shortUrl,labels,badges")
+          .describe('comma-separated fields, "all" for everything'),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
     async ({ profile, cardId, fields }) =>
-      withClient(profile, (client) => client.cardGet(cardId, { fields })),
+      withClient(profile, async (client) =>
+        slimCards(await client.cardGet(cardId, { fields })),
+      ),
   );
 
   server.registerTool(

package/src/mcp/tools/lists.ts

@@ -1,6 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+import {
+  profileField,
+  toolEnvelopeSchema,
+  withCardListResult,
+  withClient,
+} from "../handlers.ts";
 
 export function registerListTools(server: McpServer): void {
   const outputSchema = toolEnvelopeSchema;
@@ -26,12 +31,30 @@ export function registerListTools(server: McpServer): void {
   server.registerTool(
     "trello_list_cards",
     {
-      description: "List cards in a list.",
-      inputSchema: { profile: profileField, listId: z.string().min(1) },
+      description:
+        "List cards in a list. Response includes `display` (markdown-v1, linked titles + 💬📎✓⏰ badges) — when the user should SEE cards, paste `display` verbatim; do not reformat as a plain title list.",
+      inputSchema: {
+        profile: profileField,
+        listId: z.string().min(1),
+        fields: z
+          .string()
+          .default("id,name,idList,due,dueComplete,shortUrl,closed,badges,labels")
+          .describe('comma-separated fields, "all" for everything'),
+        displayHeading: z
+          .string()
+          .optional()
+          .describe(
+            'Optional markdown heading prepended to `display` (e.g. "**Dogster → To do**")',
+          ),
+      },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
-    async ({ profile, listId }) =>
-      withClient(profile, (client) => client.listCards(listId)),
+    async ({ profile, listId, fields, displayHeading }) =>
+      withCardListResult(
+        profile,
+        (client) => client.listCards(listId, { fields }),
+        displayHeading,
+      ),
   );
 }

package/src/mcp/tools/search.ts

@@ -15,16 +15,28 @@ export function registerSearchTools(server: McpServer): void {
         modelTypes: z.string().optional(),
         cardsLimit: z.number().int().positive().optional(),
         boardsLimit: z.number().int().positive().optional(),
+        cardFields: z.string().default("id,name,idList,shortUrl"),
+        boardFields: z.string().default("id,name,shortUrl"),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
-    async ({ profile, query, modelTypes, cardsLimit, boardsLimit }) =>
+    async ({
+      profile,
+      query,
+      modelTypes,
+      cardsLimit,
+      boardsLimit,
+      cardFields,
+      boardFields,
+    }) =>
       withClient(profile, (client) =>
         client.search(query, {
           modelTypes,
           cards_limit: cardsLimit,
           boards_limit: boardsLimit,
+          card_fields: cardFields,
+          board_fields: boardFields,
         }),
       ),
   );

package/src/util/card-display.ts

@@ -0,0 +1,100 @@
+import { dueStatus, formatDue } from "../cli/ui/palette.ts";
+
+/** Markdown emoji for Trello label colors (agent-facing card lists). */
+const LABEL_DOT: Record<string, string> = {
+  red: "🔴",
+  orange: "🟠",
+  yellow: "🟡",
+  green: "🟢",
+  lime: "🟢",
+  blue: "🔵",
+  sky: "🔵",
+  sky_light: "🔵",
+  sky_dark: "🔵",
+  purple: "🟣",
+  pink: "🟣",
+  black: "⚫",
+  none: "⚪",
+};
+
+export type CardDisplayInput = {
+  name?: string;
+  shortUrl?: string;
+  url?: string;
+  due?: string | null;
+  dueComplete?: boolean;
+  badges?: {
+    comments?: number;
+    attachments?: number;
+    checkItems?: number;
+    checkItemsChecked?: number;
+  };
+  labels?: Array<{ name?: string; color?: string | null }>;
+};
+
+function labelDot(color: string | null | undefined): string {
+  if (!color) return "⚪";
+  const base = color.split("_")[0] ?? color;
+  return LABEL_DOT[color] ?? LABEL_DOT[base] ?? "⚪";
+}
+
+function labelParts(labels: CardDisplayInput["labels"]): string[] {
+  if (!labels?.length) return [];
+  return labels
+    .map((label) => {
+      const name = (label.name ?? "").trim();
+      const dot = labelDot(label.color);
+      return name ? `${dot} \`${name}\`` : dot;
+    })
+    .filter(Boolean);
+}
+
+function badgeParts(badges: CardDisplayInput["badges"]): string[] {
+  if (!badges) return [];
+  const parts: string[] = [];
+  const comments = badges.comments ?? 0;
+  const attachments = badges.attachments ?? 0;
+  const total = badges.checkItems ?? 0;
+  const checked = badges.checkItemsChecked ?? 0;
+  if (comments > 0) parts.push(`💬 ${comments}`);
+  if (attachments > 0) parts.push(`📎 ${attachments}`);
+  if (total > 0) parts.push(`✓ ${checked}/${total}`);
+  return parts;
+}
+
+function duePart(
+  due: string | null | undefined,
+  dueComplete: boolean | undefined,
+): string {
+  if (!due) return "";
+  const status = dueStatus(due, dueComplete);
+  const label = formatDue(due);
+  if (status === "complete") return `⏰ ${label} ✓`;
+  if (status === "overdue") return `⏰ ${label} (overdue)`;
+  return `⏰ ${label}`;
+}
+
+/** One markdown line: `[name](shortUrl)` + labels + non-zero badges + due. */
+export function formatCardLine(card: CardDisplayInput, index?: number): string {
+  const name = card.name ?? "(untitled)";
+  const href = card.shortUrl ?? card.url ?? "";
+  const prefix = index === undefined ? "" : `${index}. `;
+  const title = href ? `[${name}](${href})` : name;
+  const extras = [...labelParts(card.labels), ...badgeParts(card.badges)];
+  const due = duePart(card.due, card.dueComplete);
+  if (due) extras.push(due);
+  if (extras.length === 0) return `${prefix}${title}`;
+  return `${prefix}${title} · ${extras.join(" · ")}`;
+}
+
+/** Numbered markdown list for agent/user display (`displayFormat: markdown-v1`). */
+export function formatCardListMarkdown(
+  cards: CardDisplayInput[],
+  heading?: string,
+): string {
+  const lines = cards.map((card, i) => formatCardLine(card, i + 1));
+  if (!heading) return lines.join("\n");
+  return `${heading}\n\n${lines.join("\n")}`;
+}
+
+export const CARD_LIST_DISPLAY_FORMAT = "markdown-v1";