trelly 0.1.1 → 0.2.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "trelly",
+  "version": "0.1.1",
+  "description": "Trello CLI + MCP tools — boards, lists, cards, search, and raw API via trelly-mcp",
+  "author": {
+    "name": "brandonkramer",
+    "url": "https://github.com/brandonkramer"
+  },
+  "homepage": "https://github.com/brandonkramer/trelly#readme",
+  "repository": "https://github.com/brandonkramer/trelly",
+  "license": "MIT",
+  "keywords": ["trello", "trelly", "mcp", "kanban", "productivity"],
+  "skills": ["./skills"],
+  "mcpServers": "./.mcp.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "trelly",
+  "version": "0.1.1",
+  "description": "Trello CLI + MCP — boards, lists, cards, search, and raw API via trelly-mcp",
+  "author": {
+    "name": "brandonkramer",
+    "url": "https://github.com/brandonkramer"
+  },
+  "homepage": "https://github.com/brandonkramer/trelly#readme",
+  "repository": "https://github.com/brandonkramer/trelly",
+  "license": "MIT",
+  "keywords": ["trello", "trelly", "mcp", "kanban"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Trelly",
+    "shortDescription": "Trello boards, cards, and search from Codex",
+    "longDescription": "Manage Trello with trelly-mcp tools and CLI guidance. Auth once with trelly auth login.",
+    "developerName": "brandonkramer",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://github.com/brandonkramer/trelly",
+    "privacyPolicyURL": "https://github.com/brandonkramer/trelly/blob/main/PRIVACY.md"
+  }
+}

package/.cursor-plugin/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "trelly": {
+      "command": "bash",
+      "args": ["../bin/trelly-mcp"],
+      "env": {
+        "TRELLO_PROFILE": "default"
+      }
+    }
+  }
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "trelly",
+  "version": "0.1.1",
+  "description": "Trello boards, lists, cards, search, and comments via MCP — with agent skills for CLI and trelly-mcp tools.",
+  "author": {
+    "name": "brandonkramer"
+  },
+  "homepage": "https://github.com/brandonkramer/trelly#readme",
+  "repository": "https://github.com/brandonkramer/trelly",
+  "license": "MIT",
+  "keywords": ["trello", "trelly", "mcp", "kanban", "productivity"],
+  "logo": "assets/logo.svg",
+  "skills": "./skills/",
+  "mcpServers": "mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "trelly": {
+    "command": "${CLAUDE_PLUGIN_ROOT}/bin/trelly-mcp",
+    "env": {
+      "TRELLO_PROFILE": "default"
+    }
+  }
+}

package/PLUGIN.md

