marcus · marcus · Apr 27, 2026
diff --git a/README.md b/README.md
@@ -23,6 +23,7 @@ A minimalist CLI for tracking tasks across AI coding sessions. When your context
 - [Query Language (TDQ)](#query-language-tdq)
 - [Epics](#epics)
 - [Multi-Issue Work Sessions](#multi-issue-work-sessions)
+- [Deferral & Due Dates](#deferral--due-dates)
 - [File Tracking](#file-tracking)
 - [Minor Tasks](#minor-tasks)
 - [Analytics & Stats](#analytics--stats)
@@ -350,6 +351,31 @@ td ws log "Shared token storage"    # Log fans out to all tagged issues
 td ws handoff                       # Capture state for all, end session
 ```
 
+## Deferral & Due Dates
+
+Keep the default backlog focused on work that is actionable now:
+
+```bash
+# Create with scheduling metadata
+td create "Review vendor contract" --defer next-week --due 2026-05-15
+
+# Add or change dates later
+td defer td-a1b2 +7d          # Hide until seven days from now
+td due td-a1b2 friday         # Keep visible, but mark with a deadline
+td defer td-a1b2 --clear      # Make actionable again
+td due td-a1b2 --clear        # Remove the deadline
+
+# Scheduling-aware list filters
+td list                       # Hides future-deferred issues by default
+td list --all                 # Includes all statuses and deferred issues
+td list --deferred            # Only future-deferred issues
+td list --surfacing           # Deferred issues now actionable again
+td list --overdue             # Open issues past their due date
+td list --due-soon            # Issues due within the next 3 days
+```
+
+`defer_until` is a snooze date: future-deferred issues are hidden from `td list` until the date arrives. `due_date` is a deadline: it stays visible and is highlighted when due soon or overdue. Date fields accept `today`, `tomorrow`, weekday names, `next-week`, `next-month`, relative offsets like `+7d`, `+2w`, `+1m`, and exact `YYYY-MM-DD` dates.
+
 ## File Tracking
 
 Know exactly what changed:
@@ -402,8 +428,14 @@ Analytics are stored locally and help identify workflow patterns. Disable with `
 | See current state                | `td usage`                                       |
 | Compact state (after first read) | `td usage -q`                                    |
 | Create issue                     | `td create "title" --type feature --priority P1` |
+| Create with scheduling           | `td create "title" --defer next-week --due +2w`  |
 | Create minor task                | `td add "title" --minor`                         |
 | List all issues                  | `td list`                                        |
+| List including deferred/closed    | `td list --all`                                  |
+| List deferred issues             | `td list --deferred`                             |
+| List surfacing issues            | `td list --surfacing`                            |
+| List overdue issues              | `td list --overdue`                              |
+| List due-soon issues             | `td list --due-soon`                             |
 | List by status                   | `td list --status in_progress`                   |
 | What should I work on?           | `td next`                                        |
 | Start work                       | `td start <id>`                                  |
@@ -412,6 +444,11 @@ Analytics are stored locally and help identify workflow patterns. Disable with `
 | Log a decision                   | `td log --decision "chose X because Y"`          |
 | Log a blocker                    | `td log --blocker "stuck on X"`                  |
 | View issue details               | `td show <id>`                                   |
+| Defer issue                      | `td defer <id> +7d`                              |
+| Clear deferral                   | `td defer <id> --clear`                          |
+| Set due date                     | `td due <id> friday`                             |
+| Clear due date                   | `td due <id> --clear`                            |
+| Update scheduling                | `td update <id> --defer "" --due 2026-05-15`     |
 | Capture handoff state            | `td handoff <id> --done "..." --remaining "..."` |
 | Submit for review                | `td review <id>`                                 |
 | See reviewable issues            | `td reviewable`                                  |

diff --git a/docs/primer.md b/docs/primer.md
@@ -40,6 +40,25 @@ Each issue has:
 - **Priority** — `P0` (critical) through `P4` (none), defaulting to `P2`
 - **Labels** — freeform tags for categorization
 
+### Deferral and Due Dates
+
+td has two scheduling fields with different meanings:
+
+- **`defer_until`** — a snooze date. If it is in the future, the issue is hidden from the default `td list` output until that date arrives.
+- **`due_date`** — a deadline. The issue remains visible, and list/detail views can flag it as due soon or overdue.
+
+Use `td defer <id> <date>` and `td due <id> <date>` to set them after creation, or pass `--defer` and `--due` to `td create` or `td update`:
+
+```bash
+td create "Review release notes" --defer next-week --due +2w
+td update td-a1b2 --defer "" --due friday
+td list --deferred
+td list --overdue
+td list --due-soon
+```
+
+Supported date formats are exact dates (`2026-05-15`), relative offsets (`+7d`, `+2w`, `+1m`), weekday names (`monday`, `friday`), and keywords (`today`, `tomorrow`, `next-week`, `next-month`). `td list --all` includes deferred and closed issues; `td list --surfacing` shows previously deferred issues whose `defer_until` date is today or earlier.
+
 ### Issue Lifecycle
 
 Issues move through a state machine:

diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md
@@ -10,10 +10,10 @@ Complete reference for all `td` commands.
 
 | Command | Description |
 |---------|-------------|
-| `td create "title" [flags]` | Create issue. Flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor` |
-| `td list [flags]` | List issues. Flags: `--status`, `--type`, `--priority`, `--epic` |
+| `td create "title" [flags]` | Create issue. Flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor`, `--defer`, `--due` |
+| `td list [flags]` | List issues. Flags: `--status`, `--type`, `--priority`, `--epic`, `--all`, `--deferred`, `--surfacing`, `--overdue`, `--due-soon` |
 | `td show <id>` | Display full issue details |
-| `td update <id> [flags]` | Update fields. Flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels` |
+| `td update <id> [flags]` | Update fields. Flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels`, `--defer`, `--due` |
 | `td delete <id>` | Soft-delete issue |
 | `td restore <id>` | Restore soft-deleted issue |
 
@@ -48,7 +48,7 @@ Date formats: `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-mont
 
 The `--defer` and `--due` flags are also available on `td create` and `td update`.
 
-**List filters:** `--all` (include deferred), `--deferred`, `--surfacing`, `--overdue`, `--due-soon`
+**List filters:** `--all` (include all statuses and deferred issues), `--deferred` (future-deferred only), `--surfacing` (previously deferred and now actionable), `--overdue`, `--due-soon`
 
 ## Agent-Safe Rich Text Input
 

diff --git a/website/docs/deferral.md b/website/docs/deferral.md
@@ -83,9 +83,9 @@ By default, `td list` **hides deferred tasks** — tasks whose `defer_until` is
 
 ```bash
 td list                  # Actionable tasks only (deferred hidden)
-td list --all            # Everything, including deferred
+td list --all            # All statuses, including deferred and closed
 td list --deferred       # Only deferred tasks
-td list --surfacing      # Tasks whose deferral expires today
+td list --surfacing      # Previously deferred tasks now actionable again
 td list --overdue        # Tasks past their due date
 td list --due-soon       # Tasks due within 3 days
 ```

diff --git a/website/docs/intro.md b/website/docs/intro.md
@@ -94,4 +94,5 @@ Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI.
 
 - [Core Workflow](./core-workflow.md) -- Issue lifecycle, logging, handoffs, and reviews in depth
 - [Boards](./boards.md) -- Visual overview of issue status across your project
+- [Deferral & Due Dates](./deferral.md) -- Hide future work until it is actionable and track deadlines
 - [Query Language](./query-language.md) -- Filter and search issues with structured queries