From 0875e50f85f19fb04328b141c9bda8d479655102 Mon Sep 17 00:00:00 2001
From: Steve Yegge <stevey@sourcegraph.com>
Date: Wed, 5 Nov 2025 01:02:55 -0800
Subject: [PATCH] docs: Document new bd list query facilities (pattern
 matching, date ranges, empty checks)

Amp-Thread-ID: https://ampcode.com/threads/T-4d8dfaab-6a44-4ee5-ad11-93b915bbe1dc
Co-authored-by: Amp <amp@ampcode.com>
---
 AGENTS.md | 35 +++++++++++++++++++++++++++++++++--
 README.md | 26 ++++++++++++++++++++++----
 2 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0010334e..1185df5e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -186,8 +186,39 @@ bd label remove <id> [<id>...] <label> --json
 bd label list <id> --json
 bd label list-all --json
 
-# Filter issues by label
-bd list --label bug,critical --json
+# Filter and search issues
+bd list --status open --priority 1 --json               # Status and priority
+bd list --assignee alice --json                         # By assignee
+bd list --type bug --json                               # By issue type
+bd list --label bug,critical --json                     # Labels (AND: must have ALL)
+bd list --label-any frontend,backend --json             # Labels (OR: has ANY)
+bd list --id bd-123,bd-456 --json                       # Specific IDs
+bd list --title "auth" --json                           # Title search (substring)
+
+# Pattern matching (case-insensitive substring)
+bd list --title-contains "auth" --json                  # Search in title
+bd list --desc-contains "implement" --json              # Search in description
+bd list --notes-contains "TODO" --json                  # Search in notes
+
+# Date range filters (YYYY-MM-DD or RFC3339)
+bd list --created-after 2024-01-01 --json               # Created after date
+bd list --created-before 2024-12-31 --json              # Created before date
+bd list --updated-after 2024-06-01 --json               # Updated after date
+bd list --updated-before 2024-12-31 --json              # Updated before date
+bd list --closed-after 2024-01-01 --json                # Closed after date
+bd list --closed-before 2024-12-31 --json               # Closed before date
+
+# Empty/null checks
+bd list --empty-description --json                      # Issues with no description
+bd list --no-assignee --json                            # Unassigned issues
+bd list --no-labels --json                              # Issues with no labels
+
+# Priority ranges
+bd list --priority-min 0 --priority-max 1 --json        # P0 and P1 only
+bd list --priority-min 2 --json                         # P2 and below
+
+# Combine filters
+bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json
 
 # Complete work (supports multiple IDs)
 bd close <id> [<id>...] --reason "Done" --json
diff --git a/README.md b/README.md
index d8667e32..a0dd40ff 100644
--- a/README.md
+++ b/README.md
@@ -390,10 +390,28 @@ bd list --label-any=frontend,backend       # Filter by labels (OR)
 # Advanced filters
 bd list --title-contains "auth"            # Search title
 bd list --desc-contains "implement"        # Search description
-bd list --priority-min 0 --priority-max 1  # Priority range
-bd list --created-after 2025-01-01         # Date range
-bd list --empty-description                # Find issues with no description
-bd list --no-assignee                      # Find unassigned issues
+bd list --notes-contains "TODO"            # Search notes
+bd list --id bd-123,bd-456                 # Specific IDs (comma-separated)
+
+# Date range filters (YYYY-MM-DD or RFC3339)
+bd list --created-after 2024-01-01         # Created after date
+bd list --created-before 2024-12-31        # Created before date
+bd list --updated-after 2024-06-01         # Updated after date
+bd list --updated-before 2024-12-31        # Updated before date
+bd list --closed-after 2024-01-01          # Closed after date
+bd list --closed-before 2024-12-31         # Closed before date
+
+# Empty/null checks
+bd list --empty-description                # Issues with no description
+bd list --no-assignee                      # Unassigned issues
+bd list --no-labels                        # Issues with no labels
+
+# Priority ranges
+bd list --priority-min 0 --priority-max 1  # P0 and P1 only
+bd list --priority-min 2                   # P2 and below
+
+# Combine multiple filters
+bd list --status open --priority 1 --label-any urgent,critical --no-assignee
 
 # JSON output for agents
 bd info --json