@@ -0,0 +1,85 @@
+# Trelly agent plugin
+
+Marketplace-facing overview for **Cursor**, **Claude Code**, and **Codex**. The npm
+package root is the plugin bundle (skills + MCP + launcher scripts).
+
+## What it does
+
+- **Skills** teach agents when to use the CLI vs MCP, how auth works, and archive vs
+  delete safety (`skills/trelly`, `skills/trelly-mcp`).
+- **MCP** exposes 27 Trello tools via stdio (`trelly-mcp` → `src/mcp/server.ts`).
+- **CLI** (`trelly`) is optional for humans/scripts; the plugin does not require global
+  npm install if the IDE loads the plugin from this repository (MCP uses bundled
+  `bin/trelly-mcp`).
+
+## Prerequisites (end users)
+
+1. **Node 22+** (or Bun) — `bin/run-ts` falls back to bundled `tsx` for MCP/CLI.
+2. One-time Trello auth:
+   ```bash
+   trelly auth setup    # API key from https://trello.com/power-ups/admin
+   trelly auth login    # browser OAuth → ~/.config/trelly/config.json
+   ```
+3. macOS or Linux (`package.json` `"os"`).
+
+## Plugin layout
+
+| Path | Purpose |
+|------|---------|
+| `.cursor-plugin/plugin.json` | Cursor manifest |
+| `.cursor-plugin/mcp.json` | Cursor MCP (bundled `bin/trelly-mcp`) |
+| `.claude-plugin/plugin.json` | Claude Code manifest |
+| `.mcp.json` | Claude/Codex MCP (`${CLAUDE_PLUGIN_ROOT}/bin/trelly-mcp`) |
+| `.codex-plugin/plugin.json` | Codex manifest |
+| `skills/` | Agent skills (source of truth) |
+| `assets/logo.svg` | Plugin logo |
+| [PRIVACY.md](PRIVACY.md) | Data handling |
+
+## Test locally (Cursor)
+
+Symlinks are unreliable in Cursor plugins — **copy** the repo:
+
+```bash
+./bin/install-cursor-plugin-local.sh
+```
+
+Then **Developer: Reload Window** in Cursor. Verify MCP **trelly** is connected and skills
+appear. Run `trelly auth list` in a terminal if tools return auth errors.
+
+## Test locally (Claude Code)
+
+```bash
+claude plugin install /absolute/path/to/trelly
+# or after npm install -g trelly:
+claude plugin install "$(npm root -g)/trelly"
+```
+
+Reload Claude Code. Confirm MCP server **trelly** and skills load.
+
+## Submit to official marketplaces
+
+| Platform | Action |
+|----------|--------|
+| **Cursor** | [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish) — repo `https://github.com/brandonkramer/trelly` |
+| **Claude Code** | [clau.de/plugin-directory-submission](https://clau.de/plugin-directory-submission) — same repo |
+
+Requirements:
+
+- Open source (MIT) ✅
+- Valid manifests and skill frontmatter ✅
+- Logo at `assets/logo.svg` ✅
+- Privacy summary in [PRIVACY.md](PRIVACY.md) ✅
+- Manual review on updates (Cursor); Anthropic review for official directory
+
+After Claude approval, users install with:
+
+```text
+/plugin install trelly@claude-plugins-official
+```
+
+## MCP safety notes for reviewers
+
+- **`trello_card_archive`** / **`trello_board_archive`** — reversible (Trello `closed=true`)
+- **`trello_card_delete`** — permanent; marked `destructiveHint` in MCP registration
+- No MCP board-delete tool
+- Auth never appears in URLs; tokens in `Authorization` header only

package/PRIVACY.md

@@ -0,0 +1,43 @@
+# Trelly privacy
+
+Trelly is a local CLI and MCP plugin for [Trello](https://trello.com). This document
+describes data handling for marketplace review and end users.
+
+## What runs locally
+
+- **CLI (`trelly`)** and **MCP server (`trelly-mcp`)** run on your machine as child
+  processes of your terminal or IDE.
+- **Credentials** (API key + token) are stored only in `~/.config/trelly/config.json`
+  (file mode `600`). The plugin does not upload credentials to any server operated by
+  the trelly author.
+- **Agent skills** are static markdown instructions bundled in the package. They contain
+  no telemetry or phone-home logic.
+
+## What leaves your machine
+
+- API requests go **directly to Trello** (`https://api.trello.com`) using your token in
+  the `Authorization` header. Trello’s privacy policy applies to that data:
+  [Atlassian Privacy Policy](https://www.atlassian.com/legal/privacy-policy).
+- The trelly package does **not** collect analytics, crash reports, or usage metrics.
+
+## MCP and IDE plugins
+
+- Cursor, Claude Code, and Codex plugins bundle the same `trelly-mcp` stdio server and
+  skills. Enabling the plugin lets the IDE spawn `trelly-mcp`; tool calls follow the same
+  Trello API path as the CLI.
+- IDE vendors (Cursor, Anthropic, OpenAI) may log prompts or tool traffic according to
+  their own product policies. That is outside trelly’s control.
+
+## Your responsibilities
+
+- Register your own Trello Power-Up API key at
+  [power-ups/admin](https://trello.com/power-ups/admin).
+- Treat `~/.config/trelly/config.json` like a password file.
+- Prefer **`trello_*_archive`** MCP tools over **`trello_card_delete`** unless permanent
+  deletion is intended.
+
+## Contact
+
+Issues and security reports: [github.com/brandonkramer/trelly/issues](https://github.com/brandonkramer/trelly/issues)
+
+License: MIT — see [LICENSE](LICENSE).

package/README.md

@@ -1,21 +1,25 @@
-# trelly ~ trello CLI
+<p>
+  <img src="assets/logo.svg" alt="Trelly" width="128" height="128" />
+</p>
+
+# Trelly -- Trello CLI
 
 Fast Trello CLI + MCP server ([npm](https://www.npmjs.com/package/trelly): `npm install -g trelly`).
 **Human, Trello-styled output by default**; add `--json` for scripts and automation.
 Commands: **`trelly`** (CLI) and **`trelly-mcp`** (MCP server).
 
-![trelly interactive UI](cli.gif)
+![trelly terminal UI](assets/terminal.gif)
 
 Boards, lists, cards, checklists, labels, custom fields, search, webhooks, multi-profile
 auth, interactive kanban TUI, raw `trelly api` escape hatch.
 
-## Quick start
+## Install
 
 ```bash
-npm install -g trelly   # or: brew install brandonkramer/tap/trelly · bunx trelly · npx trelly
-trelly auth setup    # once: API key from power-ups/admin
-trelly auth login    # browser → Allow
-trelly boards list
+npm install -g trelly                   # npm (Node 22+)
+brew install brandonkramer/tap/trelly   # Homebrew
+bunx trelly                             # run without installing (Bun)
+npx trelly                              # run without installing (Node 22+)
 ```
 
 From source (repo [brandonkramer/trelly](https://github.com/brandonkramer/trelly)):
@@ -32,6 +36,24 @@ No Bun? `npm install` in the clone — tsx is the fallback runtime.
 
 Optional: `bun link` / `npm link`, or add `bin/` to `PATH`.
 
+### Updating
+
+```bash
+npm update -g trelly          # or: npm install -g trelly@latest
+brew upgrade trelly           # Homebrew
+```
+
+Auth in `~/.config/trelly/config.json` is kept across upgrades. Reload your IDE after
+updating if you use the agent plugin MCP server.
+
+## Quick start
+
+```bash
+trelly auth setup    # once: API key from power-ups/admin
+trelly auth login    # browser → Allow
+trelly boards list
+```
+
 ## Output
 
 | Mode | Command | stdout |
@@ -56,6 +78,8 @@ trelly ui BOARD_ID  # jump straight to a board
 
 Requires a TTY. Keys: **arrows** / **hjkl** move focus, **Enter** card detail, **r** refresh, **q** / **Esc** back or quit.
 
+In card detail: **↑↓** move over attachments and comments, **Enter** opens the focused attachment in your browser or expands/collapses the focused comment, **c** new comment, **r** reply to the focused comment (prefills `@author`), **a** attach a file path or URL, **Esc** back.
+
 See the demo above or run `trelly --help` for all subcommands.
 
 ## Auth
@@ -93,6 +117,7 @@ trelly --profile work boards lists BOARD_ID
 trelly cards create --list LIST_ID --name "Ship feature"
 trelly cards comments CARD_ID
 trelly cards comment CARD_ID --text "Shipped"
+trelly cards add-attachment CARD_ID --file screenshot.png   # or --url https://…
 trelly search "customer onboarding"
 trelly api -X PUT --path /cards/CARD_ID --query idList=LIST_ID
 trelly api -X POST --path /cards --body '{"idList":"LIST_ID","name":"Hi"}'
@@ -111,7 +136,7 @@ Top-level: `auth` · `boards` · `lists` · `cards` · `checklists` · `labels`
 | **auth** | `setup` · `login` · `list` · `use` · `logout` · `url` |
 | **boards** | `list` · `get` · `create` · `update` · `archive` · `delete` · `lists` · `cards` · `labels` · `members` · `actions` · `custom-fields` |
 | **lists** | `get` · `create` · `update` · `archive` · `cards` |
-| **cards** | `get` · `list` · `create` · `update` · `move` · `comments` · `comment` · `archive` · `delete` · `members` · `add-member` · `remove-member` · `labels` · `add-label` · `remove-label` · `actions` · `attachments` · `add-attachment` · `custom-fields` |
+| **cards** | `get` · `list` · `create` · `update` · `move` · `comments` · `comment` · `archive` · `delete` · `members` · `add-member` · `remove-member` · `labels` · `add-label` · `remove-label` · `actions` · `attachments` · `add-attachment` · `delete-attachment` · `custom-fields` |
 | **checklists** | `get` · `create` · `update` · `delete` · `add-item` · `update-item` · `delete-item` |
 | **labels** | `get` · `create` · `update` · `delete` |
 | **custom-fields** | `get` · `create` · `update` · `delete` · `set-item` |
@@ -184,7 +209,31 @@ bun run typecheck && bun test && bun run lint
 
 CI runs the same via `bun install --frozen-lockfile`. See `AGENTS.md` for conventions.
 
-**Agent skills:** [skills/](skills/README.md) — portable `SKILL.md` files for Cursor, Claude, Pi, Codex (`trelly`, `trelly-mcp`).
+## 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).
+
+```bash
+npm install -g trelly
+trelly auth setup && trelly auth login
+
+pi install npm:trelly
+claude plugin install "$(npm root -g)/trelly"
+./bin/install-cursor-plugin-local.sh   # Cursor local test (copy, not symlink)
+```
+
+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) |
+
+Open source (MIT). After Claude listing: `/plugin install trelly@claude-plugins-official`.
 
 ## License
 

package/assets/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="Trelly">
+  <rect width="128" height="128" rx="28" fill="#0A7EA4"/>
+  <rect x="22" y="30" width="24" height="68" rx="5" fill="#fff" opacity="0.92"/>
+  <rect x="52" y="30" width="24" height="50" rx="5" fill="#fff" opacity="0.78"/>
+  <rect x="82" y="30" width="24" height="60" rx="5" fill="#fff" opacity="0.86"/>
+</svg>

package/bin/install-cursor-plugin-local.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Copy trelly into ~/.cursor/plugins/local/trelly for marketplace preflight testing.
+# Cursor plugin symlinks are unreliable — use cp -R (see PLUGIN.md).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+DEST="${HOME}/.cursor/plugins/local/trelly"
+
+rm -rf "$DEST"
+mkdir -p "${HOME}/.cursor/plugins/local"
+cp -R "$ROOT" "$DEST"
+chmod +x "$DEST/bin/trelly" "$DEST/bin/trelly-mcp" "$DEST/bin/run-ts" 2>/dev/null || true
+
+echo "Copied trelly plugin to: $DEST"
+echo "Next: reload Cursor (Developer: Reload Window) and check MCP + skills."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trelly",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "trelly — fast Trello CLI with multi-profile auth, MCP server, and kanban TUI",
   "type": "module",
   "license": "MIT",
@@ -11,8 +11,14 @@
     "trelly",
     "mcp",
     "kanban",
-    "automation"
+    "automation",
+    "pi-package"
   ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/brandonkramer/trelly.git"
@@ -26,7 +32,15 @@
   ],
   "files": [
     "bin/",
-    "src/"
+    "src/",
+    "skills/",
+    "assets/",
+    ".claude-plugin/",
+    ".codex-plugin/",
+    ".cursor-plugin/",
+    ".mcp.json",
+    "PLUGIN.md",
+    "PRIVACY.md"
   ],
   "bin": {
     "trelly": "./bin/trelly",
@@ -40,7 +54,7 @@
     "lint": "biome check .",
     "fmt": "biome format --write .",
     "fmt:check": "biome check .",
-    "postinstall": "chmod +x bin/trelly bin/trelly-mcp bin/run-ts 2>/dev/null || true",
+    "postinstall": "chmod +x bin/trelly bin/trelly-mcp bin/run-ts bin/install-cursor-plugin-local.sh 2>/dev/null || true",
     "prepublishOnly": "bun run typecheck && bun test && bun run lint"
   },
   "engines": {

package/skills/README.md

@@ -0,0 +1,115 @@
+# trelly agent skills & plugins
+
+These ship **inside the npm package** (`npm install -g trelly`). They teach your AI agent
+how to use the CLI and MCP — for anyone using trelly on their machine, not for people
+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 |
+
+**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.
+
+## Prerequisite
+
+```bash
+npm install -g trelly    # or: brew install brandonkramer/tap/trelly
+trelly auth setup
+trelly auth login
+```
+
+## Pi
+
+```bash
+pi install npm:trelly
+```
+
+Loads both skills from the package manifest (`package.json` → `"pi": { "skills": ["./skills"] }`).
+Pi has no built-in MCP — use the **trelly** skill for CLI/bash, or wire MCP in Cursor/Claude
+below.
+
+## Claude Code
+
+Install the plugin from your global npm package (skills + MCP in one step):
+
+```bash
+claude plugin install "$(npm root -g)/trelly"
+```
+
+Reload Claude Code. The plugin starts `trelly-mcp` and loads `skills/trelly` +
+`skills/trelly-mcp`.
+
+**MCP only** (no plugin skills): add to your Claude MCP config using `trelly-mcp` on PATH
+(see [trelly-mcp/SKILL.md](trelly-mcp/SKILL.md)).
+
+## Codex
+
+Codex uses `.codex-plugin/plugin.json` (same layout as Claude: skills + `.mcp.json` at
+package root). Install via a **marketplace** — see
+[Codex plugin docs](https://developers.openai.com/codex/plugins/build).
+
+After `npm install -g trelly`:
+
+```bash
+mkdir -p ~/.agents/plugins
+ln -sf "$(npm root -g)/trelly" ~/.agents/plugins/trelly
+```
+
+`~/.agents/plugins/marketplace.json`:
+
+```json
+{
+  "name": "local-trelly",
+  "interface": { "displayName": "Trelly" },
+  "plugins": [
+    {
+      "name": "trelly",
+      "source": {
+        "source": "local",
+        "path": "./trelly"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+Restart Codex, run `/plugins`, install **Trelly**, then `trelly auth setup && trelly auth login`
+once. Codex sets `${PLUGIN_ROOT}` (and `${CLAUDE_PLUGIN_ROOT}`) so bundled MCP finds
+`bin/trelly-mcp`.
+
+For team/repo distribution, publish a marketplace with a `git-subdir` entry pointing at
+this package, or use `codex plugin marketplace add owner/repo`.
+
+## Cursor
+
+**Plugin (skills + MCP):**
+
+```bash
+./bin/install-cursor-plugin-local.sh   # from repo clone (copy — symlinks break in Cursor)
+# or after npm install -g trelly:
+cp -R "$(npm root -g)/trelly" ~/.cursor/plugins/local/trelly
+```
+
+Restart Cursor / reload MCP.
+
+**MCP only:** copy [mcp.example.json](../mcp.example.json) into `~/.cursor/mcp.json`.
+
+## What each piece does
+
+| Piece | Role |
+|-------|------|
+| `skills/` | Agent instructions (CLI vs MCP, auth, safety) — **the content** |
+| `.claude-plugin/` + `.mcp.json` | Claude Code plugin manifest + MCP wiring |
+| `.codex-plugin/` + `.mcp.json` | Codex plugin manifest + MCP wiring |
+| `.cursor-plugin/` | Cursor plugin manifest + MCP wiring |
+| `package.json` `"pi"` | Pi package manifest (skills path) |
+
+Skills tell the agent *how* to use trelly. MCP config tells the IDE *how to spawn*
+`trelly-mcp`. After `npm install -g trelly`, both bins are on PATH.