From 21d8a2365aeb1a4a10fa1d719955297caa1a02b3 Mon Sep 17 00:00:00 2001
From: Rob Zolkos <rob@zolkos.com>
Date: Thu, 29 Jan 2026 12:56:40 -0500
Subject: [PATCH 1/2] Clarify --all flag behavior and document card statuses

- Add new "Card Statuses" section explaining how to fetch cards in
  different states (closed, not_now, golden, stalled)
- Clarify that --all is a pagination flag, not a status filter
- Document how to fetch all cards on a board using multiple queries
- Add note in Pagination section linking to Card Statuses

Addresses confusion reported in #53 where users expected --all to
return closed cards.
---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e985d8f..ec93214 100644
--- a/README.md
+++ b/README.md
@@ -203,6 +203,41 @@ fizzy card update 42 --created-at "2019-01-01T00:00:00Z"
 fizzy card delete 42
 ```
 
+### Card Statuses
+
+Cards in Fizzy exist in different states. By default, `fizzy card list` returns **open cards only** (cards in triage or columns). To fetch cards in other states, use the `--indexed-by` or `--column` flags:
+
+| Status | How to fetch | Description |
+|--------|--------------|-------------|
+| Open (default) | `fizzy card list` | Cards in triage ("Maybe?") or any column |
+| Closed/Done | `fizzy card list --indexed-by closed` | Completed cards |
+| Not Now | `fizzy card list --indexed-by not_now` | Postponed cards |
+| Golden | `fizzy card list --indexed-by golden` | Starred/important cards |
+| Stalled | `fizzy card list --indexed-by stalled` | Cards with no recent activity |
+
+You can also use pseudo-columns:
+
+```bash
+fizzy card list --column done --all     # Same as --indexed-by closed
+fizzy card list --column not-now --all  # Same as --indexed-by not_now
+fizzy card list --column maybe --all    # Cards in triage (no column assigned)
+```
+
+**Fetching all cards on a board:**
+
+To get all cards regardless of status (for example, to build a complete board view), you need to make separate queries and combine the results:
+
+```bash
+# Open cards (triage + columns)
+fizzy card list --board BOARD_ID --all
+
+# Closed/Done cards
+fizzy card list --board BOARD_ID --indexed-by closed --all
+
+# Optionally, Not Now cards
+fizzy card list --board BOARD_ID --indexed-by not_now --all
+```
+
 ### Card Actions
 
 ```bash
@@ -593,13 +628,15 @@ Errors return a non-zero exit code and structured error info:
 
 ## Pagination
 
-List commands return paginated results. Use `--page` to fetch specific pages or `--all` to fetch everything:
+List commands return paginated results. Use `--page` to fetch specific pages or `--all` to fetch all pages:
 
 ```bash
 fizzy card list --page 2
-fizzy card list --all
+fizzy card list --all      # Fetches all pages of the current filter
 ```
 
+> **Note:** The `--all` flag controls pagination only - it fetches all pages of results for your current filter. It does not change which cards are included. See [Card Statuses](#card-statuses) for how to fetch closed or postponed cards.
+
 ## Development
 
 ### Building

From 29f2989b1e2e9eb13963d8f2fb82c6aede422581 Mon Sep 17 00:00:00 2001
From: Rob Zolkos <rob@zolkos.com>
Date: Thu, 29 Jan 2026 13:01:04 -0500
Subject: [PATCH 2/2] Update SKILL.md with card statuses documentation

---
 skills/fizzy/SKILL.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/skills/fizzy/SKILL.md b/skills/fizzy/SKILL.md
index a706423..c2f89be 100644
--- a/skills/fizzy/SKILL.md
+++ b/skills/fizzy/SKILL.md
@@ -276,6 +276,8 @@ fizzy card list --page 1 | jq '.data[:5]'
 fizzy card list --all
 ```
 
+**IMPORTANT:** The `--all` flag controls pagination only - it fetches all pages of results for your current filter. It does NOT change which cards are included. By default, `card list` returns only open cards. See [Card Statuses](#card-statuses) for how to fetch closed or postponed cards.
+
 Commands supporting `--all` and `--page`:
 - `board list`
 - `card list`
@@ -287,6 +289,43 @@ Commands supporting `--all` and `--page`:
 
 ---
 
+## Card Statuses
+
+Cards exist in different states. By default, `fizzy card list` returns **open cards only** (cards in triage or columns). To fetch cards in other states, use the `--indexed-by` or `--column` flags:
+
+| Status | How to fetch | Description |
+|--------|--------------|-------------|
+| Open (default) | `fizzy card list` | Cards in triage ("Maybe?") or any column |
+| Closed/Done | `fizzy card list --indexed-by closed` | Completed cards |
+| Not Now | `fizzy card list --indexed-by not_now` | Postponed cards |
+| Golden | `fizzy card list --indexed-by golden` | Starred/important cards |
+| Stalled | `fizzy card list --indexed-by stalled` | Cards with no recent activity |
+
+You can also use pseudo-columns:
+
+```bash
+fizzy card list --column done --all     # Same as --indexed-by closed
+fizzy card list --column not-now --all  # Same as --indexed-by not_now
+fizzy card list --column maybe --all    # Cards in triage (no column assigned)
+```
+
+**Fetching all cards on a board:**
+
+To get all cards regardless of status (for example, to build a complete board view), make separate queries:
+
+```bash
+# Open cards (triage + columns)
+fizzy card list --board BOARD_ID --all
+
+# Closed/Done cards
+fizzy card list --board BOARD_ID --indexed-by closed --all
+
+# Optionally, Not Now cards
+fizzy card list --board BOARD_ID --indexed-by not_now --all
+```
+
+---
+
 ## Common jq Patterns
 
 ### Reducing Output