feat(deck): compact card/comment retrieval (summaries, filters, board overview)

Deck read tools returned too many tokens to be usable as boards grow — even
deck_get_stacks(description_max_length=1) exceeded the MCP token limit because
every card was fully serialized in list views.

- Add compact projection models (DeckCardSummary, DeckCommentSummary,
  StackOverview, BoardOverviewResponse) and a uniform detail="summary"|"full"
  knob (summary default) on deck_get_cards / get_stacks / get_stack /
  get_archived_stacks.
- Add pre-serialization filtering: status (open/done/archived/all), label,
  assigned_to.
- Add deck_get_board_overview: board title + label legend + stacks with
  compact card rows + counts in a single call.
- Compact comments: detail / message_max_length / newest-first order on
  deck_get_card_comments.
- Docs + unit/integration tests.

BREAKING CHANGE: deck list tools now default to detail="summary" and
status="open". The include_archived_cards parameter is replaced by status
(use status="all" to include archived cards); pass detail="full" to restore
the previous per-card shape.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/deck.md

@@ -4,6 +4,16 @@
 
 | Tool | Description |
 |------|-------------|
+| `deck_get_boards` | List all Deck boards |
+| `deck_get_board` | Get a board (toggle `include_acl` / `include_users` / `include_labels`) |
+| `deck_get_board_overview` | **Compact whole-board snapshot** — board → stacks → summary card rows in one call |
+| `deck_get_stacks` | List stacks in a board (cards as compact summaries by default) |
+| `deck_get_stack` | Get a single stack (cards as compact summaries by default) |
+| `deck_get_archived_stacks` | List archived stacks and their cards |
+| `deck_get_cards` | List cards in a stack (compact summaries by default) |
+| `deck_get_card` | Get a single card in full detail |
+| `deck_get_labels` / `deck_get_label` | List / get board labels |
+| `deck_get_card_comments` | List card comments (compact, newest-first by default) |
 | `deck_create_board` | Create a new Deck board with title and color |
 | `deck_create_stack` | Create a new stack in a board |
 | `deck_update_stack` | Update stack title and order |
@@ -36,6 +46,44 @@
 
 
 
+### Compact Retrieval (token efficiency)
+
+On large boards the full card objects (description, nested labels, assigned
+users, attachments, etags) make `deck_get_stacks` responses too large to be
+practical. The read tools therefore return **compact card summaries by
+default** and support filtering so you fetch only what you need.
+
+**Shared knobs** on `deck_get_cards`, `deck_get_stacks`, `deck_get_stack`
+(and `deck_get_archived_stacks`, minus `status`):
+
+| Parameter | Default | Effect |
+|-----------|---------|--------|
+| `detail` | `summary` | `summary` returns compact rows (id, title, stackId, labels as titles, assignee UIDs, due/done, counts, a short `descriptionPreview`); `full` returns the complete card objects (the pre-0.92 shape). |
+| `status` | `open` | Filter before serialization: `open` (excludes archived **and** done), `done`, `archived`, or `all`. |
+| `label` | – | Only cards carrying a label with this exact title. |
+| `assigned_to` | – | Only cards assigned to this user UID. |
+| `description_max_length` | – | In `detail="full"`, truncate each description. |
+| `description_preview_length` | `140` | In `detail="summary"`, length of the preview. |
+
+**`deck_get_board_overview(board_id, status="open", label=…, assigned_to=…)`**
+is the token-efficient way to see a whole board: it returns the board title,
+its label legend, and every stack with compact card rows in a single call —
+prefer it over `deck_get_board` + `deck_get_stacks` for "show me the board"
+requests. Use `deck_get_card` for the full body of a specific card.
+
+**Comments** — `deck_get_card_comments` returns compact comments
+(`id`, `actorId`, `message`, `creationDateTime`) by default. Use
+`detail="full"` for the complete objects, `message_max_length` to truncate,
+`order` (`newest`/`oldest`) to sort the page, and `limit`/`offset` to page.
+
+> **Breaking change:** list tools now default to `detail="summary"`
+> and `status="open"`. The previous `include_archived_cards` parameter has
+> been replaced by `status` (`status="all"` includes archived cards, matching
+> `include_archived_cards=True`). Pass `detail="full"` to restore the old
+> per-card shape.
+
+
+
 ### Deck Project Management
 
 The server provides complete Nextcloud Deck integration, enabling you to manage projects, tasks, and workflows: