trelly 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trelly",
-  "version": "0.2.0",
+  "version": "0.2.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,8 @@ developing this repo.
 
 | Skill | Use when |
 |-------|----------|
-| [trelly](trelly/SKILL.md) | Terminal / bash: `trelly boards list`, auth, `--json` |
-| [trelly-mcp](trelly-mcp/SKILL.md) | IDE agent with MCP wired: tool names, envelopes, safety |
+| [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 |
 
 **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

@@ -2,9 +2,9 @@
 name: trelly
 description: >-
   Operate the trelly Trello CLI (npm trelly; bins trelly/trello): auth setup/login,
-  human vs --json output, boards/lists/cards, search, trello ui, trello api. Use when
-  the user asks to run trelly/trello commands, script Trello from the terminal, or
-  automate Trello with trelly.
+  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.
 ---
 
 # trelly
@@ -56,6 +56,8 @@ trelly cards comments CARD_ID
 trelly cards create --list LIST_ID --name "Task"
 trelly cards move CARD_ID --list OTHER_LIST_ID
 trelly cards comment CARD_ID --text "Done"
+trelly cards attachments CARD_ID
+trelly cards add-attachment CARD_ID --url "https://github.com/org/repo/pull/42"
 trelly search "query"
 trelly ui BOARD_ID                    # interactive kanban (TTY required)
 trelly auth list
@@ -73,6 +75,89 @@ trelly api -X POST --path /cards --body '{"idList":"LIST_ID","name":"Hi"}'
 
 Request body flag is **`--body`** (not `--json` — that flag is global output).
 
+## Card attachments
+
+```bash
+trelly cards attachments CARD_ID
+trelly cards add-attachment CARD_ID --url "https://…" [--name "label"]
+trelly cards add-attachment CARD_ID --file ./screenshot.png [--name "label"]
+trelly cards delete-attachment CARD_ID ATTACHMENT_ID
+```
+
+Pass **exactly one** of `--url` or `--file`. In `trelly ui`, open a card's detail (**⏎**), then **a** opens the attach prompt (URL or local path).
+
+## GitHub PR / commit on a card
+
+Boards with the **GitHub Power-Up** enabled can show rich PR metadata in the Trello UI.
+trelly attaches the same underlying **URL attachment** — it does **not** drive the
+Power-Up picker or OAuth flow.
+
+### Link a PR or commit (preferred)
+
+```bash
+# Pull request — set --name so the attachment is scannable in lists/UI
+trelly cards add-attachment CARD_ID \
+  --url "https://github.com/PangoliaDev/dogster/pull/197" \
+  --name "#197 fix(pre-existing-tests-and-types)"
+
+# Commit
+trelly cards add-attachment CARD_ID \
+  --url "https://github.com/PangoliaDev/dogster/commit/2d856ea" \
+  --name "2d856ea Merge PR #197"
+
+# Issue (same mechanism)
+trelly cards add-attachment CARD_ID \
+  --url "https://github.com/PangoliaDev/dogster/issues/42"
+```
+
+Accepted URL shapes: `…/pull/N`, `…/commit/SHA`, `…/issues/N`, `…/tree/branch`.
+Use the canonical `https://github.com/…` URL (no `/files` or `/commits` tab suffix).
+
+### Power-Up UI vs trelly URL attachment
+
+| Feature | GitHub Power-Up (Trello UI) | `cards add-attachment --url` |
+|--------|-----------------------------|------------------------------|
+| Link on card | Yes | Yes |
+| Readable `--name` / PR title | Yes (auto) | Set `--name` yourself (recommended) |
+| CI/check badges on card front | Yes | No |
+| Pick PR from repo browser | Yes | No — pass URL |
+| Comment back on GitHub PR | Yes (optional setting) | No |
+
+If the user needs badges or GitHub-side back-links, attach via **Power-Ups → GitHub**
+in Trello. For agent/CLI workflows (ship PR → link card → move list), URL attachment
+is enough.
+
+### Agent workflow patterns
+
+**After opening or merging a PR** — attach and optionally move the card:
+
+```bash
+CARD_ID=…
+PR_URL="https://github.com/PangoliaDev/dogster/pull/197"
+trelly cards add-attachment "$CARD_ID" --url "$PR_URL" --name "#197 fix scope"
+trelly cards move "$CARD_ID" --list PENDING_REVIEW_LIST_ID
+```
+
+**Fallback — comment only** (visible in activity, not Attachments):
+
+```bash
+trelly cards comment CARD_ID --text "PR: https://github.com/org/repo/pull/42"
+```
+
+**Inspect what's linked:**
+
+```bash
+trelly --json cards attachments CARD_ID | jq '.data[] | {name, url}'
+```
+
+### Raw API (same as CLI)
+
+```bash
+trelly api -X POST --path "/cards/CARD_ID/attachments" \
+  --query "url=https://github.com/org/repo/pull/42" \
+  --query "name=#42 feature title"
+```
+
 ## Custom fields (list-type)
 
 ```bash

package/skills/trelly-mcp/SKILL.md

@@ -2,8 +2,8 @@
 name: trelly-mcp
 description: >-
   Configure and use the trelly MCP stdio server (trello_boards_list,
-  trello_card_create, trello_search, etc.). Use when wiring Cursor/Claude MCP,
-  calling Trello from an IDE agent, or choosing between MCP tools vs trelly CLI.
+  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.
 ---
 
 # trelly-mcp
@@ -99,6 +99,66 @@ Starts stdio MCP manually (IDE normally launches `trelly-mcp` itself).
 | `trello_webhook_delete` | Delete webhook |
 | `trello_api` | Raw REST (`method`, `path`, `query`, `body`) |
 
+There is **no dedicated attachment MCP tool** yet — use `trello_api` or the CLI
+`cards add-attachment` (see **trelly** skill).
+
+## GitHub PR / commit on a card (MCP)
+
+Boards with the **GitHub Power-Up** show rich PR UI when attached through Trello.
+Agents link the same way via **`trello_api`** — a URL attachment, not the Power-Up
+OAuth picker.
+
+### Attach PR or commit
+
+```
+trello_api
+  method: POST
+  path: /cards/{cardId}/attachments
+  query: { "url": "https://github.com/org/repo/pull/42", "name": "#42 feature title" }
+```
+
+Commit:
+
+```
+query: { "url": "https://github.com/org/repo/commit/abc1234", "name": "abc1234 message" }
+```
+
+Always set **`name`** to something scannable (`#N title` or short SHA + subject).
+
+### List or remove attachments
+
+```
+trello_api  GET   /cards/{cardId}/attachments
+trello_api  DELETE /cards/{cardId}/attachments/{attachmentId}
+```
+
+### Comment fallback
+
+```
+trello_card_comment  cardId  text: "PR: https://github.com/org/repo/pull/42"
+```
+
+Comments appear in card activity; they are **not** Attachments.
+
+### Power-Up vs MCP/API
+
+| Feature | GitHub Power-Up (UI) | `trello_api` URL attachment |
+|--------|----------------------|-----------------------------|
+| Link on card | Yes | Yes |
+| PR title / custom name | Auto | Set `name` in query |
+| CI badges on card front | Yes | No |
+| GitHub PR back-link comment | Yes (optional) | No |
+
+Use the Power-Up UI when the user needs badges or GitHub-side comments. For
+agent workflows (link PR after push, move card to review), POST the GitHub URL.
+
+### Typical agent sequence
+
+1. `trello_search` or `trello_list_cards` — find the card
+2. `trello_api` POST `/cards/{id}/attachments` with PR URL + name
+3. `trello_card_move` — e.g. To do → Pending review
+4. Optional: `trello_card_comment` with the same PR URL
+
 ## When to use MCP vs CLI
 
 | Use MCP | Use CLI |